FIP-0022 Source

TitleBad deals don't fail PublishStorageDeals
Review period ends2021-10-11

Spec Sections

FIP-0022: Bad deals don’t fail PublishStorageDeals

Simple Summary

Change the PublishStorageDeals implementation so that a single bad deal in the parameters does not fail the message and prevent publishing all the valid deals in the parameters. Instead the message will succeed, only publish only the valid deals and include failure information in the return value.


The PublishStorageDeals message drops deals that error and publishes valid ones. To maintain complete information about published deals in the receipt the return value contains a bitfield of the indexes of all validly deals that were published.

Change Motivation

Because to some extent deal errors are unavoidable this issue is frequently brought up by storage providers as a problem. For example filecoin-project/specs-actors#1466. This change will make deal publishing errors less expensive for storage providers and less disruptive for clients.


PublishStorageDeals deal validation, duplicate deal filtering and balance locking errors do not cause message failure but instead these errors are logged and the deal causing the problem is be dropped from the publish set. VerifiedRegistry actor UseBytes calls are now moved before publishing state changes so that these errors can also be logged and deals dropped instead of triggering message failure.

PublishStorageDeals logic is changed to first iterate over deals and apply checks to filter out invalid deals without mutating the market actor state. Only after filtering invalid deals will the method iterate through valid deals and modify state for all valid deals atomically.

The return value of PublishStorageDeals is changed from

PublishStorageDealsReturn struct {
    IDs []abi.DealID


PublishStorageDealsReturn struct {
    IDs []abi.DealID
    Valid bitfield.Bitfield

We use a bitfield to keep the return bytes compact. The bitfield is over the index of the input array of client deal proposals. For example if three client deal proposals are input and the first two are invalid the Valid bitfield will be 001. With this new return format consumers of the PublishStorageDeals receipt can maintain exact information on which proposals are matched to which deal ids. All valid client deal proposals are assigned a deal ID and added in order to the return array.

If all proposals fail validation PublishStorageDeals will return an error. If an ErrIllegalState error or other internal error is encountered PublishStorageDeals will return an error.

Design Rationale

The design of the main error semantics change is trivial given the goal to improve user experience.

The Valid bitfield in the return value is over input index because deal ids are only assigned after publish storage deals runs so an index of deal ids does not work. A bitfield is used to enable return information to be compact. While marking failed deals in the output would also work this proposal chooses valid deals because the valid deal the successes are the most directly relevant to consumers which saves an extra bitfield XOR during processing.

Backwards Compatibility

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

Test Cases

  • No errors and all deals pass Correct return values and successful publishing of valid deals in the precense of the following errors:
  • Deal validation errors
  • Insufficient balance errors
  • VerifiedRegistry UseBytes errors

Security Considerations

There are no security implications.

Incentive Considerations

There are no incentive implications.

Product Considerations

Miners publishing deals will have an improved user experience. Clients and others waiting on and parsing PublishStorageDeals return values will need to update software to use the new error handling semantics. This will require being able to read filecoin RLE+ bitfields which might take some developement work.


specs-actors PR:

Copyright and related rights waived via CC0.


Please cite this document as:

ZenGround0, "FIP-0022: Bad deals don't fail PublishStorageDeals," Filecoin Improvement Proposals, no. 0022, September 2021. [Online serial]. Available: