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:
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.
func AuthenticateMessage(params AuthenticateMessage) EmptyValue ()
Authenticates whether the provided signature is valid for the provided message.
uint
AuthenticateMessageMethodNum = 2643134072.Parameters:
struct
AuthenticateMessageParamsbytes
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.
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 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.func Name() String {}
Return the name of DataCap token which is ‘DataCap’.
Unit
NameMethodNum : 48890204.Parameters:
- null
Results:
String
: DataCap
func Symbol() String {}
Return the symbol of DataCap token which is ‘DCAP’.
unit
SymbolMethodNum: 2061153854.Parameters:
- null
Results:
String
: DCAP
func TotalSupply() TokenAmount {}
Return the total supply of the DataCap token.
uint
TotalSupplyMethodNum: 114981429.Parameters:
- null
Results:
int256
TokenAmount - Total DataCap token supply.
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.
func Transfer(params TransferParams) TransferReturn {}
Transfers DataCap tokens from caller address to the to address.
uint
TransferMethodNum = 80475954;Parameters:
struct
TransferParamsbytes
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
TransferReturnint256
FromBalance - the balance of from_address.int256
ToBalance - the balance of to_address.bytes
RecipientData: data returned from receive hook.
func TransferFrom(params TransferFromParams) TransferFromReturn {}
Transfers DataCap between the from_address to the to_address.
uint
TransferFromMethodNum = 3621052141.Params:
bytes
TransferFromParamsbytes
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
TransferFromReturnint256
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.
func IncreaseAllowance(params IncreaseAllowanceParams) TokenAmount {}
Increase the DataCap token allowance that an operator can control by the requested amount.
uint
IncreaseAllowanceMethodNum = 1777121560.Params:
struct
IncreaseAllowanceParamsbytes
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.
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
DecreaseAllowanceParamsbytes
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.
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
RevokeAllowanceParamsbytes
Operator - the wallet address of the operator.
Results:
int256
TokenAmount - the old Allowance amount of the operator address.
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
BurnParamsint256
Amount - the amount the DataCap token to be burned.
Results:
int256
TokenAmount - the updated DataCap token balance of the owner/caller address.
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
BurnFromParamsbytes
Owner - the wallet address of the owner.int256
Amount - the amount of DataCap token to be burned.
Results:
struct
BurnFromReturnbytes
Owner - the wallet address of the owner.int256
Amount - the new balance of owner wallet.
func Allowance(params GetAllowanceParams) TokenAmount {}
Return the allowance between owner and operator address.
uint
AllowanceMethodNum = 4205072950;Params:
struct
GetAllowanceParamsbytes
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.
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.
func GetPeerID() GetPeerIDReturn {}
Return the Peer ID for the caller/miner address.
uint
GetPeerIDMethodNum = 2812875329.Params:
- null
Results:
struct
GetPeerIDReturnbytes
PeerID - the peer ID for the specified storage provider/miner.
func ChangePeerID(params ChangePeerIDParams) EmptyValue {}
Change the peer ID for the caller/miner address.
uint
ChangePeerIDMethodNum = 1236548004.Params:
struct
ChangePeerIDParamsbytes
NewID - the new peer ID.
Results:
struct
EmptyValue
func GetMultiaddrs() GetMultiAddrsReturn {}
Returns the multi-signature address for this caller/miner address.
uint
GetMultiaddrsMethodNum = 1332909407.Params:
- null
Results:
struct
GetMultiAddrsReturnbyte[]
MultiAddrs - the multi-signature address.
func ChangeMultiaddrs(params ChangeMultiaddrsParams) EmptyValue {}
Change the multi-signature address for this caller/miner address.
uint
ChangeMultiaddrsMethodNum = 1063480576.Params:
struct
ChangeMultiaddrsParamsbyte[]
NewMultiaddrs - the new multi-signature address.
Results:
struct
EmptyValue
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
ChangeWorkerAddressParamsbyte
NewWorker - the new worker address.byte[]
NewControlAddrs - the new controller addresses.
Results:
struct
EmptyValue
func ConfirmChangeWorkerAddress() EmptyValue {}
Confirm the worker address has been changed for the caller/miner address.
uint
ConfirmChangeWorkerAddressMethodNum = 2354970453.Params:
- null
Results:
struct
EmptyValue
func RepayDebt() EmptyValue {}
Repay as much fee debt as possible for the caller/miner address.
uint
RepayDebtMethodNum = 3665352697.Params:
- null
Results:
struct
EmptyValue
func GetOwner() GetOwnerReturn {}
Return the owner address of the caller/miner address.
uint
GetOwnerMethodNum = 3275365574.Params:
- null
Results:
struct
GetOwnerReturnbyte
Owner - owner address.
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
func GetBeneficiary() GetBeneficiaryReturn {}
Return the currently active and proposed beneficiary information.
uint
GetBeneficiaryMethodNum = 4158972569.Params:
- null
Results:
struct
GetBeneficiaryReturnstruct
ActiveBeneficiary - current active beneficiary.byte
Beneficiary - the address of the beneficiary.struct
BeneficiaryTermint256
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.
func ChangeBeneficiary(params ChangeBeneficiaryParams) EmptyValue {}
Propose or confirm a change of beneficiary information.
uint
ChangeBeneficiaryMethodNum = 1570634796.Params:
struct
ChangeBeneficiaryParamsbytes
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
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.
func GetSectorSize() GetSectorSizeReturn {}
Returns the miner’s sector size.
uint
GetSectorSizeMethodNum = 3858292296;Params:
- null
Results:
struct
GetSectorSizeReturnunit64
SectorSize - the sector size of this miner.
func GetAvailableBalance() GetAvailableBalanceReturn {}
Returns the available balance of this miner.
uint
GetAvailableBalanceMethodNum = 4026106874.Params:
- null
Results:
int256
GetAvailableBalanceReturn - the available token balance amount.
func WithdrawBalance(params WithdrawBalanceParams) WithdrawBalanceReturn {}
Withdraw the token balance for this miner.
Params:
struct
WithdrawBalanceParamsint256
AmountRequested - withdraw token amount.
Results:
int256
WithdrawBalanceReturn - the token amount withdrawn.
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
GetVestingFundsReturnstruct VestingFunds[]
Fundsint64
Epoch - the epoch of funds vested.int256
Amount - the number of funds vested.
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.
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
ProposeParamsbytes
ToAddress - the address to receive the token.int256
Value - the token amount to be transferred.uint64
Method: ?bytep[]
Params: ?
Results:
struct
ProposeReturnint64
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. IfApplied
isfalse
this field can be ignored.bytes
Ret - the return value of the transaction. IfApplied
isfalse
this field can be ignored.
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
TxnIDParamsint64
ID - the signed message ID.bytes
ProposalHash - Hash of proposal to ensure an operation can only apply to a specific proposal.
Results:
struct
ApproveReturnbool
Applied - if the transaction was applied as proposed or not?uint31
Code - the exit code of the transaction. IfApplied
isfalse
this field can be ignored.bytes
Ret - the return value of the transaction. IfApplied
isfalse
this field can be ignored.
func Cancel(param TxnIDParams) EmptyValue {}
Multi-signature wallet signer to cancel a pending multi-signatures transaction.
uint
CancelMethodNum = 3365893656.Params:
struct
TxnIDParamsint64
ID - the signed message ID.bytes
ProposalHash - Hash of proposal to ensure an operation can only apply to a specific proposal.
Results:
struct
EmptyValue.
func AddSigner(params AddSignerParams) EmptyValue {}
Add a signer to the multi-signature wallet.
uint
AddSignerMethodNum = 3028530033.Params:
struct
AddSignerParamsbytes
Signer - the new signer address.bool
Increase - increase threshold or not.
Results:
struct
EmptyValue.
func RemoveSigner(params RemoveSignerParams) EmptyValue {}
Remove a signer from the multi-signature wallet.
uint
RemoveSignerMethodNum = 21182899.Params:
struct
RemoveSignerParamsbytes
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.
func SwapSigner(params SwapSignerParams) EmptyValue {}
Swap signers for the multi-signature wallet.
uint
SwapSignerMethodNum = 3968117037;Params:
struct
SwapSignerParamsbytes
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.
func ChangeNumApprovalsThreshold(params ChangeNumApprovalsThresholdParams) EmptyValue {}
Change the threshold number required for the approvals for the multi-signature wallet.
uint
ChangeNumApprovalsThresholdMethodNum = 3375931653.Params:
struct
ChangeNumApprovalsThresholdParamsunit64
NewThreshold - the new threshold number.
Results:
struct
EmptyValue.
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
LockBalanceParamsint64
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 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.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.
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
GetBalanceReturnint256
Balance - the escrow balance for this address.int256
Locked - the escrow-locked amount for this address.
func WithdrawBalance(params WithdrawBalanceParams) WithdrawBalanceReturn {}
Withdraw the specified amount from the balance held in escrow.
uint
WithdrawBalanceMethodNum = 2280458852.Params:
struct
WithdrawBalanceParamsbytes
ProviderOrClientAddress - the address of the provider or client.int256
TokenAmount - the token amount to withdraw.
Results:
struct
WithdrawBalanceReturnint256
AmountWithdraw - the token amount withdrawn.
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
PublishStorageDealsParamsstruct ClientDealProposal[]
Deals - list of deal proposals signed by a clientstruct DealProposal
Proposalbytes
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
PublishStorageDealsReturnuint64[]
IDs - returned storage deal IDs.bytes
ValidDeals - represent all the valid deals.
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
GetDealDataCommitmentReturnbytes
Data - the data commitment of this deal.uint64
Size - the size of this deal.
func GetDealClient(params GetDealClientParams) GetDealClientReturn {}
Return the client of the deal proposal.
uint
GetDealClientMethodNum = 128053329.