Skip to content

Latest commit

 

History

History
69 lines (53 loc) · 6.72 KB

fip-0020.md

File metadata and controls

69 lines (53 loc) · 6.72 KB
Raw
fip title author discussions-to status type category created review-period-end spec-sections
0020
Add Return Value to WithdrawBalance
Steven Li (@steven004), Zenground0 (@Zenground0)
Final
Technical Core
Core
2021-06-06
2021-10-11
specs-actors

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

Abstract

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.

Specification

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.

Implementation

specs-actors PR: filecoin-project/specs-actors#1476

Copyright

Copyright and related rights waived via CC0.