Skip to content

Latest commit

 

History

History
262 lines (193 loc) · 16.4 KB

fip-0050.md

File metadata and controls

262 lines (193 loc) · 16.4 KB
Raw
fip title author discussions-to status type category (*only required for Standard Track) created
0050
API between user-programmed actors and built-in actors
Alex North (@anorth), Aayush Rajasekaran (@arajasek)
Final
<Technical (Core)>
<Core>
<2022-12-05>

FIP-0050: API between user-programmed actors and built-in actors

Simple Summary

Restrict invocation of all existing built-in actors methods to built-in actors. Re-export a stable subset of those methods, along with some new methods, for invocation by user actors.

Abstract

Built-in actors, the set of "protocol actors", have existed since the inception of the network. As the Filecoin protocol has been improved, they have repeatedly been changed, including having old functionality removed, and having interfaces modified.

User-programmed actors, or so-called "smart contracts", will start being deployed with the launch of the FEVM. These actors cannot easily (or ever) be upgraded, and will want to rely on the interfaces of the built-in actors for information about the Filecoin blockchain. This leads to a conflict of interests -- aspects of the built-in actors must continue to be updated (in order to improve the protocol), but none of the interfaces exposed to user-programmed actors can ever change (because that would "break" user-programmed actors relying on those interfaces).

This FIP proposes a way to balance these conflicting interests by only allowing a stable subset of the built-in actors interfaces to be exposed to user-programmed actors. The restriction is implemented based on method numbers derived from the calling convention in FRC-0042. All existing methods are restricted by default, with some explicitly re-exported for invocation by user actors.

Change Motivation

User-programmed actors on the FVM will want to interact with the built-in actors, especially those related to storage. The built-in actors were not designed with calls from user actors in mind, so do not present a good interface to them.

In the past, we have been able to alter the APIs presented by the built-in actors because callers were either other built in actors (which we could atomically upgrade) or off-chain parties (who can change their code). User-programmed actors will be a new class of caller which will generally be unable or unwilling to upgrade to new APIs. This means that if we ever change a built-in actor method that a user actor depends on, we would break that actor. Network stakeholders will likely be extremely reluctant to break existing actors, with the implication that built-in actor methods reachable by user-programmed actors are effectively permanent.

Indefinite compatibility requirements on a legacy or poorly-conceived interface could present a very significant restriction on future improvements to Filecoin’s protocol and capabilities.

Specification

There are two chief aspects to the proposed changes:

  • Restricting all existing methods to being "internal" to other built-in actors
  • Exporting a new list of new methods in a "public" API that can be called by user actors

In order to implement these changes, we continue the use of the calling convention developed in FRC-0042. This FRC provides a convention for converting method names to method numbers. The convention never produces a method number lower than 2^24, which provides us a range for the internal method numbers.

Restricted internal API

The currently implemented API of all built-in actors is restricted to reject calls from any caller that isn't a built-in actor. We perform this check by looking up the code ID of the calling actor, and only proceeding if the caller is a non-EVM built-in actor. These interfaces can then be relatively easily changed in the future as needed. The restriction is uniformly applied to all existing actors today. When a method is invoked, we check whether the method number is:

  • Greater than or equal to 2^24: If so, the method is presumed "exported", and are callable, regardless of the type of caller
  • Less than 2^24: If so, we lookup the code CID of the caller, which is exposed through the runtime. If the caller has one of the CIDs of the built-in actors, the invocation continues; if not, the call is rejected.

New public API

We add a series of methods to the suite of built-in actors. These methods are exported using FRC-0042, and can be called by any type of caller. Some of these methods are explicitly exported duplicates of existing methods, while others are newly added. The full listed of exported methods, broken down by actor is:

Account Actor

  • AuthenticateMessage
  • UniversalReceiverHook (already exported)

Cron Actor

No methods are exported for the Cron actor.

Datacap Actor

  • Mint
  • Destroy
  • Name
  • Symbol
  • TotalSupply
  • Balance (renamed from BalanceOf to be inline with FRC-0046)
  • Transfer
  • TransferFrom
  • IncreaseAllowance
  • DecreaseAllowance
  • RevokeAllowance
  • Burn
  • BurnFrom
  • Allowance
  • Granularity (New): Returns the granularity of the Datacap Token

Init Actor

  • No methods are exported for the Init Actor

Storage Market Actor

  • AddBalance
  • WithdrawBalance
  • PublishStorageDeals
  • GetBalance (New): Returns the escrow balance and locked amount for an address.
  • GetDealDataCommitment (New): Returns the data commitment and size of a deal proposal.
  • GetDealClient (New): Returns the client of a deal proposal.
  • GetDealProvider (New): Returns the provider of a deal proposal.
  • GetDealLabel (New): Returns the label of a deal proposal.
  • GetDealTerm (New): Returns the start epoch and duration (in epochs) of a deal proposal.
  • GetDealTotalPrice (New): Returns the total price that will be paid from the client to the provider for this deal.
  • GetDealClientCollateral (New): Returns the client collateral requirement for a deal proposal.
  • GetDealProviderCollateral (New): Returns the provider collateral requirement for a deal proposal.
  • GetDealVerified (New): Returns the verified flag for a deal proposal.
  • GetDealActivation (New): Fetches activation state for a deal.

Miner Actor

  • ChangeWorkerAddress
  • ChangePeerID
  • WithdrawBalance
  • ChangeMultiaddrs
  • ConfirmChangeWorkerAddress
  • RepayDebt
  • ChangeOwnerAddress
  • ChangeBeneficiary
  • GetBeneficiary
  • GetOwner (New): Returns the owner address.
  • IsControllingAddress (New): Returns whether the provided address is the Owner, the Worker, or any of the Control Addresses.
  • GetSectorSize (New): Returns the miner's sector size.
  • GetAvailableBalance (New): Returns the available balance of this miner.
  • GetVestingFunds (New): Returns the funds vesting in this miner as a list of (vesting_epoch, vesting_amount) tuples.
  • GetPeerID (New): Returns the Peer ID for this miner.
  • GetMultiaddrs (New): Returns the multiaddresses set for this miner.

Multisig Actor

No methods are exported for the Multisig actor, besides the UniversalReceiverHook (which was already exported).

Payment Channel Actor

No methods are exported for the Payment Channel actor.

Storage Power Actor

  • CreateMiner
  • NetworkRawPower (New): Returns the total raw power of the network.
  • MinerRawPower (New): Returns the raw power claimed by the specified miner, and whether the miner has more than the consensus minimum amount of storage active.
  • MinerCount (New): Returns the total number of miners created, regardless of whether or not they have any pledged storage.
  • MinerConsensusCount (New): Returns the total number of miners that have more than the consensus minimum amount of storage active.

Reward Actor

No methods are exported for the Reward actor.

System Actor

No methods are exported for the System actor.

Verified Registry Actor

  • AddVerifiedClient
  • RemoveExpiredAllocations
  • GetClaims
  • ExtendClaimTerms
  • RemoveExpiredClaims
  • Receive

Other Changes

We propose making some minor changes to built-in actor functionality that align with the principles of this FIP.

Change to FIP-0044:

We make the following changes related to the Account Actor's AuthenticateMessage method:

  • Market actor: Update PublishStorageDeals to use the exported AuthenticateMessage method instead

  • Payment Channel & Verifed Registry actors: Replace calls to the Runtime's verify_signature method with calls to AuthenticateMessage instead

  • All callers: Call AuthenticateMessage in read-only mode (introduced in FIP-0055)

  • Where methods have been duplicated, built-in actors start calling the exported methods where possible. The affected methods are:

    • AccountActor::AuthenticateMessage
    • DatacapActor::Mint
    • DatacapActor::Destroy
    • DatacapActor::BalanceOf (renamed to DatacapActor::Balance, to be in line with FRC-0046)
    • MarketActor::PublishStorageDeals

  • Where methods have been duplicated and have no real-world callers today, we deprecate the old method. The deprecated methods are:

    • AccountActor::AuthenticateMessage
    • DatacapActor::Mint
    • DatacapActor::Destroy
    • DatacapActor::Name
    • DatacapActor::Symbol
    • DatacapActor::TotalSupply
    • DatacapActor::BalanceOf
    • DatacapActor::Transfer
    • DatacapActor::TransferFrom
    • DatacapActor::IncreaseAllowance
    • DatacapActor::DecreaseAllowance
    • DatacapActor::Burn
    • DatacapActor::BurnFrom
    • DatacapActor::Allowance

  • Drop checks that the following entities are "signable" (currently defined as either an Account or a Multisig):

    • Callers of Market::AddBalance and Market::PublishStorageDeals
    • Owner addresses and Control addresses of Storage Miners
    • Callers of Miner::DisputeWindowedPost and Miner::ReportConsensusFault
    • Callers of Multisig::Propose, Multisig::Approve, and Multisig::Cancel
    • Callers of Power::CreateMiner

  • Modify MarketActor::PublishStorageDeals to call out to exported method MarketNotifyDeal for all deal clients

    • Parameters are deal ID and serialized proposal
    • Any failures calling MarketNotifyDeal cause the entire PublishStorageDeals message to fail

Design Rationale

The chief principle behind the design is to thoughtfully create a public API that exposes useful information & functionality to user actors, without locking in any interfaces that we consider unstable. Restricting the entirety of the existing suite of methods ensures we aren't exporting any methods without conscious thought.

Where possible, interfaces are described in terms of concepts instead of concrete details (eg. IsControllingAddress instead of GetControlAddresses). Some functionality that was previously callable by accounts & multisigs is extended to user actors, but much of this functionality is still restricted. As an example, none of the Miner Actor's interfaces that involve the current sector addressing scheme are exposed. We may re-evaluate this decision in the face of pressing user needs, but for now we are choosing not to allow (for example) a user actor to ProveCommit a sector.

The current listed of exported methods is intended to be a starting point, and is not "complete" in any sense. We will likely have similar FIPs in the future that export new pieces of information and functionality to user actors.

Backwards Compatibility

This FIP introduces several actors changes, and therefore needs a new actors version shipped in a network upgrade. No existing functionality is broken, however.

Test Cases

  • All existing methods are correctly restricted
  • User actors can call all exported methods
  • Newly introduced methods are correct

Security Considerations

This is not a particularly security-sensitive FIP. No new functionality is being introduced that can be used to attack the network, and bugs in the implementation will only lead to incorrect behaviour being observed by user actors.

Incentive Considerations

None.

Product Considerations

This FIP is intended to expose core information and functionality to user-defined actors. In doing so, it is hoped that this FIP will support the development of novel actors that interact with Filecoin's storage mechanics and unlock new use cases.

Implementation

The implementation may be found in the integration/builtin-api branch of the built-in actors repository.

Copyright

Copyright and related rights waived via CC0.