FIP-0020 Source

TitleAdd Return Value to WithdrawBalance
AuthorSteven Li, Zenground0
Review period ends2021-10-11
TypeTechnical Core

Spec Sections

FIP-0020: Add Return Value to WithdrawBalance

Simple Summary

Add a return value to market and miner withdraw methods to indicate the actual withdrawn amount


WithdrawBalance methods can succeed even when withdrawing less than the specified amount in message arguments. To resolve this ambiguity the return value should specify the amount withdrawn.

Change Motivation

Both miner and market actors have WithdrawBalance methods. Both methods are an attempt to withdraw a specified amount, but return success even when the available balance is less than the withdrawal amount specified. So the actual amount withdrawn is equal to or less than the amount specified in the method parameters, and the method always return nil. Therefore there is no way to know how much FIL is actually withdrawn by only checking the chain status and message info e.g. from node CLI or an explorer.

Adding return values specifying the withdrawn amount will improve the visibility and traceability of FIL flow. This is important especially for miners who need to have a very clear balance sheet and financial report.


Add abi.TokenAmount return values to market and miner WithdrawBalance methods and return the amount withdrawn.

Design Rationale

The design is trivial.

Backwards Compatibility

This proposal requires a breaking change in actor method signatures and therefore a new actors version.

Test Cases

For both miner and market actors

  • WithdrawBalance with an amount that can be withdrawn => the specified amount is returned
  • WithdrawBalance with an amount greater than that which can be withdrawn => the actual amount withdrawn is returned

Security Considerations

This only changes return value behavior so has no security implications.

Incentive Considerations

This only changes return value behavior so has no incentive implications.

Product Considerations

This has a positive product consideration for miners and storage clients. Most existing tools should still work since it is unlikely tools depend on the empty return value of withdraw balance. Tools can be improved and adapted to make use of the return value.


specs-actors PR:

Copyright and related rights waived via CC0.


Please cite this document as:

Steven Li, Zenground0, "FIP-0020: Add Return Value to WithdrawBalance," Filecoin Improvement Proposals, no. 0020, June 2021. [Online serial]. Available: