Filecoin Docs
BasicsStorage providersNodesNetworksSmart contractsReference
Ask or search…
⌃K
Links
Comment on page

Protocol API

This page covers the Built-in actors Protocol API.
The protocol level built-in actors API is split into the following sections:

Account actor

The account actor is responsible for user account. If you want to call these methods in your smart contracts, you need to specify method number of that method you want to invoke. Please refer the each method for its method number.

AuthenticateMessage

func AuthenticateMessage(params AuthenticateMessage) EmptyValue ()
Authenticates whether the provided signature is valid for the provided message.
uint AuthenticateMessageMethodNum = 2643134072.
Parameters:
  • struct AuthenticateMessageParams
    • bytes AuthenticateMessageParamsSignature - it should be a raw byte of signature, NOT a serialized signature object with a signatureType.
    • bytes Message - The message which is signed by the corresponding account address.
Results:
  • struct EmptyValue.

UniversalReceiverHook

func UniversalReceiverHook(params RawBytes) EmptyValue ()
Whenever the account receives transfers, this method will be invoked.
uint UniversalReceiverHookMethodNum = 3726118371.
Parameters:
  • bytes[] RawBytes - passes the bytes through how it is received.
Results:
  • struct EmptyValue - always success.

Datacap

DataCap Actor is responsible for DataCap token management. The ActorCode for DataCap actor is hex"0007" which will be used to call DataCap actor APIs. You also need to specify the method number of which method you want to invoke. Refer to each method for its method number.

Name

func Name() String {}
Return the name of DataCap token which is ‘DataCap’.
Unit NameMethodNum : 48890204.
Parameters:
  • null
Results:
  • String : DataCap

Symbol

func Symbol() String {}
Return the symbol of DataCap token which is ‘DCAP’.
unit SymbolMethodNum: 2061153854.
Parameters:
  • null
Results:
  • String : DCAP

TotalSupply

func TotalSupply() TokenAmount {}
Return the total supply of the DataCap token.
uint TotalSupplyMethodNum: 114981429.
Parameters:
  • null
Results:
  • int256 TokenAmount - Total DataCap token supply.

Balance

func Balance(params Address) TokenAmount {}
Return the DataCap token balance for the wallet address.
unit BalanceOfMethodNum: 3261979605.
Parameters:
  • bytes Address - the wallet address.
Results:
  • int256 TokenAmount - the DataCap token balance for the specified wallet address.

Transfer

func Transfer(params TransferParams) TransferReturn {}
Transfers DataCap tokens from caller address to the to address.
uint TransferMethodNum = 80475954;
Parameters:
  • struct TransferParams
    • bytes To - the address to receive DataCap token.
    • int256 Amount - A non-negative amount to transfer.
    • bytes[] OperatorData - Arbitrary data to pass on via the receiver hook.
Results:
  • struct TransferReturn
    • int256 FromBalance - the balance of from_address.
    • int256 ToBalance - the balance of to_address.
    • bytes RecipientData: data returned from receive hook.

TransferFrom

func TransferFrom(params TransferFromParams) TransferFromReturn {}
Transfers DataCap between the from_address to the to_address.
uint TransferFromMethodNum = 3621052141.
Params:
  • bytes TransferFromParams
    • bytes From - the address to send DataCap Token.
    • bytes To - the address to receive DataCap Token.
    • int256 Amount - A non-negative amount to transfer.
    • bytes OperatorData: Arbitrary data to pass on via the receiver hook.
Results:
  • struct TransferFromReturn
    • int256 FromBalance - the balance of from_address.
    • int256 ToBalance - the balance of to_address.
    • int256 Allowance - the remaining allowance of owner address.
    • bytes RecipientData - data returned from receive hook.

IncreaseAllowance

func IncreaseAllowance(params IncreaseAllowanceParams) TokenAmount {}
Increase the DataCap token allowance that an operator can control by the requested amount.
uint IncreaseAllowanceMethodNum = 1777121560.
Params:
  • struct IncreaseAllowanceParams
    • bytes Operator - the wallet address of the operator.
    • int256 increaseAmount - increase DataCap token allowance for the operator address.
Results:
  • int256 TokenAmount - the new DataCap allowance of the operator address.

DecreaseAllowance

func DecreaseAllowance(params DecreaseAllowanceParams) TokenAmount {}
Decrease the DataCap token allowance that an operator controls of the owner’s balance by the requested amount.
uint DecreaseAllowanceMethodNum = 1529376545;
Params:
  • struct DecreaseAllowanceParams
    • bytes Operator - the wallet address of the operator.
    • int256 IncreaseAmount - the decreased DataCap token allowance of the operator address.
Results:
  • int256 TokenAmount - the new DataCap allowance of the operator address.

RevokeAllowance

func RevokeAllowance(params RevokeAllowanceParams) TokenAmount {}
Revoke the DataCap token allowance from the operator and set the operator’s allowance in behave of owner/caller address to 0.
uint RevokeAllowanceMethodNum = 2765635761.
Params:
  • struct RevokeAllowanceParams
    • bytes Operator - the wallet address of the operator.
Results:
  • int256 TokenAmount - the old Allowance amount of the operator address.

Burn

func Burn(params BurnParams) TokenAmount {}
Burn an amount of DataCap token from the owner/caller address, decreasing total token supply.
uint BurnMethodNum = 1434719642.
Params:
  • struct BurnParams
    • int256 Amount - the amount the DataCap token to be burned.
Results:
  • int256 TokenAmount - the updated DataCap token balance of the owner/caller address.

BurnFrom

func BurnFrom(params BurnFromParams) BurnFromReturn {}
Burn an amount of DataCap token from the specified address (owner address), decrease the allowance of operator/caller, and decrease total token supply.
uint BurnFromMethodNum = 2979674018.
Params:
  • struct BurnFromParams
    • bytes Owner - the wallet address of the owner.
    • int256 Amount - the amount of DataCap token to be burned.
Results:
  • struct BurnFromReturn
    • bytes Owner - the wallet address of the owner.
    • int256 Amount - the new balance of owner wallet.

Allowance

func Allowance(params GetAllowanceParams) TokenAmount {}
Return the allowance between owner and operator address.
uint AllowanceMethodNum = 4205072950;
Params:
  • struct GetAllowanceParams
    • bytes Owner : the wallet address of the owner.
    • bytes Operator : the wallet address of the owner.
Results:
  • int256 TokenAmount - the allowance that an operator can control of an owner’s allowance.

Miner

The miner built-in actor responsible to deal with storage mining operations and collect proof. To interact with a specific storage provider, you must use their miner address to invoke the methods in the built-in miner actor. You also need to specify the method number for the method you want to invoke. Please refer to each method for its method number.

GetPeerID

func GetPeerID() GetPeerIDReturn {}
Return the Peer ID for the caller/miner address.
uint GetPeerIDMethodNum = 2812875329.
Params:
  • null
Results:
  • struct GetPeerIDReturn
    • bytes PeerID - the peer ID for the specified storage provider/miner.

ChangePeerID

func ChangePeerID(params ChangePeerIDParams) EmptyValue {}
Change the peer ID for the caller/miner address.
uint ChangePeerIDMethodNum = 1236548004.
Params:
  • struct ChangePeerIDParams
    • bytes NewID - the new peer ID.
Results:
  • struct EmptyValue

GetMultiaddrs

func GetMultiaddrs() GetMultiAddrsReturn {}
Returns the multi-signature address for this caller/miner address.
uint GetMultiaddrsMethodNum = 1332909407.
Params:
  • null
Results:
  • struct GetMultiAddrsReturn
    • byte[] MultiAddrs - the multi-signature address.

ChangeMultiaddrs

func ChangeMultiaddrs(params ChangeMultiaddrsParams) EmptyValue {}
Change the multi-signature address for this caller/miner address.
uint ChangeMultiaddrsMethodNum = 1063480576.
Params:
  • struct ChangeMultiaddrsParams
    • byte[] NewMultiaddrs - the new multi-signature address.
Results:
  • struct EmptyValue

ChangeWorkerAddress

func ChangeWorkerAddress(params ChangeWorkerAddressParams) EmptyValue {}
Change the worker address for the caller/miner address, and overwrite the existing addresses with the new control addresses passed in the params.
uint ChangeOwnerAddressMethodNum = 1010589339.
Params:
  • struct ChangeWorkerAddressParams
    • byte NewWorker - the new worker address.
    • byte[] NewControlAddrs - the new controller addresses.
Results:
  • struct EmptyValue

ConfirmChangeWorkerAddress

func ConfirmChangeWorkerAddress() EmptyValue {}
Confirm the worker address has been changed for the caller/miner address.
uint ConfirmChangeWorkerAddressMethodNum = 2354970453.
Params:
  • null
Results:
  • struct EmptyValue

RepayDebt

func RepayDebt() EmptyValue {}
Repay as much fee debt as possible for the caller/miner address.
uint RepayDebtMethodNum = 3665352697.
Params:
  • null
Results:
  • struct EmptyValue

GetOwner

func GetOwner() GetOwnerReturn {}
Return the owner address of the caller/miner address.
uint GetOwnerMethodNum = 3275365574.
Params:
  • null
Results:
  • struct GetOwnerReturn
    • byte Owner - owner address.

ChangeOwnerAddress

func ChangeOwnerAddress(bytes address) {}
Proposes or confirms a change of owner address.
uint ChangeOwnerAddressMethodNum = 1010589339.
Params:
  • bytes Address - the new owner address.
Results:
  • struct EmptyValue

GetBeneficiary

func GetBeneficiary() GetBeneficiaryReturn {}
Return the currently active and proposed beneficiary information.
uint GetBeneficiaryMethodNum = 4158972569.
Params:
  • null
Results:
  • struct GetBeneficiaryReturn
    • struct ActiveBeneficiary - current active beneficiary.
      • byte Beneficiary - the address of the beneficiary.
      • struct BeneficiaryTerm
        • int256 Quota - the quota token amount.
        • int256 UsedQuota - the used quota token amount.
        • uint64 Expiration - the epoch that the quota will be expired.
    • struct PendingBeneficiaryChange - the proposed and pending beneficiary.
      • bytes newBeneficiary - the new beneficiary address.
      • int256 NewQuota - the new quota token amount.
      • uint64 NewExpiration - the epoch that the new quota will be expired.
      • bool ApprovedByBeneficiary - if this proposal is approved by the beneficiary or not.
      • bool ApprovedByNominee - if this proposal is approved by the nominee or not.

ChangeBeneficiary

func ChangeBeneficiary(params ChangeBeneficiaryParams) EmptyValue {}
Propose or confirm a change of beneficiary information.
uint ChangeBeneficiaryMethodNum = 1570634796.
Params:
  • struct ChangeBeneficiaryParams
    • bytes newBeneficiary - the new beneficiary address.
    • int256 NewQuota - the new quota token amount.
    • uint64 NewExpiration - the epoch that the new quota will be expired.
Results:
  • struct EmptyValue

IsControllingAddress

func IsControllingAddress(params IsControllingAddressParams) IsControllingAddressReturn {}
Returns whether the provided address is the Owner, the Worker, or any of the control addresses.
uint IsControllingAddressMethodNum = 348244887.
Params:
  • byte IsControllingAddressParams - the address to be verified.
Results:
  • bool IsControllingAddressReturn - if the specified address is the control address.

GetSectorSize

func GetSectorSize() GetSectorSizeReturn {}
Returns the miner’s sector size.
uint GetSectorSizeMethodNum = 3858292296;
Params:
  • null
Results:
  • struct GetSectorSizeReturn
    • unit64 SectorSize - the sector size of this miner.

GetAvailableBalance

func GetAvailableBalance() GetAvailableBalanceReturn {}
Returns the available balance of this miner.
uint GetAvailableBalanceMethodNum = 4026106874.
Params:
  • null
Results:
  • int256 GetAvailableBalanceReturn - the available token balance amount.

WithdrawBalance

func WithdrawBalance(params WithdrawBalanceParams) WithdrawBalanceReturn {}
Withdraw the token balance for this miner.
Params:
  • struct WithdrawBalanceParams
    • int256 AmountRequested - withdraw token amount.
Results:
  • int256 WithdrawBalanceReturn - the token amount withdrawn.

GetVestingFunds

func GetVestingFunds() GetVestingFundsReturn {}
Return the funds vesting in this miner as a list of (vesting_epoch, vesting_amount) tuples.
uint GetVestingFundsMethodNum = 1726876304.
Params:
  • null
Results:
  • struct GetVestingFundsReturn
    • struct VestingFunds[] Funds
      • int64 Epoch - the epoch of funds vested.
      • int256 Amount - the number of funds vested.

Multisig

Multisig built-in actor is responsible for dealing with operations involving the Filecoin wallet. To interact with a specific multi-signature wallet address, you need to use this wallet address to invoke the methods in the built-in multisig actor. You also need to specify the method number of which method you want to invoke. Please refer to each method for its method number.

Propose

func Propose(params ProposeParams) ProposeReturn {...}
Propose a token transfer transaction for signers to approve. The proposer automatically approves this transaction.
uint ProposeMethodNum = 1696838335.
Params:
  • struct ProposeParams
    • bytes ToAddress - the address to receive the token.
    • int256 Value - the token amount to be transferred.
    • uint64 Method: ?
    • bytep[] Params: ?
Results:
  • struct ProposeReturn
    • int64 TxnID - the ID of the proposed transaction.
    • bool Applied - if the transaction was applied as proposed or not?
    • uint31 Code - the exit code of the transaction. If Applied is false this field can be ignored.
    • bytes Ret - the return value of the transaction. If Applied is false this field can be ignored.

Approve

func Approve(params TxnIDParams) ApproveReturn {}
Other signers of the multi-signature address can use this method to approve the proposed messages.
uint ApproveMethodNum = 1289044053.
Params:
  • struct TxnIDParams
    • int64 ID - the signed message ID.
    • bytes ProposalHash - Hash of proposal to ensure an operation can only apply to a specific proposal.
Results:
  • struct ApproveReturn
    • bool Applied - if the transaction was applied as proposed or not?
    • uint31 Code - the exit code of the transaction. If Applied is false this field can be ignored.
    • bytes Ret - the return value of the transaction. If Applied is false this field can be ignored.

Cancel

func Cancel(param TxnIDParams) EmptyValue {}
Multi-signature wallet signer to cancel a pending multi-signatures transaction.
uint CancelMethodNum = 3365893656.
Params:
  • struct TxnIDParams
    • int64 ID - the signed message ID.
    • bytes ProposalHash - Hash of proposal to ensure an operation can only apply to a specific proposal.
Results:
  • struct EmptyValue.

AddSigner

func AddSigner(params AddSignerParams) EmptyValue {}
Add a signer to the multi-signature wallet.
uint AddSignerMethodNum = 3028530033.
Params:
  • struct AddSignerParams
    • bytes Signer - the new signer address.
    • bool Increase - increase threshold or not.
Results:
  • struct EmptyValue.

RemoveSigner

func RemoveSigner(params RemoveSignerParams) EmptyValue {}
Remove a signer from the multi-signature wallet.
uint RemoveSignerMethodNum = 21182899.
Params:
  • struct RemoveSignerParams
    • bytes Signer - the signer address to be removed.
    • bool Decrease - decrease threshold or not. Only able to decrease when the threshold is larger than 2.
Results:
  • struct EmptyValue.

SwapSigner

func SwapSigner(params SwapSignerParams) EmptyValue {}
Swap signers for the multi-signature wallet.
uint SwapSignerMethodNum = 3968117037;
Params:
  • struct SwapSignerParams
    • bytes From - the signer address to be removed from the multi-signature wallet.
    • bytes To - the signer address to be added to the multi-signature wallet.
Results:
  • struct EmptyValue.

ChangeNumApprovalsThreshold

func ChangeNumApprovalsThreshold(params ChangeNumApprovalsThresholdParams) EmptyValue {}
Change the threshold number required for the approvals for the multi-signature wallet.
uint ChangeNumApprovalsThresholdMethodNum = 3375931653.
Params:
  • struct ChangeNumApprovalsThresholdParams
    • unit64 NewThreshold - the new threshold number.
Results:
  • struct EmptyValue.

LockBalance

func LockBalance(params LockBalanceParams) EmptyValue {}
Lock a number of tokens in a multi-signature wallet from the start epoch to the unlock epoch.
uint LockBalanceMethodNum = 1999470977.
Params:
  • struct LockBalanceParams
    • int64 StartEpoch - the epoch to start locking the balance.
    • int64 UnlockDuration - the epoch to unlock the balance.
    • int256 Amount - the amount of token to be locked.
Results:
  • struct EmptyValue.

Storage market actor

Storage market actor is responsible for managing storage and retrieval deals. The ActorCode for storage market actor is hex"0005" which will be used to call this actor. You also need to specify the method number of the method you want to invoke. Please refer to each method for its method number.

AddBalance

func AddBalance(address Address) EmptyValue {}
Deposit the received FIL token, which is received along with this message, into the balance held in the escrow address of the provider or client address.
uint AddBalanceMethodNum = 822473126.
Params:
  • bytes Address - the address of the provider or client.
Results:
  • struct EmptyValue.

GetBalance

func GetBalance(address Address) GetBalanceReturn {}
Return the escrow balance and locked amount for an address.
uint GetBalanceMethodNum = 726108461.
Params:
  • bytes address - the wallet address to request balance.
Results:
  • struct GetBalanceReturn
    • int256 Balance - the escrow balance for this address.
    • int256 Locked - the escrow-locked amount for this address.

WithdrawBalance

func WithdrawBalance(params WithdrawBalanceParams) WithdrawBalanceReturn {}
Withdraw the specified amount from the balance held in escrow.
uint WithdrawBalanceMethodNum = 2280458852.
Params:
  • struct WithdrawBalanceParams
    • bytes ProviderOrClientAddress - the address of the provider or client.
    • int256 TokenAmount - the token amount to withdraw.
Results:
  • struct WithdrawBalanceReturn
    • int256 AmountWithdraw - the token amount withdrawn.

PublishStorageDeals

func PublishStorageDeals(params PublishStorageDealsParams) PublishStorageDealsReturn {}
Publish a new set of storage deals that are not yet included in a sector.
uint PublishStorageDealsMethodNum = 2236929350.
Params:
  • struct PublishStorageDealsParams
    • struct ClientDealProposal[] Deals - list of deal proposals signed by a client
      • struct DealProposal Proposal
        • bytes PieceCID.
        • uint64 PieceSize - the size of the piece.
        • bool VerifiedDeal - if the deal is verified or not.
        • bytes Client - the address of the storage client.
        • bytes Provider - the address of the storage provider.
        • string Label - any label that the client chooses for the deal.
        • int64 StartEpoch - the chain epoch to start the deal.
        • int64 EndEpoch - the chain epoch to end the deal.
        • int256 StoragePricePerEpoch - the token amount to pay to the provider per epoch.
        • int256 ProviderCollateral - the token amount as collateral paid by the provider.
        • int256 ClientCollateral - the token amount as collateral paid by the client.
      • bytes ClientSignature - the signature signed by the client.
Results:
  • struct PublishStorageDealsReturn
    • uint64[] IDs - returned storage deal IDs.
    • bytes ValidDeals - represent all the valid deals.

GetDealDataCommitment

func GetDealDataCommitment(params GetDealDataCommitmentParams) GetDealDataCommitmentReturn {}
Return the data commitment and size of a deal proposal.
uint GetDealDataCommitmentMethodNum = 1157985802.
Params:
  • uint64 GetDealDataCommitmentParams - Deal ID.
Results:
  • struct GetDealDataCommitmentReturn
    • bytes Data - the data commitment of this deal.
    • uint64 Size - the size of this deal.

GetDealClient

func GetDealClient(params GetDealClientParams) GetDealClientReturn {}
Return the client of the deal proposal.
uint GetDealClientMethodNum = 128053329.