FIP-0029 Source

TitleBeneficiary address for storage providers
AuthorSteven Li
StatusLast Call

Spec Sections

FIP-0029: Beneficiary address for storage providers

Simple Summary

To provide more flexibilities for Filecoin finance market, a new role beneficiary is proposed for a storage provider, which takes over the financial control from the owner.


There are several keypairs associated with a given storage provider address for different operational purpose, including a worker and zero or more controllers block producing, making deals, onboarding sectors and proving storage. There is also the owner keypair that is used for a SP administration and fund withdraws, to be more specific, currently **only the owner address can withdraw the funds from the miner actor.

The beneficiary role is to take financial control from owner, i.e. only financiary role could withdraw filecoin from a storage provider node, and the owner keep other controls.

Change Motivation

Filecoin’s pledge collateral mechanism creates opportunities for a lending market. We already see some projects launched to solve the problem, e.g. Coinlist is running lending business to Filecoin storage providers while asking excess pledge paid in other digital currency. However, the filecoin node itself has great value including pledge collateral and locked rewards, which, ideally, can be used as collateral for filecoin lending. Some Filecoin service providers are doing this by providing collateral for their customers whole holding owner addresses.

The problem is the owner of a Filecoin node has full control of the node, including changing worker and controllers, withdraw balance or terminate sectors. This proposal is to separate the node control and financial benefit into different roles, that’s how the beneficiary comes in.


There are a few parts to be implemented to achieve the beneficiary separation and related security matters, including: 1) miner-state change to accommodate benefiary and its state; 2) methods added to miner-actor to support beneficiary change; 3) Date and/or quota experition support for beneficiary.

The following channges apply to specs-actors module:

Beneficiary information in state

  • Add Beneficiary address into MinerInfo structure
  • Add BeneficiaryTerm structure into MinerInfo structure to include {Quota (attoFIL), Expiration(Height), usedQuota(attoFIL)}.
  • The Beneficiary is set to the same address of Owner when initiating a miner without specifying a beneficiary address (for back-compatibility)
  • The Beneficiary address could be a signable address, or multisig address, or actor address (for smart contract)
  • Add a PendingBeneficiaryChange structure into MinerInfo structure to record the ChangeBeneficiary information and progress, including parameters and who has approved it.

Withdrawals to beneficiary

  • The WithdrawBalance method of a miner can be called by the miner’s Beneficiary or Owner, but the balance always being sent to the beneficiary. The total balance withdrawed to a beneficiary address could not exceed the quota.
  • If the ** BeneficiaryTerm** is expired, or has used all of its Quota, then no withdrawals are possible until the beneficiary is updated or changed. Calls to WithdrawBalance will fail in this case with USR_FORBIDDEN(18). This behaviour is different to when the owner withdraws to themselves, where a withdrawal when 0 available will “succeed” to withdraw nothing (best effort).

Setting the beneficiary address

  • Add ChangeBeneficiary method to miner actor to propose or confirm a change of beneficiary address and/or beneficiaryTerm. When changing beneficiaryTerm, the quota must be larger than the usedQuota. The beneficiaryChange is following a proposal/confirmation manner. A ChangeBeneficiary proposal can only be submitted by the Owner, and it takes effect only after approval(s) related parties if effective. The related parties include the Owner, the current Beneficiary, and the proposed Beneficiary (the nominee). However, there are scenarios of auto-approval (no message required) as below:
    • The Owner always auto-approves the proposal since Only the owner can send ChangeBeneficiary proposal
    • When current Beneficiary or proposed Beneficiary shares the Owner’s address
    • When the current BeneficiaryTerm is expired or Quota is used up
    • When current and proposed Beneficiaries are the same, One’s approval means both approvals.
  • Some other consideration related to ChangeBeneficiary:
    • A succssful ChangeOwnerAddress will invalidate any pendingBeneficiaryChange, which means, a non-fully approved ChangeBeneficiary will be deleted whenever the Owner address changes
    • UsedQuota is set to 0 whenever the Beneficiary address changes, but keeps no change if the proposed Beneficiary equals to the current Beneficiary
    • Both Experition, Quota and UserdQuota set back to default (0) when the Beneficiary changes back to the Owner
  • Add a GetBeneficiary method to the miner actor which retrieves the currently active and proposed beneficiary information. This method is for use by other actors (such as those acting as beneficiaries), and to abstract the state representation for clients.

Design Rationale

Mainly there are two scenarios for the beneficiary address being separated from owner address based on the current design.

  1. Enable lending market using the node rewards as collateral. This is actually done by some Filecoin network service providers, but, currently, it only works when the lender is the service provider. When we have the beneficiary address, the lender could be anybody else who value the node itself.
  2. For storage provider internal use, there are lots of advantages when having a separated beneficiary address, which can be controlled by the finance department, while owner be controller by the maintenance/engineering team.

But, there are more use cases can be developed when this is in place. E.g.

  • Block Reward pooling design: Rewarding sharing is a very good thing for small/medium storage providers since it can provide much more certainty of income. Almost in all mining pool design, the small/medium miners need to hand over the beneficiary address to the pool provider. In Filecoin, Owner address need to be transferred if there is no another beneficiary address, which is too risky, since owner has fully control of the node. A separated beneficiary address makes it much safer.
  • Reward pooling can be integrated with Smart Contract when it is available, in this case, the beneficiary address could be transferred to an trustless actor. We can not transfer the owner to a smart contract address, since it is hard to change it back. But we can do it with beneficiary address with a good design.

In addition, if we have the security feature, it will protest the storage provider from the beneficiary owner mistake (loss or expose of private key), or any other risks, e.g. bankruptcy, to some degree.

ChangeBeneficiary design

  • Security is one of the main considerations when desigining the ChangeBeneficiary process, especially when beneficiary can be transferred to the lending part. The basic idea is that every change of beneficiary information is based on the agreement among related parties, so the design includes proposal and confirmation process, and every part need to be involved to make it happen.
  • Quota and usedQuota is used to track the financial setting and status for a beneficiary. An altenative of this design is to use only one parameter - remainingQuota to record the status. Considering that people want to control total Quota in most cases, especially in lending market. The 2 parameters’ design is more user-friendly.

Backwards Compatibility

This FIP changes built-in actors’ behavior so it requires a new Filecoin network version. This FIP changes the miner actor state schema, so requires a migration to update all miners to the new schema. For each existing miner, the Beneficiary address is set to the current owner address, and the beneficiaryTerm set to zero values.

This will result in no change to existing functional behaviour, so is fully backwards compatible.

Filecoin client and node implementations should add new APIs or commands to query and propose beneficiaries. The design of these need not be standardised and is left to implementation maintainers.

Test Cases

This proposal has no consensus changes, there is no impact on chain sync and block generation logic.

Extensive tests are provided in the prototype (Rust) implementation at

Security Considerations

This FIP does not touch consensus, block generation.

There is a concern that the beneficiary address might be controlled by people who are not so familiar with Filecoin, which may lead to some mistake of private key loss. Basically this can not be really handled well if using a signable address as a beneficiary, but the multisigs support could mitigate this as we did for owner. In addition, the expiration date and quota setting is for kind of pretectioins.

Incentive Considerations

The primary motivation of this proposal is to provide more flexibility for storage providers from financial point of view by separating beneficiary from owner. There is almost no impact to incentivation if the beneficiary is controlled by the owner or sharing address with the owner. The question is whether it mitigate the incentivation for the network if the beneficiary is transferred to antoher party for collareral or any other reasons.

  • From the whole network point of view, this proposal creates a possibility to pledge the future rewards as collateral for storage providers to get FIL for power growth, which lowers the capital barrier for (small/medium) storage providers to join ths market. Thus, it could accelerate network power growth, and improve decentralization. It’s a great thing for the network reliability and security.
  • For a particular storage provider, when she transfers the beneficiary to a lender to get token as pledge collateral, her investment into her node is less since the lender paid some. The penalty on her will be less too if she stop to maintain the node, though the overall penalty keeps no change. This would be a mitigation of storage maintenance incentives. This should be acceptable due the following two reasons:
    • The lending market is already there without this proposal fulfilment. Some of them transferring owner instead, which is more risky. This proposal mitigates the risks comparing transferring owner.
    • The lender will consider this since she will pay the penalty if the borrower does not maintain the node well. It is a reasonable assumption that the leader will minimize the risk of her token loss in their agreements neogotiation.
  • The possible beneficiary key loss, or the beneficiary is transferred to an unintended one, which makes the owner loss control. In this case, the expiration mechanism design could mitigate this risk to some degree, at the same time, this is not worser than lossing owner’s key or transferring owner’s address to an unintended one.

Product Considerations

The implementation of separating beneficiary from owner will bring the ecosystem more flexibilities, including the lending market and the finance management. The lending market could be centralized, e.g. by institutional capitals, or decentralized by smart contracts. When the FVM is available and the user defined actors is possible, there could be differnt finance agreements for user to choose. The most important thing is, all filecoin hodlers could join to get interest by staking.


Specs-actors PR:

Builtin-actors PR:

The overall flow chart of the ChangeBeneficiary process: The overll process of ChangeBeneficiary

Copyright and related rights waived via CC0.


Please cite this document as:

Steven Li, "FIP-0029: Beneficiary address for storage providers [DRAFT]," Filecoin Improvement Proposals, no. 0029, December 2021. [Online serial]. Available: