FAQ on using Smart Contract for client allocations - filecoin-project/Allocator-Registry GitHub Wiki

FAQ: Using the Client Smart Contract to Make Allocation And Onboard Data using DDO deals

1. What is the Client Smart Contract?

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.


2. Why should allocators use the smart contract?

  • 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.


3. How do I start using the smart contract method?

This guide explains how allocators can use the Client Smart Contract to allocate DataCap to clients.

Initial Setup

To begin using the Client Smart Contract, allocators must select Allocation Type: Contract during the first allocation to a client. Screenshot from 2025-05-15 19-48-34

Granting DataCap to a Client via the Smart Contract

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:

  1. Transfer DataCap to the Smart Contract
    The allocator sends the DataCap amount to the Client Smart Contract address.

  2. 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.


4. How do I control which Storage Providers the client can use?

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.

What Is Max Deviation?

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.


5. Notification about the use of Client Smart Contract

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.


6. Can an allocator still use the direct allocation method?

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.


7. How do I grant or remove a client’s DataCap?

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.


8. What happens if a client doesn’t use all their DataCap?

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.


9. Can I still switch a client from direct to smart contract method?

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.


10. How to check current DataCap usage

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.

DataaCap used from most recent allocation


11. How to check allocations

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.


12. How to onboard data using DDO deals

  1. 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
    
  2. 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
    
  3. Now, you need to send some funds and Datacap to the wallet.

  4. 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 its payload-cid. We recommend using go-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
    
  5. Then you need to calculate the commp and piece size for the generated car 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
    
  6. 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
    
  7. 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
    
  8. Watch the boostd UI to verify that the new DDO deal reaches "Complete" and "Claim Verified" state.


13. Where can I ask questions or report issues?

We’re here to help! Reach out via:


⚠️ **GitHub.com Fallback** ⚠️