FAQ on using Smart Contract for client allocations - filecoin-project/Allocator-Registry GitHub Wiki
It’s a tool that lets allocators manage how much DataCap a client can use, where they can send it, and reclaim what’s unused. Unlike sending tokens to a wallet, it keeps DataCap in a controlled system, making it easier to track, enforce rules, and make changes when needed.
- More control: You can update or revoke unused DataCap at any time.
- Better compliance: Clients can only send DataCap to pre-approved storage providers.
- Transparent tracking: You can see exactly how much each client has used and where it went.
- Safer: Reduces the risk of accidental loss or misuse of tokens.
All of this is managed through Allocator.tech — no need to write smart contract code.
This guide explains how allocators can use the Client Smart Contract to allocate DataCap to clients.
To begin using the Client Smart Contract, allocators must select Allocation Type: Contract during the first allocation to a client.
Granting DataCap through the Client Smart Contract requires two transactions, both of which must be signed by the allocator. These transactions will be automatically executed one after the other:
-
Transfer DataCap to the Smart Contract
The allocator sends the DataCap amount to the Client Smart Contract address. -
Increase Client’s Available DataCap
The allocator calls the contract function to increase the available DataCap for the specified client.
That’s it — the client is now set up to use DataCap through Client Smart Contract.
Using the Client Smart Contract requires specifying the storage providers (SPs) that the client will interact with. After the first allocation, connect your wallet. The "Add Allowed SP" button should then become available.
The frontend accepts SP IDs in two formats:
f01234567
1234567
It is possible to manage allowed SPs by adding and removing them while the application is active.
Additionally, the max deviation is currently set to 10%. This makes sure your client spreads out storage as expected. A transaction that sets this value is automatically triggered during the initial configuration of the storage providers.
The Maximum Deviation defines how much more storage a single Storage Provider (SP) can receive compared to an equal distribution among all selected SPs.
It is currently set to 10% of the client’s total allocation and is enforced via a smart contract, which is automatically triggered during the initial setup of storage providers.
A notification informing that the allocation was made through a Client Smart Contract will be automatically posted as a comment on the associated GitHub issue after the first allocation is granted.
Yes. You can still choose to send DataCap directly to a client’s wallet. But remember:
- You won’t be able to revoke or update it.
- There’s no way to restrict how or where it’s used.
- Generally for compliance reasons this is highly discouraged and may delay the audit and refresh
We recommend using the Contract
allocation method for better safety, flexibility, and oversight.
At any time, you can:
- Trigger Refill to increase their allowance — the process happens automatically behind the scenes, so from the allocator’s perspective, nothing changes.
- Decrease Allowance to take back unused tokens — this feature is currently a work in progress.
These changes take effect immediately and are done through the website.
It stays in their contract-based allowance—not in their wallet.
You can reclaim it at any time using “Decrease Allowance.”
That way, you can reassign it to another client instead of letting it go unused.
Once the first allocation has been made, switching methods is no longer possible. To use a different method, the client must create a new application with a new wallet address.
To see the current DataCap usage, please visit Allocator.tech and find your application, where a progress bar displays the DataCap consumed by the client in their latest allocation.
The allocation will not be visible on the personal address because it is currently associated with the contract address. If you want to validate your claims go to datacapstats.io/clients and search for the client, which in this case is the contract. To check the address of the contract assigned to you, go to your allocator's bookkeeping repo. In the Applications folder, find the JSON file of your application by your address, and check the value of the Client Contract Address field.
This step-by-step guide explains how to create verified DDO deals using DataCap granted through a Client Smart Contract with Boost.
-
First, you need to initialise a new Boost client and also set the endpoint for a public Filecoin node. In this example we are using https://glif.io
export FULLNODE_API_INFO=https://api.node.glif.io boost init
-
The
init
command will output your new wallet address, and warn you that the market actor is not initialised.boost init boost/init_cmd.go:53 default wallet set {"wallet": "f3wfbcudimjcqtfztfhoskgls5gmkfx3kb2ubpycgo7a2ru77temduoj2ottwzlxbrbzm4jycrtu45deawbluq"} boost/init_cmd.go:60 wallet balance {"value": "0"} boost/init_cmd.go:65 market actor is not initialised, you must add funds to it in order to send online deals
-
Now, you need to send some funds and Datacap to the wallet.
-
You can confirm that the market actor has funds and Datacap by running
boost wallet list
.After that you need to generate a
car
file for data you want to store on Filecoin, and note down itspayload-cid.
We recommend usinggo-car
CLI to generate the car file.boostx generate-rand-car -c=50 -l=$links -s=5120000 . Payload CID: bafykbzacedr7avw5yvxgjftkhfgzgbinq523csw3ir5hyukx2ulewaigyjdrm, written to: <$CWD>/bafykbzacedr7avw5yvxgjftkhfgzgbinq523csw3ir5hyukx2ulewaigyjdrm.car
-
Then you need to calculate the
commp
andpiece size
for the generatedcar
file:boostx generate-rand-car -c=50 -l=$links -s=5120000
boostx commp bafykbzacedr7avw5yvxgjftkhfgzgbinq523csw3ir5hyukx2ulewaigyjdrm.car CommP CID: baga6ea4seaqjpldhlgodxw2vjj6g46xra7jthe2g37kt7577ep5euxipkupfsly Piece size: 8388608 Car file size: 7657847
-
Create a new verified allocation for this piece using the boost client. You can use other methods to create allocations as long as the piece details match the generated commP. If you received DataCap via a Client Smart Contract, be sure to include the
--evm-client-contract
option, and provide the proper value when creating the allocation. To check the address of the contract assigned to you, first check the associated GitHub issue. The address should be provided as a comment in the issue. If the address is not available there, go to your allocator's bookkeeping repo. In the Applications folder, find the JSON file of your application by your address, and check the value of the Client Contract Address field.boost allocate --evm-client-contract f410foc6psy3k7a2fb37tb2tslxj2hvzuj5ymcku7xia --miner=t01013 --piece-info=baga6ea4seaqjpldhlgodxw2vjj6g46xra7jthe2g37kt7577ep5euxipkupfsly=8388608 --wallet t3tejq3lb3szsq7spvttqohsfpsju2jof2dbive2qujgz2idqaj2etuolzgbmro3owsmpuebmoghwxgt6ricvq about to send message with the following gas costs max fee: 0.00000000512550864 FIL (absolute maximum amount you are willing to pay to get your transaction confirmed) gas fee cap: 0.00000000000000012 FIL gas limit: 42712572 gas premium: 0.000000000000000023 FIL basefee: 0.0000000000000001 FIL Proceed? Yes [y] / No [n]: y 2024-03-11T18:11:59.794Z INFO boost boost/direct_deal.go:112 submitted data cap allocation message {"cid": "bafy2bzacecyxmx4uyuqfy6xdnlaba2aamlghcujt2asvqmkz6trilnttcouoi"} 2024-03-11T18:11:59.794Z INFO boost boost/direct_deal.go:113 waiting for message to be included in a block AllocationID Client Miner PieceCid PieceSize TermMin TermMax Expiration 31825 1011 1013 baga6ea4seaqjpldhlgodxw2vjj6g46xra7jthe2g37kt7577ep5euxipkupfsly 8388608 518400 5256000 1601277
-
Import the piece for the newly create allocation using
boostd
. Remember that--client-addr
must be equal to the address of the Client Smart Contract.boostd import-direct --client-addr=f410foc6psy3k7a2fb37tb2tslxj2hvzuj5ymcku7xia --allocation-id=31825 baga6ea4seaqjpldhlgodxw2vjj6g46xra7jthe2g37kt7577ep5euxipkupfsly ~/bafykbzacedr7avw5yvxgjftkhfgzgbinq523csw3ir5hyukx2ulewaigyjdrm.car Direct data import scheduled for execution
-
Watch the
boostd
UI to verify that the new DDO deal reaches "Complete" and "Claim Verified" state.
We’re here to help! Reach out via:
- Email: [email protected]
-
Slack:
#filplus-allocators
channel - GitHub: fidlabs/allocator-tooling