diff --git a/docs/References/Smart Contract API/Association Contract.md b/docs/References/Smart Contract API/Association Contract.md new file mode 100644 index 0000000..da36d44 --- /dev/null +++ b/docs/References/Smart Contract API/Association Contract.md @@ -0,0 +1,416 @@ +# AElf.Contracts.Association + +**Association contract.** + +Organizations established to achieve specific goals can use this contract to cooperatively handle transactions within the organization. + +Implements AElf Standards ACS1 and ACS3. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------ | +| **CreateOrganization** | [`Association.CreateOrganizationInput`](#Association.CreateOrganizationInput) | [`aelf.Address`](#aelf.Address) | Create an organization and return its address. | +| **CreateOrganizationBySystemContract** | [`Association.CreateOrganizationBySystemContractInput`](#Association.CreateOrganizationBySystemContractInput) | [`aelf.Address`](#aelf.Address) | Creates an organization by system contract and return its address. | +| **AddMember** | [`aelf.Address`](#aelf.Address) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Add organization members. | +| **RemoveMember** | [`aelf.Address`](#aelf.Address) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Remove organization members. | +| **ChangeMember** | [`Association.ChangeMemberInput`](#Association.ChangeMemberInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Replace organization member with a new member. | +| **GetOrganization** | [`aelf.Address`](#aelf.Address) | [`Association.Organization`](#Association.Organization) | Get the organization according to the organization address. | +| **CalculateOrganizationAddress** | [`Association.CreateOrganizationInput`](#Association.CreateOrganizationInput) | [`aelf.Address`](#aelf.Address) | Calculate the input and return the organization address. | + +# AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ----------------------------- | ------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| **SetMethodFee** | [`acs1.MethodFees`](#acs1.MethodFees) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Set the method fees for the specified method. Note that this will override all fees of the method. | +| **ChangeMethodFeeController** | [`AuthorityInfo`](#AuthorityInfo) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Change the method fee controller, the default is parliament and default organization. | +| **GetMethodFee** | [`google.protobuf.StringValue`](#google.protobuf.StringValue) | [`acs1.MethodFees`](#acs1.MethodFees) | Query method fee information by method name. | +| **GetMethodFeeController** | [`google.protobuf.Empty`](#google.protobuf.Empty) | [`AuthorityInfo`](#AuthorityInfo) | Query the method fee controller. | + +# AElf.Standards.ACS3 + +| Method Name | Request Type | Response Type | Description | +| --------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **CreateProposal** | [`acs3.CreateProposalInput`](#acs3.CreateProposalInput) | [`aelf.Hash`](#aelf.Hash) | Create a proposal for which organization members can vote. When the proposal is released, a transaction will be sent to the specified contract. Return id of the newly created proposal. | +| **Approve** | [`aelf.Hash`](#aelf.Hash) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Approve a proposal according to the proposal ID. | +| **Reject** | [`aelf.Hash`](#aelf.Hash) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Reject a proposal according to the proposal ID. | +| **Abstain** | [`aelf.Hash`](#aelf.Hash) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Abstain a proposal according to the proposal ID. | +| **Release** | [`aelf.Hash`](#aelf.Hash) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Release a proposal according to the proposal ID and send a transaction to the specified contract. | +| **ChangeOrganizationThreshold** | [`acs3.ProposalReleaseThreshold`](#acs3.ProposalReleaseThreshold) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Change the thresholds associated with proposals. All fields will be overwritten by the input value and this will affect all current proposals of the organization. Note: only the organization can execute this through a proposal. | +| **ChangeOrganizationProposerWhiteList** | [`acs3.ProposerWhiteList`](#acs3.ProposerWhiteList) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Change the white list of organization proposer. This method overrides the list of whitelisted proposers. | +| **CreateProposalBySystemContract** | [`acs3.CreateProposalBySystemContractInput`](#acs3.CreateProposalBySystemContractInput) | [`aelf.Hash`](#aelf.Hash) | Create a proposal by system contracts, and return id of the newly created proposal. | +| **ClearProposal** | [`aelf.Hash`](#aelf.Hash) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Remove the specified proposal. If the proposal is in effect, the cleanup fails. | +| **GetProposal** | [`aelf.Hash`](#aelf.Hash) | [`acs3.ProposalOutput`](#acs3.ProposalOutput) | Get the proposal according to the proposal ID. | +| **ValidateOrganizationExist** | [`aelf.Address`](#aelf.Address) | [`google.protobuf.BoolValue`](#google.protobuf.BoolValue) | Check the existence of an organization. | +| **ValidateProposerInWhiteList** | [`acs3.ValidateProposerInWhiteListInput`](#acs3.ValidateProposerInWhiteListInput) | [`google.protobuf.BoolValue`](#google.protobuf.BoolValue) | Check if the proposer is whitelisted. | + +# Contract Types + +## AElf.Contracts.Association + +### Association.ChangeMemberInput + +| Field | Type | Description | Label | +| ---------- | ------------------------------- | ----------------------- | ----- | +| old_member | [`aelf.Address`](#aelf.Address) | The old member address. | | +| new_member | [`aelf.Address`](#aelf.Address) | The new member address. | | + +### Association.CreateOrganizationBySystemContractInput + +| Field | Type | Description | Label | +| ------------------------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- | +| organization_creation_input | [`CreateOrganizationInput`](#Association.CreateOrganizationInput) | The parameters of creating organization. | | +| organization_address_feedback_method | [`string`](#string) | The organization address callback method which replies the organization address to caller contract. | | + +### Association.CreateOrganizationInput + +| Field | Type | Description | Label | +| -------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- | ----- | +| organization_member_list | [`OrganizationMemberList`](#Association.OrganizationMemberList) | Initial organization members. | | +| proposal_release_threshold | [`acs3.ProposalReleaseThreshold`](#acs3.ProposalReleaseThreshold) | The threshold for releasing the proposal. | | +| proposer_white_list | [`acs3.ProposerWhiteList`](#acs3.ProposerWhiteList) | The proposer whitelist. | | +| creation_token | [`aelf.Hash`](#aelf.Hash) | The creation token is for organization address generation. | | + +### Association.MemberAdded + +| Field | Type | Description | Label | +| -------------------- | ------------------------------- | ------------------------- | ----- | +| member | [`aelf.Address`](#aelf.Address) | The added member address. | | +| organization_address | [`aelf.Address`](#aelf.Address) | The organization address. | | + +### Association.MemberChanged + +| Field | Type | Description | Label | +| -------------------- | ------------------------------- | ------------------------- | ----- | +| old_member | [`aelf.Address`](#aelf.Address) | The old member address. | | +| new_member | [`aelf.Address`](#aelf.Address) | The new member address. | | +| organization_address | [`aelf.Address`](#aelf.Address) | The organization address. | | + +### Association.MemberRemoved + +| Field | Type | Description | Label | +| -------------------- | ------------------------------- | --------------------------- | ----- | +| member | [`aelf.Address`](#aelf.Address) | The removed member address. | | +| organization_address | [`aelf.Address`](#aelf.Address) | The organization address. | | + +### Association.Organization + +| Field | Type | Description | Label | +| -------------------------- | ------------------------------- | ---------------------------------------------------------- | ----- | +| organization_member_list | `OrganizationMemberList` | The organization members. | | +| proposal_release_threshold | `acs3.ProposalReleaseThreshold` | The threshold for releasing the proposal. | | +| proposer_white_list | `acs3.ProposerWhiteList` | The proposer whitelist. | | +| organization_address | `aelf.Address` | The address of organization. | | +| organization_hash | `aelf.Hash` | The organizations id. | | +| creation_token | `aelf.Hash` | The creation token is for organization address generation. | | + +### Association.OrganizationMemberList + +| Field | Type | Description | Label | +| -------------------- | -------------- | ------------------------------------ | -------- | +| organization_members | `aelf.Address` | The address of organization members. | repeated | + +# Association.ProposalInfo + +| Field | Type | Description | Label | +| ------------------------ | --------------------------- | ------------------------------------------------------------ | -------- | +| proposal_id | `aelf.Hash` | The proposal ID. | | +| contract_method_name | `string` | The method that this proposal will call when being released. | | +| to_address | `aelf.Address` | The address of the target contract. | | +| params | `bytes` | The parameters of the release transaction. | | +| expired_time | `google.protobuf.Timestamp` | The date at which this proposal will expire. | | +| proposer | `aelf.Address` | The address of the proposer of this proposal. | | +| organization_address | `aelf.Address` | The address of this proposals organization. | | +| approvals | `aelf.Address` | Address list of approved. | repeated | +| rejections | `aelf.Address` | Address list of rejected. | repeated | +| abstentions | `aelf.Address` | Address list of abstained. | repeated | +| proposal_description_url | `string` | Url is used for proposal describing. | | + +# ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | -------- | ----------------------------------- | ----- | +| symbol | `string` | The token symbol of the method fee. | | +| basic_fee | `int64` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ----------- | ------------------------------------------------------------ | -------- | +| method_name | `string` | The name of the method to be charged. | | +| fees | `MethodFee` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool` | Optional based on the implementation of SetMethodFee method. | | + +# ACS3 + +### acs3.CreateProposalBySystemContractInput + +| Field | Type | Description | Label | +| --------------- | --------------------- | ------------------------------------ | ----- | +| proposal_input | `CreateProposalInput` | The parameters of creating proposal. | | +| origin_proposer | `aelf.Address` | The actor that trigger the call. | | + +### acs3.CreateProposalInput + +| Field | Type | Description | Label | +| ------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------ | ----- | +| contract_method_name | `string` | The name of the method to call after release. | | +| to_address | `aelf.Address` | The address of the contract to call after release. | | +| params | `bytes` | The parameter of the method to be called after the release. | | +| expired_time | `google.protobuf.Timestamp` | The timestamp at which this proposal will expire. | | +| organization_address | `aelf.Address` | The address of the organization. | | +| proposal_description_url | `string` | Url is used for proposal describing. | | +| token | `aelf.Hash` | The token is for proposal id generation and with this token, proposal id can be calculated before proposing. | | + +### ac3.organizationCreated + +| Field | Type | Description | Label | +| -------------------- | ---------------------------------- | ------------------------------------ | ----- | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | Address of the created organization. | | + +### ac3.organizationHashAddressPair + +| Field | Type | Description | Label | +| -------------------- | ---------------------------------- | ---------------------------- | ----- | +| organization_hash | `aelf.Hash <#aelf.Hash>`\_\_ | ID of the organization. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | Address of the organization. | | + +### ac3.organizationThresholdChanged + +| Field | Type | Description | Label | +| -------------------------- | --------------------------------------------------------------- | ---------------------- | ----- | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | Organization address | | +| proposer_release_threshold | `ProposalReleaseThreshold <#acs3.ProposalReleaseThreshold>`\_\_ | New release threshold. | | + +### ac3.organizationWhiteListChanged + +| Field | Type | Description | Label | +| -------------------- | ------------------------------------------------- | ----------------------- | ----- | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | Organization address | | +| proposer_white_list | `ProposerWhiteList <#acs3.ProposerWhiteList>`\_\_ | New proposer whitelist. | | + +### ac3.proposalCreated + +| Field | Type | Description | Label | +| -------------------- | ---------------------------------- | --------------------------------------------- | ----- | +| proposal_id | `aelf.Hash <#aelf.Hash>`\_\_ | ID of the created proposal. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | Organization address of the created proposal. | | + +### ac3.proposalOutput + +| Field | Type | Description | Label | +| -------------------- | ------------------------------------------------------------ | -------------------------------------------- | ----- | +| proposal_id | `aelf.Hash <#aelf.Hash>`\_\_ | ID of the proposal. | | +| contract_method_name | `string <#string>`\_\_ | Method called when the proposal is released. | | +| to_address | `aelf.Address <#aelf.Address>`\_\_ | Address of the target contract. | | +| params | `bytes <#bytes>`\_\_ | Parameters of the release transaction. | | +| expired_time | `google.protobuf.Timestamp <#google.protobuf.Timestamp>`\_\_ | Expiry date of the proposal. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | Organization's address for the proposal. | | +| proposer | `aelf.Address <#aelf.Address>`\_\_ | Address of the proposer. | | +| to_be_released | `bool <#bool>`\_\_ | Indicates if the proposal is releasable. | | +| approval_count | `int64 <#int64>`\_\_ | Number of approvals. | | +| rejection_count | `int64 <#int64>`\_\_ | Number of rejections. | | +| abstention_count | `int64 <#int64>`\_\_ | Number of abstentions. | | + +### ac3.proposalReleaseThreshold + +| Field | Type | Description | Label | +| ---------------------------- | -------------------- | ----------------------------- | ----- | +| minimal_approval_threshold | `int64 <#int64>`\_\_ | Minimum approval threshold. | | +| maximal_rejection_threshold | `int64 <#int64>`\_\_ | Maximum rejection threshold. | | +| maximal_abstention_threshold | `int64 <#int64>`\_\_ | Maximum abstention threshold. | | +| minimal_vote_threshold | `int64 <#int64>`\_\_ | Minimum vote threshold. | | + +### ac3.proposalReleased + +| Field | Type | Description | Label | +| -------------------- | ---------------------------------- | ------------------------------------------------ | ----- | +| proposal_id | `aelf.Hash <#aelf.Hash>`\_\_ | ID of the released proposal. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | Organization's address of the released proposal. | | + +### ac3.proposerWhiteList + +| Field | Type | Description | Label | +| --------- | ---------------------------------- | --------------------------- | -------- | +| proposers | `aelf.Address <#aelf.Address>`\_\_ | Addresses of the proposers. | repeated | + +### ac3.receiptCreated + +| Field | Type | Description | Label | +| -------------------- | ------------------------------------------------------------ | ---------------------------------------------- | ----- | +| proposal_id | `aelf.Hash <#aelf.Hash>`\_\_ | ID of the proposal. | | +| address | `aelf.Address <#aelf.Address>`\_\_ | Sender's address. | | +| receipt_type | `string <#string>`\_\_ | Type of receipt (Approve, Reject, or Abstain). | | +| time | `google.protobuf.Timestamp <#google.protobuf.Timestamp>`\_\_ | Timestamp of the method call. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | Organization's address. | | + +### acs3.ValidateProposerInWhiteListInput + +| Field | Type | Description | Label | +| -------------------- | ---------------------------------- | -------------------------------- | ----- | +| proposer | `aelf.Address <#aelf.Address>`\_\_ | The address to search/check. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | The address of the organization. | | + +## AElf.Types + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | -------------------- | ----------- | ----- | +| value | `bytes <#bytes>`\_\_ | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | ----------------------- | ----------------------- | -------- | +| nodes | `Hash <#aelf.Hash>`\_\_ | The leaf nodes. | repeated | +| root | `Hash <#aelf.Hash>`\_\_ | The root node hash. | | +| leaf_count | `int32 <#int32>`\_\_ | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------------------- | ----------- | ----- | +| value | `bytes <#bytes>`\_\_ | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ----------------------------- | ------------------------------------------ | -------- | +| address | `Address <#aelf.Address>`\_\_ | The contract address. | | +| name | `string <#string>`\_\_ | The name of the log event. | | +| indexed | `bytes <#bytes>`\_\_ | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes <#bytes>`\_\_ | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ------------------------------------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode <#aelf.MerklePathNode>`\_\_ | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ----------------------- | -------------------------------- | ----- | +| hash | `Hash <#aelf.Hash>`\_\_ | The node hash. | | +| is_left_child_node | `bool <#bool>`\_\_ | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------- | ----- | +| value | `sint32 <#sint32>`\_\_ | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------- | ----- | +| value | `sint64 <#sint64>`\_\_ | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | --------------------------------- | ------------------------------------------------------ | ----- | +| address | `Address <#aelf.Address>`\_\_ | The scope address, which will be the contract address. | | +| path | `StatePath <#aelf.StatePath>`\_\_ | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | ----------------------- | ------------------------------------- | ----- | +| category | `sint32 <#sint32>`\_\_ | The category of contract code(0: C#). | | +| code | `bytes <#bytes>`\_\_ | The byte array of the contract code. | | +| code_hash | `Hash <#aelf.Hash>`\_\_ | The hash of the contract code. | | +| is_system_contract | `bool <#bool>`\_\_ | Whether it is a system contract. | | +| version | `int32 <#int32>`\_\_ | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------------------------------- | -------- | +| parts | `string <#string>`\_\_ | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | `Address <#aelf.Address>`\_\_ | The address of the sender of the transaction. | | +| to | `Address <#aelf.Address>`\_\_ | The address of the contract when calling a contract. | | +| ref_block_number | `int64 <#int64>`\_\_ | The height of the referenced block hash. | | +| ref_block_prefix | `bytes <#bytes>`\_\_ | The first four bytes of the referenced block hash. | | +| method_name | `string <#string>`\_\_ | The name of a method in the smart contract at the To address. | | +| params | `bytes <#bytes>`\_\_ | The parameters to pass to the smart contract method. | | +| signature | `bytes <#bytes>`\_\_ | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | ------------------------------------------------------------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry <#aelf.TransactionExecutingStateSet.WritesEntry>`\_\_ | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry <#aelf.TransactionExecutingStateSet.ReadsEntry>`\_\_ | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry <#aelf.TransactionExecutingStateSet.DeletesEntry>`\_\_ | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------- | ----- | +| key | `string <#string>`\_\_ | | | +| value | `bool <#bool>`\_\_ | | | + +--- + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------- | ----- | +| key | `string <#string>`\_\_ | | | +| value | `bool <#bool>`\_\_ | | | + +--- + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------- | ----- | +| key | `string <#string>`\_\_ | | | +| value | `bytes <#bytes>`\_\_ | | | + +--- + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | ------------------------------------------------------------- | ----------------------------------------------------- | -------- | +| transaction_id | `Hash <#aelf.Hash>`\_\_ | The transaction id. | | +| status | `TransactionResultStatus <#aelf.TransactionResultStatus>`\_\_ | The transaction result status. | | +| logs | `LogEvent <#aelf.LogEvent>`\_\_ | The log events. | repeated | +| bloom | `bytes <#bytes>`\_\_ | Bloom filter for transaction logs. | | +| return_value | `bytes <#bytes>`\_\_ | The return value of the transaction execution. | | +| block_number | `int64 <#int64>`\_\_ | The height of the block hat packages the transaction. | | +| block_hash | `Hash <#aelf.Hash>`\_\_ | The hash of the block hat packages the transaction. | | +| error | `string <#string>`\_\_ | Failed execution error message. | | + +--- + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +--- + +### AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | ---------------------------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address <#aelf.Address>`\_\_ | The contract address of the controller. | | +| owner_address | `aelf.Address <#aelf.Address>`\_\_ | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Configuration Contract.md b/docs/References/Smart Contract API/Configuration Contract.md new file mode 100644 index 0000000..e2318e5 --- /dev/null +++ b/docs/References/Smart Contract API/Configuration Contract.md @@ -0,0 +1,208 @@ +# AElf.Contracts.Configuration + +Configuration contract. Used to manage the configuration on the blockchain. Implements AElf Standards ACS1. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ----------------------------- | ------------------------------------- | ---------------------------- | ------------------------------------------------------------ | +| SetConfiguration | `Configuration.SetConfigurationInput` | `google.protobuf.Empty` | Add or update configuration. | +| ChangeConfigurationController | `AuthorityInfo` | `google.protobuf.Empty` | Change the method fee controller, the default is Parliament. | +| GetConfiguration | `google.protobuf.StringValue` | `google.protobuf.BytesValue` | Query the configuration by configuration’s key. | +| GetConfigurationController | `google.protobuf.Empty` | `AuthorityInfo` | Query the controller information. | + +# AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees` | `google.protobuf.Empty` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue` | `acs1.MethodFees` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty` | `AuthorityInfo` | Query the method fee controller. | + +# Contract Types + +## AElf.Contracts.Configuration + +### Configuration.ConfigurationSet + +| Field | Type | Description | Label | +| ----- | -------- | ---------------------------------------- | ----- | +| key | `string` | The configuration’s key. | | +| value | `bytes` | The configuration’s value (binary data). | | + +### Configuration.SetConfigurationInput + +| Field | Type | Description | Label | +| ----- | -------- | ---------------------------------------- | ----- | +| key | `string` | The configuration’s key. | | +| value | `bytes` | The configuration’s value (binary data). | | + +## AElf.Standards.ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | -------- | ----------------------------------- | ----- | +| symbol | `string` | The token symbol of the method fee. | | +| basic_fee | `int64` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ----------- | ------------------------------------------------------------ | -------- | +| method_name | `string` | The name of the method to be charged. | | +| fees | `MethodFee` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool` | Optional based on the implementation of SetMethodFee method. | | + +## AElf.Types + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | ------- | ----------------------- | -------- | +| nodes | `Hash` | The leaf nodes. | repeated | +| root | `Hash` | The root node hash. | | +| leaf_count | `int32` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ------------------------ | ------------------------------------------ | -------- | +| address | [Address](#aelf.Address) | The contract address. | | +| name | [string](#string) | The name of the log event. | | +| indexed | [bytes](#bytes) | The indexed data, used to calculate bloom. | repeated | +| non_indexed | [bytes](#bytes) | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | -------------------------------------- | ---------------------- | -------- | +| merkle_path_nodes | [MerklePathNode](#aelf.MerklePathNode) | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------------------ | -------------------------------- | ----- | +| hash | [Hash](#aelf.Hash) | The node hash. | | +| is_left_child_node | [bool](#bool) | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | ----------------- | ----------- | ----- | +| value | [sint32](#sint32) | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | ----------------- | ----------- | ----- | +| value | [sint64](#sint64) | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ---------------------------- | ------------------------------------------------------ | ----- | +| address | [Address](#aelf.Address) | The scope address, which will be the contract address. | | +| path | [StatePath](#aelf.StatePath) | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | ------------------ | ------------------------------------- | ----- | +| category | [sint32](#sint32) | The category of contract code(0: C#). | | +| code | [bytes](#bytes) | The byte array of the contract code. | | +| code_hash | [Hash](#aelf.Hash) | The hash of the contract code. | | +| is_system_contract | [bool](#bool) | Whether it is a system contract. | | +| version | [int32](#int32) | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | ----------------- | ----------------------------------- | -------- | +| parts | [string](#string) | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | [Address](#aelf.Address) | The address of the sender of the transaction. | | +| to | [Address](#aelf.Address) | The address of the contract when calling a contract. | | +| ref_block_number | [int64](#int64) | The height of the referenced block hash. | | +| ref_block_prefix | [bytes](#bytes) | The first four bytes of the referenced block hash. | | +| method_name | [string](#string) | The name of a method in the smart contract at the To address. | | +| params | [bytes](#bytes) | The parameters to pass to the smart contract method. | | +| signature | [bytes](#bytes) | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | -------------------------------------------------------------------------------------------- | ------------------- | -------- | +| writes | [TransactionExecutingStateSet.WritesEntry](#aelf.TransactionExecutingStateSet.WritesEntry) | The changed states. | repeated | +| reads | [TransactionExecutingStateSet.ReadsEntry](#aelf.TransactionExecutingStateSet.ReadsEntry) | The read states. | repeated | +| deletes | [TransactionExecutingStateSet.DeletesEntry](#aelf.TransactionExecutingStateSet.DeletesEntry) | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | ----------------- | ----------- | ----- | +| key | [string](#string) | | | +| value | [bool](#bool) | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | ----------------- | ----------- | ----- | +| key | [string](#string) | | | +| value | [bool](#bool) | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | ----------------- | ----------- | ----- | +| key | [string](#string) | | | +| value | [bytes](#bytes) | | | + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| transaction_id | [Hash](#aelf.Hash) | The transaction id. | | +| status | [TransactionResultStatus](#aelf.TransactionResultStatus) | The transaction result status. | | +| logs | [LogEvent](#aelf.LogEvent) | The log events. | repeated | +| bloom | [bytes](#bytes) | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. Through this filter, we can quickly search for and determine whether a log exists in the transaction result. | | +| return_value | [bytes](#bytes) | The return value of the transaction execution. | | +| block_number | [int64](#int64) | The height of the block that packages the transaction. | | +| block_hash | [Hash](#aelf.Hash) | The hash of the block that packages the transaction. | | +| error | [string](#string) | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +## AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | ----------------------------- | ----------------------------------------- | ----- | +| contract_address | [aelf.Address](#aelf.Address) | The contract address of the controller. | | +| owner_address | [aelf.Address](#aelf.Address) | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Consensus Contract.md b/docs/References/Smart Contract API/Consensus Contract.md new file mode 100644 index 0000000..63ef3f7 --- /dev/null +++ b/docs/References/Smart Contract API/Consensus Contract.md @@ -0,0 +1,714 @@ +# AElf.Contracts.Consensus.AEDPoS + +## AEDPoS contract + +Used to manage block producers and synchronize data. Implements AElf Standards ACS1, ACS4, ACS6, ACS10, and ACS11. + +### Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ---------------------------------- | ------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------ | +| InitialAElfConsensusContract | `AEDPoS.InitialAElfConsensusContractInput` | `google.protobuf.Empty` | Initialize the consensus contract. | +| FirstRound | `AEDPoS.Round` | `google.protobuf.Empty` | Initializes the consensus information in the first round. | +| UpdateValue | `AEDPoS.UpdateValueInput` | `google.protobuf.Empty` | Update consensus information. | +| NextRound | `AEDPoS.NextRoundInput` | `google.protobuf.Empty` | Update consensus information, create a new round. | +| NextTerm | `AEDPoS.NextTermInput` | `google.protobuf.Empty` | Update consensus information, create a new term. | +| UpdateTinyBlockInformation | `AEDPoS.TinyBlockInput` | `google.protobuf.Empty` | Update consensus tiny block information. | +| SetMaximumMinersCount | `google.protobuf.Int32Value` | `google.protobuf.Empty` | Set the maximum count of miners, by default, is unlimited. | +| ChangeMaximumMinersCountController | `AuthorityInfo` | `google.protobuf.Empty` | Change the authority information for maximum miners count. | +| RecordCandidateReplacement | `AEDPoS.RecordCandidateReplacementInput` | `google.protobuf.Empty` | Notify AEDPoS Contract of candidate replacement. | +| GetCurrentMinerList | `google.protobuf.Empty` | `AEDPoS.MinerList` | Get the list of current miners. | +| GetCurrentMinerPubkeyList | `google.protobuf.Empty` | `AEDPoS.PubkeyList` | Get the list of current miners in hexadecimal format. | +| GetCurrentMinerListWithRoundNumber | `google.protobuf.Empty` | `AEDPoS.MinerListWithRoundNumber` | Get the list of current miners and current round number. | +| GetRoundInformation | `google.protobuf.Int64Value` | `AEDPoS.Round` | Get information of the round according to round number. | +| GetCurrentRoundNumber | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the current round number. | +| GetCurrentRoundInformation | `google.protobuf.Empty` | `AEDPoS.Round` | Get the current round information. | +| GetPreviousRoundInformation | `google.protobuf.Empty` | `AEDPoS.Round` | Get the previous round information. | +| GetCurrentTermNumber | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the current term number. | +| GetCurrentTermMiningReward | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the welfare reward for the current term. | +| GetMinerList | `AEDPoS.GetMinerListInput` | `AEDPoS.MinerList` | Get the list of miners according to term number. | +| GetPreviousMinerList | `google.protobuf.Empty` | `AEDPoS.MinerList` | Get the list of miners in the previous term. | +| GetMinedBlocksOfPreviousTerm | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the amount of mined blocks in the previous term. | +| GetNextMinerPubkey | `google.protobuf.Empty` | `google.protobuf.StringValue` | Get the miner that produces the next block. | +| IsCurrentMiner | `aelf.Address` | `google.protobuf.BoolValue` | Check if the account address is on the miner list for the current round. | +| GetNextElectCountDown | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the left time before the next election takes effect (seconds). | +| GetPreviousTermInformation | `google.protobuf.Int64Value` | `AEDPoS.Round` | Get term information according to term number. | +| GetRandomHash | `google.protobuf.Int64Value` | `aelf.Hash` | Get random hash (Compatibility note). | +| GetMaximumBlocksCount | `google.protobuf.Empty` | `google.protobuf.Int32Value` | Get the maximum of tiny blocks produced by a miner each round. | +| GetMaximumMinersCount | `google.protobuf.Empty` | `google.protobuf.Int32Value` | Get the maximum count of miners. | +| GetMaximumMinersCountController | `google.protobuf.Empty` | `AuthorityInfo` | Get the authority information for maximum miners count. | +| GetMainChainCurrentMinerList | `google.protobuf.Empty` | `AEDPoS.MinerList` | Get the list of miners in the main chain. | +| GetPreviousTermMinerPubkeyList | `google.protobuf.Empty` | `AEDPoS.PubkeyList` | Get the list of miners in the previous term. | +| GetCurrentMiningRewardPerBlock | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Query the current mining reward for each block. | +| SetMinerIncreaseInterval | `google.protobuf.Int64Value` | `google.protobuf.Empty` | Set the current miner growth time interval. | +| GetMinerIncreaseInterval | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the current miner growth time interval. | + +# AElf.Standards.ACS1 + +## ACS1 Standard Methods + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------- | ----------------------- | --------------------------------------------- | +| SetMethodFee | `acs1.MethodFees` | `google.protobuf.Empty` | Set the method fees for the specified method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty` | Change the method fee controller. | +| GetMethodFee | `google.protobuf.StringValue` | `acs1.MethodFees` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty` | `AuthorityInfo` | Query the method fee controller. | + +# AElf.Contracts.Consensus.AEDPoS + +## AEDPoS contract + +Used for managing block producers and synchronizing data. + +Implement AElf Standards ACS1, ACS4, ACS6, ACS10, and ACS11. + +### Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ---------------------------------- | ------------------------------------------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| InitialAElfConsensusContract | `AEDPoS.InitialAElfConsensusContractInput` | `google.protobuf.Empty` | Initialize the consensus contract. | +| FirstRound | `AEDPoS.Round` | `google.protobuf.Empty` | Initializes the consensus information in the first round. | +| UpdateValue | `AEDPoS.UpdateValueInput` | `google.protobuf.Empty` | Update consensus information. | +| NextRound | `AEDPoS.NextRoundInput` | `google.protobuf.Empty` | Update consensus information, create a new round. | +| NextTerm | `AEDPoS.NextTermInput` | `google.protobuf.Empty` | Update consensus information, create a new term. | +| UpdateTinyBlockInformation | `AEDPoS.TinyBlockInput` | `google.protobuf.Empty` | Update consensus tiny block information. | +| SetMaximumMinersCount | `google.protobuf.Int32Value` | `google.protobuf.Empty` | Set the maximum count of miners, by default, is unlimited. If you want to control the count of miners, you need to set it through parliament. | +| ChangeMaximumMinersCountController | `AuthorityInfo` | `google.protobuf.Empty` | The authority information for SetMaximumMinersCount, by default, is governed by parliament. | +| RecordCandidateReplacement | `AEDPoS.RecordCandidateReplacementInput` | `google.protobuf.Empty` | Election Contract can notify AEDPoS Contract to aware candidate replacement happened. | +| GetCurrentMinerList | `google.protobuf.Empty` | `AEDPoS.MinerList` | Get the list of current miners. | +| GetCurrentMinerPubkeyList | `google.protobuf.Empty` | `AEDPoS.PubkeyList` | Get the list of current miners (hexadecimal format). | +| GetCurrentMinerListWithRoundNumber | `google.protobuf.Empty` | `AEDPoS.MinerListWithRoundNumber` | Get the list of current miners and current round number. | +| GetRoundInformation | `google.protobuf.Int64Value` | `AEDPoS.Round` | Get information of the round according to round number. | +| GetCurrentRoundNumber | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the current round number. | +| GetCurrentRoundInformation | `google.protobuf.Empty` | `AEDPoS.Round` | Get the current round information. | +| GetPreviousRoundInformation | `google.protobuf.Empty` | `AEDPoS.Round` | Get the previous round information. | +| GetCurrentTermNumber | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the current term number. | +| GetCurrentTermMiningReward | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the welfare reward the current term. | +| GetMinerList | `AEDPoS.GetMinerListInput` | `AEDPoS.MinerList` | Get the list of miners according to term number. | +| GetPreviousMinerList | `google.protobuf.Empty` | `AEDPoS.MinerList` | Get the list of miner in previous term. | +| GetMinedBlocksOfPreviousTerm | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the amount of mined blocks in previous term. | +| GetNextMinerPubkey | `google.protobuf.Empty` | `google.protobuf.StringValue` | Get the miner that produces the next block. | +| IsCurrentMiner | `aelf.Address` | `google.protobuf.BoolValue` | Check to see if the account address is on the miner list for the current round. | +| GetNextElectCountDown | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Query the left time before the next election takes effects (seconds). | +| GetPreviousTermInformation | `google.protobuf.Int64Value` | `AEDPoS.Round` | Get term information according term number. | +| GetRandomHash | `google.protobuf.Int64Value` | `aelf.Hash` | Get random hash (Keep this for compatibility). | +| GetMaximumBlocksCount | `google.protobuf.Empty` | `google.protobuf.Int32Value` | Get maximum tiny blocks produced by miner each round. | +| GetMaximumMinersCount | `google.protobuf.Empty` | `google.protobuf.Int32Value` | Get the maximum count of miners. | +| GetMaximumMinersCountController | `google.protobuf.Empty` | `AuthorityInfo` | The authority information for GetMaximumMinersCount, by default, is governed by parliament. | +| GetMainChainCurrentMinerList | `google.protobuf.Empty` | `AEDPoS.MinerList` | Get the list of miners in main chain. | +| GetPreviousTermMinerPubkeyList | `google.protobuf.Empty` | `AEDPoS.PubkeyList` | Get the list of miners in previous term. | +| GetCurrentMiningRewardPerBlock | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Query the current mining reward for each block. | +| SetMinerIncreaseInterval | `google.protobuf.Int64Value` | `google.protobuf.Empty` | Set the current miner growth time interval. | +| GetMinerIncreaseInterval | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the current miner growth time interval. | + +# AElf.Standards.ACS4 + +## ACS4 Standard Methods + +| Method Name | Request Type | Response Type | Description | +| -------------------------------- | ---------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GetConsensusCommand | `google.protobuf.BytesValue` | `acs4.ConsensusCommand` | Generate a consensus command based on the consensus contract state and the input public key. | +| GetConsensusExtraData | `google.protobuf.BytesValue` | `google.protobuf.BytesValue` | Generate consensus extra data when a block is generated. | +| GenerateConsensusTransactions | `google.protobuf.BytesValue` | `acs4.TransactionList` | Generate consensus system transactions when a block is generated. Each block will contain only one consensus transaction, which is used to write the latest consensus information to the State database. | +| ValidateConsensusBeforeExecution | `google.protobuf.BytesValue` | `acs4.ValidationResult` | Before executing the block, verify that the consensus information in the block header is correct. | +| ValidateConsensusAfterExecution | `google.protobuf.BytesValue` | `acs4.ValidationResult` | After executing the block, verify that the state information written to the consensus is correct. | + +# AElf.Standards.ACS6 + +## ACS6 Standard Methods + +| Method Name | Request Type | Response Type | Description | +| -------------- | ---------------------------- | ---------------------------- | -------------------------------------------- | +| GetRandomBytes | `google.protobuf.BytesValue` | `google.protobuf.BytesValue` | Get random number according to block height. | + +# AElf.Standards.ACS10 + +## ACS10 Standard Methods + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ---------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Donate | `acs10.DonateInput` | `google.protobuf.Empty` | Donates tokens from the caller to the treasury. If the tokens are not native tokens in the current chain, they will be first converted to the native token. | +| Release | `acs10.ReleaseInput` | `google.protobuf.Empty` | Release dividend pool according the period number. | +| SetSymbolList | `acs10.SymbolList` | `google.protobuf.Empty` | Set the token symbols dividend pool supports. | +| GetSymbolList | `google.protobuf.Empty` | `acs10.SymbolList` | Query the token symbols dividend pool supports. | +| GetUndistributedDividends | `google.protobuf.Empty` | `acs10.Dividends` | Query the balance of undistributed tokens whose symbols are included in the symbol list. | +| GetDividends | `google.protobuf.Int64Value` | `acs10.Dividends` | Query the dividend information according to the height. | + +# AElf.Standards.ACS11 + +## ACS11 Standard Methods + +| Method Name | Request Type | Response Type | Description | +| --------------------------------- | ---------------------------- | ---------------------------- | ----------------------------------------------------------- | +| UpdateInformationFromCrossChain | `google.protobuf.BytesValue` | `google.protobuf.Empty` | Update the consensus information of the side chain. | +| GetChainInitializationInformation | `google.protobuf.BytesValue` | `google.protobuf.BytesValue` | Get the current miner list and consensus round information. | +| CheckCrossChainIndexingPermission | `aelf.Address` | `google.protobuf.BoolValue` | Verify that the input address is the current miner. | + +# Contract Types + +## AElf.Contracts.Consensus.AEDPoS + +### AEDPoS.AElfConsensusHeaderInformation + +| Field | Type | Description | Label | +| ------------- | ------------------------ | --------------------------- | ----- | +| sender_pubkey | `bytes` | The sender public key. | | +| round | `Round` | The round information. | | +| behaviour | `AElfConsensusBehaviour` | The behaviour of consensus. | | + +### AEDPoS.AElfConsensusHint + +| Field | Type | Description | Label | +| ----------------- | ------------------------ | --------------------------- | ----- | +| behaviour | `AElfConsensusBehaviour` | The behaviour of consensus. | | +| round_id | `int64` | The round id. | | +| previous_round_id | `int64` | The previous round id. | | + +### AEDPoS.AElfConsensusTriggerInformation + +| Field | Type | Description | Label | +| ------------------ | ------------------------ | -------------------------------- | -------- | +| pubkey | `bytes` | The miner public key. | | +| in_value | `aelf.Hash` | The InValue for current round. | | +| previous_in_value | `aelf.Hash` | The InValue for previous round. | | +| behaviour | `AElfConsensusBehaviour` | The behaviour of consensus. | | +| encrypted_pieces | `EncryptedPiecesEntry` | The encrypted pieces of InValue. | repeated | +| decrypted_pieces | `DecryptedPiecesEntry` | The decrypted pieces of InValue. | repeated | +| revealed_in_values | `RevealedInValuesEntry` | The revealed InValues. | repeated | + +### AEDPoS.AElfConsensusTriggerInformation.DecryptedPiecesEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `bytes` | | | + +### AEDPoS.AElfConsensusTriggerInformation.EncryptedPiecesEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `bytes` | | | + +### AEDPoS.AElfConsensusTriggerInformation.RevealedInValuesEntry + +| Field | Type | Description | Label | +| ----- | ----------- | ----------- | ----- | +| key | `string` | | | +| value | `aelf.Hash` | | | + +### AEDPoS.Candidates + +| Field | Type | Description | Label | +| ------- | ------- | -------------------------- | -------- | +| pubkeys | `bytes` | The candidate public keys. | repeated | + +### AEDPoS.ConsensusInformation + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +### AEDPoS.GetMinerListInput + +| Field | Type | Description | Label | +| ----------- | ------- | ---------------- | ----- | +| term_number | `int64` | The term number. | | + +### AEDPoS.HashList + +| Field | Type | Description | Label | +| ------ | ----------- | ----------- | -------- | +| values | `aelf.Hash` | | repeated | + +### AEDPoS.InitialAElfConsensusContractInput + +| Field | Type | Description | Label | +| ----------------------- | ------- | ------------------------------------------ | ----- | +| is_term_stay_one | `bool` | Whether not to change the term. | | +| is_side_chain | `bool` | Is a side chain. | | +| period_seconds | `int64` | The number of seconds per term. | | +| miner_increase_interval | `int64` | The interval second that increases miners. | | + +### AEDPoS.IrreversibleBlockFound + +| Field | Type | Description | Label | +| ------------------------- | ------- | ------------------------------------ | ----- | +| irreversible_block_height | `int64` | The irreversible block height found. | | + +### AEDPoS.IrreversibleBlockHeightUnacceptable + +| Field | Type | Description | Label | +| ------------------------------------- | ------- | ------------------------------------------------------ | ----- | +| distance_to_irreversible_block_height | `int64` | Distance to the height of the last irreversible block. | | + +### AEDPoS.LatestPubkeyToTinyBlocksCount + +| Field | Type | Description | Label | +| ------------ | -------- | --------------------------------------- | ----- | +| pubkey | `string` | The miner public key. | | +| blocks_count | `int64` | The count of blocks the miner produced. | | + +### AEDPoS.MinerInRound + +| Field | Type | Description | Label | +| --------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------- | -------- | +| order | `int32` | The order of the miner producing a block. | | +| is_extra_block_producer | `bool` | Is the extra block producer in the current round. | | +| in_value | `aelf.Hash` | Generated by secret sharing and used for validation between miners. | | +| out_value | `aelf.Hash` | Calculated from the current in value. | | +| signature | `aelf.Hash` | Calculated from the current in value and signatures of the previous round. | | +| expected_mining_time | `Timestamp` | The expected mining time. | | +| produced_blocks | `int64` | The amount of produced blocks. | | +| missed_time_slots | `int64` | The amount of missed time slots. | | +| pubkey | `string` | The public key of this miner. | | +| previous_in_value | `aelf.Hash` | The InValue of the previous round. | | +| supposed_order_of_next_round | `int32` | The supposed order of mining for the next round. | | +| final_order_of_next_round | `int32` | The final order of mining for the next round. | | +| actual_mining_times | `Timestamp` | The actual mining time, miners must fill the actual mining time when they do the mining. | repeated | +| encrypted_pieces | `MinerInRound.EncryptedPiecesEntry` | The encrypted pieces of InValue. | repeated | +| decrypted_pieces | `MinerInRound.DecryptedPiecesEntry` | The decrypted pieces of InValue. | repeated | +| produced_tiny_blocks | `int64` | The amount of produced tiny blocks. | | +| implied_irreversible_block_height | `int64` | The irreversible block height that the current miner recorded. | | + +### AEDPoS.MinerInRound.DecryptedPiecesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### AEDPoS.MinerInRound.EncryptedPiecesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### AEDPoS.MinerList + +| Field | Type | Description | Label | +| ------- | -------- | --------------------------- | -------- | +| pubkeys | `bytes ` | The miners public key list. | repeated | + +### AEDPoS.MinerListWithRoundNumber + +| Field | Type | Description | Label | +| ------------ | ------------ | ------------------- | ----- | +| miner_list | `MinerList ` | The list of miners. | | +| round_number | `int64 ` | The round number. | | + +### AEDPoS.MinerReplaced + +| Field | Type | Description | Label | +| ---------------- | --------- | ------------------------- | ----- | +| new_miner_pubkey | `string ` | The new miner public key. | | + +### AEDPoS.MiningInformationUpdated + +| Field | Type | Description | Label | +| ------------------- | ------------------------------ | --------------------------- | ----- | +| pubkey | `string ` | The miner public key. | | +| mining_time | `google.protobuf.Timestamp ` | The current block time. | | +| behaviour | `string ` | The behaviour of consensus. | | +| block_height | `int64 ` | The current block height. | | +| previous_block_hash | `aelf.Hash ` | The previous block hash. | | + +### AEDPoS.MiningRewardGenerated + +| Field | Type | Description | Label | +| ----------- | -------- | -------------------------------------------------- | ----- | +| term_number | `int64 ` | The number of term the mining reward is generated. | | +| amount | `int64 ` | The amount of mining reward. | | + +### AEDPoS.PubkeyList + +| Field | Type | Description | Label | +| ------- | --------- | --------------------------- | -------- | +| pubkeys | `string ` | The miners public key list. | repeated | + +### AEDPoS.RandomNumberRequestInformation + +| Field | Type | Description | Label | +| --------------------- | -------- | ------------------------------------------------------ | ----- | +| target_round_number | `int64 ` | The random hash is likely generated during this round. | | +| order | `int64 ` | | | +| expected_block_height | `int64 ` | | | + +### AEDPoS.RecordCandidateReplacementInput + +| Field | Type | Description | Label | +| ---------- | --------- | ----------- | ----- | +| old_pubkey | `string ` | | | +| new_pubkey | `string ` | | | + +### AEDPoS.NextRoundInput + +| Field | Type | Description | Label | +| ----------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------- | -------- | +| round_number | `int64 ` | The round number. | | +| real_time_miners_information | `Round.RealTimeMinersInformationEntry ` | Current miner information, miner public key -> miner information. | repeated | +| main_chain_miners_round_number | `int64 ` | The round number on the main chain. | | +| blockchain_age | `int64 ` | The time from chain start to current round (seconds). | | +| extra_block_producer_of_previous_round | `string ` | The miner public key that produced the extra block in the previous round. | | +| term_number | `int64 ` | The current term number. | | +| confirmed_irreversible_block_height | `int64 ` | The height of the confirmed irreversible block. | | +| confirmed_irreversible_block_round_number | `int64 ` | The round number of the confirmed irreversible block. | | +| is_miner_list_just_changed | `bool ` | Is miner list different from the the miner list in the previous round. | | +| round_id_for_validation | `int64 ` | The round id, calculated by summing block producers’ expecting time (second). | | +| random_number | `bytes ` | The random number. | | + +### AEDPoS.NextTermInput + +| Field | Type | Description | Label | +| ----------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------- | -------- | +| round_number | `int64 ` | The round number. | | +| real_time_miners_information | `Round.RealTimeMinersInformationEntry ` | Current miner information, miner public key -> miner information. | repeated | +| main_chain_miners_round_number | `int64 ` | The round number on the main chain. | | +| blockchain_age | `int64 ` | The time from chain start to current round (seconds). | | +| extra_block_producer_of_previous_round | `string ` | The miner public key that produced the extra block in the previous round. | | +| term_number | `int64 ` | The current term number. | | +| confirmed_irreversible_block_height | `int64 ` | The height of the confirmed irreversible block. | | +| confirmed_irreversible_block_round_number | `int64 ` | The round number of the confirmed irreversible block. | | +| is_miner_list_just_changed | `bool ` | Is miner list different from the the miner list in the previous round. | | +| round_id_for_validation | `int64 ` | The round id, calculated by summing block producers’ expecting time (second). | | +| random_number | `bytes ` | The random number. | | + +### AEDPoS.Round.RealTimeMinersInformationEntry + +| Field | Type | Description | Label | +| ----- | --------------- | ----------- | ----- | +| key | `string ` | | | +| value | `MinerInRound ` | | | + +### AEDPoS.SecretSharingInformation + +| Field | Type | Description | Label | +| ----------------- | -------- | ------------------------------- | ----- | +| previous_round | `Round ` | The previous round information. | | +| current_round_id | `int64 ` | The current round id. | | +| previous_round_id | `int64 ` | The previous round id. | | + +### AEDPoS.TermInfo + +| Field | Type | Description | Label | +| ------------ | -------- | ----------- | ----- | +| term_number | `int64 ` | | | +| round_number | `int64 ` | | | + +### AEDPoS.TermNumberLookUp + +| Field | Type | Description | Label | +| ----- | ---------------------------- | ---------------------------- | -------- | +| map | `TermNumberLookUp.MapEntry ` | Term number -> Round number. | repeated | + +
+
+ +### AEDPoS.TermNumberLookUp.MapEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `int64 ` | | | +| value | `int64 ` | | | + +### AEDPoS.TinyBlockInput + +| Field | Type | Description | Label | +| ------------------ | ------------------------------ | ------------------------- | ----- | +| round_id | `int64 ` | The round id. | | +| actual_mining_time | `google.protobuf.Timestamp ` | The actual mining time. | | +| produced_blocks | `int64 ` | Count of blocks produced. | | + +### AEDPoS.UpdateValueInput + +| Field | Type | Description | Label | +| --------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | +| out_value | `aelf.Hash ` | Calculated from current in value. | | +| signature | `aelf.Hash ` | Calculated from current in value and signatures of previous round. | | +| round_id | `int64 ` | To ensure the values to update will apply to the correct round by comparing round id. | | +| previous_in_value | `aelf.Hash ` | Publishes previous in value for validation of previous signature and previous out value. | | +| actual_mining_time | `google.protobuf.Timestamp ` | The actual mining time; miners must fill actual mining time when they mine. | | +| supposed_order_of_next_round | `int32 ` | The supposed order of mining for the next round. | | +| tune_order_information | `UpdateValueInput.TuneOrderInformationEntry ` | The tuning order of mining for the next round, miner public key -> order. | repeated | +| encrypted_pieces | `UpdateValueInput.EncryptedPiecesEntry ` | The encrypted pieces of InValue. | repeated | +| decrypted_pieces | `UpdateValueInput.DecryptedPiecesEntry ` | The decrypted pieces of InValue. | repeated | +| produced_blocks | `int64 ` | The amount of produced blocks. | | +| miners_previous_in_values | `UpdateValueInput.MinersPreviousInValuesEntry ` | The InValue in the previous round, miner public key -> InValue. | repeated | +| implied_irreversible_block_height | `int64 ` | The irreversible block height that the miner recorded. | | + +### AEDPoS.UpdateValueInput.DecryptedPiecesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### AEDPoS.UpdateValueInput.EncryptedPiecesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### AEDPoS.UpdateValueInput.MinersPreviousInValuesEntr + +| Field | Type | Description | Label | +| ----- | -------------- | ----------- | ----- | +| key | `string ` | | | +| value | `aelf.Hash ` | | | + +### AEDPoS.UpdateValueInput.TuneOrderInformationEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int32 ` | | | + +### AEDPoS.VoteMinersCountInput + +| Field | Type | Description | Label | +| ------------ | -------- | ----------- | ----- | +| miners_count | `int32 ` | | | +| amount | `int64 ` | | | + +### AEDPoS.AElfConsensusBehaviour + +| Name | Number | Description | +| ------------ | ------ | ----------- | +| UPDATE_VALUE | 0 | | +| NEXT_ROUND | 1 | | +| NEXT_TERM | 2 | | +| NOTHING | 3 | | +| TINY_BLOCK | 4 | | + +## AElf.Standards.ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | --------- | ----------------------------------- | ----- | +| symbol | `string ` | The token symbol of the method fee. | | +| basic_fee | `int64 ` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | -------------- | ------------------------------------------------------------ | -------- | +| method_name | `string ` | The name of the method to be charged. | | +| fees | `MethodFee ` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool ` | Optional based on the implementation of SetMethodFee method. | | + +### acs4.ConsensusCommand + +| Field | Type | Description | Label | +| ---------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------ | ----- | +| limit_milliseconds_of_mining_block | `int32 ` | Time limit of mining next block. | | +| hint | `bytes ` | Context of Hint is diverse according to the consensus protocol we choose, so we use bytes. | | +| arranged_mining_time | `google.protobuf.Timestamp ` | The time of arrange mining. | | +| mining_due_time | `google.protobuf.Timestamp ` | The expiration time of mining. | | + +### acs4.TransactionList + +| Field | Type | Description | Label | +| ------------ | --------------------- | ------------------------------ | -------- | +| transactions | `aelf.Transaction ` | Consensus system transactions. | repeated | + +### acs4.ValidationResult + +| Field | Type | Description | Label | +| ------------- | --------- | -------------------------------- | ----- | +| success | `bool ` | Is successful. | | +| message | `string ` | The error message. | | +| is_re_trigger | `bool ` | Whether to trigger mining again. | | + +### acs10.Dividends + +| Field | Type | Description | Label | +| ----- | ------------------------- | -------------------------------- | -------- | +| value | `Dividends.ValueEntry ` | The dividends, symbol -> amount. | repeated | + +### acs10.Dividends.ValueEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int64 ` | | | + +### acs10.DonateInput + +| Field | Type | Description | Label | +| ------ | --------- | --------------------------- | ----- | +| symbol | `string ` | The token symbol to donate. | | +| amount | `int64 ` | The amount to donate. | | + +### acs10.DonationReceived + +| Field | Type | Description | Label | +| ------------- | --------------- | ----------------------------- | ----- | +| from | `aelf.Address ` | The address of donors. | | +| pool_contract | `aelf.Address ` | The address of dividend pool. | | +| symbol | `string ` | The token symbol Donated. | | +| amount | `int64 ` | The amount Donated. | | + +### acs10.ReleaseInput + +| Field | Type | Description | Label | +| ------------- | -------- | ----------------------------- | ----- | +| period_number | `int64 ` | The period number to release. | | + +### acs10.SymbolList + +| Field | Type | Description | Label | +| ----- | --------- | ---------------------- | -------- | +| value | `string ` | The token symbol list. | repeated | + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | --------- | ----------------------- | -------- | +| nodes | `Hash ` | The leaf nodes. | repeated | +| root | `Hash ` | The root node hash. | | +| leaf_count | `int32 ` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ---------- | -------------------------- | -------- | +| address | `Address ` | The contract address. | | +| name | `string ` | The name of the log event. | | +| indexed | `bytes ` | The indexed data. | repeated | +| non_indexed | `bytes ` | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ---------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode` | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------- | -------------------------------- | ----- | +| hash | `Hash ` | The node hash. | | +| is_left_child_node | `bool ` | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint32 ` | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `sint64` | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ----------- | ------------------------------------------------------ | ----- | +| address | `Address ` | The scope address, which will be the contract address. | | +| path | `StatePath` | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | --------- | -------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code (0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| code_hash | `Hash ` | The hash of the contract code. | | +| is_system_contract | `bool ` | Whether it is a system contract. | | +| version | `int32 ` | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | --------- | ----------------------------------- | -------- | +| parts | `string ` | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ---------- | ------------------------------------------------------------------ | ----- | +| from | `Address ` | The address of the sender of the transaction. | | +| to | `Address ` | The address of the contract when calling a contract. | | +| ref_block_number | `int64 ` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes ` | The first four bytes of the referenced block hash. | | +| method_name | `string ` | The name of a method in the smart contract at the To address. | | +| params | `bytes ` | The parameters to pass to the smart contract method. | | +| signature | `bytes ` | When signing a transaction it’s actually a subset of the fields... | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | -------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry ` | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry ` | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry ` | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | ------------------------- | ------------------------------------------------------ | -------- | +| transaction_id | `Hash ` | The transaction id. | | +| status | `TransactionResultStatus` | The transaction result status. | | +| logs | `LogEvent ` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. | | +| return_value | `bytes ` | The return value of the transaction execution. | | +| block_number | `int64 ` | The height of the block that packages the transaction. | | +| block_hash | `Hash ` | The hash of the block that packages the transaction. | | +| error | `string ` | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | ------------------------------------------------------------------ | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully... | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other... | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +### AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | --------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address of the controller. | | +| owner_address | `aelf.Address ` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Cross Chain Contract.md b/docs/References/Smart Contract API/Cross Chain Contract.md new file mode 100644 index 0000000..b5ab2e3 --- /dev/null +++ b/docs/References/Smart Contract API/Cross Chain Contract.md @@ -0,0 +1,620 @@ +# AElf.Contracts.CrossChain + +Cross-Chain contract. + +Implement AElf Standards ACS1 and ACS7. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| -------------------------------------------- | ------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Initialize | `CrossChain.InitializeInput` | `google.protobuf.Empty` | Propose once cross chain indexing. | +| SetInitialSideChainLifetimeControllerAddress | `aelf.Address` | `google.protobuf.Empty` | Set the initial SideChainLifetimeController address which should be parliament organization by default. | +| SetInitialIndexingControllerAddress | `aelf.Address` | `google.protobuf.Empty` | Set the initial CrossChainIndexingController address which should be parliament organization by default. | +| ChangeCrossChainIndexingController | `AuthorityInfo` | `google.protobuf.Empty` | Change the cross chain indexing controller. | +| ChangeSideChainLifetimeController | `AuthorityInfo` | `google.protobuf.Empty` | Change the lifetime controller of the side chain. | +| ChangeSideChainIndexingFeeController | `CrossChain.ChangeSideChainIndexingFeeControllerInput` | `google.protobuf.Empty` | Change indexing fee adjustment controller for specific side chain. | +| AcceptCrossChainIndexingProposal | `CrossChain.AcceptCrossChainIndexingProposalInput` | `google.protobuf.Empty` | When the indexing proposal is released, clean up the pending proposal. | +| GetSideChainCreator | `google.protobuf.Int32Value` | `aelf.Address` | Get the side chain creator address according to side chain id. | +| GetChainStatus | `google.protobuf.Int32Value` | `CrossChain.GetChainStatusOutput` | Get the current status of side chain according to side chain id. | +| GetSideChainHeight | `google.protobuf.Int32Value` | `google.protobuf.Int64Value` | Get the side chain height according to side chain id. | +| GetParentChainHeight | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the height of parent chain. | +| GetParentChainId | `google.protobuf.Empty` | `google.protobuf.Int32Value` | Get the chain id of parent chain. | +| GetSideChainBalance | `google.protobuf.Int32Value` | `google.protobuf.Int64Value` | Get the balance of side chain indexing according to side chain id. | +| GetSideChainIndexingFeeDebt | `google.protobuf.Int32Value` | `google.protobuf.Int64Value` | Get the fee debt of side chain indexing according to side chain id. | +| GetIndexingProposalStatus | `google.protobuf.Empty` | `CrossChain.GetIndexingProposalStatusOutput` | Get the status of the current indexing proposal. | +| GetSideChainIndexingFeePrice | `google.protobuf.Int32Value` | `google.protobuf.Int64Value` | Get the side chain indexing fee price according to side chain id. | +| GetSideChainLifetimeController | `google.protobuf.Empty` | `AuthorityInfo` | Get the lifetime controller of the side chain. | +| GetCrossChainIndexingController | `google.protobuf.Empty` | `AuthorityInfo` | Get the cross chain indexing controller. | +| GetSideChainIndexingFeeController | `google.protobuf.Int32Value` | `AuthorityInfo` | Get the indexing fee controller of side chain according to side chain id. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees` | `google.protobuf.Empty` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue` | `acs1.MethodFees` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty` | `AuthorityInfo` | Query the method fee controller. | + +## AElf.Standards.ACS7 + +| Method Name | Request Type | Response Type | Description | +| ---------------------------------------------- | --------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| ProposeCrossChainIndexing | `acs7.CrossChainBlockData` | `google.protobuf.Empty` | Propose once cross chain indexing. | +| ReleaseCrossChainIndexingProposal | `acs7.ReleaseCrossChainIndexingProposalInput` | `google.protobuf.Empty` | Release the proposed indexing if already approved. | +| RequestSideChainCreation | `acs7.SideChainCreationRequest` | `google.protobuf.Empty` | Request side chain creation. | +| ReleaseSideChainCreation | `acs7.ReleaseSideChainCreationInput` | `google.protobuf.Empty` | Release the side chain creation request if already approved and it will call the method CreateSideChain. | +| CreateSideChain | `acs7.CreateSideChainInput` | `google.protobuf.Int32Value` | Create the side chain and returns the newly created side chain ID. | +| Recharge | `acs7.RechargeInput` | `google.protobuf.Empty` | Recharge for the specified side chain. | +| DisposeSideChain | `google.protobuf.Int32Value` | `google.protobuf.Int32Value` | Dispose a side chain according to side chain id. | +| AdjustIndexingFeePrice | `acs7.AdjustIndexingFeeInput` | `google.protobuf.Empty` | Adjust side chain indexing fee. | +| VerifyTransaction | `acs7.VerifyTransactionInput` | `google.protobuf.BoolValue` | Verify cross chain transaction. | +| GetSideChainIdAndHeight | `google.protobuf.Empty` | `acs7.ChainIdAndHeightDict` | Gets all the side chain id and height of the current chain. | +| GetSideChainIndexingInformationList | `google.protobuf.Empty` | `acs7.SideChainIndexingInformationList` | Get indexing information of side chains. | +| GetAllChainsIdAndHeight | `google.protobuf.Empty` | `acs7.ChainIdAndHeightDict` | Get id and recorded height of all chains. | +| GetIndexedSideChainBlockDataByHeight | `google.protobuf.Int64Value` | `acs7.IndexedSideChainBlockData` | Get block data of indexed side chain according to height. | +| GetBoundParentChainHeightAndMerklePathByHeight | `google.protobuf.Int64Value` | `acs7.CrossChainMerkleProofContext` | Get merkle path bound up with side chain according to height. | +| GetChainInitializationData | `google.protobuf.Int32Value` | `acs7.ChainInitializationData` | Get initialization data for specified side chain. | + +### CrossChain.AcceptCrossChainIndexingProposalInput + +| Field | Type | Description | Label | +| -------- | ----- | ---------------------------------- | ----- | +| chain_id | int32 | The chain id of accepted indexing. | | + +### CrossChain.ChainIndexingProposal + +| Field | Type | Description | Label | +| ------------------------------- | -------------------------------- | -------------------------------------------- | ----- | +| proposal_id | aelf.Hash | The id of cross chain indexing proposal. | | +| proposer | aelf.Address | The proposer of cross chain indexing. | | +| proposed_cross_chain_block_data | acs7.CrossChainBlockData | The cross chain data proposed. | | +| status | CrossChainIndexingProposalStatus | The status of cross chain indexing proposal. | | +| chain_id | int32 | The chain id of the indexing. | | + +### CrossChain.ChangeSideChainIndexingFeeControllerInput + +| Field | Type | Description | Label | +| -------------- | ------------- | --------------------------------------- | ----- | +| chain_id | int32 | The side chain id. | | +| authority_info | AuthorityInfo | The changed controller of indexing fee. | | + +### CrossChain.CrossChainIndexingControllerChanged + +| Field | Type | Description | Label | +| -------------- | ------------- | ----------------------------------- | ----- | +| authority_info | AuthorityInfo | The changed controller of indexing. | | + +### CrossChain.Disposed + +| Field | Type | Description | Label | +| -------- | ----- | --------------------------- | ----- | +| chain_id | int32 | The disposed side chain id. | | + +### CrossChain.GetChainStatusOutput + +| Field | Type | Description | Label | +| ------ | --------------- | ------------------------- | ----- | +| status | SideChainStatus | The status of side chain. | | + +### CrossChain.GetIndexingProposalStatusOutput + +| Field | Type | Description | Label | +| ------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------- | -------- | +| chain_indexing_proposal_status | GetIndexingProposalStatusOutput.ChainIndexingProposalStatusEntry | The collection of pending indexing proposal, the key is chain id. | repeated | + +#### CrossChain.GetIndexingProposalStatusOutput.ChainIndexingProposalStatusEntry + +| Field | Type | Description | Label | +| ----- | ---------------------------------- | ----------- | ----- | +| key | int32 | | | +| value | PendingChainIndexingProposalStatus | | | + +#### CrossChain.GetPendingCrossChainIndexingProposalOutput + +| Field | Type | Description | Label | +| ------------------------------- | ------------------------- | ------------------------------------------------------ | ----- | +| proposal_id | aelf.Hash | The proposal id of cross chain indexing. | | +| proposer | aelf.Address | The proposer of cross chain indexing proposal. | | +| to_be_released | bool | True if the proposal can be released, otherwise false. | | +| proposed_cross_chain_block_data | acs7.CrossChainBlockData | The cross chain data proposed. | | +| expired_time | google.protobuf.Timestamp | The proposal expiration time. | | + +#### CrossChain.InitializeInput + +| Field | Type | Description | Label | +| ------------------------------- | ----- | ------------------------------------------------- | ----- | +| parent_chain_id | int32 | The id of parent chain. | | +| creation_height_on_parent_chain | int64 | The height of side chain created on parent chain. | | +| is_privilege_preserved | bool | True if chain privilege needed, otherwise false. | | + +#### CrossChain.ParentChainIndexed + +| Field | Type | Description | Label | +| -------------- | ----- | ------------------------ | ----- | +| chain_id | bytes | Indexed parent chain id. | | +| indexed_height | int64 | Indexed block height. | | + +#### CrossChain.PendingChainIndexingProposalStatus + +| Field | Type | Description | Label | +| ------------------------------- | ------------------------- | ------------------------------------------------------ | ----- | +| proposal_id | aelf.Hash | The id of cross chain indexing proposal. | | +| proposer | aelf.Address | The proposer of cross chain indexing. | | +| to_be_released | bool | True if the proposal can be released, otherwise false. | | +| proposed_cross_chain_block_data | acs7.CrossChainBlockData | The cross chain data proposed. | | +| expired_time | google.protobuf.Timestamp | The proposal expiration time. | | + +#### CrossChain.ProposedCrossChainIndexing + +| Field | Type | Description | Label | +| ----------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- | -------- | +| chain_indexing_proposal_collections | ProposedCrossChainIndexing.ChainIndexingProposalCollectionsEntry | The collection of chain indexing proposal, the key is chain id. | repeated | + +#### CrossChain.ProposedCrossChainIndexing.ChainIndexingProposalCollectionsEntry + +| Field | Type | Description | Label | +| ----- | --------------------- | ----------- | ----- | +| key | int32 | | | +| value | ChainIndexingProposal | | | + +#### CrossChain.SideChainCreatedEvent + +| Field | Type | Description | Label | +| ------- | ------------ | -------------------------------------------------- | ----- | +| creator | aelf.Address | The proposer who propose to create the side chain. | | +| chainId | int32 | The created side chain id. | | + +#### CrossChain.SideChainCreationRequestState + +| Field | Type | Description | Label | +| --------------------------- | ----------------------------- | --------------------------------------------------- | ----- | +| side_chain_creation_request | acs7.SideChainCreationRequest | The parameters of creating side chain. | | +| expired_time | google.protobuf.Timestamp | The expiration date of the proposal. | | +| proposer | aelf.Address | The proposer who proposed to create the side chain. | | + +#### CrossChain.SideChainIndexed + +| Field | Type | Description | Label | +| -------------- | ----- | ---------------------- | ----- | +| chain_id | bytes | Indexed side chain id. | | +| indexed_height | int64 | Indexed block height. | | + +#### CrossChain.SideChainIndexingFeeControllerChanged + +| Field | Type | Description | Label | +| -------------- | ------------- | -------------------------------------------------- | ----- | +| chain_id | int32 | The side chain id. | | +| authority_info | AuthorityInfo | The changed controller of side chain indexing fee. | | + +#### CrossChain.SideChainInfo + +| Field | Type | Description | Label | +| ------------------------------- | ----------------------------------------- | ---------------------------------------------------- | -------- | +| proposer | aelf.Address | The proposer who propose to create the side chain. | | +| side_chain_status | CrossChain.SideChainStatus | The status of side chain. | | +| side_chain_id | int32 | The side chain id. | | +| creation_timestamp | google.protobuf.Timestamp | The time of side chain created. | | +| creation_height_on_parent_chain | int64 | The height of side chain created on parent chain. | | +| indexing_price | int64 | The price of indexing fee. | | +| is_privilege_preserved | bool | True if chain privilege needed, otherwise false. | | +| arrears_info | CrossChain.SideChainInfo.ArrearsInfoEntry | Creditor and amounts for the chain indexing fee debt | repeated | +| indexing_fee_controller | AuthorityInfo | The controller of indexing fee. | | + +#### CrossChain.SideChainInfo.ArrearsInfoEntry + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| key | string | | | +| value | int64 | | | + +#### CrossChain.SideChainLifetimeControllerChanged + +| Field | Type | Description | Label | +| -------------- | ------------- | ---------------------------------------------- | ----- | +| authority_info | AuthorityInfo | The changed controller of side chain lifetime. | | + +#### CrossChain.CrossChainIndexingProposalStatus + +| Name | Number | Description | +| ------------ | ------ | ------------------------------- | +| NON_PROPOSED | 0 | | +| PENDING | 1 | The proposal is pending. | +| ACCEPTED | 2 | The proposal has been released. | + +#### CrossChain.SideChainStatus + +| Name | Number | Description | +| ----------------- | ------ | ------------------------------------------- | +| FATAL | 0 | Currently no meaning. | +| ACTIVE | 1 | The side chain is being indexed. | +| INDEXING_FEE_DEBT | 2 | The side chain is in debt for indexing fee. | +| TERMINATED | 3 | The side chain is disposed. | + +# AElf.Standards.ACS1 + +## acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | ------ | ----------------------------------- | ----- | +| symbol | string | The token symbol of the method fee. | | +| basic_fee | int64 | The amount of fees to be charged. | | + +## acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | -------------- | ------------------------------------------------------------ | -------- | +| method_name | string | The name of the method to be charged. | | +| fees | acs1.MethodFee | List of fees to be charged. | repeated | +| is_size_fee_free | bool | Optional based on the implementation of SetMethodFee method. | | + +## AElf.Standards.ACS7 + +### acs7.AdjustIndexingFeeInput + +| Field | Type | Description | Label | +| ------------- | ----- | ------------------------------ | ----- | +| side_chain_id | int32 | The side chain id to adjust. | | +| indexing_fee | int64 | The new price of indexing fee. | | + +### acs7.ChainIdAndHeightDict + +| Field | Type | Description | Label | +| -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------- | -------- | +| id_height_dict | ChainIdAndHeightDict.IdHeightDictEntry | A collection of chain ids and heights, where the key is the chain id and the value is the height. | repeated | + +### acs7.ChainIdAndHeightDict.IdHeightDictEntry + +| Field | Type | Description | Label | +| ----- | ----- | ----------- | ----- | +| key | int32 | | | +| value | int64 | | | + +### acs7.ChainInitializationConsensusInfo + +| Field | Type | Description | Label | +| ---------------------- | ----- | ----------------------- | ----- | +| initial_consensus_data | bytes | Initial consensus data. | | + +### acs7.ChainInitializationData + +| Field | Type | Description | Label | +| ----------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- | ----- | +| chain_id | int32 | The id of side chain. | | +| creator | aelf.Address | The side chain creator. | | +| creation_timestamp | google.protobuf.Timestamp | The timestamp for side chain creation. | | +| creation_height_on_parent_chain | int64 | The height of side chain creation on parent chain. | | +| chain_creator_privilege_preserved | bool | Creator privilege boolean flag: True if chain creator privilege preserved, otherwise false. | | +| parent_chain_token_contract_address | aelf.Address | Parent chain token contract address. | | +| chain_initialization_consensus_info | ChainInitializationConsensusInfo | Initial consensus information. | | +| native_token_info_data | bytes | The native token info. | | +| resource_token_info | ResourceTokenInfo | The resource token information. | | +| chain_primary_token_info | ChainPrimaryTokenInfo | The chain primary token information. | | + +### acs7.ChainPrimaryTokenInfo + +| Field | Type | Description | Label | +| ----------------------------------- | -------------------------- | ------------------------------------------------ | -------- | +| chain_primary_token_data | bytes | The side chain primary token data. | | +| side_chain_token_initial_issue_list | SideChainTokenInitialIssue | The side chain primary token initial issue list. | repeated | + +### acs7.CreateSideChainInput + +| Field | Type | Description | Label | +| --------------------------- | ------------------------ | --------------------------------------------------- | ----- | +| side_chain_creation_request | SideChainCreationRequest | The request information of the side chain creation. | | +| proposer | aelf.Address | The proposer of the side chain creation. | | + +### acs7.CrossChainBlockData + +| Field | Type | Description | Label | +| ---------------------------- | -------------------- | ------------------------------------------ | -------- | +| side_chain_block_data_list | SideChainBlockData | The side chain block data list to index. | repeated | +| parent_chain_block_data_list | ParentChainBlockData | The parent chain block data list to index. | repeated | + +### acs7.CrossChainExtraData + +| Field | Type | Description | Label | +| ----------------------------------- | --------- | ------------------------------------------------------------- | ----- | +| transaction_status_merkle_tree_root | aelf.Hash | Merkle tree root of side chain block transaction status root. | | + +### acs7.CrossChainIndexingDataProposedEvent + +| Field | Type | Description | Label | +| ------------------------- | ------------------- | ---------------------------------------- | ----- | +| proposed_cross_chain_data | CrossChainBlockData | Proposed cross chain data to be indexed. | | +| proposal_id | aelf.Hash | The proposal id. | | + +### acs7.CrossChainMerkleProofContext + +| Field | Type | Description | Label | +| ----------------------------- | --------------- | ---------------------------------------------------- | ----- | +| bound_parent_chain_height | int64 | The height of parent chain bound up with side chain. | | +| merkle_path_from_parent_chain | aelf.MerklePath | The merkle path generated from parent chain. | | + +### acs7.IndexedParentChainBlockData + +| Field | Type | Description | Label | +| ---------------------------- | -------------------- | ------------------------------------------------------------- | -------- | +| local_chain_height | int64 | The height of the local chain when indexing the parent chain. | | +| parent_chain_block_data_list | ParentChainBlockData | Parent chain block data. | repeated | + +### acs7.IndexedSideChainBlockData + +| Field | Type | Description | Label | +| -------------------------- | ------------------ | ---------------------- | -------- | +| side_chain_block_data_list | SideChainBlockData | Side chain block data. | repeated | + +### acs7.ParentChainBlockData + +| Field | Type | Description | Label | +| ----------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- | -------- | +| height | int64 | The height of parent chain. | | +| cross_chain_extra_data | CrossChainExtraData | The merkle tree root computing from side chain roots. | | +| chain_id | int32 | The parent chain id. | | +| transaction_status_merkle_tree_root | aelf.Hash | The merkle tree root computing from transactions status in parent chain block. | | +| indexed_merkle_path | ParentChainBlockData.IndexedMerklePathEntry | Indexed block height from side chain and merkle path for this side chain block. | repeated | +| extra_data | ParentChainBlockData.ExtraDataEntry | Extra data map. | repeated | + +### acs7.ParentChainBlockData.ExtraDataEntry + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| key | string | | | +| value | bytes | | | + +### acs7.ParentChainBlockData.IndexedMerklePathEntry + +| Field | Type | Description | Label | +| ----- | ----------------- | ----------- | ----- | +| key | `int64 ` | | | +| value | `aelf.MerklePath` | | | + +### acs7.RechargeInput + +| Field | Type | Description | Label | +| -------- | -------- | ------------------------- | ----- | +| chain_id | `int32 ` | The chain id to recharge. | | +| amount | `int64 ` | The amount to recharge. | | + +### acs7.ReleaseCrossChainIndexingProposalInput + +| Field | Type | Description | Label | +| ------------- | -------- | ----------------------------- | -------- | +| chain_id_list | `int32 ` | List of chain ids to release. | repeated | + +### acs7.ReleaseSideChainCreationInput + +| Field | Type | Description | Label | +| ----------- | ------------ | --------------------------------------- | ----- | +| proposal_id | `aelf.Hash ` | The proposal id of side chain creation. | | + +### acs7.ResourceTokenInfo + +| Field | Type | Description | Label | +| ------------------------ | ----------------------------- | ---------------------------------- | -------- | +| resource_token_list_data | `bytes ` | The resource token information. | | +| initial_resource_amount | `InitialResourceAmountEntry ` | The initial resource token amount. | repeated | + +### acs7.ResourceTokenInfo.InitialResourceAmountEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int32 ` | | | + +### acs7.SideChainBlockData + +| Field | Type | Description | Label | +| ----------------------------------- | ------------ | ---------------------------------------------------------------------------- | ----- | +| height | `int64 ` | The height of side chain block. | | +| block_header_hash | `aelf.Hash ` | The hash of side chain block. | | +| transaction_status_merkle_tree_root | `aelf.Hash ` | The merkle tree root computing from transactions status in side chain block. | | +| chain_id | `int32 ` | The id of side chain. | | + +### acs7.SideChainCreationRequest + +| Field | Type | Description | Label | +| ----------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- | -------- | +| indexing_price | `int64 ` | The cross chain indexing price. | | +| locked_token_amount | `int64 ` | Initial locked balance for a new side chain. | | +| is_privilege_preserved | `bool ` | Creator privilege boolean flag: True if chain creator privilege preserved, otherwise false. | | +| side_chain_token_creation_request | `SideChainTokenCreationRequest ` | Side chain token information. | | +| side_chain_token_initial_issue_list | `SideChainTokenInitialIssue ` | A list of accounts and amounts that will be issued when the chain starts. | repeated | +| initial_resource_amount | `InitialResourceAmountEntry ` | The initial rent resources. | repeated | + +### acs7.SideChainCreationRequest.InitialResourceAmountEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int32 ` | | | + +### acs7.SideChainIndexingInformation + +| Field | Type | Description | Label | +| -------------- | -------- | ------------------- | ----- | +| chain_id | `int32 ` | The side chain id. | | +| indexed_height | `int64 ` | The indexed height. | | + +### acs7.SideChainIndexingInformationList + +| Field | Type | Description | Label | +| ------------------------- | ------------------------------- | ---------------------------------------------------- | -------- | +| indexing_information_list | `SideChainIndexingInformation ` | A list contains indexing information of side chains. | repeated | + +### acs7.SideChainTokenCreationRequest + +| Field | Type | Description | Label | +| ----------------------------- | --------- | -------------------------------------------------- | ----- | +| side_chain_token_symbol | `string ` | Token symbol of the side chain to be created | | +| side_chain_token_name | `string ` | Token name of the side chain to be created | | +| side_chain_token_total_supply | `int64 ` | Token total supply of the side chain to be created | | +| side_chain_token_decimals | `int32 ` | Token decimals of the side chain to be created | | + +### acs7.SideChainTokenInitialIssue + +| Field | Type | Description | Label | +| ------- | --------------- | -------------------------------- | ----- | +| address | `aelf.Address ` | The account that will be issued. | | +| amount | `int64 ` | The amount that will be issued. | | + +### acs7.VerifyTransactionInput + +| Field | Type | Description | Label | +| ------------------- | ------------------- | ---------------------------------------------------------- | ----- | +| transaction_id | `aelf.Hash ` | The cross chain transaction id to verify. | | +| path | `aelf.MerklePath ` | The merkle path of the transaction. | | +| parent_chain_height | `int64 ` | The height of parent chain that indexing this transaction. | | +| verified_chain_id | `int32 ` | The chain if to verify. | | + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | -------- | ----------------------- | -------- | +| nodes | `Hash ` | The leaf nodes. | repeated | +| root | `Hash ` | The root node hash. | | +| leaf_count | `int32 ` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ---------- | ------------------------------------------ | -------- | +| address | `Address ` | The contract address. | | +| name | `string ` | The name of the log event. | | +| indexed | `bytes ` | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes ` | The non-indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ------------------ | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode ` | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------- | -------------------------------- | ----- | +| hash | `Hash ` | The node hash. | | +| is_left_child_node | `bool ` | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint32 ` | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint64 ` | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ------------ | ------------------------------------------------------ | ----- | +| address | `Address ` | The scope address, which will be the contract address. | | +| path | `StatePath ` | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | --------- | -------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code (0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| code_hash | `Hash ` | The hash of the contract code. | | +| is_system_contract | `bool ` | Whether it is a system contract. | | +| version | `int32 ` | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | --------- | ----------------------------------- | -------- | +| parts | `string ` | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | `Address ` | The address of the sender of the transaction. | | +| to | `Address ` | The address of the contract when calling a contract. | | +| ref_block_number | `int64 ` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes ` | The first four bytes of the referenced block hash. | | +| method_name | `string ` | The name of a method in the smart contract at the To address. | | +| params | `bytes ` | The parameters to pass to the smart contract method. | | +| signature | `bytes ` | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | -------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry ` | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry ` | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry ` | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| transaction_id | `Hash ` | The transaction id. | | +| status | `TransactionResultStatus ` | The transaction result status. | | +| logs | `LogEvent ` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. | | +| return_value | `bytes ` | The return value of the transaction execution. | | +| block_number | `int64 ` | The height of the block that packages the transaction. | | +| block_hash | `Hash ` | The hash of the block that packages the transaction. | | +| error | `string ` | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +# AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | --------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address of the controller. | | +| owner_address | `aelf.Address ` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Economic Contract.md b/docs/References/Smart Contract API/Economic Contract.md new file mode 100644 index 0000000..33e6380 --- /dev/null +++ b/docs/References/Smart Contract API/Economic Contract.md @@ -0,0 +1,225 @@ +# AElf.Contracts.Economic + +## Economic Contract + +The Economic contract establishes the economic system of the AElf. When the blockchain starts to work, this contract will initialize other contracts related to economic activities. + +Implements AElf Standards ACS1. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| --------------------- | -------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| IssueNativeToken | [Economic.IssueNativeTokenInput](#economicissuenativetokeninput) | [google.protobuf.Empty](#googleprotobufempty) | Only ZeroContract is able to issue the native token. | +| InitialEconomicSystem | [Economic.InitialEconomicSystemInput](#economicinitialeconomicsysteminput) | [google.protobuf.Empty](#googleprotobufempty) | It will initialize other contracts related to economic activities (For instance, create the native token). This transaction only can be sent once because after the first sending, its state will be set to initialized. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | --------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | [acs1.MethodFees](#acs1methodfees) | [google.protobuf.Empty](#googleprotobufempty) | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | [AuthorityInfo](#authorityinfo) | [google.protobuf.Empty](#googleprotobufempty) | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | [google.protobuf.StringValue](#googleprotobufstringvalue) | [acs1.MethodFees](#acs1methodfees) | Query method fee information by method name. | +| GetMethodFeeController | [google.protobuf.Empty](#googleprotobufempty) | [AuthorityInfo](#authorityinfo) | Query the method fee controller. | + +## Contract Types + +### AElf.Contracts.Economic + +#### Economic.InitialEconomicSystemInput + +| Field | Type | Description | Label | +| ------------------------------- | ----------------- | ----------------------------------------------------------------- | ----- | +| native_token_symbol | [string](#string) | The native token symbol. | | +| native_token_name | [string](#string) | The native token name. | | +| native_token_total_supply | [int64](#int64) | The native token total supply. | | +| native_token_decimals | [int32](#int32) | The accuracy of the native token. | | +| is_native_token_burnable | [bool](#bool) | It indicates if the token is burnable. | | +| mining_reward_total_amount | [int64](#int64) | It determines how much native token is used to reward the miners. | | +| transaction_size_fee_unit_price | [int64](#int64) | todo: remove unused fields | | + +#### Economic.IssueNativeTokenInput + +| Field | Type | Description | Label | +| ------ | ---------------------------- | --------------------------- | ----- | +| amount | [int64](#int64) | The amount of token. | | +| memo | [string](#string) | The memo. | | +| to | [aelf.Address](#aelfaddress) | The recipient of the token. | | + +#### Economic.IssueResourceTokenInput + +| Field | Type | Description | Label | +| ------ | ---------------------------- | ----------------------------- | ----- | +| symbol | [string](#string) | The symbol of resource token. | | +| amount | [int64](#int64) | The amount of resource token. | | +| memo | [string](#string) | The memo. | | +| to | [aelf.Address](#aelfaddress) | The recipient of the token. | | + +### AElf.Standards.ACS1 + +#### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | ----------------- | ----------------------------------- | ----- | +| symbol | [string](#string) | The token symbol of the method fee. | | +| basic_fee | [int64](#int64) | The amount of fees to be charged. | | + +#### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | --------------------------- | ------------------------------------------------------------ | -------- | +| method_name | [string](#string) | The name of the method to be charged. | | +| fees | [MethodFee](#acs1methodfee) | List of fees to be charged. | repeated | +| is_size_fee_free | [bool](#bool) | Optional based on the implementation of SetMethodFee method. | | + +### AElf.Types + +#### aelf.Address + +| Field | Type | Description | Label | +| ----- | --------------- | ----------- | ----- | +| value | [bytes](#bytes) | | | + +#### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | ----------------- | ----------------------- | -------- | +| nodes | [Hash](#aelfhash) | The leaf nodes. | repeated | +| root | [Hash](#aelfhash) | The root node hash. | | +| leaf_count | [int32](#int32) | The count of leaf node. | | + +#### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +#### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ---------- | ------------------------------------------ | -------- | +| address | `Address ` | The contract address. | | +| name | `string ` | The name of the log event. | | +| indexed | `bytes ` | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes ` | The non indexed data. | | + +#### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ----------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode ` | The merkle path nodes. | repeated | + +#### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------- | -------------------------------- | ----- | +| hash | `Hash ` | The node hash. | | +| is_left_child_node | `bool ` | Whether it is a left child node. | | + +#### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint32 ` | | | + +#### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint64 ` | | | + +#### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ------------ | ------------------------------------------------------ | ----- | +| address | `Address ` | The scope address, which will be the contract address. | | +| path | `StatePath ` | The path of contract state. | | + +#### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | --------- | ------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code(0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| code_hash | `Hash ` | The hash of the contract code. | | +| is_system_contract | `bool ` | Whether it is a system contract. | | +| version | `int32 ` | The version of the current contract. | | + +#### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | --------- | ----------------------------------- | -------- | +| parts | `string ` | The partial path of the state path. | repeated | + +#### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | `Address ` | The address of the sender of the transaction. | | +| to | `Address ` | The address of the contract when calling a contract. | | +| ref_block_number | `int64 ` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes ` | The first four bytes of the referenced block hash. | | +| method_name | `string ` | The name of a method in the smart contract at the To address. | | +| params | `bytes ` | The parameters to pass to the smart contract method. | | +| signature | `bytes ` | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | | + +#### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | -------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry ` | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry` | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry ` | The deleted states. | repeated | + +#### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +#### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +#### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +#### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| transaction_id | `Hash ` | The transaction id. | | +| status | `TransactionResultStatus ` | The transaction result status. | | +| logs | `LogEvent ` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. Through this filter, we can quickly search for and determine whether a log exists in the transaction result. | | +| return_value | `bytes ` | The return value of the transaction execution. | | +| block_number | `int64 ` | The height of the block hat packages the transaction. | | +| block_hash | `Hash ` | The hash of the block hat packages the transaction. | | +| error | `string ` | Failed execution error message. | | + +#### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +## AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | --------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address of the controller. | | +| owner_address | `aelf.Address ` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Election Contract.md b/docs/References/Smart Contract API/Election Contract.md new file mode 100644 index 0000000..1c5a79e --- /dev/null +++ b/docs/References/Smart Contract API/Election Contract.md @@ -0,0 +1,528 @@ +# AElf.Contracts.Election + +## Election contract + +Used for voting for Block Producers.Implement AElf Standards ACS1. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ---------------------------------- | -------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| InitialElectionContract | `Election.InitialElectionContractInput` | `google.protobuf.Empty` | Initialize the election contract. | +| RegisterElectionVotingEvent | `google.protobuf.Empty` | `google.protobuf.Empty` | Register a new voting item through the vote contract. | +| TakeSnapshot | `Election.TakeElectionSnapshotInput` | `google.protobuf.Empty` | Take a snapshot according to the term number and distribute profits. | +| AnnounceElection | `aelf.Address` | `google.protobuf.Empty` | To be a block producer, a user should first register to be a candidate and lock some tokens as a deposit. If the data center is not full, the user will be added automatically and get one weight for sharing a bonus in the future. | +| QuitElection | `google.protobuf.StringValue` | `google.protobuf.Empty` | A candidate is able to quit the election provided they are not currently elected. If you quit successfully, the candidate will get their locked tokens back and will not receive any more bonus. | +| Vote | `Election.VoteMinerInput` | `aelf.Hash` | Used for voting for a candidate to be elected. The tokens you vote with will be locked until the end time. According to the number of tokens you voted and their lock time, you can get a corresponding weight for sharing the bonus in the future. Returns the vote id. | +| ChangeVotingOption | `Election.ChangeVotingOptionInput` | `google.protobuf.Empty` | Before the end time, you are able to change your vote target to other candidates. | +| Withdraw | `aelf.Hash` | `google.protobuf.Empty` | After the lock time, your locked tokens will be unlocked, and you can withdraw them according to the vote id. | +| UpdateCandidateInformation | `Election.UpdateCandidateInformationInput` | `google.protobuf.Empty` | Update candidate information by the consensus contract. | +| UpdateMultipleCandidateInformation | `Election.UpdateMultipleCandidateInformationInput` | `google.protobuf.Empty` | Batch update candidate information by the consensus contract. | +| UpdateMinersCount | `Election.UpdateMinersCountInput` | `google.protobuf.Empty` | Update the count of miners by the consensus contract. | +| SetProfitsReceiver | `Election.SetProfitsReceiverInput` | `google.protobuf.Empty` | Set the collect profits receiver address. | +| SetTreasurySchemeIds | `Election.SetTreasurySchemeIdsInput` | `google.protobuf.Empty` | Set the treasury profit ids. | +| SetVoteWeightInterest | `Election.VoteWeightInterestList` | `google.protobuf.Empty` | Set the weight of vote interest. | +| SetVoteWeightProportion | `Election.VoteWeightProportion` | `google.protobuf.Empty` | Set the weight of lock time and votes in the calculation of voting weight. | +| ChangeVoteWeightInterestController | `AuthorityInfo` | `google.protobuf.Empty` | Change the controller for the weight of vote interest. | +| ReplaceCandidatePubkey | `Election.ReplaceCandidatePubkeyInput` | `google.protobuf.Empty` | Candidate admin can replace the candidate pubkey with a new pubkey. | +| SetCandidateAdmin | `Election.SetCandidateAdminInput` | `google.protobuf.Empty` | Set the admin address of the candidate (mostly supply). | +| GetCandidates | `google.protobuf.Empty` | `Election.PubkeyList` | Get all candidates' public keys. | +| GetVotedCandidates | `google.protobuf.Empty` | `Election.PubkeyList` | Get all candidates whose number of votes is greater than 0. | +| | +| GetCandidateInformation | `google.protobuf.StringValue` | `Election.CandidateInformation` | Get a candidate’s information. | +| GetVictories | `google.protobuf.Empty` | `Election.PubkeyList` | Get the victories of the latest term. | +| GetTermSnapshot | `Election.GetTermSnapshotInput` | `Election.TermSnapshot` | Get the snapshot of term according to the term number. | +| GetMinersCount | `google.protobuf.Empty` | `google.protobuf.Int32Value` | Get the count of miners. | +| GetElectionResult | `Election.GetElectionResultInput` | `Election.ElectionResult` | Get the election result according to the term id. | +| GetElectorVote | `google.protobuf.StringValue` | `Election.ElectorVote` | Get the voter information according to the voter public key. | +| GetElectorVoteWithRecords | `google.protobuf.StringValue` | `Election.ElectorVote` | Gets the voter information including the active voting records (excluding withdrawn voting records). | +| GetElectorVoteWithAllRecords | `google.protobuf.StringValue` | `Election.ElectorVote` | Gets the voter information including the active and withdrawn voting records. | +| GetCandidateVote | `google.protobuf.StringValue` | `Election.CandidateVote` | Get voting information for the candidate according to the public key of the candidate. | +| GetCandidateVoteWithRecords | `google.protobuf.StringValue` | `Election.CandidateVote` | Get voting information for the candidate according to the public key of the candidate. | +| GetCandidateVoteWithAllRecords | `google.protobuf.StringValue` | `Election.CandidateVote` | Get voting information for the candidate according to the public key of the candidate (including the active and withdrawn voting records). | +| GetVotersCount | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the total number of voters. | +| GetVotesAmount | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Get the total number of vote tokens. | +| GetPageableCandidateInformation | `Election.PageInformation` | `Election.GetPageableCandidateInformationOutput` | Get candidate information according to the index and length. | +| GetMinerElectionVotingItemId | `google.protobuf.Empty` | `aelf.Hash` | Get the voting item id of miner election. | +| GetDataCenterRankingList | `google.protobuf.Empty` | `Election.DataCenterRankingList` | Get the data center ranking list. | +| GetVoteWeightSetting | `google.protobuf.Empty` | `Election.VoteWeightInterestList` | Get the weight of vote interest. | +| GetVoteWeightProportion | `google.protobuf.Empty` | `Election.VoteWeightProportion` | Get the weight of lock time and votes in the calculation of voting weight. | +| GetCalculateVoteWeight | `Election.VoteInformation` | `google.protobuf.Int64Value` | Used to calculate the bonus weights that users can get by voting. | +| GetVoteWeightInterestController | `google.protobuf.Empty` | `AuthorityInfo` | Query the controller for the weight of vote interest. | +| GetMinerReplacementInformation | `Election.GetMinerReplacementInformationInput` | `Election.MinerReplacementInformation` | Inspect the evil nodes included in the specified miners and return to the replacement node. | +| GetCandidateAdmin | `google.protobuf.StringValue` | `aelf.Address` | Query candidate admin. | +| GetNewestPubkey | `google.protobuf.StringValue` | `google.protobuf.StringValue` | Query the newest pubkey of an old pubkey. | +| GetReplacedPubkey | `google.protobuf.StringValue` | `google.protobuf.StringValue` | Query the old pubkey. | + +# AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees` | `google.protobuf.Empty` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue` | `acs1.MethodFees` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty` | `AuthorityInfo` | Query the method fee controller. | + +# Contract Types + +## AElf.Contracts.Election + +### Election.CandidateDetail + +| Field | Type | Description | Label | +| --------------------- | ---------------------- | --------------------------------------------- | ----- | +| candidate_information | `CandidateInformation` | The candidate information. | | +| obtained_votes_amount | `int64` | The number of votes a candidate has obtained. | | + +### Election.CandidateInformation + +| Field | Type | Description | Label | +| --------------------------- | ----------- | ------------------------------------------------------------------ | -------- | +| pubkey | `string` | Candidate’s public key. | | +| terms | `int64` | The number of terms that the candidate is elected. | repeated | +| produced_blocks | `int64` | The number of blocks the candidate has produced. | | +| missed_time_slots | `int64` | The time slot for which the candidate failed to produce blocks. | | +| continual_appointment_count | `int64` | The count of continual appointment. | | +| announcement_transaction_id | `aelf.Hash` | The transaction id when the candidate announced. | | +| is_current_candidate | `bool` | Indicate whether the candidate can be elected in the current term. | | + +### Election.CandidatePubkeyReplaced + +| Field | Type | Description | Label | +| ---------- | -------- | ----------- | ----- | +| old_pubkey | `string` | | | +| new_pubkey | `string` | | | + +### Election.CandidateVote + +| Field | Type | Description | Label | +| ------------------------------------ | ---------------------- | ------------------------------------------------- | -------- | +| obtained_active_voting_record_ids | `aelf.Hash` | The active voting record ids obtained. | repeated | +| obtained_withdrawn_voting_record_ids | `aelf.Hash` | The active voting record ids that were withdrawn. | repeated | +| obtained_active_voted_votes_amount | `int64` | The total number of active votes obtained. | | +| all_obtained_voted_votes_amount | `int64` | The total number of votes obtained. | | +| obtained_active_voting_records | `ElectionVotingRecord` | The active voting records. | repeated | +| obtained_withdrawn_votes_records | `ElectionVotingRecord` | The voting records that were withdrawn. | repeated | +| pubkey | `bytes` | Public key for candidate. | | + +### Election.ChangeVotingOptionInput + +| Field | Type | Description | Label | +| ---------------- | ----------- | ----------------------------- | ----- | +| vote_id | `aelf.Hash` | The vote id to change. | | +| candidate_pubkey | `string` | The new candidate public key. | | + +### Election.DataCenterRankingList + +| Field | Type | Description | Label | +| ------------ | ---------------------------------------- | -------------------------------------------------------------------------------- | -------- | +| data_centers | `DataCenterRankingList.DataCentersEntry` | The top n \* 5 candidates with vote amount, candidate public key -> vote amount. | repeated | + +### Election.DataCenterRankingList.DataCentersEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +### Election.ElectionResult + +| Field | Type | Description | Label | +| ----------- | ----------------------------- | --------------------------------------------------------------- | -------- | +| term_number | `int64` | The term number | | +| results | `ElectionResult.ResultsEntry` | The election result, candidates’ public key -> number of votes. | repeated | +| is_active | `bool` | Whether an election is currently being held. | | + +### Election.ElectionResult.ResultsEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +### Election.ElectionVotingRecord + +| Field | Type | Description | Label | +| ------------------ | --------------------------- | ----------------------------------------- | ----- | +| voter | `aelf.Address` | The address of voter. | | +| candidate | `string` | The public key of candidate. | | +| amount | `int64` | Amount of voting. | | +| term_number | `int64` | The term number of voting. | | +| vote_id | `aelf.Hash` | The vote id. | | +| lock_time | `int64` | Vote lock time. | | +| unlock_timestamp | `google.protobuf.Timestamp` | The unlock timestamp. | | +| withdraw_timestamp | `google.protobuf.Timestamp` | The withdraw timestamp. | | +| vote_timestamp | `google.protobuf.Timestamp` | The vote timestamp. | | +| is_withdrawn | `bool` | Indicates if the vote has been withdrawn. | | +| weight | `int64` | Vote weight for sharing bonus. | | +| is_change_target | `bool` | Whether vote others. | | + +### Election.ElectorVote + +| Field | Type | Description | Label | +| --------------------------- | ---------------------- | -------------------------------------------------------------------- | -------- | +| active_voting_record_ids | `aelf.Hash` | The active voting record ids. | repeated | +| withdrawn_voting_record_ids | `aelf.Hash` | The voting record ids that were withdrawn. | repeated | +| active_voted_votes_amount | `int64` | The total number of active votes. | | +| all_voted_votes_amount | `int64` | The total number of votes (including the number of votes withdrawn). | | +| active_voting_records | `ElectionVotingRecord` | The active voting records. | repeated | +| withdrawn_votes_records | `ElectionVotingRecord` | The voting records that were withdrawn. | repeated | +| pubkey | `bytes` | Public key for voter. | | +| address | `aelf.Address` | Address for voter. | | + +### Election.EvilMinerDetected + +| Field | Type | Description | Label | +| ------ | -------- | ----------------------------- | ----- | +| pubkey | `string` | The public key of evil miner. | | + +### Election.GetElectionResultInput + +| Field | Type | Description | Label | +| ----------- | ------- | ---------------- | ----- | +| term_number | `int64` | The term number. | | + +### Election.GetMinerReplacementInformationInput + +| Field | Type | Description | Label | +| ------------------ | -------- | ---------------------------------- | -------- | +| current_miner_list | `string` | The current miner list to inspect. | repeated | + +### Election.GetPageableCandidateInformationOutput + +| Field | Type | Description | Label | +| ----- | ----------------- | ------------------------------ | -------- | +| value | `CandidateDetail` | The details of the candidates. | repeated | + +### Election.GetTermSnapshotInput + +| Field | Type | Description | Label | +| ----------- | ------- | ---------------- | ----- | +| term_number | `int64` | The term number. | | + +### Election.InitialElectionContractInput + +| Field | Type | Description | Label | +| ----------------------- | -------- | -------------------------------------------------------- | -------- | +| minimum_lock_time | `int64` | Minimum number of seconds for locking. | | +| maximum_lock_time | `int64` | Maximum number of seconds for locking. | | +| miner_list | `string` | The current miner list. | repeated | +| time_each_term | `int64` | The number of seconds per term. | | +| miner_increase_interval | `int64` | The interval second that increases the number of miners. | | + +### Election.MinerReplacementInformation + +| Field | Type | Description | Label | +| ----------------------------- | -------- | -------------------------------------- | -------- | +| alternative_candidate_pubkeys | `string` | The alternative candidate public keys. | repeated | +| evil_miner_pubkeys | `string` | The evil miner public keys. | repeated | + +### Election.PageInformation + +| Field | Type | Description | Label | +| ------ | ------- | ---------------------- | ----- | +| start | `int32` | The start index. | | +| length | `int32` | The number of records. | | + +### Election.PubkeyList + +| Field | Type | Description | Label | +| ----- | ------- | ----------------------- | -------- | +| value | `bytes` | Candidates’ public keys | repeated | + +### Election.ReplaceCandidatePubkeyInput + +| Field | Type | Description | Label | +| ---------- | -------- | ----------- | ----- | +| old_pubkey | `string` | | | +| new_pubkey | `string` | | | + +### Election.SetCandidateAdminInput + +| Field | Type | Description | Label | +| ------ | -------------- | ----------- | ----- | +| pubkey | `string` | | | +| admin | `aelf.Address` | | | + +### Election.SetProfitsReceiverInput + +| Field | Type | Description | Label | +| ------------------------- | -------------- | ----------------------------------------- | ----- | +| candidate_pubkey | `string` | The candidate's public key. | | +| profits_receiver_address | `aelf.Address` | The address of profits receiver. | | +| previous_receiver_address | `aelf.Address` | The previous address of profits receiver. | | + +### Election.SetTreasurySchemeIdsInput + +| Field | Type | Description | Label | +| ----------------------- | ----------- | ------------------------------------ | ----- | +| treasury_hash | `aelf.Hash` | The scheme id of treasury reward. | | +| welfare_hash | `aelf.Hash` | The scheme id of welfare reward. | | +| subsidy_hash | `aelf.Hash` | The scheme id of subsidy reward. | | +| votes_reward_hash | `aelf.Hash` | The scheme id of votes reward. | | +| re_election_reward_hash | `aelf.Hash` | The scheme id of re-election reward. | | + +### Election.TakeElectionSnapshotInput + +| Field | Type | Description | Label | +| ------------ | ------- | ---------------------------------------- | ----- | +| term_number | `int64` | The term number to take snapshot. | | +| mined_blocks | `int64` | The number of mined blocks of this term. | | +| round_number | `int64` | The end round number of this term. | | + +### Election.TermSnapshot + +| Field | Type | Description | Label | +| ---------------- | -------------------------------------------------------------- | --------------------------------------------------------------- | -------- | +| end_round_number | `int64` | The end round number of this term. | | +| mined_blocks | `int64` | The number of blocks mined in this term. | | +| election_result | `TermSnapshot.ElectionResultEntry` (key: string, value: int64) | The election result, candidates’ public key -> number of votes. | repeated | + +### Election.TermSnapshot.ElectionResultEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +### Election.UpdateCandidateInformationInput + +| Field | Type | Description | Label | +| -------------------------- | -------- | ------------------------------------------------------- | ----- | +| pubkey | `string` | The candidate public key. | | +| recently_produced_blocks | `int64` | The number of blocks recently produced. | | +| recently_missed_time_slots | `int64` | The number of time slots recently missed. | | +| is_evil_node | `bool` | Is it an evil node. If true, will remove the candidate. | | + +### Election.UpdateMinersCountInput + +| Field | Type | Description | Label | +| ------------ | ------- | ------------------- | ----- | +| miners_count | `int32` | The count of miner. | | + +### Election.UpdateMultipleCandidateInformationInput + +| Field | Type | Description | Label | +| ----- | --------------------------------------------- | ------------------------------------ | -------- | +| value | `UpdateCandidateInformationInput` (see below) | The candidate information to update. | repeated | + +### UpdateCandidateInformationInput + +| Field | Type | Description | Label | +| -------------------------- | -------- | ------------------------------------------------------- | ----- | +| pubkey | `string` | The candidate public key. | | +| recently_produced_blocks | `int64` | The number of blocks recently produced. | | +| recently_missed_time_slots | `int64` | The number of time slots recently missed. | | +| is_evil_node | `bool` | Is it an evil node. If true, will remove the candidate. | | + +### Election.UpdateTermNumberInput + +| Field | Type | Description | Label | +| ----------- | ------- | ---------------- | ----- | +| term_number | `int64` | The term number. | | + +### Election.VoteInformation + +| Field | Type | Description | Label | +| --------- | ------- | ----------------- | ----- | +| amount | `int64` | Amount of voting. | | +| lock_time | `int64` | Vote lock time. | | + +### Election.VoteMinerInput + +| Field | Type | Description | Label | +| ---------------- | --------------------------- | ------------------------------- | ----- | +| candidate_pubkey | `string` | The candidate public key. | | +| amount | `int64` | The amount token to vote. | | +| end_timestamp | `google.protobuf.Timestamp` | The end timestamp of this vote. | | +| token | `aelf.Hash` | Used to generate vote id. | | + +### Election.VoteWeightInterest + +| Field | Type | Description | Label | +| -------- | ------- | ---------------------- | ----- | +| day | `int32` | Number of days locked. | | +| interest | `int32` | Locked interest. | | +| capital | `int32` | | | + +### Election.VoteWeightInterestList + +| Field | Type | Description | Label | +| -------------------------- | -------------------------------- | ---------------------------- | -------- | +| vote_weight_interest_infos | `VoteWeightInterest` (see above) | The weight of vote interest. | repeated | + +### Election.VoteWeightProportion + +| Field | Type | Description | Label | +| ----------------- | ------- | ----------------------------- | ----- | +| time_proportion | `int32` | The weight of lock time. | | +| amount_proportion | `int32` | The weight of the votes cast. | | + +# AElf.Standards.ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | -------- | ----------------------------------- | ----- | +| symbol | `string` | The token symbol of the method fee. | | +| basic_fee | `int64` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ----------------------- | ------------------------------------------------------------ | -------- | +| method_name | `string` | The name of the method to be charged. | | +| fees | `MethodFee` (see above) | List of fees to be charged. | repeated | +| is_size_fee_free | `bool` | Optional based on the implementation of SetMethodFee method. | | + +## AElf.Types + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | ------------------ | ----------------------- | -------- | +| nodes | `Hash` (see below) | The leaf nodes. | repeated | +| root | `Hash` (see below) | The root node hash. | | +| leaf_count | `int32` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | --------------------- | ------------------------------------------ | -------- | +| address | `Address` (see above) | The contract address. | | +| name | `string` | The name of the log event. | | +| indexed | `bytes` (see below) | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes` | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ---------------------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode` (see below) | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------- | ------ | ----------- | ----- | +| hash | `Hash` | | | +| is_left_child | `bool` | | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | ---------- | ----------- | ----- | +| value | `sint32 ` | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | ----------- | ----------- | ----- | +| value | `sint64 ` | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ------------ | ------------------------------------------------------ | ----- | +| address | `Address ` | The scope address, which will be the contract address. | | +| path | `StatePath ` | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | ---------- | ------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code(0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| code_hash | `Hash ` | The hash of the contract code. | | +| is_system_contract | `bool ` | Whether it is a system contract. | | +| version | `int32 ` | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | ----------- | ----------------------------------- | -------- | +| parts | `string ` | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | `Address ` | The address of the sender of the transaction. | | +| to | `Address ` | The address of the contract when calling a contract. | | +| ref_block_number | `int64 ` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes ` | The first four bytes of the referenced block hash. | | +| method_name | `string ` | The name of a method in the smart contract at the To address. | | +| params | `bytes ` | The parameters to pass to the smart contract method. | | +| signature | `bytes ` | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | -------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry ` | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry` | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry ` | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | ----------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | ----------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | ----------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | -------------------------- | ----------------------------------------------------- | -------- | +| transaction_id | `Hash ` | The transaction id. | | +| status | `TransactionResultStatus ` | The transaction result status. | | +| logs | `LogEvent ` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. | | +| return_value | `bytes ` | The return value of the transaction execution. | | +| block_number | `int64 ` | The height of the block hat packages the transaction. | | +| block_hash | `Hash ` | The hash of the block hat packages the transaction. | | +| error | `string ` | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +## AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | ----------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address of the controller. | | +| owner_address | `aelf.Address ` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Genesis Contract.md b/docs/References/Smart Contract API/Genesis Contract.md new file mode 100644 index 0000000..9be84cf --- /dev/null +++ b/docs/References/Smart Contract API/Genesis Contract.md @@ -0,0 +1,426 @@ +# AElf.Contracts.Genesis + +Genesis contract. Used to manage the deployment and update of contracts. +Implement AElf Standards ACS0 and ACS1. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ---------------------------------------------- | --------------------------------------------------- | ----------------------- | ----------------------------------------------------------- | +| Initialize | `Zero.InitializeInput` | `google.protobuf.Empty` | Initializes the genesis contract. | +| SetInitialControllerAddress | `aelf.Address` | `google.protobuf.Empty` | Sets the initial controller address. | +| ChangeContractDeploymentController | `AuthorityInfo` | `google.protobuf.Empty` | Modifies the contract deployment controller authority. | +| ChangeCodeCheckController | `AuthorityInfo` | `google.protobuf.Empty` | Modifies the contract code check controller authority. | +| GetContractDeploymentController | `google.protobuf.Empty` | `AuthorityInfo` | Queries the ContractDeploymentController authority info. | +| GetCodeCheckController | `google.protobuf.Empty` | `AuthorityInfo` | Queries the CodeCheckController authority info. | +| SetContractProposalExpirationTimePeriod | `Zero.SetContractProposalExpirationTimePeriodInput` | `google.protobuf.Empty` | Sets expiration time for contract proposals. | +| GetCurrentContractProposalExpirationTimePeriod | `google.protobuf.Empty` | `int32` | Gets the expiration time for the current contract proposal. | + +## AElf.Standards.ACS0 + +### Contract Methods + +| Method Name | Request Type | Response Type | Description | +| -------------------------------------- | ----------------------------------------- | ------------------------------------ | --------------------------------------------------------- | +| DeploySystemSmartContract | `acs0.SystemContractDeploymentInput` | `aelf.Address` | Deploys a system smart contract and returns the address. | +| DeploySmartContract | `acs0.ContractDeploymentInput` | `aelf.Address` | Deploys a smart contract and returns the address. | +| UpdateSmartContract | `acs0.ContractUpdateInput` | `aelf.Address` | Updates a smart contract on chain. | +| ProposeNewContract | `acs0.ContractDeploymentInput` | `aelf.Hash` | Creates a proposal to deploy a new contract. | +| ProposeContractCodeCheck | `acs0.ContractCodeCheckInput` | `aelf.Hash` | Creates a proposal to check the code of a contract. | +| ProposeUpdateContract | `acs0.ContractUpdateInput` | `aelf.Hash` | Creates a proposal to update a contract. | +| ReleaseApprovedContract | `acs0.ReleaseContractInput` | `google.protobuf.Empty` | Releases an approved contract proposal. | +| ReleaseCodeCheckedContract | `acs0.ReleaseContractInput` | `google.protobuf.Empty` | Releases a code-checked contract proposal. | +| ValidateSystemContractAddress | `acs0.ValidateSystemContractAddressInput` | `google.protobuf.Empty` | Validates the existence of an input system contract. | +| SetContractProposerRequiredState | `google.protobuf.BoolValue` | `google.protobuf.Empty` | Sets authority of contract deployment. | +| CurrentContractSerialNumber | `google.protobuf.Empty` | `google.protobuf.Int64Value` | Gets the current serial number of the genesis contract. | +| GetContractInfo | `aelf.Address` | `acs0.ContractInfo` | Gets detailed information about a contract. | +| GetContractAuthor | `aelf.Address` | `aelf.Address` | Gets the author of a contract. | +| GetContractHash | `aelf.Address` | `aelf.Hash` | Gets the code hash of a contract. | +| GetContractAddressByName | `aelf.Hash` | `aelf.Address` | Gets the address of a system contract by its name. | +| GetSmartContractRegistrationByAddress | `aelf.Address` | `aelf.SmartContractRegistration` | Gets the registration of a smart contract by its address. | +| GetSmartContractRegistrationByCodeHash | `aelf.Hash` | `aelf.SmartContractRegistration` | Gets the registration of a smart contract by code hash. | +| DeployUserSmartContract | `acs0.UserContractDeploymentInput` | `acs0.DeployUserSmartContractOutput` | Deploys a user smart contract and returns the code hash. | +| UpdateUserSmartContract | `acs0.UserContractUpdateInput` | `google.protobuf.Empty` | Updates a user smart contract on chain. | +| ReleaseApprovedUserSmartContract | `acs0.ReleaseContractInput` | `google.protobuf.Empty` | Releases an approved user smart contract proposal. | +| PerformDeployUserSmartContract | `acs0.UserContractDeploymentInput` | `aelf.Address` | Performs user contract deployment. | +| PerformUpdateUserSmartContract | `acs0.UserContractUpdateInput` | `google.protobuf.Empty` | Performs user contract update. | +| SetContractAuthor | `acs0.SetContractAuthorInput` | `google.protobuf.Empty` | Sets the author of a contract. | +| SetSigner | `aelf.Address` | `google.protobuf.Empty` | Sets proxy signer for contract deployment/update. | +| RemoveSigner | `google.protobuf.Empty` | `google.protobuf.Empty` | Removes proxy signer for contract deployment/update. | +| GetSigner | `aelf.Address` | `aelf.Address` | Queries signer of specified address. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------- | ----------------------- | ---------------------------------------------- | +| SetMethodFee | `acs1.MethodFees` | `google.protobuf.Empty` | Sets method fees for the specified method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty` | Changes the method fee controller. | +| GetMethodFee | `google.protobuf.StringValue` | `acs1.MethodFees` | Queries method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty` | `AuthorityInfo` | Queries the method fee controller. | + +## Contract Types + +### AElf.Contracts.Genesis + +#### Zero.ContractProposingInput + +| Field | Type | Description | Label | +| ------------ | ------------------------------ | ------------------------------------------------------- | ----- | +| proposer | `aelf.Address` | The address of proposer for contract deployment/update. | | +| status | `ContractProposingInputStatus` | The status of proposal. | | +| expired_time | `google.protobuf.Timestamp` | The expiration time of proposal. | | + +#### Zero.InitializeInput + +| Field | Type | Description | Label | +| -------------------------------------- | ------ | ------------------------------------------------------ | ----- | +| contract_deployment_authority_required | `bool` | Whether contract deployment/update requires authority. | | + +#### Zero.ContractProposingInputStatus + +| Name | Number | Description | +| ------------------- | ------ | ----------------------------------- | +| PROPOSED | 0 | Proposal is proposed. | +| APPROVED | 1 | Proposal is approved by parliament. | +| CODE_CHECK_PROPOSED | 2 | Code check is proposed. | +| CODE_CHECKED | 3 | Passed code checks. | + +#### Zero.SetContractProposalExpirationTimePeriodInput + +| Field | Type | Description | Label | +| ---------------------- | ------- | ----------------------------- | ----- | +| expiration_time_period | `int32` | The period of expiration time | | + +### AElf.Standards.ACS0 + +#### acs0.AuthorUpdated + +| Field | Type | Description | Label | +| --------------------- | -------------- | ------------------------------------------------- | ----- | +| address | `aelf.address` | The byte array of the contract code. | | +| old_author | `aelf.address` | The category of contract code (0: C#). | | +| CrossChainCreateToken | `aelf.address` | Indicates if the contract is the system contract. | | + +### AElf.Standards.ACS0 + +#### acs0.CodeCheckRequired + +| Field | Type | Description | Label | +| ---------------------------- | ----------- | ------------------------------------------------- | ----- | +| code | `bytes` | The byte array of the contract code. | | +| proposed_contract_input_hash | `aelf.Hash` | The id of the proposed contract. | | +| category | `sint32` | The category of contract code (0: C#). | | +| is_system_contract | `bool` | Indicates if the contract is the system contract. | | +| is_user_contract | `bool` | Indicates if the contract is the user contract. | | + +#### acs0.CodeUpdated + +| Field | Type | Description | Label | +| ------------- | -------------- | ---------------------------------------- | ----- | +| address | `aelf.Address` | The address of the updated contract. | | +| old_code_hash | `aelf.Hash` | The byte array of the old contract code. | | +| new_code_hash | `aelf.Hash` | The byte array of the new contract code. | | +| version | `int32` | The version of the current contract. | | + +#### acs0.ContractCodeCheckInput + +| Field | Type | Description | Label | +| ---------------------------- | ----------- | -------------------------------------------------------------------------------------- | ----- | +| contract_input | `bytes` | The byte array of the contract code to be checked. | | +| is_contract_deployment | `bool` | Whether the input contract is to be deployed or updated. | | +| code_check_release_method | `string` | Method to call after code check complete (DeploySmartContract or UpdateSmartContract). | | +| proposed_contract_input_hash | `aelf.Hash` | The id of the proposed contract. | | +| category | `sint32` | The category of contract code (0: C#). | | +| is_system_contract | `bool` | Indicates if the contract is the system contract. | | + +#### acs0.ContractDeployed + +| Field | Type | Description | Label | +| ---------------- | -------------- | ---------------------------------------------------------- | ----- | +| author | `aelf.Address` | The author of the contract. | | +| code_hash | `aelf.Hash` | The hash of the contract code. | | +| address | `aelf.Address` | The address of the contract. | | +| version | `int32` | The version of the current contract. | | +| name | `aelf.Hash` | The name of the contract. | | +| contract_version | `string` | The version of the current contract. | | +| deployer | `aelf.Address` | The actual address that initiated the contract deployment. | | + +#### acs0.ContractDeploymentInput + +| Field | Type | Description | Label | +| ------------------ | ------------------------ | ----------------------------------------------- | ----- | +| category | `sint32` | The category of contract code (0: C#). | | +| code | `bytes` | The byte array of the contract code. | | +| contract_operation | `acs0.ContractOperation` | The information needed for contract deployment. | | + +#### acs0.ContractInfo + +| Field | Type | Description | Label | +| ------------------ | -------------- | ---------------------------------------------------------- | ----- | +| serial_number | `int64` | The serial number of the contract. | | +| author | `aelf.Address` | The author of the contract. | | +| category | `sint32` | The category of contract code (0: C#). | | +| code_hash | `aelf.Hash` | The hash of the contract code. | | +| is_system_contract | `bool` | Whether it is a system contract. | | +| version | `int32` | The version of the current contract. | | +| contract_version | `string` | The version of the current contract. | | +| is_user_contract | `bool` | Indicates if the contract is the user contract. | | +| deployer | `aelf.Address` | The actual address that initiated the contract deployment. | | + +#### acs0.ContractProposed + +| Field | Type | Description | Label | +| ---------------------------- | ----------- | -------------------------------- | ----- | +| proposed_contract_input_hash | `aelf.Hash` | The id of the proposed contract. | | + +#### acs0.ContractUpdateInput + +| Field | Type | Description | Label | +| ------------------ | ------------------------- | ---------------------------------------------- | ----- | +| address | `aelf.Address ` | The contract address that needs to be updated. | | +| code | `bytes ` | The byte array of the new contract code. | | +| contract_operation | `acs0.ContractOperation ` | The information needed for contract update. | | + +#### acs0.UserContractUpdateInput + +| Field | Type | Description | Label | +| ------- | ------------------ | --------------------------------------------------- | ----- | +| address | `aelf.Address ` | The user contract address that needs to be updated. | | +| code | `bytes ` | The byte array of the new user contract code. | | + +#### acs0.ReleaseContractInput + +| Field | Type | Description | Label | +| ---------------------------- | --------------- | -------------------------------- | ----- | +| proposal_id | `aelf.Hash ` | The hash of the proposal. | | +| proposed_contract_input_hash | `aelf.Hash ` | The id of the proposed contract. | | + +#### acs0.SystemContractDeploymentInput + +| Field | Type | Description | Label | +| ---------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code(0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| name | `aelf.Hash ` | The name of the contract. It has to be unique. | | +| transaction_method_call_list | `SystemContractDeploymentInput.SystemTransactionMethodCallList ` | An initial list of transactions for the system contract, which is executed in sequence when the contract is deployed. | | + +#### acs0.SystemContractDeploymentInput.SystemTransactionMethodCall + +| Field | Type | Description | Label | +| ----------- | ------------ | ---------------------------------------- | ----- | +| method_name | `string ` | The method name of system transaction. | | +| params | `bytes ` | The params of system transaction method. | | + +#### acs0.SystemContractDeploymentInput.SystemTransactionMethodCallList + +| Field | Type | Description | Label | +| ----- | ------------------------------------------------------------ | -------------------------------- | -------- | +| value | `SystemContractDeploymentInput.SystemTransactionMethodCall ` | The list of system transactions. | repeated | + +#### acs0.ValidateSystemContractAddressInput + +| Field | Type | Description | Label | +| ------------------------- | ------------------ | ------------------------------ | ----- | +| system_contract_hash_name | `aelf.Hash ` | The name hash of the contract. | | +| address | `aelf.Address ` | The address of the contract. | | + +#### acs0.DeployUserSmartContractOutput + +| Field | Type | Description | Label | +| --------- | --------------- | ------------------------------------------- | ----- | +| code_hash | `aelf.Hash ` | The deployed or updated contract code hash. | | + +#### acs0.SetContractAuthorInput + +| Field | Type | Description | Label | +| ---------------- | ------------------ | -------------------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The author's contract address needs to be updated. | | +| new_author | `aelf.Address ` | The new contract author. | | + +#### acs0.ContractOperation + +| Field | Type | Description | Label | +| --------- | ------------------ | --------------------------------------------------------------- | ----- | +| chain_id | `int32 ` | The ID of the chain where the contract is deployed/updated. | | +| code_hash | `aelf.Hash ` | The hash of the contract code. | | +| deployer | `aelf.Address ` | The actual address that initiates the contract deployment. | | +| salt | `aelf.Hash ` | The hash based on which the user contract address is generated. | | +| version | `int32 ` | The version of the deployed/updated contract. | | +| signature | `bytes ` | The signature for deployer verification. | | + +#### acs0.UserContractDeploymentInput + +| Field | Type | Description | Label | +| -------- | --------------- | ----------------------------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code(0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| salt | `aelf.Hash ` | The hash based on which user contract address is generated. | | + +### AElf.Standards.ACS1 + +#### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | -------- | ----------------------------------- | ----- | +| symbol | `string` | The token symbol of the method fee. | | +| basic_fee | `int64` | The amount of fees to be charged. | | + +#### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ------------------ | ------------------------------------------------------------ | -------- | +| method_name | `string` | The name of the method to be charged. | | +| fees | `MethodFee` (List) | List of fees to be charged. | repeated | +| is_size_fee_free | `bool` | Optional based on the implementation of SetMethodFee method. | | + +## AElf.Types + +#### aelf.Address + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +#### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | ------------- | ----------------------- | -------- | +| nodes | `Hash` (List) | The leaf nodes. | repeated | +| root | `Hash` | The root node hash. | | +| leaf_count | `int32` | The count of leaf node. | | + +#### aelf.Hash + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +#### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | -------------- | -------------------------- | -------- | +| address | `Address` | The contract address. | | +| name | `string` | The name of the log event. | | +| indexed | `bytes` (List) | The indexed data. | repeated | +| non_indexed | `bytes` | The non indexed data. | | + +#### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ----------------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode` (List) | The merkle path nodes. | repeated | + +#### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------ | -------------------------------- | ----- | +| hash | `Hash` | The node hash. | | +| is_left_child_node | `bool` | Whether it is a left child node. | | + +#### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `sint32` | | | + +#### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `sint64` | | | + +#### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ----------- | ------------------------------------------------------ | ----- | +| address | `Address` | The scope address, which will be the contract address. | | +| path | `StatePath` | The path of contract state. | | + +#### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | -------- | ------------------------------------- | ----- | +| category | `sint32` | The category of contract code(0: C#). | | +| code | `bytes` | The byte array of the contract code. | | +| code_hash | `Hash` | The hash of the contract code. | | +| is_system_contract | `bool` | Whether it is a system contract. | | +| version | `int32` | The version of the current contract. | | + +#### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | --------------- | ----------------------------------- | -------- | +| parts | `string` (List) | The partial path of the state path. | repeated | + +#### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----- | +| from | `aelf.Address` | The address of the sender of the transaction. | | +| to | `aelf.Address` | The address of the contract when calling a contract. | | +| ref_block_number | `int64` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes` | The first four bytes of the referenced block hash. | | +| method_name | `string` | The name of a method in the smart contract at the To address. | | +| params | `bytes` | The parameters to pass to the smart contract method. | | +| signature | `bytes` | When signing a transaction, it's a subset of the fields: from/to and the target method as well as the parameter that were given. | | + +#### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | ---------------------------------------------------------------------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry` ([see details](#aelftransactionexecutingstatesetwritesentry)) | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry` ([see details](#aelftransactionexecutingstatesetreadsentry)) | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry` ([see details](#aelftransactionexecutingstatesetdeletesentry)) | The deleted states. | repeated | + +#### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `bool` | | | + +##### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `bool` | | | + +##### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `bytes` | | | + +#### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| transaction_id | `aelf.Hash` | The transaction id. | | +| status | `TransactionResultStatus` | The transaction result status. | | +| logs | `aelf.LogEvent` (List) | The log events. | repeated | +| bloom | `bytes` | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. | | +| return_value | `bytes` | The return value of the transaction execution. | | +| block_number | `int64` | The height of the block that packages the transaction. | | +| block_hash | `aelf.Hash` | The hash of the block that packages the transaction. | | +| error | `string` | Failed execution error message. | | + +#### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +## AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | -------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address` | The contract address of the controller. | | +| owner_address | `aelf.Address` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Multi Token Contract.md b/docs/References/Smart Contract API/Multi Token Contract.md new file mode 100644 index 0000000..20f52b1 --- /dev/null +++ b/docs/References/Smart Contract API/Multi Token Contract.md @@ -0,0 +1,1095 @@ +# AElf.Contracts.MultiToken + +MultiToken contract. + +The MultiToken contract is mainly used to manage the user's account and transaction fees related settings. + +Implements AElf Standards ACS1 and ACS2. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | +| AdvanceResourceToken | [`tokenimpl.AdvanceResourceTokenInput`](#tokenimpl.AdvanceResourceTokenInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Transfer resource tokens to designated contract address. | +| TakeResourceTokenBack | [`tokenimpl.TakeResourceTokenBackInput`](#tokenimpl.TakeResourceTokenBackInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Take token from contract address. | +| RegisterCrossChainTokenContractAddress | [`tokenimpl.RegisterCrossChainTokenContractAddressInput`](#tokenimpl.RegisterCrossChainTokenContractAddressInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Register the token contract address for cross chain. | +| SetFeeReceiver | [`aelf.Address`](#aelf.Address) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Set the receiver address of the side chain transaction fee. | +| ValidateTokenInfoExists | [`tokenimpl.ValidateTokenInfoExistsInput`](#tokenimpl.ValidateTokenInfoExistsInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Validates if the token exist. | +| UpdateRental | [`tokenimpl.UpdateRentalInput`](#tokenimpl.UpdateRentalInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Update the rental unit price of the side chain. | +| UpdateRentedResources | [`tokenimpl.UpdateRentedResourcesInput`](#tokenimpl.UpdateRentedResourcesInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Set the amount of resources fee per minute for the side chain. | +| TransferToContract | [`tokenimpl.TransferToContractInput`](#tokenimpl.TransferToContractInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Transfer Token to the specified contract. | +| ChangeSideChainRentalController | [`AuthorityInfo`](#AuthorityInfo) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Change the governance organization of side chain rental. | +| ChangeSymbolsToPayTXSizeFeeController | [`AuthorityInfo`](#AuthorityInfo) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Change the governance organization for tokens to pay transaction fees. | +| ChangeCrossChainTokenContractRegistrationController | [`AuthorityInfo`](#AuthorityInfo) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Change the governance organization for cross-chain token contract address registration. | +| ChangeUserFeeController | [`AuthorityInfo`](#AuthorityInfo) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Change the governance organization of the coefficient of the user transaction fee calculation formula. | +| ChangeDeveloperController | [`AuthorityInfo`](#AuthorityInfo) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Change the governance organization of the coefficient of the developer's transaction resource fee calculation formula. | +| ConfigTransactionFeeFreeAllowances | [`token.ConfigTransactionFeeFreeAllowancesInput`](#token.ConfigTransactionFeeFreeAllowancesInput) | [`google.protobuf.Empty`](#google.protobuf.Empty) | Set allowance configurations for transaction fee exemption. | +| GetFeeReceiver | [`google.protobuf.Empty`](#google.protobuf.Empty) | [`aelf.Address`](#aelf.Address) | Get the address of fee receiver. | +| GetResourceUsage | `google.protobuf.Empty ` | `tokenimpl.ResourceUsage ` | Query the amount of resources usage currently. | +| GetSymbolsToPayTXSizeFeeController | `google.protobuf.Empty ` | `AuthorityInfo ` | Query the governance organization for tokens to pay transaction fees. | +| GetCrossChainTokenContractRegistrationController | `google.protobuf.Empty ` | `AuthorityInfo ` | Query the governance organization of the | +| GetUserFeeController | `google.protobuf.Empty ` | `tokenimpl.UserFeeController ` | Query the governance organization that calculates the formula coefficient for the transaction cost the user sends the contract. | +| GetDeveloperFeeController | `google.protobuf.Empty ` | `tokenimpl.DeveloperFeeController ` | Query the governing organization of the formula coefficients for calculating developer contract transaction fee. | +| GetSideChainRentalControllerCreateInfo | `google.protobuf.Empty ` | `AuthorityInfo ` | Query the organization that governs the side chain rental fee. | +| GetTransactionFeeFreeAllowances | `aelf.Address ` | `token.TransactionFeeFreeAllowancesMap >` | Get the allowances for transaction fee exemption. | +| GetTransactionFeeFreeAllowancesConfig | `google.protobuf.Empty ` | `token.GetTransactionFeeFreeAllowancesConfigOutput ` | Query allowance configurations for transaction fee exemption. | +| GetTransactionFeeDelegatees | `token.GetTransactionFeeDelegateesInput ` | `token.GetTransactionFeeDelegateesOutput ` | Retrieve a list of proxy addresses corresponding to a given address. | +| GetVirtualAddressForLocking | `tokenimpl.GetVirtualAddressForLockingInput ` | `aelf.Address ` | Compute the virtual address for locking. | +| GetOwningRental | `google.protobuf.Empty ` | `tokenimpl.OwningRental ` | Query how much resource tokens should be paid currently. | +| GetOwningRentalUnitValue | `google.protobuf.Empty ` | `tokenimpl.OwningRentalUnitValue ` | Query the unit price of the side chain resource cost, resource cost = unit price \* quantity, the quantity can be queried through GetResourceUsage. | +| Create | `token.CreateInput ` | `google.protobuf.Empty ` | Create a new token/collection/nft. | +| Issue | `token.IssueInput ` | `google.protobuf.Empty ` | Issuing some amount of tokens/collection/nft to an address is the action of increasing that addresses balance for the given token. The total amount of issued tokens must not exceed the total supply of the token and only the issuer (creator) of the token/collection/nft can issue tokens. Issuing token/collection/nft effectively increases the circulating supply. | +| Transfer | `token.TransferInput ` | `google.protobuf.Empty ` | Transferring tokens simply is the action of transferring a given amount of tokens from one address to another. The origin or source address is the signer of the transaction. The balance of the sender must be higher than the amount that is transferred. | +| TransferFrom | `token.TransferFromInput ` | `google.protobuf.Empty ` | The TransferFrom action will transfer a specified amount of tokens from one address to another. For this operation to succeed the from address needs to have approved (see allowances) enough tokens to Sender of this transaction. If successful the amount will be removed from the allowance. | +| Approve | `token.ApproveInput ` | `google.protobuf.Empty ` | The approve action increases the allowance from the Sender to the Spender address, enabling the Spender to call TransferFrom. | +| UnApprove | `token.UnApproveInput ` | `google.protobuf.Empty ` | This is the reverse operation for Approve, it will decrease the allowance. | +| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Lock | `token.LockInput ` | `google.protobuf.Empty ` | This method can be used to lock tokens. | +| Unlock | `token.UnlockInput ` | `google.protobuf.Empty ` | This is the reverse operation of locking, it un-locks some previously locked tokens. | +| Burn | `token.BurnInput ` | `google.protobuf.Empty ` | This action will burn the specified amount of tokens, removing them from the token’s Supply. | +| SetPrimaryTokenSymbol | `token.SetPrimaryTokenSymbolInput ` | `google.protobuf.Empty ` | Set the primary token of side chain. | +| CrossChainTransfer | `token.CrossChainTransferInput ` | `google.protobuf.Empty ` | This interface is used for cross-chain transfer. | +| CrossChainReceiveToken | `token.CrossChainReceiveTokenInput ` | `google.protobuf.Empty ` | This method is used to receive cross-chain transfers. | +| CrossChainCreateToken | `token.CrossChainCreateTokenInput ` | `google.protobuf.Empty ` | Create token/collection/nft on the other chain. Collection must be created before creating nft. | +| InitializeFromParentChain | `token.InitializeFromParentChainInput ` | `google.protobuf.Empty ` | When the side chain is started, the side chain is initialized with the parent chain information. | +| ClaimTransactionFees | `token.TotalTransactionFeesMap ` | `google.protobuf.Empty ` | Handle the transaction fees charged by ChargeTransactionFees. | +| ChargeTransactionFees | `token.ChargeTransactionFeesInput` | `token.ChargeTransactionFeesOutput ` | Used to collect transaction fees. | +| ChargeUserContractTransactionFees | `token.ChargeTransactionFeesInput` | `token.ChargeTransactionFeesOutput ` | Used to collect transaction fees of user contract . | +| CheckThreshold | `token.CheckThresholdInput ` | `google.protobuf.Empty ` | Check the token threshold. | +| InitialCoefficients | `google.protobuf.Empty ` | `google.protobuf.Empty ` | Initialize coefficients of every type of tokens supporting charging fee. | +| DonateResourceToken | `token.TotalResourceTokensMaps ` | `google.protobuf.Empty ` | Processing resource token received. | +| ChargeResourceToken | `token.ChargeResourceTokenInput ` | `google.protobuf.Empty ` | A transaction resource fee is charged to implement the ACS8 standards. | +| CheckResourceToken | `google.protobuf.Empty ` | `google.protobuf.Empty ` | Verify that the resource token are sufficient. | +| SetSymbolsToPayTxSizeFee | `token.SymbolListToPayTxSizeFee ` | `google.protobuf.Empty ` | Set the list of tokens to pay transaction fees. | +| UpdateCoefficientsForSender | `token.UpdateCoefficientsInput ` | `google.protobuf.Empty ` | Update the coefficient of the transaction fee calculation formula. | | +| UpdateCoefficientsForContract | `token.UpdateCoefficientsInput ` | `google.protobuf.Empty ` | Update the coefficient of the transaction fee calculation formula. | +| InitializeAuthorizedController | `google.protobuf.Empty ` | `google.protobuf.Empty ` | This method is used to initialize the governance organization for some functions, including: the coefficient of the user transaction fee calculation formula, the coefficient of the contract developer resource fee calculation formula, and the side chain rental fee. | +| GetTokenInfo | `token.GetTokenInfoInput ` | `token.TokenInfo ` | Query token information. | +| GetNativeTokenInfo | `google.protobuf.Empty ` | `token.TokenInfo ` | Query native token information. | +| GetResourceTokenInfo | `google.protobuf.Empty ` | `token.TokenInfoList <#token.TokenInfoList>` | Query resource token information. | +| GetBalance | `token.GetBalanceInput ` | `token.GetBalanceOutput ` | Query the balance at the specified address. | +| GetAllowance | `token.GetAllowanceInput ` | `token.GetAllowanceOutput ` | Query the account's allowance for other addresses | +| IsInWhiteList | `token.IsInWhiteListInput ` | `google.protobuf.BoolValue ` | Check whether the token is in the whitelist of an address, which can be called TransferFrom to transfer the token under the condition of not being credited. | +| GetLockedAmount | `token.GetLockedAmountInput ` | `token.GetLockedAmountOutput <#token.GetLockedAmountOutput>` | Query the information for a lock. | +| GetCrossChainTransferTokenContractAddress | `token.GetCrossChainTransferTokenContractAddressInput <#token.GetCrossChainTransferTokenContractAddressInput>` | `aelf.Address ` | Query the address of receiving token in cross-chain transfer. | +| GetPrimaryTokenSymbol | `google.protobuf.Empty ` | `google.protobuf.StringValue ` | Query the name of the primary Token. | +| GetCalculateFeeCoefficientsForContract | `google.protobuf.Int32Value ` | `token.CalculateFeeCoefficients ` | Query the coefficient of the transaction fee calculation formula. | +| UpdateCoefficientsForContract | `token.UpdateCoefficientsInput ` | `google.protobuf.Empty ` | Update the coefficient of the transaction fee calculation formula. | +| InitializeAuthorizedController | `google.protobuf.Empty ` | `google.protobuf.Empty ` | This method is used to initialize the governance organization for some functions, including: the coefficient of the user transaction fee calculation formula, the coefficient of the contract developer resource fee calculation formula, and the side chain rental fee. | +| GetTokenInfo | `token.GetTokenInfoInput ` | `token.TokenInfo ` | Query token information. | +| GetNativeTokenInfo | `google.protobuf.Empty ` | `token.TokenInfo ` | Query native token information. | +| GetResourceTokenInfo | `google.protobuf.Empty ` | `token.TokenInfoList ` | Query resource token information. | +| GetBalance | `token.GetBalanceInput ` | `token.GetBalanceOutput` | Query the balance at the specified address. | +| GetAllowance | `token.GetAllowanceInput ` | `token.GetAllowanceOutput ` | Query the account's allowance for other addresses | +| IsInWhiteList | `token.IsInWhiteListInput ` | `google.protobuf.BoolValue ` | Check whether the token is in the whitelist of an address, which can be called TransferFrom to transfer the token under the condition of not being credited. | +| GetLockedAmount | `token.GetLockedAmountInput ` | `token.GetLockedAmountOutput ` | Query the information for a lock. | +| GetCrossChainTransferTokenContractAddress | `token.GetCrossChainTransferTokenContractAddressInput ` | `aelf.Address ` | Query the address of receiving token in cross-chain transfer. | +| GetPrimaryTokenSymbol | `google.protobuf.Empty ` | `google.protobuf.StringValue ` | Query the name of the primary Token. | +| GetCalculateFeeCoefficientsForContract | `google.protobuf.Int32Value ` | `token.CalculateFeeCoefficients ` | Query the coefficient of the transaction fee calculation formula. | +| GetCalculateFeeCoefficientsForSender | `google.protobuf.Empty ` | `token.CalculateFeeCoefficients ` | Query the coefficient of the transaction fee calculation formula. | +| GetSymbolsToPayTxSizeFee | `google.protobuf.Empty ` | `token.SymbolListToPayTxSizeFee ` | Query tokens that can pay transaction fees. | +| GetLatestTotalTransactionFeesMapHash | `google.protobuf.Empty ` | `aelf.Hash ` | Query the hash of the last input of ClaimTransactionFees. | +| GetLatestTotalResourceTokensMapsHash | `google.protobuf.Empty ` | `aelf.Hash ` | Query the hash of the last input of DonateResourceToken. | +| IsTokenAvailableForMethodFee | `google.protobuf.StringValue ` | `google.protobuf.BoolValue ` | | +| SetTransactionFeeDelegations | `token.SetTransactionFeeDelegationsInput ` | `token.SetTransactionFeeDelegationsOutput <#token.SetTransactionFeeDelegationsOutput>` | Set delegation of transaction fee payment. | +| SetTransactionFeeDelegateInfos | `token.SetTransactionFeeDelegateInfosInput ` | `google.protobuf.Empty ` | Set delegate info to pay transaction fee. | +| RemoveTransactionFeeFreeAllowancesConfig | `token.RemoveTransactionFeeFreeAllowancesConfigInput ` | `google.protobuf.Empty ` | Remove allowance configurations for transaction fee exemption. | +| RemoveTransactionFeeDelegator | `token.RemoveTransactionFeeDelegatorInput ` | `google.protobuf.Empty ` | Remove transaction fee delegator. | +| RemoveTransactionFeeDelegatorInfos | `token.RemoveTransactionFeeDelegatorInfosInput ` | `google.protobuf.Empty ` | Remove delegator info of the delegatee. | +| RemoveTransactionFeeDelegatee | `token.RemoveTransactionFeeDelegateeInput ` | `google.protobuf.Empty ` | Remove transaction fee delegatee. | +| RemoveTransactionFeeDelegateeInfos | `token.RemoveTransactionFeeDelegateeInfosInput` | `google.protobuf.Empty ` | Remove delegatee info of the delegator. | +| GetTransactionFeeDelegationsOfADelegatee | `token.GetTransactionFeeDelegationsOfADelegateeInput ` | `token.TransactionFeeDelegations ` | Get the delegation of transaction fee payment of a delegatee. | +| GetTransactionFeeDelegateeList | `token.GetTransactionFeeDelegateeListInput ` | `token.GetTransactionFeeDelegateeListOutput ` | Get all delegatee list of a delegator. | +| GetTransactionFeeDelegateInfo | `token.GetTransactionFeeDelegateInfoInput ` | `token.TransactionFeeDelegations ` | Get delegate info for transaction fee. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ------------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees ` | `google.protobuf.Empty ` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo ` | `google.protobuf.Empty ` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue ` | `acs1.MethodFees ` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty ` | `AuthorityInfo ` | Query the method fee controller. | + +## AElf.Standards.ACS2 + +| Method Name | Request Type | Response Type | Description | +| --------------- | -------------------------------------- | -------------------- | ------------------------------------------------------------------------ | +| GetResourceInfo | `aelf.Transaction <#aelf.Transaction>` | `acs2.ResourceInfo ` | Gets the resource information that the transaction execution depends on. | + +## Contract Types + +### AElf.Contracts.MultiToken + +#### tokenimpl.AdvanceResourceTokenInput + +| Field | Type | Description | Label | +| --------------------- | --------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address to transfer. | | +| resource_token_symbol | `string ` | The resource token symbol to transfer. | | +| amount | `int64 ` | The amount of resource token to transfer. | | + +#### tokenimpl.DeveloperFeeController + +| Field | Type | Description | Label | +| --------------------- | ---------------- | ---------------------------------------------- | ----- | +| root_controller | `AuthorityInfo ` | The association that governs the organization. | | +| parliament_controller | `AuthorityInfo ` | The parliament organization of members. | | +| developer_controller | `AuthorityInfo ` | The developer organization of members. | | + +#### tokenimpl.GetVirtualAddressForLockingInput + +| Field | Type | Description | Label | +| ------- | --------------- | ------------------------ | ----- | +| address | `aelf.Address ` | The address of the lock. | | +| lock_id | `aelf.Hash ` | The id of the lock. | | + +#### tokenimpl.OwningRental + +| Field | Type | Description | Label | +| --------------- | ----------------------------------- | ----------------------------------------------------- | -------- | +| resource_amount | `OwningRental.ResourceAmountEntry ` | The amount of resource tokens owed, symbol -> amount. | repeated | + +##### tokenimpl.OwningRental.ResourceAmountEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int64 ` | | | + +#### tokenimpl.OwningRentalUnitValue + +| Field | Type | Description | Label | +| ------------------- | ----------------------------------------------- | ------------------------------------------ | -------- | +| resource_unit_value | `OwningRentalUnitValue.ResourceUnitValueEntry ` | Resource unit price, symbol -> unit price. | repeated | + +##### tokenimpl.OwningRentalUnitValue.ResourceUnitValueEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int64 ` | | | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees` | `google.protobuf.Empty` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue` | `acs1.MethodFees` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty` | `AuthorityInfo` | Query the method fee controller. | + +## AElf.Standards.ACS2 + +| Method Name | Request Type | Response Type | Description | +| --------------- | ------------------ | ------------------- | ------------------------------------------------------------------------ | +| GetResourceInfo | `aelf.Transaction` | `acs2.ResourceInfo` | Gets the resource information that the transaction execution depends on. | + +## AElf.Contracts.MultiToken - tokenimpl.AdvanceResourceTokenInput + +| Field | Type | Description | Label | +| --------------------- | -------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address` | The contract address to transfer. | | +| resource_token_symbol | `string` | The resource token symbol to transfer. | | +| amount | `int64` | The amount of resource token to transfer. | | + +... + +## tokenimpl.RegisterCrossChainTokenContractAddressInput + +| Field | Type | Description | Label | +| ---------------------- | ----------------- | --------------------------------------------- | ----- | +| from_chain_id | `int32` | The source chain id. | | +| parent_chain_height | `int64` | The parent chain height of the transaction. | | +| transaction_bytes | `bytes` | The raw bytes of the transfer transaction. | | +| merkle_path | `aelf.MerklePath` | The merkle path created from the transaction. | | +| token_contract_address | `aelf.Address` | The token contract address. | | + +... + +## tokenimpl.ValidateTokenInfoExistsInput + +| Field | Type | Description | Label | +| -------------- | -------------------- | ------------------------------------------------------------------ | ----- | +| symbol | `string` | The symbol of the token. | | +| token_name | `string` | The full name of the token. | | +| total_supply | `int64` | The total supply of the token. | | +| decimals | `int32` | The precision of the token. | | +| issuer | `aelf.Address` | The address that has permission to issue the token/collection/nft. | | +| is_burnable | `bool` | A flag indicating if this token is burnable. | | +| issue_chain_id | `int32` | The chain id of the token. | | +| external_info | `map` | Attributes or description of the token/collection/nft. | | +| owner | `aelf.Address` | The address that has permission to create nft. | | + +## token.AllCalculateFeeCoefficients + +| Field | Type | Description | Label | +| ----- | -------------------------- | ------------------------------------ | -------- | +| value | `CalculateFeeCoefficients` | The coefficients of fee Calculation. | repeated | + +## token.ApproveInput + +| Field | Type | Description | Label | +| ------- | -------------- | --------------------------------------------- | ----- | +| spender | `aelf.Address` | The address that allowance will be increased. | | +| symbol | `string` | The symbol of token to approve. | | +| amount | `int64` | The amount of token to approve. | | + +### token.Approved + +| Field | Type | Description | Label | +| ------- | -------------- | ---------------------------------------- | ----- | +| owner | `aelf.Address` | The address of the token owner. | | +| spender | `aelf.Address` | The address that allowance be increased. | | +| symbol | `string` | The symbol of approved token. | | +| amount | `int64` | The amount of approved token. | | + +### token.BurnInput + +| Field | Type | Description | Label | +| ------ | -------- | ---------------------------- | ----- | +| symbol | `string` | The symbol of token to burn. | | +| amount | `int64` | The amount of token to burn. | | + +### token.Burned + +| Field | Type | Description | Label | +| ------ | -------------- | ------------------------------------ | ----- | +| burner | `aelf.Address` | The address who wants to burn token. | | +| symbol | `string` | The symbol of burned token. | | +| amount | `int64` | The amount of burned token. | | + +### token.CalculateFeeAlgorithmUpdated + +| Field | Type | Description | Label | +| ------------------------- | ----------------------------- | -------------------------------------------------- | ----- | +| all_type_fee_coefficients | `AllCalculateFeeCoefficients` | All calculate fee coefficients after modification. | | + +### token.CalculateFeeCoefficients + +| Field | Type | Description | Label | +| ----------------------- | ------------------------------- | --------------------------------------------- | -------- | +| fee_token_type | `int32` | The resource fee type, like READ, WRITE, etc. | | +| piece_coefficients_list | `CalculateFeePieceCoefficients` | Coefficients of one single piece. | repeated | + +### token.CalculateFeePieceCoefficients + +| Field | Type | Description | Label | +| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | +| value | `int32` | Coefficients of one single piece. The first char is its type: liner / power. The second char is its piece upper bound. | repeated | + +### token.ChainPrimaryTokenSymbolSet + +| Field | Type | Description | Label | +| ------------ | -------- | -------------------- | ----- | +| token_symbol | `string` | The symbol of token. | | + +### token.ChargeResourceTokenInput + +| Field | Type | Description | Label | +| -------- | --------------------------------------- | ---------------------------------------------------- | -------- | +| cost_dic | `ChargeResourceTokenInput.CostDicEntry` | Collection of charge resource token, Symbol->Amount. | repeated | +| caller | `aelf.Address` | The sender of the transaction. | | + +### token.ChargeResourceTokenInput.CostDicEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +### token.ChargeTransactionFeesInput + +| Field | Type | Description | Label | +| -------------------------- | ---------------------- | ------------------------------------ | -------- | +| method_name | `string` | The method name of transaction. | | +| contract_address | `aelf.Address` | The contract address of transaction. | | +| transaction_size_fee | `int64` | The amount of transaction size fee. | | +| symbols_to_pay_tx_size_fee | `SymbolToPayTxSizeFee` | Transaction fee token information. | repeated | + +### token.ChargeTransactionFeesOutput + +| Field | Type | Description | +| -------------------- | -------- | ---------------------------------- | +| success | `bool` | Whether the charge was successful. | +| charging_information | `string` | The charging information. | + +### token.CheckThresholdInput + +| Field | Type | Description | +| ------------------- | ------------------------ | ---------------------------------------- | +| sender | `aelf.Address` | The sender of the transaction. | +| symbol_to_threshold | `SymbolToThresholdEntry` | The threshold to set, Symbol->Threshold. | +| is_check_allowance | `bool` | Whether to check the allowance. | + +### token.CheckThresholdInput.SymbolToThresholdEntry + +| Field | Type | Description | +| ----- | -------- | ----------- | +| key | `string` | | +| value | `int64` | | + +### token.ConfigTransactionFeeFreeAllowancesInput + +| Field | Type | Description | +| ----- | ----------------------------------- | ------------------------------------ | +| value | `ConfigTransactionFeeFreeAllowance` | The configuration of free allowance. | + +### token.ConfigTransactionFeeFreeAllowance + +| Field | Type | Description | +| ------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- | +| symbol | `string` | The symbol of threshold token. | +| transaction_fee_free_allowances | `TransactionFeeFreeAllowances` | The allowance of each token when a user gets his allowance of the full amount. | +| refresh_seconds | `int64` | The time needed for a user’s allowance to be refreshed back to the full amount. Unit: second | +| threshold | `int64` | The required amount of Token in possession for a user to be eligible for transaction fee exemption. | + +### token.TransactionFeeFreeAllowances + +| Field | Type | Description | +| ----- | ----------------------------- | --------------------------- | +| value | `TransactionFeeFreeAllowance` | The allowance of the token. | + +### token.TransactionFeeFreeAllowance + +| Field | Type | Description | +| ------ | -------- | --------------------------------- | +| symbol | `string` | Token symbol. | +| amount | `int64` | The amount of fee free allowance. | + +### token.TransactionFeeFreeAllowanceConfig + +| Field | Type | Description | +| --------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | +| symbol | `string` | The symbol of threshold token. | +| free_allowances | `TransactionFeeFreeAllowanceMap` | The allowance of each token when a user gets his allowance of the full amount. | +| refresh_seconds | `int64` | The time needed for a user’s allowance to be refreshed back to the full amount. Unit: second | +| threshold | `int64` | The required amount of Token in possession for a user to be eligible for transaction fee exemption. | + +### token.TransactionFeeFreeAllowanceMap + +| Field | Type | Description | +| ----- | ------------------------------------------ | --------------------------------------- | +| map | `map` | | + +### token.ContractTotalResourceTokens + +| Field | Type | Description | +| ---------------- | ------------------------ | -------------------------- | +| contract_address | `aelf.Address` | The contract address. | +| tokens_map | `TotalResourceTokensMap` | Resource tokens to charge. | + +### token.CreateInput + +| Field | Type | Description | +| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| symbol | `string` | The symbol of the token/collection/nft. | +| token_name | `string` | The full name of the token/collection/nft. | +| total_supply | `int64` | The total supply of the token/collection/nft. | +| decimals | `int32` | The precision of the toke/collection/nft. | +| issuer | `aelf.Address` | The address that has permission to issue the token/collection/nft. | +| is_burnable | `bool` | A flag indicating if this token/collection/nft is burnable. | +| lock_white_list | `aelf.Address` | A whitelist address list used to lock tokens/collection/nft. | +| issue_chain_id | `int32` | The chain id of the token/collection/nft. | +| external_info | `map` | Attributes or description of the token/collcection/nft. There is no mandatory constraint on the naming of the key. But it is recommended to use **nft as the prefix key to set the nft attribute, such as**nft_image_url. | +| owner | `aelf.Address` | The address that has permission to create nft. | + +### token.CrossChainCreateTokenInput + +| Field | Type | Description | Label | +| ------------------- | ----------------- | -------------------------------------------------------------------------- | ----- | +| from_chain_id | `int32` | The chain id of the chain on which the token was created. | | +| parent_chain_height | `int64` | The height of the transaction that created the token/collection/nft. | | +| transaction_bytes | `bytes` | The transaction that created the token/collection/nft. | | +| merkle_path | `aelf.MerklePath` | The merkle path created from the transaction that created the transaction. | | + +### token.CrossChainReceiveTokenInput + +| Field | Type | Description | Label | +| -------------------------- | ----------------- | ------------------------------------------------------ | ----- | +| from_chain_id | `int32` | The source chain id. | | +| parent_chain_height | `int64` | The height of the transfer transaction. | | +| transfer_transaction_bytes | `bytes` | The raw bytes of the transfer transaction. | | +| merkle_path | `aelf.MerklePath` | The merkle path created from the transfer transaction. | | + +### token.CrossChainReceived + +| Field | Type | Description | Label | +| ----------------------- | -------------- | ---------------------------------------------------- | ----- | +| from | `aelf.Address` | The source address of the transferred token. | | +| to | `aelf.Address` | The destination address of the transferred token. | | +| symbol | `string` | The symbol of the received token. | | +| amount | `int64` | The amount of the received token. | | +| memo | `string` | The memo. | | +| from_chain_id | `int32` | The destination chain id. | | +| issue_chain_id | `int32` | The chain id of the token. | | +| parent_chain_height | `int64` | The parent chain height of the transfer transaction. | | +| transfer_transaction_id | `aelf.Hash` | The id of transfer transaction. | | + +### token.CrossChainTransferInput + +| Field | Type | Description | Label | +| -------------- | -------------- | -------------------------------- | ----- | +| to | `aelf.Address` | The receiver of transfer. | | +| symbol | `string` | The symbol of token. | | +| amount | `int64` | The amount of token to transfer. | | +| memo | `string` | The memo. | | +| to_chain_id | `int32` | The destination chain id. | | +| issue_chain_id | `int32` | The chain id of the token. | | + +### token.CrossChainTransferred + +| Field | Type | Description | Label | +| -------------- | -------------- | ------------------------------------------------- | ----- | +| from | `aelf.Address` | The source address of the transferred token. | | +| to | `aelf.Address` | The destination address of the transferred token. | | +| symbol | `string` | The symbol of the transferred token. | | +| amount | `int64` | The amount of the transferred token. | | +| memo | `string` | The memo. | | +| to_chain_id | `int32` | The destination chain id. | | +| issue_chain_id | `int32` | The chain id of the token. | | + +### token.ExtraTokenListModified + +| Field | Type | Description | Label | +| ------------------------------ | -------------------------- | ---------------------------------- | ----- | +| symbol_list_to_pay_tx_size_fee | `SymbolListToPayTxSizeFee` | Transaction fee token information. | | + +### token.GetAllowanceInput + +| Field | Type | Description | Label | +| ------- | -------------- | ------------------------------- | ----- | +| symbol | `string` | The symbol of token. | | +| owner | `aelf.Address` | The address of the token owner. | | +| spender | `aelf.Address` | The address of the spender. | | + +### token.GetAllowanceOutput + +| Field | Type | Description | Label | +| --------- | -------------- | ------------------------------- | ----- | +| symbol | `string` | The symbol of token. | | +| owner | `aelf.Address` | The address of the token owner. | | +| spender | `aelf.Address` | The address of the spender. | | +| allowance | `int64` | The amount of allowance. | | + +### token.GetBalanceInput + +| Field | Type | Description | Label | +| ------ | -------------- | -------------------------------- | ----- | +| symbol | `string` | The symbol of token. | | +| owner | `aelf.Address` | The target address of the query. | | + +### token.GetBalanceOutput + +| Field | Type | Description | Label | +| ------- | -------------- | -------------------------------- | ----- | +| symbol | `string` | The symbol of token. | | +| owner | `aelf.Address` | The target address of the query. | | +| balance | `int64` | The balance of the owner. | | + +### token.GetCrossChainTransferTokenContractAddressInput + +| Field | Type | Description | Label | +| ------- | ------- | ------------- | ----- | +| chainId | `int32` | The chain id. | | + +### token.GetLockedAmountInput + +| Field | Type | Description | Label | +| ------- | -------------- | ------------------------ | ----- | +| address | `aelf.Address` | The address of the lock. | | +| symbol | `string` | The token symbol. | | +| lock_id | `aelf.Hash` | The id of the lock. | | + +### token.GetLockedAmountOutput + +| Field | Type | Description | Label | +| ------- | -------------- | ------------------------ | ----- | +| address | `aelf.Address` | The address of the lock. | | +| symbol | `string` | The token symbol. | | +| lock_id | `aelf.Hash` | The id of the lock. | | +| amount | `int64` | The locked amount. | | + +### token.GetTokenInfoInput + +| Field | Type | Description | Label | +| ------ | -------- | -------------------- | ----- | +| symbol | `string` | The symbol of token. | | + +### token.GetTransactionFeeDelegateesInput + +| Field | Type | Description | Label | +| ----------------- | -------------- | ------------------------- | ----- | +| delegator_address | `aelf.Address` | The address of delegator. | | + +### token.GetTransactionFeeDelegateeListInput + +| Field | Type | Description | Label | +| ----------------- | -------------- | ------------------------- | ----- | +| delegator_address | `aelf.Address` | The address of delegator. | | +| contract_address | `aelf.Address` | The contract address. | | +| method_name | `string` | The method name. | | + +### token.GetTransactionFeeDelegateeListOutput + +| Field | Type | Description | Label | +| ------------------- | -------------- | ------------------------------ | -------- | +| delegatee_addresses | `aelf.Address` | The address list of delegatee. | repeated | + +### token.GetTransactionFeeDelegateInfoInput + +| Field | Type | Description | Label | +| ----------------- | -------------- | ------------------------- | ----- | +| delegator_address | `aelf.Address` | The address of delegator. | | +| delegatee_address | `aelf.Address` | The address of delegatee. | | +| contract_address | `aelf.Address` | The contract address. | | +| method_name | `string` | The method name. | | + +### token.GetTransactionFeeFreeAllowancesConfigOutput + +| Field | Type | Description | Label | +| ----- | ------------------------------------------ | ---------------------------------------------------- | -------- | +| value | `token.TransactionFeeFreeAllowanceConfigs` | The configuration of transaction fee free allowance. | repeated | + +### token.InitializeFromParentChainInput + +| Field | Type | Description | Label | +| ----------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ | -------- | +| resource_amount | `InitializeFromParentChainInput.ResourceAmountEntry` | The amount of resource. | repeated | +| registered_other_token_contract_addresses | `InitializeFromParentChainInput.RegisteredOtherTokenContractAddressesEntry` | The token contract addresses. | repeated | +| creator | `aelf.Address` | The creator of the side chain. | | + +### token.InitializeFromParentChainInput.RegisteredOtherTokenContractAddressesEntry + +| Field | Type | Description | Label | +| ----- | -------------- | ----------- | ----- | +| key | `int32` | | | +| value | `aelf.Address` | | | + +### token.InitializeFromParentChainInput.ResourceAmountEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int32` | | | + +### `token.IsInWhiteListInput` + +| Field | Type | Description | Label | +| ------- | -------------- | --------------------- | ----- | +| symbol | `string` | The symbol of token. | | +| address | `aelf.Address` | The address to check. | | + +### token.IssueInput + +| Field | Type | Description | Label | +| ------ | -------------- | ----------------------------------------- | ----- | +| symbol | `string` | The token/collection/nft symbol to issue. | | +| amount | `int64` | The token/collection/nft amount to issue. | | +| memo | `string` | The memo. | | +| to | `aelf.Address` | The target address to issue. | | + +### token.Issued + +| Field | Type | Description | Label | +| ------ | -------------- | --------------------------- | ----- | +| symbol | `string` | The symbol of issued token. | | +| amount | `int64` | The amount of issued token. | | +| memo | `string` | The memo. | | +| to | `aelf.Address` | The issued target address. | | + +### token.LockInput + +| Field | Type | Description | Label | +| ------- | -------------- | -------------------------------------- | ----- | +| address | `aelf.Address` | The one who wants to lock their token. | | +| lock_id | `aelf.Hash` | The id of the lock. | | +| symbol | `string` | The symbol of the token to lock. | | +| usage | `string` | A memo. | | +| amount | `int64` | The amount of tokens to lock. | | + +### token.RemoveTransactionFeeDelegatorInfosInput + +| Field | Type | Description | Label | +| ------------------------- | --------------------------- | --------------------------------- | -------- | +| delegator_address | `aelf.Address` | The address of delegator. | | +| delegate_transaction_list | `token.DelegateTransaction` | The transaction list of delegate. | repeated | + +### token.RemoveTransactionFeeDelegateeInfosInput + +| Field | Type | Description | Label | +| ------------------------- | --------------------------- | --------------------------------- | -------- | +| delegator_address | `aelf.Address` | The address of delegatee. | | +| delegate_transaction_list | `token.DelegateTransaction` | The transaction list of delegate. | repeated | + +### token.DelegateTransaction + +| Field | Type | Description | Label | +| ---------------- | --------------- | --------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address. | | +| method_name | `string ` | The method name. | | + +### token.RentalAccountBalanceInsufficient + +| Field | Type | Description | Label | +| ------ | --------- | -------------------------------------------------- | ----- | +| symbol | `string ` | The symbol of insufficient rental account balance. | | +| amount | `int64 ` | The balance of the account. | | + +### token.RentalCharged + +| Field | Type | Description | Label | +| -------- | --------------- | --------------------------------- | ----- | +| symbol | `string ` | The symbol of rental fee charged. | | +| amount | `int64 ` | The amount of rental fee charged. | | +| payer | `aelf.Address ` | The payer of rental fee. | | +| receiver | `aelf.Address ` | The receiver of rental fee. | | + +### token.RemoveTransactionFeeFreeAllowancesConfigInput + +| Field | Type | Description | Label | +| ------- | --------- | ------------------------------------------------------------------------------- | -------- | +| symbols | `string ` | List of symbols to remove from configuration of transaction fee free allowance. | repeated | + +### token.ResourceTokenClaimed + +| Field | Type | Description | Label | +| -------- | --------------- | -------------------------- | ----- | +| symbol | `string ` | The symbol of fee claimed. | | +| amount | `int64 ` | The amount of fee claimed. | | +| payer | `aelf.Address ` | The payer of fee. | | +| receiver | `aelf.Address ` | The receiver of fee. | | + +### token.SetTransactionFeeDelegateInfos + +| Field | Type | Description | Label | +| ------------------ | --------------------- | --------------------------------------------- | -------- | +| delegator_address | `aelf.Address ` | The address of delegator. | | +| delegate_info_list | `token.DelegateInfo ` | The delegate information for the transaction. | repeated | + +### token.DelegateInfo + +| Field | Type | Description | Label | +| ------------------- | --------------------- | --------------------------------------------------------------- | ----- | +| delegations | `map ` | | | +| contract_address | `aelf.Address ` | The contract address. | | +| method_name | `string ` | The method name. | | +| isUnlimitedDelegate | `bool ` | Whether to pay transaction fee continuously without limitation. | | + +### token.SetPrimaryTokenSymbolInput + +| Field | Type | Description | Label | +| ------ | --------- | ------------------------ | ----- | +| symbol | `string ` | The symbol of the token. | | + +### token.SymbolListToPayTxSizeFee + +| Field | Type | Description | Label | +| -------------------------- | ----------------------- | ---------------------------------- | -------- | +| symbols_to_pay_tx_size_fee | `SymbolToPayTxSizeFee ` | Transaction fee token information. | repeated | + +### token.SymbolToPayTxSizeFee + +| Field | Type | Description | Label | +| ------------------ | --------- | ----------------------------------- | ----- | +| token_symbol | `string ` | The symbol of token. | | +| base_token_weight | `int32 ` | The charge weight of primary token. | | +| added_token_weight | `int32 ` | The new added token charge weight. | | + +### token.TransactionFeeClaimed + +| Field | Type | Description | Label | +| -------- | --------------- | -------------------------- | ----- | +| symbol | `string ` | The symbol of fee claimed. | | +| amount | `int64 ` | The amount of fee claimed. | | +| receiver | `aelf.Address ` | The receiver of fee. | | + +### token.TransactionFeeFreeAllowancesMap + +| Field | Type | Description | Label | +| ----- | ---------------------------------------------- | ----------------------------------- | ----- | +| map | `map ` | | | + +### token.TokenCreated + +| Field | Type | Description | Label | +| -------------- | --------------- | -------------------------------------------- | ----- | +| symbol | `string ` | The symbol of the token. | | +| token_name | `string ` | The full name of the token. | | +| total_supply | `int64 ` | The total supply of the token. | | +| decimals | `int32 ` | The precision of the token. | | +| issuer | `aelf.Address ` | The address that created the token. | | +| is_burnable | `bool ` | A flag indicating if this token is burnable. | | +| issue_chain_id | `int32 ` | The chain id of the token. | | + +### token.TokenInfo + +| Field | Type | Description | Label | +| -------------- | --------------- | -------------------------------------------- | ----- | +| symbol | `string ` | The symbol of the token. | | +| token_name | `string ` | The full name of the token. | | +| supply | `int64 ` | The current supply of the token. | | +| total_supply | `int64 ` | The total supply of the token. | | +| decimals | `int32 ` | The precision of the token. | | +| issuer | `aelf.Address ` | The address that created the token. | | +| is_burnable | `bool ` | A flag indicating if this token is burnable. | | +| issue_chain_id | `int32 ` | The chain id of the token. | | +| issued | `int64 ` | The amount of issued tokens. | | + +### token.TokenInfoList + +| Field | Type | Description | Label | +| ----- | ------------ | -------------------------- | -------- | +| value | `TokenInfo ` | List of token information. | repeated | + +### token.TotalResourceTokensMap + +| Field | Type | Description | Label | +| ----- | ------------------------------------ | ------------------------------------------ | -------- | +| value | `TotalResourceTokensMap.ValueEntry ` | Resource token dictionary, Symbol->Amount. | repeated | + +### token.TotalResourceTokensMap.ValueEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int64 ` | | | + +### token.TotalResourceTokensMaps + +| Field | Type | Description | Label | +| ------------ | ------------------------------ | --------------------------------------------------- | -------- | +| value | `ContractTotalResourceTokens ` | Resource tokens to charge. | repeated | +| block_hash | `aelf.Hash ` | The hash of the block processing the transaction. | | +| block_height | `int64 ` | The height of the block processing the transaction. | | + +### token.TotalTransactionFeesMap + +| Field | Type | Description | Label | +| ------------ | ------------------------------------- | ------------------------------------------------------------- | -------- | +| value | `TotalTransactionFeesMap.ValueEntry ` | Token dictionary that charge transaction fee, Symbol->Amount. | repeated | +| block_hash | `aelf.Hash ` | The hash of the block processing the transaction. | | +| block_height | `int64 ` | The height of the block processing the transaction. | | + +### token.TransactionFeeCharged + +| Field | Type | Description | Label | +| --------------- | ------------ | --------------------------------------------------- | -------- | +| symbol | `string ` | Resource tokens to charge. | repeated | +| amount | `int64 ` | The hash of the block processing the transaction. | | +| chargingAddress | `aelf.Hash ` | The height of the block processing the transaction. | | + +### token.TotalTransactionFeesMap.ValueEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int64 ` | | | + +### token.TransactionFeeBill + +| Field | Type | Description | Label | +| -------- | ---------------------------------- | -------------------------------------------- | -------- | +| fees_map | `TransactionFeeBill.FeesMapEntry ` | The transaction fee dictionary, Symbol->fee. | repeated | + +### token.TransactionFeeBill.FeesMapEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int64 ` | | | + +### token.TransferFromInput + +| Field | Type | Description | Label | +| ------ | --------------- | ------------------------------------- | ----- | +| from | `aelf.Address ` | The source address of the token. | | +| to | `aelf.Address ` | The destination address of the token. | | +| symbol | `string ` | The symbol of the token to transfer. | | +| amount | `int64 ` | The amount to transfer. | | +| memo | `string ` | The memo. | | + +### token.TransferInput + +| Field | Type | Description | Label | +| ------ | --------------- | ----------------------------- | ----- | +| to | `aelf.Address ` | The receiver of the token. | | +| symbol | `string ` | The token symbol to transfer. | | +| amount | `int64 ` | The amount to transfer. | | +| memo | `string ` | The memo. | | + +### token.Transferred + +| Field | Type | Description | Label | +| ------ | --------------- | ------------------------------------------------- | ----- | +| from | `aelf.Address ` | The source address of the transferred token. | | +| to | `aelf.Address ` | The destination address of the transferred token. | | +| symbol | `string ` | The symbol of the transferred token. | | +| amount | `int64 ` | The amount of the transferred token. | | +| memo | `string ` | The memo. | | + +### token.UnApproveInput + +| Field | Type | Description | Label | +| ------- | --------------- | --------------------------------------------- | ----- | +| spender | `aelf.Address ` | The address that allowance will be decreased. | | +| symbol | `string ` | The symbol of token to un-approve. | | +| amount | `int64 ` | The amount of token to un-approve. | | + +### token.UnApproved + +| Field | Type | Description | Label | +| ------- | --------------- | ---------------------------------------- | ----- | +| owner | `aelf.Address ` | The address of the token owner. | | +| spender | `aelf.Address ` | The address that allowance be decreased. | | +| symbol | `string ` | The symbol of un-approved token. | | +| amount | `int64 ` | The amount of un-approved token. | | + +### token.UnlockInput + +| Field | Type | Description | Label | +| ------- | --------------- | ----------------------------------- | ----- | +| address | `aelf.Address ` | The one want to un-lock his token. | | +| lock_id | `aelf.Hash ` | Id of the lock. | | +| symbol | `string ` | The symbol of the token to un-lock. | | + +| usage | `string `** | A memo. | | +| amount | `int64 `** | The amount of tokens to un-lock. | | + +### token.UpdateCoefficientsInput + +| Field | Type | Description | Label | +| ------------- | --------------------------- | -------------------------------- | -------- | +| piece_numbers | `int32 ` | The specify pieces gonna update. | repeated | +| coefficients | `CalculateFeeCoefficients ` | Coefficients of one single type. | | + +### token.FeeTypeEnum + +| Name | Number | Description | +| ------- | ------ | ----------- | +| READ | 0 | | +| STORAGE | 1 | | +| WRITE | 2 | | +| TRAFFIC | 3 | | +| TX | 4 | | + +### token.SetTransactionFeeDelegationsInput + +| Field | Type | Description | Label | +| ----------------- | --------------------- | --------------------------- | ----- | +| delegator_address | `aelf.Addresss ` | The address of delegator. | | +| delegations | `map ` | \ | | + +### token.SetTransactionFeeDelegationsOutput + +| Field | Type | Description | Label | +| ------- | ------- | ------------------------------- | ----- | +| success | `bool ` | Whether set delegation success. | | + +### token.RemoveTransactionFeeDelegatorInput + +| Field | Type | Description | Label | +| ----------------- | ---------------- | ------------------------- | ----- | +| delegator_address | `aelf.Addresss ` | The address of delegator. | | + +### token.RemoveTransactionFeeDelegateeInput + +| Field | Type | Description | Label | +| ----------------- | ---------------- | ------------------------- | ----- | +| delegatee_address | `aelf.Addresss ` | The address of delegatee. | | + +### token.MethodFeeFreeAllowance + +| Field | Type | Description | Label | +| ------ | --------- | -------------------------------- | ----- | +| symbol | `string ` | Token symbol | | +| amount | `int64 ` | The amount of fee free allowance | | + +### token.GetTransactionFeeDelegationsOfADelegateeInput + +| Field | Type | Description | Label | +| ----------------- | ---------------- | ------------------------- | ----- | +| delegatee_address | `aelf.Addresss ` | The address of delegatee. | | +| delegator_address | `aelf.Addresss ` | The address of delegator. | | + +### token.TransactionFeeDelegations + +| Field | Type | Description | Label | +| ------------ | --------------------- | ------------------------------------------------------------ | ----- | +| delegations | `map ` | The number of tokens allowed to be delegated | | +| block_height | `int64 ` | The block height when the information of delegation is added | | + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | --------- | ----------------------------------- | ----- | +| symbol | `string ` | The token symbol of the method fee. | | +| basic_fee | `int64 ` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ------------ | ------------------------------------------------------------ | -------- | +| method_name | `string ` | The name of the method to be charged. | | +| fees | `MethodFee ` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool ` | Optional based on the implementation of SetMethodFee method. | | + +### acs2.ResourceInfo + +| Field | Type | Description | Label | +| ------------------ | ----------------------- | ---------------------------------------------------- | -------- | +| write_paths | `aelf.ScopedStatePath ` | The state path that depends on when writing. | repeated | +| read_paths | `aelf.ScopedStatePath ` | The state path that depends on when reading. | repeated | +| non_parallelizable | `bool ` | Whether the transaction is not executed in parallel. | | + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | -------- | ----------------------- | -------- | +| nodes | `Hash ` | The leaf nodes. | repeated | +| root | `Hash ` | The root node hash. | | +| leaf_count | `int32 ` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ---------- | ------------------------------------------ | -------- | +| address | `Address ` | The contract address. | | +| name | `string ` | The name of the log event. | | +| indexed | `bytes ` | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes ` | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ----------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode ` | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------- | -------------------------------- | ----- | +| hash | `Hash ` | The node hash. | | +| is_left_child_node | `bool ` | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `sint32` | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `sint64` | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ------------ | ------------------------------------------------------ | ----- | +| address | `Address ` | The scope address, which will be the contract address. | | +| path | `StatePath ` | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | --------- | ------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code(0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| code_hash | `Hash ` | The hash of the contract code. | | +| is_system_contract | `bool ` | Whether it is a system contract. | | +| version | `int32 ` | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | --------- | ----------------------------------- | -------- | +| parts | `string ` | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | `Address ` | The address of the sender of the transaction. | | +| to | `Address ` | The address of the contract when calling a contract. | | +| ref_block_number | `int64 ` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes ` | The first four bytes of the referenced block hash. | | +| method_name | `string ` | The name of a method in the smart contract at the To address. | | +| params | `bytes ` | The parameters to pass to the smart contract method. | | +| signature | `bytes ` | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | --------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry ` | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry ` | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry >` | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +--- + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| transaction_id | `Hash ` | The transaction id. | | +| status | `TransactionResultStatus ` | The transaction result status. | | +| logs | `LogEvent ` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. Through this filter, we can quickly search for and determine whether a log exists in the transaction result. | | +| return_value | `bytes ` | The return value of the transaction execution. | | +| block_number | `int64 ` | The height of the block that packages the transaction. | | +| block_hash | `Hash ` | The hash of the block that packages the transaction. | | +| error | `string ` | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +# AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | --------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address of the controller. | | +| owner_address | `aelf.Address ` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Parliament Contract.md b/docs/References/Smart Contract API/Parliament Contract.md new file mode 100644 index 0000000..90d0ed1 --- /dev/null +++ b/docs/References/Smart Contract API/Parliament Contract.md @@ -0,0 +1,392 @@ +# AElf.Contracts.Parliament + +Parliament contract. + +The production nodes use the Parliament contract to govern important matters. In the initial state, the production nodes are members of the parliament, and only when two-thirds of the production nodes vote in favor of a given decision, will it be executed. + +Implement AElf Standards ACS1 and ACS3. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ----------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| Initialize | [Parliament.InitializeInput](#Parliament.InitializeInput) | [google.protobuf.Empty](#google.protobuf.Empty) | Initialize parliament proposer whitelist and create the first parliament organization with specific proposer_authority_required. | +| CreateOrganization | [Parliament.CreateOrganizationInput](#Parliament.CreateOrganizationInput) | [aelf.Address](#aelf.Address) | Create an organization and return its address. | +| ApproveMultiProposals | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | [google.protobuf.Empty](#google.protobuf.Empty) | Batch approval proposal. | +| CreateOrganizationBySystemContract | [Parliament.CreateOrganizationBySystemContractInput](#Parliament.CreateOrganizationBySystemContractInput) | [aelf.Address](#aelf.Address) | Creates an organization by system contract and return its address. | +| GetOrganization | [aelf.Address](#aelf.Address) | [Parliament.Organization](#Parliament.Organization) | Get the organization according to the organization address. | +| GetDefaultOrganizationAddress | [google.protobuf.Empty](#google.protobuf.Empty) | [aelf.Address](#aelf.Address) | Get the default organization address. | +| ValidateAddressIsParliamentMember | [aelf.Address](#aelf.Address) | [google.protobuf.BoolValue](#google.protobuf.BoolValue) | Validates if the provided address is a parliament member. | +| GetProposerWhiteList | [google.protobuf.Empty](#google.protobuf.Empty) | [acs3.ProposerWhiteList](#acs3.ProposerWhiteList) | Returns the list of whitelisted proposers. | +| GetNotVotedPendingProposals | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | Filter still pending ones not yet voted by the sender from provided proposals. | +| GetNotVotedProposals | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | Filter not yet voted ones by the sender from provided proposals. | +| CalculateOrganizationAddress | [Parliament.CreateOrganizationInput](#Parliament.CreateOrganizationInput) | [aelf.Address](#aelf.Address) | Calculates with input and return the organization address. | +| GetReleaseThresholdReachedProposals | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | Filter reached release threshold proposals. | +| GetAvailableProposals | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | [Parliament.ProposalIdList](#Parliament.ProposalIdList) | Filter available proposals. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | [acs1.MethodFees](#acs1.MethodFees) | [google.protobuf.Empty](#google.protobuf.Empty) | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | [AuthorityInfo](#AuthorityInfo) | [google.protobuf.Empty](#google.protobuf.Empty) | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | [google.protobuf.StringValue](#google.protobuf.StringValue) | [acs1.MethodFees](#acs1.MethodFees) | Query method fee information by method name. | +| GetMethodFeeController | [google.protobuf.Empty](#google.protobuf.Empty) | [AuthorityInfo](#AuthorityInfo) | Query the method fee controller. | + +# AElf.Standards.ACS3 + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ----------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CreateProposal | [acs3.CreateProposalInput](#acs3.CreateProposalInput) | [aelf.Hash](#aelf.Hash) | Create a proposal for which organization members can vote. When the proposal is released, a transaction will be sent to the specified contract. Return id of the newly created proposal. | +| Approve | [aelf.Hash](#aelf.Hash) | [google.protobuf.Empty](#google.protobuf.Empty) | Approve a proposal according to the proposal ID. | +| Reject | [aelf.Hash](#aelf.Hash) | [google.protobuf.Empty](#google.protobuf.Empty) | Reject a proposal according to the proposal ID. | +| Abstain | [aelf.Hash](#aelf.Hash) | [google.protobuf.Empty](#google.protobuf.Empty) | Abstain a proposal according to the proposal ID. | +| Release | [aelf.Hash](#aelf.Hash) | [google.protobuf.Empty](#google.protobuf.Empty) | Release a proposal according to the proposal ID and send a transaction to the specified contract. | +| ChangeOrganizationThreshold | [acs3.ProposalReleaseThreshold](#acs3.ProposalReleaseThreshold) | [google.protobuf.Empty](#google.protobuf.Empty) | Change the thresholds associated with proposals. All fields will be overwritten by the input value and this will affect all current proposals of the organization. Note: only the organization can execute this through a proposal. | +| ChangeOrganizationProposerWhiteList | [acs3.ProposerWhiteList](#acs3.ProposerWhiteList) | [google.protobuf.Empty](#google.protobuf.Empty) | Change the white list of organization proposer. This method overrides the list of whitelisted proposers. | +| CreateProposalBySystemContract | [acs3.CreateProposalBySystemContractInput](#acs3.CreateProposalBySystemContractInput) | [aelf.Hash](#aelf.Hash) | Create a proposal by system contracts, and return id of the newly created proposal. | +| ClearProposal | [aelf.Hash](#aelf.Hash) | [google.protobuf.Empty](#google.protobuf.Empty) | Remove the specified proposal. If the proposal is in effect, the cleanup fails. | +| GetProposal | [aelf.Hash](#aelf.Hash) | [acs3.ProposalOutput](#acs3.ProposalOutput) | Get the proposal according to the proposal ID. | +| ValidateOrganizationExist | [aelf.Address](#aelf.Address) | [google.protobuf.BoolValue](#google.protobuf.BoolValue) | Check the existence of an organization. | +| ValidateProposerInWhiteList | [acs3.ValidateProposerInWhiteListInput](#acs3.ValidateProposerInWhiteListInput) | [google.protobuf.BoolValue](#google.protobuf.BoolValue) | Check if the proposer is whitelisted. | + +## #Contract Types + +## AElf.Contracts.Parliament + +### `Parliament.CreateOrganizationBySystemContractInput` + +| Field | Type | Description | Label | +| ------------------------------------ | ------------------------- | --------------------------------------------------------------------------------------------------- | ----- | +| organization_creation_input | `CreateOrganizationInput` | The parameters of creating organization. | +| organization_address_feedback_method | `string` | The organization address callback method which replies the organization address to caller contract. | + +### `Parliament.CreateOrganizationInput` + +| Field | Type | Description | Label | +| ----------------------------------- | ------------------------------- | --------------------------------------------------------------------- | ----- | +| proposal_release_threshold | `acs3.ProposalReleaseThreshold` | The threshold for releasing the proposal. | +| proposer_authority_required | `bool ` | Setting this to true can allow anyone to create proposals. | +| parliament_member_proposing_allowed | `bool ` | Setting this to true can allow parliament member to create proposals. | +| creation_token | `aelf.Hash` | The creation token is for organization address generation. | + +### `Parliament.InitializeInput` + +| Field | Type | Description | Label | +| --------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- | ----- | +| privileged_proposer | `aelf.Address` | Privileged proposer would be the first address in parliament proposer whitelist. | +| proposer_authority_required | `bool ` | The setting indicates if proposals need authority to be created for first/default parliament organization. | + +### `Parliament.Organization` + +| Field | Type | Description | Label | +| ----------------------------------- | ------------------------------- | ---------------------------------------------------------------- | ----- | +| proposer_authority_required | `bool ` | Indicates if proposals need authority to be created. | +| organization_address | `aelf.Address` | The organization address. | +| organization_hash | `aelf.Hash` | The organization id. | +| proposal_release_threshold | `acs3.ProposalReleaseThreshold` | The threshold for releasing the proposal. | +| parliament_member_proposing_allowed | `bool ` | Indicates if parliament member can propose to this organization. | +| creation_token | `aelf.Hash` | The creation token is for organization address generation. | + +### `Parliament.ProposalIdList` + +| Field | Type | Description | Label | +| ------------ | ----------- | ------------------------- | -------- | +| proposal_ids | `aelf.Hash` | The list of proposal ids. | repeated | + +### `Parliament.ProposalInfo` + +| Field | Type | Description | Label | +| ------------------------ | ---------------------------- | ------------------------------------------------------------ | -------- | +| proposal_id | `aelf.Hash` | The proposal ID. | +| contract_method_name | `string ` | The method that this proposal will call when being released. | +| to_address | `aelf.Address` | The address of the target contract. | +| params | `bytes ` | The parameters of the release transaction. | +| expired_time | `google.protobuf.Timestamp ` | The date at which this proposal will expire. | +| proposer | `aelf.Address` | The address of the proposer of this proposal. | +| organization_address | `aelf.Address` | The address of this proposals organization. | +| approvals | `aelf.Address` | Address list of approved. | repeated | +| rejections | `aelf.Address` | Address list of rejected. | repeated | +| abstentions | `aelf.Address` | Address list of abstained. | repeated | +| proposal_description_url | `string ` | Url is used for proposal describing. | + +## AElf.Standards.ACS1 + +### `acs1.MethodFee` + +| Field | Type | Description | Label | +| --------- | --------- | ----------------------------------- | ----- | +| symbol | `string ` | The token symbol of the method fee. | +| basic_fee | `int64 ` | The amount of fees to be charged. | + +### `acs1.MethodFees` + +| Field | Type | Description | Label | +| ---------------- | ------------ | ------------------------------------------------------------ | -------- | +| method_name | `string ` | The name of the method to be charged. | +| fees | `MethodFee ` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool ` | Optional based on the implementation of SetMethodFee method. | + +## AElf.Standards.ACS3 + +### `acs3.CreateProposalBySystemContractInput` + +| Field | Type | Description | Label | +| --------------- | ---------------------- | ------------------------------------ | ----- | +| proposal_input | `CreateProposalInput ` | The parameters of creating proposal. | +| origin_proposer | `aelf.Address` | The actor that triggers the call. | + +### `acs3.CreateProposalInput` + +| Field | Type | Description | Label | +| ------------------------ | ---------------------------- | ------------------------------------------------------------ | ----- | +| contract_method_name | `string ` | The name of the method to call after release. | +| to_address | `aelf.Address` | The address of the contract to call after release. | +| params | `bytes ` | The parameters of the method to be called after the release. | +| expired_time | `google.protobuf.Timestamp ` | The timestamp at which this proposal will expire. | +| organization_address | `aelf.Address` | The address of the organization. | +| proposal_description_url | `string ` | URL used for proposal description. | +| token | `aelf.Hash` | The token for proposal ID generation and calculation. | + +### `acs3.OrganizationCreated` + +| Field | Type | Description | Label | +| -------------------- | -------------- | ---------------------------------------- | ----- | +| organization_address | `aelf.Address` | The address of the created organization. | + +### `acs3.OrganizationHashAddressPair` + +| Field | Type | Description | Label | +| -------------------- | -------------- | -------------------------------- | ----- | +| organization_hash | `aelf.Hash` | The ID of the organization. | +| organization_address | `aelf.Address` | The address of the organization. | + +### `acs3.OrganizationThresholdChanged` + +| Field | Type | Description | Label | +| -------------------------- | -------------------------- | -------------------------- | ----- | +| organization_address | `aelf.Address` | The organization address | +| proposer_release_threshold | `ProposalReleaseThreshold` | The new release threshold. | + +### `acs3.OrganizationWhiteListChanged` + +| Field | Type | Description | Label | +| -------------------- | -------------------- | --------------------------- | ----- | +| organization_address | `aelf.Address` | The organization address. | +| proposer_white_list | `ProposerWhiteList ` | The new proposer whitelist. | + +### `acs3.ProposalCreated` + +| Field | Type | Description | Label | +| -------------------- | -------------- | ------------------------------------------------- | ----- | +| proposal_id | `aelf.Hash` | The id of the created proposal. | +| organization_address | `aelf.Address` | The organization address of the created proposal. | + +### `acs3.ProposalOutput` + +| Field | Type | Description | Label | +| -------------------- | ---------------------------- | ------------------------------------------------------------ | ----- | +| proposal_id | `aelf.Hash` | The id of the proposal. | +| contract_method_name | `string ` | The method that this proposal will call when being released. | +| to_address | `aelf.Address` | The address of the target contract. | +| params | `bytes ` | The parameters of the release transaction. | +| expired_time | `google.protobuf.Timestamp ` | The date at which this proposal will expire. | +| organization_address | `aelf.Address` | The address of this proposals organization. | +| proposer | `aelf.Address` | The address of the proposer of this proposal. | +| to_be_released | `bool ` | Indicates if this proposal is releasable. | +| approval_count | `int64 ` | Approval count for this proposal. | +| rejection_count | `int64 ` | Rejection count for this proposal. | +| abstention_count | `int64 ` | Abstention count for this proposal. | + +### `acs3.ProposalReleaseThreshold` + +| Field | Type | Description | Label | +| ---------------------------- | -------- | ----------------------------------------------- | ----- | +| minimal_approval_threshold | `int64 ` | The value for the minimum approval threshold. | +| maximal_rejection_threshold | `int64 ` | The value for the maximal rejection threshold. | +| maximal_abstention_threshold | `int64 ` | The value for the maximal abstention threshold. | +| minimal_vote_threshold | `int64 ` | The value for the minimal vote threshold. | + +### `acs3.ProposalReleased` + +| Field | Type | Description | Label | +| -------------------- | -------------- | -------------------------------------------------- | ----- | +| proposal_id | `aelf.Hash` | The id of the released proposal. | +| organization_address | `aelf.Address` | The organization address of the released proposal. | + +### `acs3.ProposerWhiteList` + +| Field | Type | Description | Label | +| --------- | -------------- | ---------------------------- | -------- | +| proposers | `aelf.Address` | The address of the proposers | repeated | + +### `acs3.ReceiptCreated` + +| Field | Type | Description | Label | +| -------------------- | ---------------------------- | ---------------------------------- | ----- | +| proposal_id | `aelf.Hash` | The id of the proposal. | +| address | `aelf.Address` | The sender address. | +| receipt_type | `string ` | The type of receipt | +| time | `google.protobuf.Timestamp ` | The timestamp of this method call. | +| organization_address | `aelf.Address` | The address of the organization. | + +### `acs3.ValidateProposerInWhiteListInput` + +| Field | Type | Description | Label | +| -------------------- | -------------- | -------------------------------- | ----- | +| proposer | `aelf.Address` | The address to search/check. | +| organization_address | `aelf.Address` | The address of the organization. | + +##AElf.Types + +### `aelf.Address` + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | + +### `aelf.BinaryMerkleTree` + +| Field | Type | Description | Label | +| ---------- | -------- | ----------------------- | -------- | +| nodes | `Hash` | The leaf nodes. | repeated | +| root | `Hash` | The root node hash. | +| leaf_count | `int32 ` | The count of leaf node. | + +### `aelf.Hash` + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | + +### `aelf.LogEvent` + +| Field | Type | Description | Label | +| ----------- | --------- | ------------------------------------------ | -------- | +| address | `Address` | The contract address. | +| name | `string ` | The name of the log event. | +| indexed | `bytes ` | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes ` | The non indexed data. | + +### `aelf.MerklePath` + +| Field | Type | Description | Label | +| ----------------- | ----------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode ` | The merkle path nodes. | repeated | + +### `aelf.MerklePathNode` + +| Field | Type | Description | Label | +| ------------------ | ------- | -------------------------------- | ----- | +| hash | `Hash` | The node hash. | +| is_left_child_node | `bool ` | Whether it is a left child node. | + +### `aelf.SInt32Value` + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint32 ` | | + +### `aelf.SInt64Value` + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint64 ` | | + +### `aelf.ScopedStatePath` + +| Field | Type | Description | Label | +| ------- | ------------ | ------------------------------------------------------ | ----- | +| address | `Address` | The scope address, which will be the contract address. | +| path | `StatePath ` | The path of contract state. | + +### `aelf.SmartContractRegistration` + +| Field | Type | Description | Label | +| ------------------ | --------- | ------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code(0: C#). | +| code | `bytes` | The byte array of the contract code. | +| code_hash | `Hash` | The hash of the contract code. | +| is_system_contract | `bool` | Whether it is a system contract. | +| version | `int32` | The version of the current contract. | + +### `aelf.StatePath` + +| Field | Type | Description | Label | +| ----- | -------- | ----------------------------------- | -------- | +| parts | `string` | The partial path of the state path. | repeated | + +### `aelf.Transaction` + +| Field | Type | Description | Label | +| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | `Address` | The address of the sender of the transaction. | +| to | `Address` | The address of the contract when calling a contract. | +| ref_block_number | `int64` | The height of the referenced block hash. | +| ref_block_prefix | `bytes` | The first four bytes of the referenced block hash. | +| method_name | `string` | The name of a method in the smart contract at the To address. | +| params | `bytes` | The parameters to pass to the smart contract method. | +| signature | `bytes` | When signing a transaction it's actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | + +### `aelf.TransactionExecutingStateSet` + +| Field | Type | Description | Label | +| ------- | ------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry` | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry` | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry` | The deleted states. | repeated | + +### `aelf.TransactionExecutingStateSet.DeletesEntry` + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | +| value | `bool` | | + +### `aelf.TransactionExecutingStateSet.ReadsEntry` + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | +| value | `bool` | | + +### `aelf.TransactionExecutingStateSet.WritesEntry` + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | +| value | `bytes` | | + +### `aelf.TransactionResult` + +| Field | Type | Description | Label | +| -------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| transaction_id | `Hash` | The transaction id. | +| status | `TransactionResultStatus` | The transaction result status. | +| logs | `LogEvent` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. Through this filter, we can quickly search for and determine whether a log exists in the transaction result. | +| return_value | `bytes ` | The return value of the transaction execution. | +| block_number | `int64` | The height of the block hat packages the transaction. | +| block_hash | `Hash` | The hash of the block hat packages the transaction. | +| error | `string` | Failed execution error message. | + +### `aelf.TransactionResultStatus` + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +## AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | -------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address` | The contract address of the controller. | +| owner_address | `aelf.Address` | The address of the owner of the contract. | diff --git a/docs/References/Smart Contract API/Profit Contract.md b/docs/References/Smart Contract API/Profit Contract.md new file mode 100644 index 0000000..f6a513a --- /dev/null +++ b/docs/References/Smart Contract API/Profit Contract.md @@ -0,0 +1,454 @@ +# AElf.Contracts.Profit + +## Profit contract + +The Profit contract is an abstract layer for creating a scheme to share bonuses. Developers can build a system to distribute bonuses by calling this contract. + +Implement AElf Standards ACS1. + +### Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | -------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| CreateScheme | Profit.CreateSchemeInput | aelf.Hash | Create a scheme for profit distribution and return the created scheme id. | +| AddBeneficiary | Profit.AddBeneficiaryInput | google.protobuf.Empty | Add beneficiary to scheme. | +| RemoveBeneficiary | Profit.RemoveBeneficiaryInput | google.protobuf.Empty | Remove beneficiary from scheme. | +| AddBeneficiaries | Profit.AddBeneficiariesInput | google.protobuf.Empty | Batch add beneficiaries to scheme. | +| RemoveBeneficiaries | Profit.RemoveBeneficiariesInput | google.protobuf.Empty | Batch remove beneficiaries from scheme. | +| ContributeProfits | Profit.ContributeProfitsInput | google.protobuf.Empty | Contribute profit to a scheme. | +| ClaimProfits | Profit.ClaimProfitsInput | google.protobuf.Empty | The beneficiary draws tokens from the scheme. | +| DistributeProfits | Profit.DistributeProfitsInput | google.protobuf.Empty | Distribute profits to schemes, including its sub-schemes according to period and token symbol; should be called by the manager. | +| AddSubScheme | Profit.AddSubSchemeInput | google.protobuf.Empty | Add sub-scheme to a scheme. This effectively adds the specified sub-scheme as a beneficiary of the parent scheme. | +| RemoveSubScheme | Profit.RemoveSubSchemeInput | google.protobuf.Empty | Remove sub-scheme from a scheme. | +| ResetManager | Profit.ResetManagerInput | google.protobuf.Empty | Reset the manager of a scheme. | +| GetManagingSchemeIds | Profit.GetManagingSchemeIdsInput | Profit.CreatedSchemeIds | Get all schemes managed by the specified manager. | +| GetScheme | aelf.Hash | Profit.Scheme | Get scheme according to scheme id. | +| GetSchemeAddress | Profit.SchemePeriod | aelf.Address | Get the virtual address of the number of periods of the scheme. | +| GetDistributedProfitsInfo | Profit.SchemePeriod | Profit.DistributedProfitsInfo | Query the distributed profit information for the specified period. | +| GetProfitDetails | Profit.GetProfitDetailsInput | Profit.ProfitDetails | Query the beneficiary's profit information on the scheme. | +| GetProfitAmount | Profit.GetProfitAmountInput | google.protobuf.Int64Value | Query the amount of profit according to token symbol (up to 10 periods). | +| GetProfitsMap | Profit.ClaimProfitsInput | Profit.ReceivedProfitsMap | Query all profit (up to 10 periods). | + +### AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | --------------------------- | --------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | acs1.MethodFees | google.protobuf.Empty | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | AuthorityInfo | google.protobuf.Empty | Change the method fee controller; the default is parliament and default organization. | +| GetMethodFee | google.protobuf.StringValue | acs1.MethodFees | Query method fee information by method name. | +| GetMethodFeeController | google.protobuf.Empty | AuthorityInfo | Query the method fee controller. | + +# Contract Types + +## AElf.Contracts.Profit + +### Profit.AddBeneficiariesInput + +| Field | Type | Description | Label | +| ------------------ | ---------------- | --------------------------------------- | -------- | +| scheme_id | aelf.Hash | The scheme id. | | +| beneficiary_shares | BeneficiaryShare | The beneficiary information. | repeated | +| end_period | int64 | The end period for beneficiary profits. | | + +### Profit.AddBeneficiaryInput + +| Field | Type | Description | Label | +| ----------------- | ---------------- | --------------------------------------- | ----- | +| scheme_id | aelf.Hash | The scheme id. | | +| beneficiary_share | BeneficiaryShare | The beneficiary information. | | +| end_period | int64 | The end period for beneficiary profits. | | + +### Profit.AddSubSchemeInput + +| Field | Type | Description | Label | +| ----------------- | --------- | -------------------------------- | ----- | +| scheme_id | aelf.Hash | The parent scheme id. | | +| sub_scheme_id | aelf.Hash | The sub scheme id. | | +| sub_scheme_shares | int64 | The profit weight of sub scheme. | | + +### Profit.BeneficiaryShare + +| Field | Type | Description | Label | +| ----------- | ------------ | ------------------------------------- | ----- | +| beneficiary | aelf.Address | The beneficiary's address. | | +| shares | int64 | The profit weight of the beneficiary. | | + +### Profit.ClaimProfitsInput + +| Field | Type | Description | Label | +| ----------- | ------------ | -------------------------- | ----- | +| scheme_id | aelf.Hash | The scheme id. | | +| beneficiary | aelf.Address | The beneficiary's address. | | + +### Profit.ContributeProfitsInput + +| Field | Type | Description | Label | +| --------- | --------- | ------------------------------------ | ----- | +| scheme_id | aelf.Hash | The scheme id to contribute. | | +| amount | int64 | The amount to contribute. | | +| period | int64 | The number of periods for dividends. | | +| symbol | string | The token symbol to contribute. | | + +### Profit.CreateSchemeInput + +| Field | Type | Description | Label | +| -------------------------------------------- | ------------ | ---------------------------------------------------------- | ----- | +| profit_receiving_due_period_count | int64 | Period of profit distribution. | | +| is_release_all_balance_every_time_by_default | bool | Whether all the scheme balance is distributed each period. | | +| delay_distribute_period_count | int32 | Delay distribute period. | | +| manager | aelf.Address | The manager of the scheme. | | +| can_remove_beneficiary_directly | bool | Whether you can directly remove beneficiaries. | | +| token | aelf.Hash | Used to generate scheme id. | | + +### Profit.CreatedSchemeIds + +| Field | Type | Description | Label | +| ---------- | --------- | --------------- | -------- | +| scheme_ids | aelf.Hash | The scheme ids. | repeated | + +Here's the content converted to Markdown format with the information presented in boxes: + +### Profit.DistributeProfitsInput + +| Field | Type | Description | Label | +| ----------- | --------------- | ------------------------------------------------ | -------- | +| scheme_id | aelf.Hash | The scheme id to distribute. | | +| period | int64 | The period number to distribute, current period. | | +| amounts_map | AmountsMapEntry | The amount to distribute, symbol -> amount. | repeated | + +#### Profit.DistributeProfitsInput.AmountsMapEntry + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| key | string | | | +| value | int64 | | | + +### Profit.DistributedProfitsInfo + +| Field | Type | Description | Label | +| ------------ | --------------- | -------------------------------------------------------- | -------- | +| total_shares | int64 | Total shares in this scheme at the current period. | | +| amounts_map | AmountsMapEntry | Contributed amount in this scheme at the current period. | repeated | +| is_released | bool | Whether released. | | + +#### Profit.DistributedProfitsInfo.AmountsMapEntry + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| key | string | | | +| value | sint64 | | | + +### Profit.GetManagingSchemeIdsInput + +| Field | Type | Description | Label | +| ------- | ------------ | -------------------- | ----- | +| manager | aelf.Address | The manager address. | | + +### Profit.GetProfitAmountInput + +| Field | Type | Description | Label | +| ----------- | ------------ | ---------------------- | ----- | +| scheme_id | aelf.Hash | The scheme id. | | +| symbol | string | The token symbol. | | +| beneficiary | aelf.Address | Beneficiary's address. | | + +### Profit.GetProfitDetailsInput + +| Field | Type | Description | Label | +| ----------- | ------------ | ---------------------- | ----- | +| scheme_id | aelf.Hash | The scheme id. | | +| beneficiary | aelf.Address | Beneficiary's address. | | + +### Profit.ProfitDetail + +| Field | Type | Description | Label | +| ------------------ | ----- | ---------------------------------------------------------------- | ----- | +| start_period | int64 | The start period number. | | +| end_period | int64 | The end period number. | | +| shares | int64 | The weight of the proceeds on the current period of the scheme. | | +| last_profit_period | int64 | The last period number that the beneficiary received the profit. | | +| is_weight_removed | bool | Whether the weight has been removed. | | + +### Profit.ProfitDetails + +| Field | Type | Description | Label | +| ------- | ------------ | ----------------------- | -------- | +| details | ProfitDetail | The profit information. | repeated | + +#### Profit.ProfitDetails.ProfitDetail + +| Field | Type | Description | Label | +| ------------------ | ----- | --------------------------- | ----- | +| start_period | int64 | The start period number. | | +| end_period | int64 | The end period number. | | +| shares | int64 | The weight of the proceeds. | | +| last_profit_period | int64 | The last period received. | | +| is_weight_removed | bool | Whether weight removed. | | + +### Profit.ProfitsClaimed + +| Field | Type | Description | Label | +| -------------- | ------------ | ------------------------------- | ----- | +| beneficiary | aelf.Address | Beneficiary's address claimed. | | +| symbol | string | Token symbol claimed. | | +| amount | int64 | The amount claimed. | | +| period | int64 | The period number claimed. | | +| claimer_shares | int64 | Shares of the claimer. | | +| total_shares | int64 | Total shares at current period. | | + +### Profit.ReceivedProfitsMap + +| Field | Type | Description | Label | +| ----- | ----------------------------- | ------------------------------------------------- | -------- | +| value | ReceivedProfitsMap.ValueEntry | Collection of profits received, symbol -> amount. | repeated | + +#### Profit.ReceivedProfitsMap.ValueEntry + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| key | string | | | +| value | int64 | | | + +### Profit.RemoveBeneficiariesInput + +| Field | Type | Description | Label | +| ------------- | ------------ | --------------------------- | -------- | +| beneficiaries | aelf.Address | Addresses of beneficiaries. | repeated | +| scheme_id | aelf.Hash | The scheme id. | | + +### Profit.RemoveBeneficiaryInput + +| Field | Type | Description | Label | +| ----------- | ------------ | ---------------------- | ----- | +| beneficiary | aelf.Address | Beneficiary's address. | | +| scheme_id | aelf.Hash | The scheme id. | | + +### Profit.RemoveSubSchemeInput + +| Field | Type | Description | Label | +| ------------- | --------- | --------------------- | ----- | +| scheme_id | aelf.Hash | The parent scheme id. | | +| sub_scheme_id | aelf.Hash | The sub scheme id. | | + +### Profit.ResetManagerInput + +| Field | Type | Description | Label | +| ----------- | ------------ | ----------------------- | ----- | +| scheme_id | aelf.Hash | The scheme id. | | +| new_manager | aelf.Address | Address of new manager. | | + +### Profit.Scheme + +| Field | Type | Description | Label | +| -------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ | -------- | +| virtual_address | aelf.Address | The virtual address of the scheme. | | +| total_shares | int64 | The total weight of the scheme. | | +| manager | aelf.Address | The manager of the scheme. | | +| current_period | int64 | The current period. | | +| sub_schemes | SchemeBeneficiaryShare | Sub schemes information. | repeated | +| can_remove_beneficiary_directly | bool | Whether you can directly remove the beneficiary. | | +| profit_receiving_due_period_count | int64 | Period of profit distribution. | | +| is_release_all_balance_every_time_by_default | bool | Whether all the schemes balance will be distributed during distribution each period. | | +| scheme_id | aelf.Hash | The is of the scheme. | | +| delay_distribute_period_count | int32 | Delay distribute period. | | +| cached_delay_total_shares | Scheme.CachedDelayTotalSharesEntry | Record the scheme's current total share for deferred distribution of benefits, period -> total shares. | repeated | +| received_token_symbols | string | The received token symbols. | repeated | + +### Profit.Scheme.CachedDelayTotalSharesEntry + +| Field | Type | Description | Label | +| ----- | ----- | ----------- | ----- | +| key | int64 | | | +| value | int64 | | | + +### Profit.SchemeBeneficiaryShare + +| Field | Type | Description | Label | +| --------- | --------- | ----------------------------- | ----- | +| scheme_id | aelf.Hash | The id of the sub scheme. | | +| shares | int64 | The weight of the sub scheme. | | + +### Profit.SchemeCreated + +| Field | Type | Description | Label | +| -------------------------------------------- | ------------ | ---------------------------------------------------------------- | ----- | +| virtual_address | aelf.Address | The virtual address of the created scheme. | | +| manager | aelf.Address | The manager of the created scheme. | | +| profit_receiving_due_period_count | int64 | Period of profit distribution. | | +| is_release_all_balance_every_time_by_default | bool | Whether all the schemes balance will be distributed each period. | | +| scheme_id | aelf.Hash | The id of the created scheme. | | + +### Profit.SchemePeriod + +| Field | Type | Description | Label | +| --------- | --------- | ------------------ | ----- | +| scheme_id | aelf.Hash | The scheme id. | | +| period | int64 | The period number. | | + +## AElf.Standards.ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | ------ | ----------------------------------- | ----- | +| symbol | string | The token symbol of the method fee. | | +| basic_fee | int64 | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | --------- | ------------------------------------------------------------ | -------- | +| method_name | string | The name of the method. | | +| fees | MethodFee | List of fees to be charged. | repeated | +| is_size_fee_free | bool | Optional based on the implementation of SetMethodFee method. | | + +## AElf.Types + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | ----- | ----------- | ----- | +| value | bytes | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | ----- | ----------------------- | -------- | +| nodes | Hash | The leaf nodes. | repeated | +| root | Hash | The root node hash. | | +| leaf_count | int32 | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | ----- | ----------- | ----- | +| value | bytes | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ------- | ------------------------------------------ | -------- | +| address | Address | The contract address. | | +| name | string | The name of the log event. | | +| indexed | bytes | The indexed data, used to calculate bloom. | repeated | +| non_indexed | bytes | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | -------------- | ---------------------- | -------- | +| merkle_path_nodes | MerklePathNode | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ---- | -------------------------------- | ----- | +| hash | Hash | The node hash. | | +| is_left_child_node | bool | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| value | sint32 | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| value | sint64 | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | --------- | ------------------------------------------------------ | ----- | +| address | Address | The scope address, which will be the contract address. | | +| path | StatePath | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | ------ | ------------------------------------- | ----- | +| category | sint32 | The category of contract code(0: C#). | | +| code | bytes | The byte array of the contract code. | | +| code_hash | Hash | The hash of the contract code. | | +| is_system_contract | bool | Whether it is a system contract. | | +| version | int32 | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | ------ | ----------------------------------- | -------- | +| parts | string | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----- | +| from | Address | The address of the sender of the transaction. | | +| to | Address | The address of the contract when calling a contract. | | +| ref_block_number | int64 | The height of the referenced block hash. | | +| ref_block_prefix | bytes | The first four bytes of the referenced block hash. | | +| method_name | string | The name of a method in the smart contract at the To address. | | +| params | bytes | The parameters to pass to the smart contract method. | | +| signature | bytes | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | ----------------------------------------- | ------------------- | -------- | +| writes | TransactionExecutingStateSet.WritesEntry | The changed states. | repeated | +| reads | TransactionExecutingStateSet.ReadsEntry | The read states. | repeated | +| deletes | TransactionExecutingStateSet.DeletesEntry | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| key | string | | | +| value | bool | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| key | string | | | +| value | bool | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | ------ | ----------- | ----- | +| key | string | | | +| value | bytes | | | + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | ----------------------- | ------------------------------------------------------ | -------- | +| transaction_id | Hash | The transaction id. | | +| status | TransactionResultStatus | The transaction result status. | | +| logs | LogEvent | The log events. | repeated | +| bloom | bytes | Bloom filter for transaction logs. | | +| return_value | bytes | The return value of the transaction execution. | | +| block_number | int64 | The height of the block that packages the transaction. | | +| block_hash | Hash | The hash of the block that packages the transaction. | | +| error | string | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +# AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | ------------ | --------------------------------------- | ----- | +| contract_address | aelf.Address | The contract address of the controller. | | diff --git a/docs/References/Smart Contract API/Referendum Contract.md b/docs/References/Smart Contract API/Referendum Contract.md new file mode 100644 index 0000000..e2d2d55 --- /dev/null +++ b/docs/References/Smart Contract API/Referendum Contract.md @@ -0,0 +1,489 @@ +# AElf.Contracts.Referendum + +Referendum contract. + +Production nodes or associations cannot determine all decisions. Some extremely important decisions, especially those involving user rights and interests, should involve all users and give full control to the user's voting for governance. The Referendum contract is built for this. + +Implement AElf Standards ACS1 and ACS3. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ | +| ReclaimVoteToken | `aelf.Hash <#aelf.Hash>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Unlock the token used for voting according to proposal id. | +| CreateOrganization | `Referendum.CreateOrganizationInput <#Referendum.CreateOrganizationInput>`\_\_ | `aelf.Address <#aelf.Address>`\_\_ | Create an organization and return its address. | +| CreateOrganizationBySystemContract | `Referendum.CreateOrganizationBySystemContractInput <#Referendum.CreateOrganizationBySystemContractInput>`\_\_ | `aelf.Address <#aelf.Address>`\_\_ | Creates an organization by system contract and return its address. | +| GetOrganization | `aelf.Address <#aelf.Address>`\_\_ | `Referendum.Organization <#Referendum.Organization>`\_\_ | Get the organization according to the organization address. | +| CalculateOrganizationAddress | `Referendum.CreateOrganizationInput <#Referendum.CreateOrganizationInput>`\_\_ | `aelf.Address <#aelf.Address>`\_\_ | Calculate the input and return the organization address. | +| GetProposalVirtualAddress | `aelf.Hash <#aelf.Hash>`\_\_ | `aelf.Address <#aelf.Address>`\_\_ | Get the virtual address of a proposal based on the proposal id. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees <#acs1.MethodFees>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo <#AuthorityInfo>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue <#google.protobuf.StringValue>`\_\_ | `acs1.MethodFees <#acs1.MethodFees>`\_\_ | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | `AuthorityInfo <#AuthorityInfo>`\_\_ | Query the method fee controller. | + +## AElf.Standards.ACS3 + +| Method Name | Request Type | Response Type | Description | +| ----------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CreateProposal | `acs3.CreateProposalInput <#acs3.CreateProposalInput>`\_\_ | `aelf.Hash <#aelf.Hash>`\_\_ | Create a proposal for which organization members can vote. When the proposal is released, a transaction will be sent to the specified contract. Return id of the newly created proposal. | +| Approve | `aelf.Hash <#aelf.Hash>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Approve a proposal according to the proposal ID. | +| Reject | `aelf.Hash <#aelf.Hash>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Reject a proposal according to the proposal ID. | +| Abstain | `aelf.Hash <#aelf.Hash>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Abstain a proposal according to the proposal ID. | +| Release | `aelf.Hash <#aelf.Hash>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Release a proposal according to the proposal ID and send a transaction to the specified contract. | +| ChangeOrganizationThreshold | `acs3.ProposalReleaseThreshold <#acs3.ProposalReleaseThreshold>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Change the thresholds associated with proposals. All fields will be overwritten by the input value and this will affect all current proposals of the organization. Note: only the organization can execute this through a proposal. | +| ChangeOrganizationProposerWhiteList | `acs3.ProposerWhiteList <#acs3.ProposerWhiteList>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Change the white list of organization proposer. This method overrides the list of whitelisted proposers. | +| CreateProposalBySystemContract | `acs3.CreateProposalBySystemContractInput <#acs3.CreateProposalBySystemContractInput>`\_\_ | `aelf.Hash <#aelf.Hash>`\_\_ | Create a proposal by system contracts, and return id of the newly created proposal. | +| ClearProposal | `aelf.Hash <#aelf.Hash>`\_\_ | `google.protobuf.Empty <#google.protobuf.Empty>`\_\_ | Remove the specified proposal. If the proposal is in effect, the cleanup fails. | +| GetProposal | `aelf.Hash <#aelf.Hash>`\_\_ | `acs3.ProposalOutput <#acs3.ProposalOutput>`\_\_ | Get the proposal according to the proposal ID. | +| ValidateOrganizationExist | `aelf.Address <#aelf.Address>`\_\_ | `google.protobuf.BoolValue <#google.protobuf.BoolValue>`\_\_ | Check the existence of an organization. | +| ValidateProposerInWhiteList | `acs3.ValidateProposerInWhiteListInput <#acs3.ValidateProposerInWhiteListInput>`\_\_ | `google.protobuf.BoolValue <#google.protobuf.BoolValue>`\_\_ | Check if the proposer is whitelisted. | + +# Contract Types + +## AElf.Contracts.Referendum + +### `Referendum.CreateOrganizationBySystemContractInput` + +| Field | Type | Description | Label | +| ------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----- | +| organization_creation_input | `CreateOrganizationInput <#Referendum.CreateOrganizationInput>`\_\_ | The parameters of creating organization. | | +| organization_address_feedback_method | `string <#string>`\_\_ | The organization address callback method which replies the organization address to caller contract. | | + +### `Referendum.CreateOrganizationInput` + +| Field | Type | Description | Label | +| -------------------------- | ------------------------------- | ---------------------------------------------------------- | ----- | +| token_symbol | `string` | The token used during proposal operations. | | +| proposal_release_threshold | `acs3.ProposalReleaseThreshold` | The threshold for releasing the proposal. | | +| proposer_white_list | `acs3.ProposerWhiteList` | The proposer whitelist. | | +| creation_token | `aelf.Hash` | The creation token is for organization address generation. | | + +### `Referendum.Organization` + +| Field | Type | Description | Label | +| -------------------------- | ------------------------------- | ---------------------------------------------------------- | ----- | +| proposal_release_threshold | `acs3.ProposalReleaseThreshold` | The threshold for releasing the proposal. | | +| token_symbol | `string` | The token used during proposal operations. | | +| organization_address | `aelf.Address` | The address of organization. | | +| organization_hash | `aelf.Hash` | The organization's id. | | +| proposer_white_list | `acs3.ProposerWhiteList` | The proposer whitelist. | | +| creation_token | `aelf.Hash` | The creation token is for organization address generation. | | + +### `Referendum.ProposalInfo` + +| Field | Type | Description | Label | +| ------------------------ | --------------------------- | ------------------------------------------------------------ | ----- | +| proposal_id | `aelf.Hash` | The proposal ID. | | +| contract_method_name | `string` | The method that this proposal will call when being released. | | +| to_address | `aelf.Address` | The address of the target contract. | | +| params | `bytes` | The parameters of the release transaction. | | +| expired_time | `google.protobuf.Timestamp` | The date at which this proposal will expire. | | +| proposer | `aelf.Address` | The address of the proposer of this proposal. | | +| organization_address | `aelf.Address` | The address of this proposal's organization. | | +| approval_count | `int64` | The count of approved. | | +| rejection_count | `int64` | The count of rejected. | | +| abstention_count | `int64` | The count of abstained. | | +| proposal_description_url | `string` | URL used for proposal describing. | | + +### `Referendum.Receipt` + +| Field | Type | Description | Label | +| ------------ | ----------- | --------------------------- | ----- | +| amount | `int64` | The amount of token locked. | | +| token_symbol | `string` | The symbol of token locked. | | +| lock_id | `aelf.Hash` | The lock ID. | | + +### `Referendum.ReferendumReceiptCreated` + +| Field | Type | Description | Label | +| -------------------- | --------------------------- | -------------------------------------------------- | ----- | +| proposal_id | `aelf.Hash` | The ID of the proposal. | | +| address | `aelf.Address` | The sender address. | | +| symbol | `string` | The symbol of token locked. | | +| amount | `int64` | The amount of token locked. | | +| receipt_type | `string` | The type of receipt (Approve, Reject, or Abstain). | | +| time | `google.protobuf.Timestamp` | The timestamp of this method call. | | +| organization_address | `aelf.Address` | The address of the organization. | | + +## AElf.Standards.ACS1 + +### `acs1.MethodFee` + +| Field | Type | Description | Label | +| --------- | ---------------------- | ----------------------------------- | ----- | +| symbol | `string <#string>`\_\_ | The token symbol of the method fee. | | +| basic_fee | `int64 <#int64>`\_\_ | The amount of fees to be charged. | | + +### `acs1.MethodFees` + +| Field | Type | Description | Label | +| ---------------- | --------------------------------- | ------------------------------------- | -------- | +| method_name | `string <#string>`\_\_ | The name of the method to be charged. | | +| fees | `MethodFee <#acs1.MethodFee>`\_\_ | List of fees to be charged. | repeated | +| is_size_fee_free | `bool <#bool>`\_\_ | Optional based on the implementation. | | + +## AElf.Standards.ACS3 + +### `acs3.CreateProposalBySystemContractInput` + +| Field | Type | Description | Label | +| --------------- | ----------------------------------------------------- | ------------------------------------ | ----- | +| proposal_input | `CreateProposalInput <#acs3.CreateProposalInput>`\_\_ | The parameters of creating proposal. | | +| origin_proposer | `aelf.Address <#aelf.Address>`\_\_ | The actor that triggers the call. | | + +### `acs3.CreateProposalInput` + +| Field | Type | Description | Label | +| ------------------------ | ------------------------------------------------------------ | ----------------------------------------------------------- | ----- | +| contract_method_name | `string <#string>`\_\_ | The name of the method to call after release. | | +| to_address | `aelf.Address <#aelf.Address>`\_\_ | The address of the contract to call after release. | | +| params | `bytes <#bytes>`\_\_ | The parameter of the method to be called after the release. | | +| expired_time | `google.protobuf.Timestamp <#google.protobuf.Timestamp>`\_\_ | The timestamp at which this proposal will expire. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | The address of the organization. | | +| proposal_description_url | `string <#string>`\_\_ | URL used for proposal description. | | +| token | `aelf.Hash <#aelf.Hash>`\_\_ | The token for proposal ID generation. | | + +### `acs3.OrganizationCreated` + +| Field | Type | Description | Label | +| -------------------- | ---------------------------------- | ---------------------------------------- | ----- | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | The address of the created organization. | | + +### `acs3.OrganizationHashAddressPair` + +| Field | Type | Description | Label | +| -------------------- | ---------------------------------- | ---------------------------- | ----- | +| organization_hash | `aelf.Hash <#aelf.Hash>`\_\_ | The ID of the organization. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | The address of organization. | | + +### `acs3.OrganizationThresholdChanged` + +| Field | Type | Description | Label | +| -------------------------- | --------------------------------------------------------------- | -------------------------- | ----- | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | The organization address | | +| proposer_release_threshold | `ProposalReleaseThreshold <#acs3.ProposalReleaseThreshold>`\_\_ | The new release threshold. | | + +### `acs3.OrganizationWhiteListChanged` + +| Field | Type | Description | Label | +| -------------------- | ------------------------------------------------- | --------------------------- | ----- | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | The organization address. | | +| proposer_white_list | `ProposerWhiteList <#acs3.ProposerWhiteList>`\_\_ | The new proposer whitelist. | | + +### `acs3.ProposalCreated` + +| Field | Type | Description | Label | +| -------------------- | ---------------------------------- | ------------------------------------------------- | ----- | +| proposal_id | `aelf.Hash <#aelf.Hash>`\_\_ | The ID of the created proposal. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | The organization address of the created proposal. | | + +### `acs3.ProposalOutput` + +| Field | Type | Description | Label | +| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ----- | +| proposal_id | `aelf.Hash <#aelf.Hash>`\_\_ | The ID of the proposal. | | +| contract_method_name | `string <#string>`\_\_ | The method that this proposal will call when being released. | | +| to_address | `aelf.Address <#aelf.Address>`\_\_ | The address of the target contract. | | +| params | `bytes <#bytes>`\_\_ | The parameters of the release transaction. | | +| expired_time | `google.protobuf.Timestamp <#google.protobuf.Timestamp>`\_\_ | The date at which this proposal will expire. | | +| organization_address | `aelf.Address <#aelf.Address>`\_\_ | The address of this proposal's organization. | | +| proposer | `aelf.Address <#aelf.Address>`\_\_ | The address of the proposer of this proposal. | | +| to_be_released | `bool <#bool>`\_\_ | Indicates if this proposal is releasable. | | +| approval_count | `int64 <#int64>`\_\_ | Approval count for this proposal. | | +| rejection_count | `int64 <#int64>`\_\_ | Rejection count for this proposal. | | +| abstention_count | `int64 <#int64>`\_\_ | Abstention count for this proposal. | | + +### `acs3.ProposalReleaseThreshold` + +| Field | Type | Description | Label | +| ---------------------------- | -------------------- | ----------------------------------------------- | ----- | +| minimal_approval_threshold | `int64 <#int64>`\_\_ | The value for the minimum approval threshold. | | +| maximal_rejection_threshold | `int64 <#int64>`\_\_ | The value for the maximal rejection threshold. | | +| maximal_abstention_threshold | `int64 <#int64>`\_\_ | The value for the maximal abstention threshold. | | +| minimal_vote_threshold | `int64 <#int64>`\_\_ | The value for the minimal vote threshold. | | + +## AElf.Standards.ACS1 + +### `acs1.MethodFee` + +| Field | Type | Description | Label | +| --------- | -------- | ----------------------------------- | ----- | +| symbol | `string` | The token symbol of the method fee. | | +| basic_fee | `int64` | The amount of fees to be charged. | | + +#### `acs1.MethodFees` + +| Field | Type | Description | Label | +| ---------------- | ----------- | ------------------------------------- | -------- | +| method_name | `string` | The name of the method to be charged. | | +| fees | `MethodFee` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool` | Optional based on the implementation. | | + +## AElf.Standards.ACS3 + +### `acs3.CreateProposalBySystemContractInput` + +| Field | Type | Description | Label | +| --------------- | --------------------- | ------------------------------------ | ----- | +| proposal_input | `CreateProposalInput` | The parameters of creating proposal. | | +| origin_proposer | `aelf.Address` | The actor that triggers the call. | | + +### `acs3.CreateProposalInput` + +| Field | Type | Description | Label | +| ------------------------ | --------------------------- | ----------------------------------------------------------- | ----- | +| contract_method_name | `string` | The name of the method to call after release. | | +| to_address | `aelf.Address` | The address of the contract to call after release. | | +| params | `bytes` | The parameter of the method to be called after the release. | | +| expired_time | `google.protobuf.Timestamp` | The timestamp at which this proposal will expire. | | +| organization_address | `aelf.Address` | The address of the organization. | | +| proposal_description_url | `string` | URL used for proposal description. | | +| token | `aelf.Hash` | The token for proposal ID generation. | | + +### `acs3.OrganizationCreated` + +| Field | Type | Description | Label | +| -------------------- | -------------- | ---------------------------------------- | ----- | +| organization_address | `aelf.Address` | The address of the created organization. | | + +### `acs3.OrganizationHashAddressPair` + +| Field | Type | Description | Label | +| -------------------- | -------------- | ---------------------------- | ----- | +| organization_hash | `aelf.Hash` | The ID of organization. | | +| organization_address | `aelf.Address` | The address of organization. | | + +### `acs3.OrganizationThresholdChanged` + +| Field | Type | Description | Label | +| -------------------------- | -------------------------- | -------------------------- | ----- | +| organization_address | `aelf.Address` | The organization address | | +| proposer_release_threshold | `ProposalReleaseThreshold` | The new release threshold. | | + +### `acs3.OrganizationWhiteListChanged` + +| Field | Type | Description | Label | +| -------------------- | ------------------- | --------------------------- | ----- | +| organization_address | `aelf.Address` | The organization address. | | +| proposer_white_list | `ProposerWhiteList` | The new proposer whitelist. | | + +### `acs3.ProposalCreated` + +| Field | Type | Description | Label | +| -------------------- | -------------- | ------------------------------- | ----- | +| proposal_id | `aelf.Hash` | The ID of the created proposal. | | +| organization_address | `aelf.Address` | The organization address. | | + +### `acs3.ProposalOutput` + +| Field | Type | Description | Label | +| -------------------- | --------------------------- | ------------------------------------------------------------ | ----- | +| proposal_id | `aelf.Hash` | The ID of the proposal. | | +| contract_method_name | `string` | The method that this proposal will call when being released. | | +| to_address | `aelf.Address` | The address of the target contract. | | +| params | `bytes` | The parameters of the release transaction. | | +| expired_time | `google.protobuf.Timestamp` | The date at which this proposal will expire. | | +| organization_address | `aelf.Address` | The address of this proposal's organization. | | +| proposer | `aelf.Address` | The address of the proposer of this proposal. | | +| to_be_released | `bool` | Indicates if this proposal is releasable. | | +| approval_count | `int64` | Approval count for this proposal. | | +| rejection_count | `int64` | Rejection count for this proposal. | | +| abstention_count | `int64` | Abstention count for this proposal. | | + +### `acs3.ProposalReleaseThreshold` + +| Field | Type | Description | Label | +| ---------------------------- | ------- | ----------------------------------------------- | ----- | +| minimal_approval_threshold | `int64` | The value for the minimum approval threshold. | | +| maximal_rejection_threshold | `int64` | The value for the maximal rejection threshold. | | +| maximal_abstention_threshold | `int64` | The value for the maximal abstention threshold. | | +| minimal_vote_threshold | `int64` | The value for the minimal vote threshold. | | + +### `acs3.ProposalReleased` + +| Field | Type | Description | Label | +| -------------------- | -------------- | -------------------------------------------------- | ----- | +| proposal_id | `aelf.Hash` | The id of the released proposal. | | +| organization_address | `aelf.Address` | The organization address of the released proposal. | | + +### `acs3.ProposerWhiteList` + +| Field | Type | Description | Label | +| --------- | -------------- | ---------------------------- | -------- | +| proposers | `aelf.Address` | The address of the proposers | repeated | + +### `acs3.ReceiptCreated` + +| Field | Type | Description | Label | +| -------------------- | --------------------------- | -------------------------------------------------- | ----- | +| proposal_id | `aelf.Hash` | The id of the proposal. | | +| address | `aelf.Address` | The sender address. | | +| receipt_type | `string` | The type of receipt (Approve, Reject, or Abstain). | | +| time | `google.protobuf.Timestamp` | The timestamp of this method call. | | +| organization_address | `aelf.Address` | The address of the organization. | | + +### `acs3.ValidateProposerInWhiteListInput` + +| Field | + +| Type | Description | Label | +| -------------------- | -------------- | -------------------------------- | --- | +| proposer | `aelf.Address` | The address to search/check. | | +| organization_address | `aelf.Address` | The address of the organization. | | + +## AElf.Types + +### `aelf.Address` + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +### `aelf.BinaryMerkleTree` + +| Field | Type | Description | Label | +| ---------- | ------- | ----------------------- | -------- | +| nodes | `Hash` | The leaf nodes. | repeated | +| root | `Hash` | The root node hash. | | +| leaf_count | `int32` | The count of leaf node. | | + +### `aelf.Hash` + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +### `aelf.LogEvent` + +| Field | Type | Description | Label | +| ----------- | --------- | -------------------------- | -------- | +| address | `Address` | The contract address. | | +| name | `string` | The name of the log event. | | +| indexed | `bytes` | The indexed data. | repeated | +| non_indexed | `bytes` | The non-indexed data. | | + +### `aelf.MerklePath` + +| Field | Type | Description | Label | +| ----------------- | ---------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode` | The merkle path nodes. | repeated | + +### `aelf.MerklePathNode` + +| Field | Type | Description | Label | +| ------------------ | ------ | -------------------------------- | ----- | +| hash | `Hash` | The node hash. | | +| is_left_child_node | `bool` | Whether it is a left child node. | | + +### `aelf.SInt32Value` + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `sint32` | | | + +### `aelf.SInt64Value` + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `sint64` | | | + +### `aelf.ScopedStatePath` + +| Field | Type | Description | Label | +| ------- | ----------- | --------------------------- | ----- | +| address | `Address` | The scope address. | | +| path | `StatePath` | The path of contract state. | | + +### `aelf.SmartContractRegistration` + +| Field | Type | Description | Label | +| ------------------ | ----------------------- | ------------------------------------- | ----- | +| category | `sint32 <#sint32>`\_\_ | The category of contract code(0: C#). | | +| code | `bytes <#bytes>`\_\_ | The byte array of the contract code. | | +| code_hash | `Hash <#aelf.Hash>`\_\_ | The hash of the contract code. | | +| is_system_contract | `bool <#bool>`\_\_ | Whether it is a system contract. | | +| version | `int32 <#int32>`\_\_ | The version of the current contract. | | + +### `aelf.StatePath` + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------------------------------- | -------- | +| parts | `string <#string>`\_\_ | The partial path of the state path. | repeated | + +### `aelf.Transaction` + +| Field | Type | Description | Label | +| ---------------- | ----------------------------- | ---------------------------------------------------------------- | ----- | +| from | `Address <#aelf.Address>`\_\_ | The address of the sender of the transaction. | | +| to | `Address <#aelf.Address>`\_\_ | The address of the contract when calling a contract. | | +| ref_block_number | `int64 <#int64>`\_\_ | The height of the referenced block hash. | | +| ref_block_prefix | `bytes <#bytes>`\_\_ | The first four bytes of the referenced block hash. | | +| method_name | `string <#string>`\_\_ | The name of a method in the smart contract at the To address. | | +| params | `bytes <#bytes>`\_\_ | The parameters to pass to the smart contract method. | | +| signature | `bytes <#bytes>`\_\_ | When signing a transaction it’s actually a subset of the fields. | | + +### `aelf.TransactionExecutingStateSet` + +| Field | Type | Description | Label | +| ------- | ------------------------------------------------------------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry <#aelf.TransactionExecutingStateSet.WritesEntry>`\_\_ | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry <#aelf.TransactionExecutingStateSet.ReadsEntry>`\_\_ | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry <#aelf.TransactionExecutingStateSet.DeletesEntry>`\_\_ | The deleted states. | repeated | + +### `aelf.TransactionExecutingStateSet.DeletesEntry` + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------- | ----- | +| key | `string <#string>`\_\_ | | | +| value | `bool <#bool>`\_\_ | | | + +### `aelf.TransactionExecutingStateSet.ReadsEntry` + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------- | ----- | +| key | `string <#string>`\_\_ | | | +| value | `bool <#bool>`\_\_ | | | + +### `aelf.TransactionExecutingStateSet.WritesEntry` + +| Field | Type | Description | Label | +| ----- | ---------------------- | ----------- | ----- | +| key | `string <#string>`\_\_ | | | +| value | `bytes <#bytes>`\_\_ | | | + +### `aelf.TransactionResult` + +| Field | Type | Description | Label | +| -------------- | ------------------------------------------------------------- | ----------------------------------------------------- | -------- | +| transaction_id | `Hash <#aelf.Hash>`\_\_ | The transaction id. | | +| status | `TransactionResultStatus <#aelf.TransactionResultStatus>`\_\_ | The transaction result status. | | +| logs | `LogEvent <#aelf.LogEvent>`\_\_ | The log events. | repeated | +| bloom | `bytes <#bytes>`\_\_ | Bloom filter for transaction logs. | | +| return_value | `bytes <#bytes>`\_\_ | The return value of the transaction execution. | | +| block_number | `int64 <#int64>`\_\_ | The height of the block hat packages the transaction. | | +| block_hash | `Hash <#aelf.Hash>`\_\_ | The hash of the block hat packages the transaction. | | +| error | `string <#string>`\_\_ | Failed execution error message. | | + +### `aelf.TransactionResultStatus` + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +## AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | ------------------------------ | ----------------------------------------- | ----- | +| contract_address | `aelf.Address <#aelf.Address>` | The contract address of the controller. | | +| owner_address | `aelf.Address <#aelf.Address>` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Token Converter.md b/docs/References/Smart Contract API/Token Converter.md new file mode 100644 index 0000000..76db6b6 --- /dev/null +++ b/docs/References/Smart Contract API/Token Converter.md @@ -0,0 +1,309 @@ +# AElf.Contracts.TokenConverter + +Using this contract can build a connection between the base token and other tokens created on the chain. After building the connection, users can trade tokens with the Bancor model. You can find detailed information about Bancor in the AElf Economic System White Paper. + +Implement AElf Standards ACS1. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ------------------------------- | --------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- | +| Initialize | `TokenConverter.InitializeInput` | `google.protobuf.Empty` | Initialize TokenConvert contract. | +| SetConnector | `TokenConverter.Connector` | `google.protobuf.Empty` | | +| Buy | `TokenConverter.BuyInput` | `google.protobuf.Empty` | After establishing Bancor model of token and base token, you can buy token through this method. | +| Sell | `TokenConverter.SellInput` | `google.protobuf.Empty` | After establishing Bancor model of token and base token, you can sell token through this method. | +| SetFeeRate | `google.protobuf.StringValue` | `google.protobuf.Empty` | Set the fee rate for buy/sell (fee amount = cost \* feeRate). | +| UpdateConnector | `TokenConverter.Connector` | `google.protobuf.Empty` | Before calling the EnableConnector, the connector controller can update the pair connector through this method. | +| AddPairConnector | `TokenConverter.PairConnectorParam` | `google.protobuf.Empty` | Add a pair connector for new token and the base token. | +| EnableConnector | `TokenConverter.ToBeConnectedTokenInfo` | `google.protobuf.Empty` | After adding a pair, you need to call this method to enable it before buying and selling tokens. | +| ChangeConnectorController | `AuthorityInfo` | `google.protobuf.Empty` | Set the governance authority information for TokenConvert contract. | +| GetPairConnector | `TokenConverter.TokenSymbol` | `TokenConverter.PairConnector` | Query the pair connector according to token symbol. | +| GetFeeRate | `google.protobuf.Empty` | `google.protobuf.StringValue` | Query the fee rate for buy/sell. | +| GetBaseTokenSymbol | `google.protobuf.Empty` | `TokenConverter.TokenSymbol` | Query the symbol of base token. | +| GetNeededDeposit | `TokenConverter.ToBeConnectedTokenInfo` | `TokenConverter.DepositInfo` | Query how much the base token needs to be deposited before enabling the connector. | +| GetDepositConnectorBalance | `google.protobuf.StringValue` | `google.protobuf.Int64Value` | Query how much the base token has been deposited. | +| GetControllerForManageConnector | `google.protobuf.Empty` | `AuthorityInfo` | Query the governance authority information for TokenConvert contract. | +| IsSymbolAbleToSell | `google.protobuf.StringValue` | `google.protobuf.BoolValue` | Query whether the token can be sold. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees` | `google.protobuf.Empty` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue` | `acs1.MethodFees` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty` | `AuthorityInfo` | Query the method fee controller. | + +# Contract Types + +## AElf.Contracts.TokenConverter + +### TokenConverter.BuyInput + +| Field | Type | Description | Label | +| --------- | -------- | -------------------------------------------------------------------------------------------------------------- | ----- | +| symbol | `string` | The token symbol you want to buy. | | +| amount | `int64` | The amount you want to buy. | | +| pay_limit | `int64` | Limit of cost. If the token required for buy exceeds this value, the buy will be abandoned. And 0 is no limit. | | + +### TokenConverter.Connector + +| Field | Type | Description | Label | +| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | ----- | +| symbol | `string` | The token symbol. | | +| virtual_balance | `int64` | The virtual balance for base token. | | +| weight | `string` | The calculated weight value for this Connector. | | +| is_virtual_balance_enabled | `bool` | Whether to use Virtual Balance. | | +| is_purchase_enabled | `bool` | Whether the connector is enabled. | | +| related_symbol | `string` | Indicates its related connector, the pair connector includes a new created token connector and the base token connector. | | +| is_deposit_account | `bool` | Indicates if the connector is base token connector. | | + +### TokenConverter.DepositInfo + +| Field | Type | Description | Label | +| --------------------------- | ------- | ---------------------------------------------------- | ----- | +| need_amount | `int64` | How much more base Token is needed as the deposit. | | +| amount_out_of_token_convert | `int64` | How many tokens are not on the TokenConvert address. | | + +### TokenConverter.InitializeInput + +| Field | Type | Description | Label | +| ----------------- | ----------- | ------------------------------------------------------ | -------- | +| base_token_symbol | `string` | Base token symbol, default is the native token symbol. | | +| fee_rate | `string` | The fee rate for buy/sell. | | +| connectors | `Connector` | The default added connectors. | repeated | + +### TokenConverter.PairConnector + +| Field | Type | Description | Label | +| ------------------ | ----------- | ------------------------------------- | ----- | +| resource_connector | `Connector` | The connector of the specified token. | | +| deposit_connector | `Connector` | The related connector. | | + +### TokenConverter.PairConnectorParam + +| Field | Type | Description | Label | +| ------------------------- | -------- | --------------------------------------------------- | ----- | +| resource_connector_symbol | `string` | The token symbol. | | +| resource_weight | `string` | The weight value of this token in the Bancor model. | | +| native_virtual_balance | `int64` | This token corresponds to the value of base token. | | +| native_weight | `string` | The weight value of base token in Bancor model. | | + +### TokenConverter.SellInput + +| Field | Type | Description | Label | +| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----- | +| symbol | `string` | The token symbol you want to sell. | | +| amount | `int64` | The amount you want to sell. | | +| receive_limit | `int64` | Limits on tokens obtained by selling. If the token obtained is less than this value, the sale will be abandoned. And 0 is no limit. | | + +### TokenConverter.ToBeConnectedTokenInfo + +| Field | Type | Description | Label | +| ----------------------- | -------- | ----------------------------------------------------------------------- | ----- | +| token_symbol | `string` | The token symbol. | | +| amount_to_token_convert | `int64` | Specifies the number of tokens to convert to the TokenConvert contract. | | + +### TokenConverter.TokenBought + +| Field | Type | Description | Label | +| ------------- | -------- | --------------------------------- | ----- | +| symbol | `string` | The token symbol bought. | | +| bought_amount | `int64` | The amount bought. | | +| base_amount | `int64` | The total cost of the base token. | | +| fee_amount | `int64` | The fee amount. | | + +### TokenConverter.TokenSold + +| Field | Type | Description | Label | +| ----------- | -------- | ------------------------------------- | ----- | +| symbol | `string` | The token symbol sold. | | +| sold_amount | `int64` | The amount sold. | | +| base_amount | `int64` | The total received of the base token. | | +| fee_amount | `int64` | The fee amount. | | + +### TokenConverter.TokenSymbol + +| Field | Type | Description | Label | +| ------ | --------- | ----------------- | ----- | +| symbol | `string ` | The token symbol. | | + +## AElf.Standards.ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | --------- | ----------------------------------- | ----- | +| symbol | `string ` | The token symbol of the method fee. | | +| basic_fee | `int64 ` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ------------ | ------------------------------------------------------------ | -------- | +| method_name | `string ` | The name of the method to be charged. | | +| fees | `MethodFee ` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool` | Optional based on the implementation of SetMethodFee method. | | + +## AElf.Types + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | -------- | ----------------------- | -------- | +| nodes | `Hash ` | The leaf nodes. | repeated | +| root | `Hash ` | The root node hash. | | +| leaf_count | `int32 ` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ---------- | ------------------------------------------ | -------- | +| address | `Address ` | The contract address. | | +| name | `string ` | The name of the log event. | | +| indexed | `bytes ` | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes ` | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ----------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode ` | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------- | -------------------------------- | ----- | +| hash | `Hash ` | The node hash. | | +| is_left_child_node | `bool` | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint32 ` | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint64 ` | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ------------------------------ | ------------------------------------------------------ | ----- | +| address | [`Address`](#aelf.Address) | The scope address, which will be the contract address. | | +| path | [`StatePath`](#aelf.StatePath) | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | -------------------- | -------------------------------------- | ----- | +| category | [`sint32`](#sint32) | The category of contract code (0: C#). | | +| code | [`bytes`](#bytes) | The byte array of the contract code. | | +| code_hash | [`Hash`](#aelf.Hash) | The hash of the contract code. | | +| is_system_contract | [`bool`](#bool) | Whether it is a system contract. | | +| version | [`int32`](#int32) | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | ------------------- | ----------------------------------- | -------- | +| parts | [`string`](#string) | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | [`Address`](#aelf.Address) | The address of the sender of the transaction. | | +| to | [`Address`](#aelf.Address) | The address of the contract when calling a contract. | | +| ref_block_number | [`int64`](#int64) | The height of the referenced block hash. | | +| ref_block_prefix | [`bytes`](#bytes) | The first four bytes of the referenced block hash. | | +| method_name | [`string`](#string) | The name of a method in the smart contract at the To address. | | +| params | [`bytes`](#bytes) | The parameters to pass to the smart contract method. | | +| signature | [`bytes`](#bytes) | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | ---------------------------------------------------------------------------------------------- | ------------------- | -------- | +| writes | [`TransactionExecutingStateSet.WritesEntry`](#aelf.TransactionExecutingStateSet.WritesEntry) | The changed states. | repeated | +| reads | [`TransactionExecutingStateSet.ReadsEntry`](#aelf.TransactionExecutingStateSet.ReadsEntry) | The read states. | repeated | +| deletes | [`TransactionExecutingStateSet.DeletesEntry`](#aelf.TransactionExecutingStateSet.DeletesEntry) | The deleted states. | repeated | + +
+ +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | ------------------- | ----------- | ----- | +| key | [`string`](#string) | | | +| value | [`bool`](#bool) | | | + +
+ +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | ------------------- | ----------- | ----- | +| key | [`string`](#string) | | | +| value | [`bool`](#bool) | | | + +
+ +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | ------------------- | ----------- | ----- | +| key | [`string`](#string) | | | +| value | [`bytes`](#bytes) | | | + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| transaction_id | [`Hash`](#aelf.Hash) | The transaction id. | | +| status | [`TransactionResultStatus`](#aelf.TransactionResultStatus) | The transaction result status. | | +| logs | [`LogEvent`](#aelf.LogEvent) | The log events. | repeated | +| bloom | [`bytes`](#bytes) | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. Through this filter, we can quickly search for and determine whether a log exists in the transaction result. | | +| return_value | [`bytes`](#bytes) | The return value of the transaction execution. | | +| block_number | [`int64`](#int64) | The height of the block hat packages the transaction. | | +| block_hash | [`Hash`](#aelf.Hash) | The hash of the block hat packages the transaction. | | +| error | [`string`] | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +## AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | ------------------------------- | ----------------------------------------- | ----- | +| contract_address | [`aelf.Address`](#aelf.Address) | The contract address of the controller. | | +| owner_address | [`aelf.Address`](#aelf.Address) | The address of the owner of the contract. | | + +``` + +Feel free to copy and save this content to a `.md` file. If you need any modifications or additions, let me know! +``` diff --git a/docs/References/Smart Contract API/Token Holder.md b/docs/References/Smart Contract API/Token Holder.md new file mode 100644 index 0000000..1d18697 --- /dev/null +++ b/docs/References/Smart Contract API/Token Holder.md @@ -0,0 +1,297 @@ +# AElf.Contracts.TokenHolder + +TokenHolder contract. + +Used to build a bonus model for distributing bonuses to those who hold the token. + +Implement AElf Standards ACS1. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ------------------ | ------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| CreateScheme | `TokenHolder.CreateTokenHolderProfitSchemeInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Create a scheme for distributing bonuses. | +| AddBeneficiary | `TokenHolder.AddTokenHolderBeneficiaryInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Add a beneficiary to a scheme. | +| RemoveBeneficiary | `TokenHolder.RemoveTokenHolderBeneficiaryInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Removes a beneficiary from a scheme. Note: amount > 0: update the weight of the beneficiary, amount = 0: remove the beneficiary. | +| ContributeProfits | `TokenHolder.ContributeProfitsInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Contribute profit to a scheme. | +| DistributeProfits | `TokenHolder.DistributeProfitsInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | To distribute the profits of the scheme, the stakeholders of the project may go to receive dividends. | +| RegisterForProfits | `TokenHolder.RegisterForProfitsInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | The user registers a bonus project. | +| Withdraw | `aelf.Address ` | `google.protobuf.Empty <#google.protobuf.Empty>` | After the lockup time expires, the user can withdraw tokens. | +| ClaimProfits | `TokenHolder.ClaimProfitsInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | After DistributeProfits, the holder can get his dividend. | +| GetScheme | `aelf.Address ` | `TokenHolder.TokenHolderProfitScheme ` | Query the details of the specified scheme. | +| GetProfitsMap | `TokenHolder.ClaimProfitsInput` | `TokenHolder.ReceivedProfitsMap ` | Query the dividends available to the holder. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ------------------------------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo <#AuthorityInfo>` | `google.protobuf.Empty <#google.protobuf.Empty>` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue <#google.protobuf.StringValue>` | `acs1.MethodFees <#acs1.MethodFees>` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty <#google.protobuf.Empty>` | `AuthorityInfo <#AuthorityInfo>` | Query the method fee controller. | + +## Contract Types + +### TokenHolder.AddTokenHolderBeneficiaryInput + +| Field | Type | Description | Label | +| ----------- | --------------- | -------------------------------------------------------- | ----- | +| beneficiary | `aelf.Address ` | Beneficiary's address. | | +| shares | `int64 ` | The weight of the beneficiary's dividends in the scheme. | | + +### TokenHolder.ClaimProfitsInput + +| Field | Type | Description | Label | +| -------------- | -------------------- | -------------------------- | ----- | +| scheme_manager | `aelf.Address ` | The manager of the scheme. | | +| beneficiary | `aelf.Address <#aelf | + +### TokenHolder.ContributeProfitsInput + +| Field | Type | Description | Label | +| -------------- | -------------- | ---------------------------------- | ----- | +| scheme_manager | `aelf.Address` | The manager of the scheme. | | +| amount | `int64` | The amount of token to contribute. | | +| symbol | `string` | The symbol of token to contribute. | | + +### TokenHolder.CreateTokenHolderProfitSchemeInput + +| Field | Type | Description | Label | +| ------------------------- | ----------------------------------------------------------------- | ------------------------------------------ | -------- | +| symbol | `string` | The token symbol. | | +| minimum_lock_minutes | `int64` | Minimum lock time for holding token. | | +| auto_distribute_threshold | `CreateTokenHolderProfitSchemeInput.AutoDistributeThresholdEntry` | Threshold setting for releasing dividends. | repeated | + +### TokenHolder.CreateTokenHolderProfitSchemeInput.AutoDistributeThresholdEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +### TokenHolder.DistributeProfitsInput + +| Field | Type | Description | Label | +| -------------- | ---------------------------------------- | ------------------------------------------ | -------- | +| scheme_manager | `aelf.Address` | The manager of the scheme. | | +| amounts_map | `DistributeProfitsInput.AmountsMapEntry` | The token to distribute, symbol -> amount. | repeated | + +### TokenHolder.DistributeProfitsInput.AmountsMapEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +### TokenHolder.ReceivedProfitsMap + +| Field | Type | Description | Label | +| ----- | ------------------------------- | -------------------------------------------------------------- | -------- | +| value | `ReceivedProfitsMap.ValueEntry` | The amount of token the beneficiary can get, symbol -> amount. | repeated | + +### TokenHolder.ReceivedProfitsMap.ValueEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +### TokenHolder.RegisterForProfitsInput + +| Field | Type | Description | Label | +| -------------- | -------------- | ---------------------------- | ----- | +| scheme_manager | `aelf.Address` | The manager of the scheme. | | +| amount | `int64` | The amount of token holding. | | + +### TokenHolder.RemoveTokenHolderBeneficiaryInput + +| Field | Type | Description | Label | +| ----------- | -------------- | -------------------------------- | ----- | +| beneficiary | `aelf.Address` | Beneficiary's address. | | +| amount | `int64` | The amount of weights to remove. | | + +### TokenHolder.TokenHolderProfitScheme + +| Field | Type | Description | Label | +| ------------------------- | ------------------------------------------------------ | ------------------------------------------ | -------- | +| symbol | `string` | The token symbol. | | +| scheme_id | `aelf.Hash` | The scheme id. | | +| period | `int64` | The current dividend period. | | +| minimum_lock_minutes | `int64` | Minimum lock time for holding token. | | +| auto_distribute_threshold | `TokenHolderProfitScheme.AutoDistributeThresholdEntry` | Threshold setting for releasing dividends. | repeated | + +### TokenHolder.TokenHolderProfitScheme.AutoDistributeThresholdEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +## AElf.Standards.ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | -------- | ----------------------------------- | ----- | +| symbol | `string` | The token symbol of the method fee. | | +| basic_fee | `int64` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ----------- | ------------------------------------------------------------ | -------- | +| method_name | `string` | The name of the method to be charged. | | +| fees | `MethodFee` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool` | Optional based on the implementation of SetMethodFee method. | | + +## AElf.Types + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | ------- | ----------- | ----- | +| value | `bytes` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | ------- | ----------------------- | -------- | +| nodes | `Hash` | The leaf nodes. | repeated | +| root | `Hash` | The root node hash. | | +| leaf_count | `int32` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ---------- | ------------------------------------------ | -------- | +| address | `Address ` | The contract address. | | +| name | `string ` | The name of the log event. | | +| indexed | `bytes ` | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes ` | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | --------------------------------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode <#aelf.MerklePathNode>` | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------- | -------------------------------- | ----- | +| hash | `Hash ` | The node hash. | | +| is_left_child_node | `bool ` | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint32 ` | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint64 ` | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ------------ | ------------------------------------------------------ | ----- | +| address | `Address ` | The scope address, which will be the contract address. | | +| path | `StatePath ` | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | -------- | -------------------------------------- | ----- | +| category | `sint32` | The category of contract code (0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| code_hash | `Hash ` | The hash of the contract code. | | +| is_system_contract | `bool ` | Whether it is a system contract. | | +| version | `int32 ` | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | --------- | ----------------------------------- | -------- | +| parts | `string ` | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | +| from | `Address ` | The address of the sender of the transaction. | | +| to | `Address ` | The address of the contract when calling a contract. | | +| ref_block_number | `int64 ` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes ` | The first four bytes of the referenced block hash. | | +| method_name | `string ` | The name of a method in the smart contract at the To address. | | +| params | `bytes ` | The parameters to pass to the smart contract method. | | +| signature | `bytes ` | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | -------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry ` | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry ` | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry ` | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| transaction_id | `Hash ` | The transaction id. | | +| status | `TransactionResultStatus ` | The transaction result status. | | +| logs | `LogEvent ` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. Through this filter, we can quickly search for and determine whether a log exists in the transaction result. | | +| return_value | `bytes ` | The return value of the transaction execution. | | +| block_number | `int64 ` | The height of the block that packages the transaction. | | +| block_hash | `Hash ` | The hash of the block that packages the transaction. | | +| error | `string ` | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +# AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | --------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address of the controller. | | +| owner_address | `aelf.Address ` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Treasury Contract.md b/docs/References/Smart Contract API/Treasury Contract.md new file mode 100644 index 0000000..d547783 --- /dev/null +++ b/docs/References/Smart Contract API/Treasury Contract.md @@ -0,0 +1,359 @@ +# AElf.Contracts.Treasury + +Treasury contract. + +Used for distributing bonuses to voters and candidates during the election process. + +Implement AElf Standards ACS1 and ACS10. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| ------------------------------- | ----------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------- | +| InitialTreasuryContract | `google.protobuf.Empty` | `google.protobuf.Empty` | Initialize treasury contract. | +| InitialMiningRewardProfitItem | `google.protobuf.Empty` | `google.protobuf.Empty` | Initialize the sub-item of the bonus scheme. | +| DonateAll | `Treasury.DonateAllInput` | `google.protobuf.Empty` | Donate all tokens owned by the sender. | +| SetDividendPoolWeightSetting | `Treasury.DividendPoolWeightSetting` | `google.protobuf.Empty` | Set the dividend weight of the sub-item of the dividend item. | +| SetMinerRewardWeightSetting | `Treasury.MinerRewardWeightSetting` | `google.protobuf.Empty` | Set the miner reward weight. | +| SetProfitsReceiver | `Treasury.SetProfitsReceiverInput` | `google.protobuf.Empty` | Set collect profits receiver address. | +| UpdateMiningReward | `google.protobuf.Int64Value` | `google.protobuf.Empty` | Set the reward for mining. | +| ChangeTreasuryController | `AuthorityInfo` | `google.protobuf.Empty` | Change the governance authority information for the treasury contract. | +| RecordMinerReplacement | `Treasury.RecordMinerReplacementInput` | `google.protobuf.Empty` | AEDPoS Contract can notify Treasury Contract to be aware of miner replacement happening. | +| GetWelfareRewardAmountSample | `Treasury.GetWelfareRewardAmountSampleInput` | `Treasury.GetWelfareRewardAmountSampleOutput` | Used to estimate the revenue weight of 10000 tokens voted by users. | +| GetTreasurySchemeId | `google.protobuf.Empty` | `aelf.Hash` | Get the scheme id of treasury. | +| GetDividendPoolWeightProportion | `google.protobuf.Empty` | `Treasury.DividendPoolWeightProportion` | Query the weight percentage of dividend pool items. | +| GetMinerRewardWeightProportion | `google.protobuf.Empty` | `Treasury.MinerRewardWeightProportion` | Query the weight percentage of the dividend item for miners. | +| GetTreasuryController | `google.protobuf.Empty` | `AuthorityInfo` | Query the governance authority information. | +| GetProfitsReceiver | `google.protobuf.StringValue` | `aelf.Address` | Get profits receiver. If not set, return the candidate's address. | +| GetProfitsReceiverOrDefault | `google.protobuf.StringValue` | `aelf.Address` | Get profits receiver. If not set, return null. | +| ReplaceCandidateProfitsReceiver | `Treasury.ReplaceCandidateProfitsReceiverInput` | `google.protobuf.Empty` | Query the governance authority information. | + +## AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ----------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees` | `google.protobuf.Empty` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue` | `acs1.MethodFees` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty` | `AuthorityInfo` | Query the method fee controller. | + +## AElf.Standards.ACS10 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ---------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Donate | `acs10.DonateInput` | `google.protobuf.Empty` | Donates tokens from the caller to the treasury. If the tokens are not native tokens in the current chain, they will be first converted to the native token. | +| Release | `acs10.ReleaseInput` | `google.protobuf.Empty` | Release dividend pool according to the period number. | +| SetSymbolList | `acs10.SymbolList` | `google.protobuf.Empty` | Set the token symbols dividend pool supports. | +| GetSymbolList | `google.protobuf.Empty` | `acs10.SymbolList` | Query the token symbols dividend pool supports. | +| GetUndistributedDividends | `google.protobuf.Empty` | `acs10.Dividends` | Query the balance of undistributed tokens whose symbols are included in the symbol list. | +| GetDividends | `google.protobuf.Int64Value` | `acs10.Dividends` | Query the dividend information according to the height. | + +## Contract Types + +## AElf.Contracts.Treasury + +### Treasury.DividendPoolWeightProportion + +| Field | Type | Description | Label | +| ------------------------------- | ---------------------- | ---------------------------------- | ----- | +| citizen_welfare_proportion_info | `SchemeProportionInfo` | The proportion of citizen welfare. | | +| backup_subsidy_proportion_info | `SchemeProportionInfo` | The proportion of candidate nodes. | | +| miner_reward_proportion_info | `SchemeProportionInfo` | The proportion of miner | | + +### Treasury.DividendPoolWeightSetting + +| Field | Type | Description | Label | +| ---------------------- | ------- | --------------------------------------- | ----- | +| citizen_welfare_weight | `int32` | The dividend weight of citizen welfare. | | +| backup_subsidy_weight | `int32` | The dividend weight of candidate nodes. | | +| miner_reward_weight | `int32` | The dividend weight of miner. | | + +### Treasury.DonateAllInput + +| Field | Type | Description | Label | +| ------ | -------- | --------------------------- | ----- | +| symbol | `string` | The token symbol to donate. | | + +### Treasury.GetWelfareRewardAmountSampleInput + +| Field | Type | Description | Label | +| ----- | ------- | ---------------- | -------- | +| value | `int64` | Token lock time. | repeated | + +### Treasury.GetWelfareRewardAmountSampleOutput + +| Field | Type | Description | Label | +| ----- | ------- | ---------------------- | -------- | +| value | `int64` | The weight calculated. | repeated | + +### Treasury.MinerReElectionInformation + +| Field | Type | Description | Label | +| --------------------------- | ----------------------------------------------------------- | ---------------------------------------- | -------- | +| continual_appointment_times | `MinerReElectionInformation.ContinualAppointmentTimesEntry` | The reappointment information for miner. | repeated | + +### Treasury.MinerReElectionInformation.ContinualAppointmentTimesEntry + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| key | `string` | | | +| value | `int64` | | | + +### Treasury.MinerRewardWeightProportion + +| Field | Type | Description | Label | +| ----------------------------------- | ---------------------- | ------------------------------------------------- | ----- | +| basic_miner_reward_proportion_info | `SchemeProportionInfo` | The proportion of the basic income of the miner. | | +| votes_weight_reward_proportion_info | `SchemeProportionInfo` | The proportion of the vote of the miner. | | +| re_election_reward_proportion_info | `SchemeProportionInfo` | The proportion of the reappointment of the miner. | | + +### Treasury.MinerRewardWeightSetting + +| Field | Type | Description | Label | +| -------------------------- | ------- | ------------------------------------------------------ | ----- | +| basic_miner_reward_weight | `int32` | The dividend weight of the basic income of the miner. | | +| votes_weight_reward_weight | `int32` | The dividend weight of the vote of the miner. | | +| re_election_reward_weight | `int32` | The dividend weight of the reappointment of the miner. | | + +### Treasury.RecordMinerReplacementInput + +| Field | Type | Description | Label | +| ------------------- | -------- | ----------- | ----- | +| old_pubkey | `string` | | | +| new_pubkey | `string` | | | +| current_term_number | `int64` | | | + +### Treasury.SchemeProportionInfo + +| Field | Type | Description | Label | +| ---------- | ----------- | --------------------------- | ----- | +| scheme_id | `aelf.Hash` | The scheme id. | | +| proportion | `int32` | Dividend weight percentage. | | + +### Treasury.SetProfitsReceiverInput + +| Field | Type | Description | Label | +| ------------------------ | ----------- | -------------------------------- | ----- | +| pubkey | `string` | The candidate's public key. | | +| profits_receiver_address | `aelf.Hash` | The address of profits receiver. | | + +### Treasury.ReplaceCandidateProfitsReceiverInput + +| Field | Type | Description | Label | +| ---------- | -------- | ------------------------------- | ----- | +| old_pubkey | `string` | The old candidate's public key. | | +| new_pubkey | `string` | The new candidate's public key. | | + +Sure, I can help with that. Here's the content converted to Markdown format without the HTML tags: + +# AElf.Standards.ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | --------- | ----------------------------------- | ----- | +| symbol | `string ` | The token symbol of the method fee. | | +| basic_fee | `int64 ` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ------------ | ------------------------------------- | -------- | +| method_name | `string ` | The name of the method to be charged. | | +| fees | `MethodFee ` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool ` | Optional based on the implementation. | | + +# AElf.Standards.ACS10 + +### acs10.Dividends + +| Field | Type | Description | Label | +| ----- | ----------------------- | -------------------------------- | -------- | +| value | `Dividends.ValueEntry ` | The dividends, symbol -> amount. | repeated | + +### acs10.Dividends.ValueEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int64 ` | | | + +### acs10.DonateInput + +| Field | Type | Description | Label | +| ------ | --------- | --------------------------- | ----- | +| symbol | `string ` | The token symbol to donate. | | +| amount | `int64 ` | The amount to donate. | | + +### acs10.DonationReceived + +| Field | Type | Description | Label | +| ------------- | --------------- | ----------------------------- | ----- | +| from | `aelf.Address ` | The address of donors. | | +| pool_contract | `aelf.Address ` | The address of dividend pool. | | +| symbol | `string ` | The token symbol Donated. | | +| amount | `int64 ` | The amount Donated. | | + +### acs10.ReleaseInput + +| Field | Type | Description | Label | +| ------------- | -------- | ----------------------------- | ----- | +| period_number | `int64 ` | The period number to release. | | + +### acs10.SymbolList + +| Field | Type | Description | Label | +| ----- | --------- | ---------------------- | -------- | +| value | `string ` | The token symbol list. | repeated | + +# AElf.Types + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | -------- | ----------------------- | -------- | +| nodes | `Hash ` | The leaf nodes. | repeated | +| root | `Hash ` | The root node hash. | | +| leaf_count | `int32 ` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ---------- | ------------------------------------------ | -------- | +| address | `Address ` | The contract address. | | +| name | `string ` | The name of the log event. | | +| indexed | `bytes ` | The indexed data, used to calculate bloom. | repeated | +| non_indexed | `bytes ` | The non-indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ----------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode ` | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------- | ------------------------------- | ----- | +| hash | `Hash ` | The node hash. | | +| is_left_child_node | `bool ` | Whether it's a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint32 ` | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint64 ` | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ------------ | ------------------------------------------------------ | ----- | +| address | `Address ` | The scope address, which will be the contract address. | | +| path | `StatePath ` | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | --------- | -------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code (0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| code_hash | `Hash ` | The hash of the contract code. | | +| is_system_contract | `bool ` | Whether it is a system contract. | | +| version | `int32 ` | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | --------- | ----------------------------------- | -------- | +| parts | `string ` | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | +| from | `Address ` | The address of the sender of the transaction. | | +| to | `Address ` | The address of the contract when calling a contract. | | +| ref_block_number | `int64 ` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes ` | The first four bytes of the referenced block hash. | | +| method_name | `string ` | The name of a method in the smart contract at the To address. | | +| params | `bytes ` | The parameters to pass to the smart contract method. | | +| signature | `bytes ` | When signing a transaction, it’s actually a subset of the fields: from/to and the target method, as well as the parameter that were given. It also contains the reference block number and prefix. | | + +### aelf.TransactionExecutingStateSet + +| Field | Type | Description | Label | +| ------- | -------------------------------------------- | ------------------- | -------- | +| writes | `TransactionExecutingStateSet.WritesEntry ` | The changed states. | repeated | +| reads | `TransactionExecutingStateSet.ReadsEntry ` | The read states. | repeated | +| deletes | `TransactionExecutingStateSet.DeletesEntry ` | The deleted states. | repeated | + +### aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +### aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| transaction_id | `Hash ` | The transaction id. | | +| status | `TransactionResultStatus ` | The transaction result status. | | +| logs | `LogEvent ` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. | | +| return_value | `bytes ` | The return value of the transaction execution. | | +| block_number | `int64 ` | The height of the block that packages the transaction. | | +| block_hash | `Hash ` | The hash of the block that packages the transaction. | | +| error | `string ` | Failed execution error message. | | + +### aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +# AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | --------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address of the controller. | | +| owner_address | `aelf.Address ` | The address of the owner of the contract. | | diff --git a/docs/References/Smart Contract API/Vote Contract.md b/docs/References/Smart Contract API/Vote Contract.md new file mode 100644 index 0000000..5e6ae24 --- /dev/null +++ b/docs/References/Smart Contract API/Vote Contract.md @@ -0,0 +1,402 @@ +# AElf.Contracts.Vote + +Vote contract. + +The Vote contract is an abstract layer for voting. Developers implement +concrete voting activities by calling this contract. + +Implements AElf Standards ACS1. + +## Contract Methods + +| Method Name | Request Type | Response Type | Description | +| --------------------- | ----------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------- | +| Register | `Vote.VotingRegisterInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Create a voting activity. | +| Vote | `Vote.VoteInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | After successfully creating a voting activity, others are able to vote. | +| Withdraw | `Vote.WithdrawInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | A voter can withdraw the token after the lock time. | +| TakeSnapshot | `Vote.TakeSnapshotInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Save the result of the specified number of votes and generates a new round of votes. | +| AddOption | `Vote.AddOptionInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Add an option to a voting activity. | +| RemoveOption | `Vote.RemoveOptionInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Remove an option from a voting activity. | +| AddOptions | `Vote.AddOptionsInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Add multiple options to a voting activity. | +| RemoveOptions | `Vote.RemoveOptionsInput ` | `google.protobuf.Empty <#google.protobuf.Empty>` | Remove multiple options from a voting activity. | +| GetVotingItem | `Vote.GetVotingItemInput ` | `Vote.VotingItem ` | Get a voting activity information. | +| GetVotingResult | `Vote.GetVotingResultInput ` | `Vote.VotingResult ` | Get a voting result according to the provided voting activity id and snapshot number. | +| GetLatestVotingResult | `aelf.Hash ` | `Vote.VotingResult ` | Gets the latest result according to the voting activity id. | +| GetVotingRecord | `aelf.Hash ` | `Vote.VotingRecord ` | Get the voting record according to vote id. | +| GetVotingRecords | `Vote.GetVotingRecordsInput ` | `Vote.VotingRecords <#Vote.VotingRecords>` | Get the voting record according to vote ids. | +| GetVotedItems | `aelf.Address ` | `Vote.VotedItems <#Vote.VotedItems>` | Get all voted information according to voter address. | +| GetVotingIds | `Vote.GetVotingIdsInput ` | `Vote.VotedIds ` | Get the vote ids according to voting activity id. | + +# AElf.Standards.ACS1 + +| Method Name | Request Type | Response Type | Description | +| ------------------------- | ------------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------- | +| SetMethodFee | `acs1.MethodFees ` | `google.protobuf.Empty ` | Set the method fees for the specified method. Note that this will override all fees of the method. | +| ChangeMethodFeeController | `AuthorityInfo` | `google.protobuf.Empty ` | Change the method fee controller, the default is parliament and default organization. | +| GetMethodFee | `google.protobuf.StringValue ` | `acs1.MethodFees ` | Query method fee information by method name. | +| GetMethodFeeController | `google.protobuf.Empty ` | `AuthorityInfo` | Query the method fee controller. | + +# Contract Types + +## AElf.Contracts.Vote + +### Vote.AddOptionInput + +| Field | Type | Description | Label | +| -------------- | ------------ | ----------------------- | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| option | `string ` | The new option to add. | | + +### Vote.AddOptionsInput + +| Field | Type | Description | Label | +| -------------- | ------------ | ----------------------- | -------- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| options | `string ` | The new options to add. | repeated | + +### Vote.GetVotingIdsInput + +| Field | Type | Description | Label | +| -------------- | --------------- | ----------------------- | ----- | +| voter | `aelf.Address ` | The address of voter. | | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | + +### Vote.GetVotingItemInput + +| Field | Type | Description | Label | +| -------------- | ------------ | ----------------------- | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | + +### Vote.GetVotingRecordsInput + +| Field | Type | Description | Label | +| ----- | ------------ | ------------- | -------- | +| ids | `aelf.Hash ` | The vote ids. | repeated | + +### Vote.GetVotingResultInput + +| Field | Type | Description | Label | +| --------------- | ------------ | ----------------------- | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| snapshot_number | `int64 ` | The snapshot number. | | + +### Vote.RemoveOptionInput + +| Field | Type | Description | Label | +| -------------- | ------------ | ----------------------- | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| option | `string ` | The option to remove. | | + +### Vote.RemoveOptionsInput + +| Field | Type | Description | Label | +| -------------- | ------------ | ----------------------- | -------- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| options | `string ` | The options to remove. | repeated | + +### Vote.TakeSnapshotInput + +| Field | Type | Description | Label | +| --------------- | ------------ | ---------------------------- | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| snapshot_number | `int64 ` | The snapshot number to take. | | + +### Vote.VoteInput + +| Field | Type | Description | Label | +| ---------------- | --------------- | ----------------------- | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| voter | `aelf.Address ` | The address of voter. | | +| amount | `int64 ` | The amount of vote. | | +| option | `string ` | The option to vote. | | +| vote_id | `aelf.Hash ` | The vote id. | | +| is_change_target | `bool ` | Whether vote others. | | + +### Vote.Voted + +| Field | Type | Description | Label | +| --------------- | -------------------------------------------------------- | ----------------------- | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| voter | `aelf.Address ` | The address of voter. | | +| snapshot_number | `int64 ` | The snapshot number. | | +| amount | `int64 ` | The amount of vote. | | +| vote_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The time of vote. | | +| option | `string ` | The option voted. | | +| vote_id | `aelf.Hash ` | The vote id. | | + +### Vote.VotedIds + +| Field | Type | Description | Label | +| --------------- | ------------ | ----------------------- | -------- | +| active_votes | `aelf.Hash ` | The active vote ids. | repeated | +| withdrawn_votes | `aelf.Hash ` | The withdrawn vote ids. | repeated | + +### Vote.VotedItems + +| Field | Type | Description | Label | +| ------------------- | ----------------------------------- | -------------- | -------- | +| voted_item_vote_ids | `VotedItems.VotedItemVoteIdsEntry ` | The voted ids. | repeated | + +### Vote.VotedItems.VotedItemVoteIdsEntry + +| Field | Type | Description | Label | +| ----- | ----------- | ----------- | ----- | +| key | `string ` | | | +| value | `VotedIds ` | | | + +### Vote.VotingItem + +| Field | Type | Description | Label | +| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------- | -------- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| accepted_currency | `string ` | The token symbol which will be accepted. | | +| is_lock_token | `bool ` | Whether the vote will lock token. | | +| current_snapshot_number | `int64 ` | The current snapshot number. | | +| total_snapshot_number | `int64 ` | The total snapshot number. | | +| options | `string ` | The list of options. | repeated | +| register_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The register time of the voting activity. | | +| start_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The start time of the voting. | | +| end_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The end time of the voting. | | +| current_snapshot_start_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The start time of current round of the voting. | | +| sponsor | `aelf.Address ` | The sponsor address of the voting activity. | | + +### Vote.VotingItemRegistered + +| Field | Type | Description | Label | +| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------- | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| accepted_currency | `string ` | The token symbol which will be accepted. | | +| is_lock_token | `bool ` | Whether the vote will lock token. | | +| current_snapshot_number | `int64 ` | The current snapshot number. | | +| total_snapshot_number | `int64 ` | The total number of snapshots of the vote. | | +| register_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The register time of the voting activity. | | +| start_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The start time of the voting. | | +| end_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The end time of the voting. | | +| current_snapshot_start_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The start time of current round of the voting. | | +| sponsor | `aelf.Address ` | The sponsor address of the voting activity. | | + +### Vote.VotingRecord + +| Field | Type | Description | Label | +| ------------------ | -------------------------------------------------------- | ------------------------------------ | ----- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| voter | `aelf.Address ` | The address of voter. | | +| snapshot_number | `int64 ` | The snapshot number. | | +| amount | `int64 ` | The amount of vote. | | +| withdraw_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The time of withdraw. | | +| vote_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The time of vote. | | +| is_withdrawn | `bool ` | Whether the vote had been withdrawn. | | +| option | `string ` | The option voted. | | +| is_change_target | `bool ` | Whether vote others. | | + +### Vote.VotingRecords + +| Field | Type | Description | Label | +| ------- | --------------- | ------------------- | -------- | +| records | `VotingRecord ` | The voting records. | repeated | + +### Vote.VotingRegisterInput + +| Field | Type | Description | Label | +| --------------------- | -------------------------------------------------------- | ------------------------------------------ | -------- | +| start_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The start time of the voting. | | +| end_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The end time of the voting. | | +| accepted_currency | `string ` | The token symbol which will be accepted. | | +| is_lock_token | `bool ` | Whether the vote will lock token. | | +| total_snapshot_number | `int64 ` | The total number of snapshots of the vote. | | +| options | `string ` | The list of options. | repeated | + +### Vote.VotingResult + +| Field | Type | Description | Label | +| ------------------------ | -------------------------------------------------------- | --------------------------------------------------------- | -------- | +| voting_item_id | `aelf.Hash ` | The voting activity id. | | +| results | `VotingResult.ResultsEntry ` | The voting result, option -> amount of votes, | repeated | +| snapshot_number | `int64 ` | The snapshot number. | | +| voters_count | `int64 ` | The total number of voters. | | +| snapshot_start_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The start time of this snapshot. | | +| snapshot_end_timestamp | `google.protobuf.Timestamp <#google.protobuf.Timestamp>` | The end time of this snapshot. | | +| votes_amount | `int64 ` | Total votes received during the process of this snapshot. | | + +### Vote.VotingResult.ResultsEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `int64 ` | | | + +### Vote.WithdrawInput + +| Field | Type | Description | Label | +| ------- | ------------ | ------------ | ----- | +| vote_id | `aelf.Hash ` | The vote id. | | + +### Vote.Withdrawn + +| Field | Type | Description | Label | +| ------- | ------------ | ------------ | ----- | +| vote_id | `aelf.Hash ` | The vote id. | | + +## AElf.Standards.ACS1 + +### acs1.MethodFee + +| Field | Type | Description | Label | +| --------- | --------- | ----------------------------------- | ----- | +| symbol | `string ` | The token symbol of the method fee. | | +| basic_fee | `int64 ` | The amount of fees to be charged. | | + +### acs1.MethodFees + +| Field | Type | Description | Label | +| ---------------- | ------------ | ------------------------------------------------------------ | -------- | +| method_name | `string ` | The name of the method to be charged. | | +| fees | `MethodFee ` | List of fees to be charged. | repeated | +| is_size_fee_free | `bool ` | Optional based on the implementation of SetMethodFee method. | | + +## AElf.Types + +### aelf.Address + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.BinaryMerkleTree + +| Field | Type | Description | Label | +| ---------- | -------- | ----------------------- | -------- | +| nodes | `Hash ` | The leaf nodes. | repeated | +| root | `Hash ` | The root node hash. | | +| leaf_count | `int32 ` | The count of leaf node. | | + +### aelf.Hash + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `bytes ` | | | + +### aelf.LogEvent + +| Field | Type | Description | Label | +| ----------- | ---------- | -------------------------- | -------- | +| address | `Address ` | The contract address. | | +| name | `string ` | The name of the log event. | | +| indexed | `bytes ` | The indexed data. | repeated | +| non_indexed | `bytes ` | The non indexed data. | | + +### aelf.MerklePath + +| Field | Type | Description | Label | +| ----------------- | ----------------- | ---------------------- | -------- | +| merkle_path_nodes | `MerklePathNode ` | The merkle path nodes. | repeated | + +### aelf.MerklePathNode + +| Field | Type | Description | Label | +| ------------------ | ------- | -------------------------------- | ----- | +| hash | `Hash ` | The node hash. | | +| is_left_child_node | `bool ` | Whether it is a left child node. | | + +### aelf.SInt32Value + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| value | `sint32 ` | | | + +### aelf.SInt64Value + +| Field | Type | Description | Label | +| ----- | -------- | ----------- | ----- | +| value | `sint64` | | | + +### aelf.ScopedStatePath + +| Field | Type | Description | Label | +| ------- | ----------------------------- | ------------------------------------------------------ | ----- | +| address | `Address ` | The scope address, which will be the contract address. | | +| path | `StatePath <#aelf.StatePath>` | The path of contract state. | | + +### aelf.SmartContractRegistration + +| Field | Type | Description | Label | +| ------------------ | --------- | ------------------------------------- | ----- | +| category | `sint32 ` | The category of contract code(0: C#). | | +| code | `bytes ` | The byte array of the contract code. | | +| code_hash | `Hash ` | The hash of the contract code. | | +| is_system_contract | `bool ` | Whether it is a system contract. | | +| version | `int32 ` | The version of the current contract. | | + +### aelf.StatePath + +| Field | Type | Description | Label | +| ----- | --------- | ----------------------------------- | -------- | +| parts | `string ` | The partial path of the state path. | repeated | + +### aelf.Transaction + +| Field | Type | Description | Label | +| ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----- | +| from | `Address ` | The address of the sender of the transaction. | | +| to | `Address ` | The address of the contract when calling a contract. | | +| ref_block_number | `int64 ` | The height of the referenced block hash. | | +| ref_block_prefix | `bytes ` | The first four bytes of the referenced block hash. | | +| method_name | `string ` | The name of a method in the smart contract at the To address. | | +| params | `bytes ` | The parameters to pass to the smart contract method. | | +| signature | `bytes ` | When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. | | + +## aelf.TransactionExecutingStateSet.DeletesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.ReadsEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bool ` | | | + +### aelf.TransactionExecutingStateSet.WritesEntry + +| Field | Type | Description | Label | +| ----- | --------- | ----------- | ----- | +| key | `string ` | | | +| value | `bytes ` | | | + +## aelf.TransactionResult + +| Field | Type | Description | Label | +| -------------- | -------------------------- | ---------------------------------------------- | -------- | +| transaction_id | `Hash ` | The transaction id. | | +| status | `TransactionResultStatus ` | The transaction result status. | | +| logs | `LogEvent ` | The log events. | repeated | +| bloom | `bytes ` | Bloom filter for transaction logs. | | +| return_value | `bytes ` | The return value of the transaction execution. | + + | | + +| block_number | `int64 `** | The height of the block that packages the transaction. | | +| block_hash | `Hash `** | The hash of the block that packages the transaction. | | +| error | `string ` | Failed execution error message. | | + +## aelf.TransactionResultStatus + +| Name | Number | Description | +| ---------------------- | ------ | --------------------------------------------------------------------------------- | +| NOT_EXISTED | 0 | The execution result of the transaction does not exist. | +| PENDING | 1 | The transaction is in the transaction pool waiting to be packaged. | +| FAILED | 2 | Transaction execution failed. | +| MINED | 3 | The transaction was successfully executed and successfully packaged into a block. | +| CONFLICT | 4 | When executed in parallel, there are conflicts with other transactions. | +| PENDING_VALIDATION | 5 | The transaction is waiting for validation. | +| NODE_VALIDATION_FAILED | 6 | Transaction validation failed. | + +# AuthorityInfo + +| Field | Type | Description | Label | +| ---------------- | --------------- | ----------------------------------------- | ----- | +| contract_address | `aelf.Address ` | The contract address of the controller. | | +| owner_address | `aelf.Address ` | The address of the owner of the contract. | |