Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore: docs: add user contract api docs #1210

Open
wants to merge 10 commits into
base: release/v10
Choose a base branch
from
Open

chore: docs: add user contract api docs #1210

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
47f0cea
add user contract api docs.
jennijuju Feb 13, 2023
e1c4edc
remove duplicate name from datacap
longfeiWan9 Feb 13, 2023
bbe5946
add Miner WithdrawBalance missing method num
longfeiWan9 Feb 13, 2023
cc5dcc1
add datacap mint & destroy & Granularity
longfeiWan9 Feb 13, 2023
45c7b88
add hyperlinks to each method in the mega table
longfeiWan9 Feb 13, 2023
e76eb5b
add ethaccount builtIn actor
longfeiWan9 Feb 13, 2023
f5311fe
Merge branch 'release/v10' into jen/apidocs
jennijuju Feb 14, 2023
0634bb3
Merge branch 'release/v10' into jen/apidocs
longfeiWan9 Mar 7, 2023
996ab43
add read only flags
longfeiWan9 Mar 7, 2023
852b3eb
cargo to ignore docs
jennijuju Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ authors = ["Protocol Labs", "Filecoin Core Devs"]
edition = "2021"
repository = "https://github.com/filecoin-project/builtin-actors"
keywords = ["filecoin", "web3", "wasm"]
exclude = ["examples", ".github"]
exclude = ["examples", ".github", "./actors/docs"]

# We don't publish the bundle to crates.io anymore. Instead, we build in CI.
publish = false
Expand Down Expand Up @@ -56,6 +56,10 @@ members = [
"runtime",
"test_vm",
]
exclude = [
"actors/docs",
# Add any other paths to exclude if needed
]

[patch.crates-io]
#fvm_shared = { git = "https://github.com/filecoin-project/ref-fvm", branch = "master" }
Expand Down Expand Up @@ -130,3 +134,4 @@ incremental = false
codegen-units = 1
opt-level = 0
overflow-checks = false

73 changes: 73 additions & 0 deletions actors/docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
## APIs between user programmed actors and built-in actors

[FIP-0050](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0050.md) exports a stable subset of the built-in actor methods, along with some new methods, for invocation around storage, market, miner and etc by user actors.

The method number of the exported methods follows [FRC-0042](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0042.md) and can be called by any type of caller. Read-only method will not modify the state, it is similar as view functions in solidity.

This API docs intend to provide information about how to use those exported APIs in user-defined actors. You can find the docs of the exported APIs and their usage in this folder.


## Exported API list

| actor | method | method number | ReadOnly |
| ---------- | ------------------------------------------------------------ | ------------- | ------------------ |
| account | [AuthenticateMessage](account.md#AuthenticateMessage) | 2643134072 | :heavy_check_mark: |
| datacap | [Name](datacap.md#Name) | 48890204 | :heavy_check_mark: |
| datacap | [Symbol](datacap.md#Symbol) | 2061153854 | :heavy_check_mark: |
| datacap | [Granularity](datacap.md#Granularity) | 3936767397 | :heavy_check_mark: |
| datacap | [TotalSupply](datacap.md#TotalSupply) | 114981429 | :heavy_check_mark: |
| datacap | [Balance](datacap.md#Balance) | 3261979605 | :heavy_check_mark: |
| datacap | [Transfer](datacap.md#Transfer) | 80475954 | |
| datacap | [TransferFrom](datacap.md#TransferFrom) | 3621052141 | |
| datacap | [IncreaseAllowance](datacap.md#IncreaseAllowance) | 1777121560 | |
| datacap | [DecreaseAllowance](datacap.md#DecreaseAllowance) | 1529376545 | |
| datacap | [RevokeAllowance](datacap.md#RevokeAllowance) | 2765635761 | |
| datacap | [Burn](datacap.md#Burn) | 1434719642 | |
| datacap | [BurnFrom](datacap.md#BurnFrom) | 2979674018 | |
| datacap | [Allowance](datacap.md#Allowance) | 4205072950 | :heavy_check_mark: |
| datacap | [Mint](datacap.md#mint) | 116935346 | |
| datacap | [Destroy](datacap.md#Destroy) | 2624896501 | |
| ethaccount | [AuthenticateMessage](ethaccount.md#AuthenticateMessage) | 2643134072 | :heavy_check_mark: |
| evm | InvokeEVM | 3844450837 | |
| market | [AddBalance](market.md#AddBalance) | 822473126 | |
| market | [WithdrawBalance](market.md#WithdrawBalance) | 2280458852 | |
| market | [PublishStorageDeals](market.md#PublishStorageDeals) | 2236929350 | |
| market | [GetBalance](market.md#GetBalance) | 726108461 | :heavy_check_mark: |
| market | [GetDealDataCommitment](market.md#GetDealDataCommitment) | 1157985802 | :heavy_check_mark: |
| market | [GetDealClient](market.md#GetDealClient) | 128053329 | :heavy_check_mark: |
| market | [GetDealProvider](market.md#GetDealProvider) | 935081690 | :heavy_check_mark: |
| market | [GetDealLabel](market.md#GetDealLabel) | 46363526 | :heavy_check_mark: |
| market | [GetDealTerm](market.md#GetDealTerm) | 163777312 | :heavy_check_mark: |
| market | [GetDealTotalPrice](market.md#GetDealTotalPrice) | 4287162428 | :heavy_check_mark: |
| market | [GetDealClientCollateral](market.md#GetDealClientCollateral) | 200567895 | :heavy_check_mark: |
| market | [GetDealProviderCollateral](market.md#GetDealProviderCollateral) | 2986712137 | :heavy_check_mark: |
| market | [GetDealVerified](market.md#GetDealVerified) | 2627389465 | :heavy_check_mark: |
| market | [GetDealActivation](market.md#GetDealActivation) | 2567238399 | :heavy_check_mark: |
| miner | [ChangeWorkerAddress](miner.md#ChangeWorkerAddress) | 1010589339 | |
| miner | [ChangePeerID](miner.md#ChangePeerID) | 1236548004 | |
| miner | [WithdrawBalance](miner.md#WithdrawBalance) | 2280458852 | |
| miner | [ChangeMultiaddrs](miner.md#ChangeMultiaddrs) | 1063480576 | |
| miner | [ConfirmChangeWorkerAddress](miner.md#ConfirmChangeWorkerAddress) | 2354970453 | |
| miner | [RepayDebt](miner.md#RepayDebt) | 3665352697 | |
| miner | [ChangeOwnerAddress](miner.md#ChangeOwnerAddress) | 1010589339 | |
| miner | [ChangeBeneficiary](miner.md#ChangeBeneficiary) | 1570634796 | |
| miner | [GetBeneficiary](miner.md#GetBeneficiary) | 4158972569 | :heavy_check_mark: |
| miner | [GetOwner](miner.md#GetOwner) | 3275365574 | :heavy_check_mark: |
| miner | [IsControllingAddress](miner.md#IsControllingAddress) | 348244887 | :heavy_check_mark: |
| miner | [GetSectorSize](miner.md#GetSectorSize) | 3858292296 | :heavy_check_mark: |
| miner | [GetAvailableBalance](miner.md#GetAvailableBalance) | 4026106874 | :heavy_check_mark: |
| miner | [GetVestingFunds](miner.md#GetVestingFunds) | 1726876304 | :heavy_check_mark: |
| miner | [GetPeerID](miner.md#GetPeerID) | 2812875329 | :heavy_check_mark: |
| miner | [GetMultiaddrs](miner.md#GetMultiaddrs) | 1332909407 | :heavy_check_mark: |
| multisig | [Receive](multisig.md#Receive) | 3726118371 | |
| power | [CreateMiner](power.md#CreateMiner) | 1173380165 | |
| power | [NetworkRawPower](power.md#NetworkRawPower) | 931722534 | :heavy_check_mark: |
| power | [MinerRawPower](power.md#MinerRawPower) | 3753401894 | :heavy_check_mark: |
| power | [MinerCount](power.md#MinerCount) | 3753401894 | :heavy_check_mark: |
| power | [MinerConsensusCount](power.md#MinerConsensusCount) | 196739875 | :heavy_check_mark: |
| verifreg | [AddVerifiedClient](verifreg.md#AddVerifiedClient) | 3916220144 | |
| verifreg | [RemoveExpiredAllocations](verifreg.md#RemoveExpiredAllocations) | 2873373899 | |
| verifreg | [GetClaims](verifreg.md#GetClaims) | 2199871187 | :heavy_check_mark: |
| verifreg | [ExtendClaimTerms](verifreg.md#ExtendClaimTerms) | 1752273514 | |
| verifreg | [RemoveExpiredClaims](verifreg.md#RemoveExpiredClaims) | 2873373899 | |
| verifreg | [Receive](verifreg.md#Receive) | 3726118371 | |
43 changes: 43 additions & 0 deletions actors/docs/account.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# 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**

```go
func AuthenticateMessage(params AuthenticateMessage) EmptyValue ()
```

Authenticates whether the provided signature is valid for the provided message.

`uint` AuthenticateMessageMethodNum = 2643134072.

**Params**:

+ `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**

```go
func AuthenticateMessage(params RawBytes) EmptyValue ()
```

Whenever the account receives transfers, this method will be invoked.

`uint` UniversalReceiverHookMethodNum = 3726118371.

**Params**:

+ `bytes[]` RawBytes - passes the bytes through how it is received.

**Results**:

+ `struct` EmptyValue - always success.
Loading