From 8124d48fdee370b59a4e33ecf707f502415deab7 Mon Sep 17 00:00:00 2001 From: AelfHarsh Date: Wed, 26 Jun 2024 16:18:20 +0530 Subject: [PATCH] Minor fixes --- .../operate-a-node/run-a-side-chain/index.md | 4 - .../request-side-chain-creation/index.md | 424 +++++++++ .../running-a-side-chain/index.md | 95 +++ .../operate-a-node/run-aelf-on-cloud/index.md | 52 ++ docs/references/web-api/chain-api/index.md | 801 +++--------------- docs/references/web-api/net-api/index.md | 677 +-------------- .../cross-chain/cross-chain-transfer/index.md | 110 +-- .../cross-chain-verification/index.md | 43 +- .../cross-chain/verify/index.md | 5 +- 9 files changed, 815 insertions(+), 1396 deletions(-) delete mode 100644 docs/Tutorials/operate-a-node/run-a-side-chain/index.md create mode 100644 docs/Tutorials/operate-a-node/run-a-side-chain/request-side-chain-creation/index.md create mode 100644 docs/Tutorials/operate-a-node/run-a-side-chain/running-a-side-chain/index.md diff --git a/docs/Tutorials/operate-a-node/run-a-side-chain/index.md b/docs/Tutorials/operate-a-node/run-a-side-chain/index.md deleted file mode 100644 index a693333..0000000 --- a/docs/Tutorials/operate-a-node/run-a-side-chain/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -sidebar_position: 3 -title: Run a Side Chain ---- diff --git a/docs/Tutorials/operate-a-node/run-a-side-chain/request-side-chain-creation/index.md b/docs/Tutorials/operate-a-node/run-a-side-chain/request-side-chain-creation/index.md new file mode 100644 index 0000000..753e2ba --- /dev/null +++ b/docs/Tutorials/operate-a-node/run-a-side-chain/request-side-chain-creation/index.md @@ -0,0 +1,424 @@ +--- +sidebar_position: 1 +title: Request a Side Chain +--- + + +Side chains can be created in the aelf ecosystem to enable scalability. This section introduces the process in detail. + +## Side Chain Creation API + +Anyone can request the creation of a side chain in the aelf ecosystem. The proposer/creator of a new side chain needs to request the creation through the cross-chain contract on the main chain. The request contains fields that determine the type of side chain to be created. + +### API for Proposing Side Chain Creation + +The fields in the `SideChainCreationRequest` determine the type of side chain that is created. For more details, follow `RequestSideChainCreation` in the [Crosschain contract documentation](../../../reference/smart-contract-api/cross-chain). + +Upon creating a new proposal for the side chain, the `ProposalCreated` event containing the proposal ID will be fired. A parliament organization, specified since the chain's launch, will approve this proposal within 24 hours (refer to the [Parliament contract documentation](../../../reference/smart-contract-api/parliament) for details). The proposer can release the side chain creation request with the proposal ID once it can be released. Refer to `ReleaseSideChainCreation` in the [Crosschain contract documentation](../../../reference/smart-contract-api/cross-chain). + +Once the side chain is created, the `SideChainCreatedEvent` containing the chain ID will be fired. + +The side chain node can be launched once it is created on the main chain. Ensure the side chain ID from the creation result is configured correctly before launching the side chain node. Make sure the cross-chain communication context is correctly set, as the side chain node will request main chain node for chain initialization data. For more details, check the [side chain node running tutorial](running-side-chain). + +## Side Chain Types + +Two types of side chains currently exist: **exclusive** and **shared**. An **exclusive** side chain allows developers to choose the transaction fee model and set the transaction fee price. Only the creator of an **exclusive** side chain can propose deploying a new contract. + +## Paying for Side Chain + +### Indexing Fee + +The indexing fee is paid for side chain indexing. You can specify the indexing fee price and prepayments amount when requesting side chain creation. The cross-chain contract charges prepayments once the side chain is created and pays the miner who indexes the side chain block every time. + +### Resource Fee + +Developers of an exclusive side chain pay producers for running it by paying CPU, RAM, DISK, and NET resource tokens. This model is called _charge-by-time_. The amount the side chain creator must share with the producers is set after the chain's creation. The **exclusive** side chain is priced according to the time used. The unit price of the fee is determined through negotiation between the production node and the developer. + +For more information, see the [Economic whitepaper - 4.3 Sidechain Developer Charging Model](https://aelf.com/gridcn/aelf_Economic_and_Governance_Whitepaper_v1.2_en.pdf). + +## Simple Demo for Side Chain Creation Request + +When a user (usually a developer) feels the need to create a new side chain on aelf, they must call the cross-chain contract and request a side chain creation. After the request, parliament organization members will either approve or reject the creation. If the request is approved, the developer must then release the proposal. + +### Step-by-Step Code Snippets + +We'll use the [aelf-js-sdk](https://github.com/AElfProject/aelf-sdk.js/tree/master) to create a new side chain. The full script will be provided at the end. + +This creation of a side chain (logical, on-chain creation) is done in four steps: + +1. The developer must _allow/approve_ some tokens to the cross-chain contract of the main chain. +2. The developer calls the cross-chain contract of the main chain to _request_ the creation. +3. The parliament organization members must _approve_ this request. +4. Finally, the developer must _release_ the request to finalize the creation. + +### Set-Up + +To test the creation process, you will need a producer node running and the following: + +- A `key-pair` (account) created; this will be your Producer (also used to create the creation request in this tutorial). +- The node needs to be configured with an API endpoint, account, and miner list that correspond to what is in the script. + +Here is the initialization code: + +```javascript +const AElf = require('aelf-sdk'); +const Wallet = AElf.wallet; + +const { sha256 } = AElf.utils; + +// set the private key of the block producer. +// REPLACE +const defaultPrivateKey = 'e119487fea0658badc42f089fbaa56de23d8c0e8d999c5f76ac12ad8ae897d76'; +const defaultPrivateKeyAddress = 'HEtBQStfqu53cHVC3PxJU6iGP3RGxiNUfQGvAPTjfrF3ZWH3U'; + +// load the wallet associated with your block producer's account. +const wallet = Wallet.getWalletByPrivateKey(defaultPrivateKey); + +// API link to the node +// REPLACE +const aelf = new AElf(new AElf.providers.HttpProvider('http://127.0.0.1:1234')); + +// names of the contracts that will be used. +const tokenContractName = 'AElf.ContractNames.Token'; +const parliamentContractName = 'AElf.ContractNames.Parliament'; +const crossChainContractName = 'AElf.ContractNames.CrossChain'; + +... + +const createSideChain = async () => { + // check the chain status to make sure the node is running + const chainStatus = await aelf.chain.getChainStatus({sync: true}); + const genesisContract = await aelf.chain.contractAt(chainStatus.GenesisContractAddress, wallet) + .catch((err) => { + console.log(err); + }); + + // get the addresses of the contracts that we'll need to call + const tokenContractAddress = await genesisContract.GetContractAddressByName.call(sha256(tokenContractName)); + const parliamentContractAddress = await genesisContract.GetContractAddressByName.call(sha256(parliamentContractName)); + const crossChainContractAddress = await genesisContract.GetContractAddressByName.call(sha256(crossChainContractName)); + + // build the aelf-sdk contract instance objects + const parliamentContract = await aelf.chain.contractAt(parliamentContractAddress, wallet); + const tokenContract = await aelf.chain.contractAt(tokenContractAddress, wallet); + const crossChainContract = await aelf.chain.contractAt(crossChainContractAddress, wallet); + + ... +} +``` + +When running the script, the **createSideChain** function will be executed and will run through the full process of creating the side chain. + +### Creation of the Side Chain + +#### Set the Allowance + +First, the developer must approve some ELF tokens for use by the cross-chain contract. + +```javascript +var setAllowance = async function (tokenContract, crossChainContractAddress) { + // set some allowance to the cross-chain contract + const approvalResult = await tokenContract.Approve({ + symbol: "ELF", + spender: crossChainContractAddress, + amount: 20000, + }); + + let approveTransactionResult = await pollMining(approvalResult.TransactionId); +}; +``` + +#### Creation Request + +To request a side chain creation, the developer must call **RequestSideChainCreation** on the cross-chain contract. This creates a proposal with the **Parliament** contract. After calling this method, a **ProposalCreated** log will be created containing the **ProposalId**. + +```protobuf +rpc RequestSideChainCreation(SideChainCreationRequest) returns (google.protobuf.Empty){} + +message SideChainCreationRequest { + int64 indexing_price = 1; // The cross chain indexing price. + int64 locked_token_amount = 2; // Initial locked balance for a new side chain. + bool is_privilege_preserved = 3; // Creator privilege boolean flag. + SideChainTokenCreationRequest side_chain_token_creation_request = 4; // Side chain token information. + repeated SideChainTokenInitialIssue side_chain_token_initial_issue_list = 5; // A list of accounts and amounts that will be issued when the chain starts. + map initial_resource_amount = 6; // The initial rent resources. +} + +message SideChainTokenCreationRequest{ + string side_chain_token_symbol = 1; // Token symbol of the side chain to be created. + string side_chain_token_name = 2; // Token name of the side chain to be created. + int64 side_chain_token_total_supply = 3; // Token total supply of the side chain to be created. + int32 side_chain_token_decimals = 4; // Token decimals of the side chain to be created. +} + +message SideChainTokenInitialIssue{ + aelf.Address address = 1; // The account that will be issued. + int64 amount = 2; // The amount that will be issued. +} +``` + +In order for the creation request to succeed, some assertions must pass: + +- The Sender can only have one pending request at any time. +- The `locked_token_amount` cannot be lower than the indexing price. +- If `is_privilege_preserved` is true (exclusive side chain), the token initial issue list cannot be empty and all with an `amount` greater than 0. +- If `is_privilege_preserved` is true (exclusive side chain), the `initial_resource_amount` must contain all resource tokens of the chain, and the value must be greater than 0. +- The allowance approved to cross-chain contract from the proposer (Sender of the transaction) cannot be lower than the `locked_token_amount`. +- No need to provide data about side chain token if `is_privilege_preserved` is false. + +```javascript +var sideChainCreationRequest = async function (crossChainContract) { + // call the cross-chain contract to request the creation + const creationRequestResult = + await crossChainContract.RequestSideChainCreation({ + indexing_price: 1, + locked_token_amount: 20000, + is_privilege_preserved: true, + side_chain_token_creation_request: { + side_chain_token_symbol: "MEGA", + side_chain_token_name: "MEGA", + side_chain_token_total_supply: 100000000, + side_chain_token_decimals: 8, + }, + side_chain_token_initial_issue_list: [ + { + address: defaultPrivateKeyAddress, + amount: 10000000, + }, + ], + initial_resource_amount: { + CPU: 100, + RAM: 100, + DISK: 100, + NET: 100, + }, + }); + + let sideChainProposalResult = await pollMining( + creationRequestResult.TransactionId + ); + let logs = parseLogs(sideChainProposalResult.Logs); + let proposalId = logs.ProposalId; +}; +``` + +The **cross-chain** contract emits an event containing the **ProposalId**. This is needed for the last step. + +#### Approve the Proposal + +This is where the parliament organization members approve the proposal: + +```protobuf +var proposalApproveTx = await parliamentContract.Approve(deserializedLogs[0].proposalId); + +await pollMining(proposalApproveTx.TransactionId); +``` + +**Note**: when calling **Approve** it will be the _Sender_ of the transaction that approves. Here the script is set to use the key of one parliament organization member, see full script at the end. + +#### Release the Proposal + +This part of the script releases the proposal: + +```protobuf +var releaseResult = await crossChainContract.ReleaseSideChainCreation({ + proposalId: deserializedLogs[0].proposalId +}); + +let releaseTxResult = await pollMining(releaseResult.TransactionId); + +// Parse the logs to get the chain id. +let sideChainCreationEvent = crossChainContract.deserializeLog(releaseTxResult.Logs, 'SideChainCreatedEvent'); +``` + +This is the last step involved in creating a side chain, after this the chain id of the new side chain is accessible in the **SideChainCreatedEvent** event log. + +### Complete Script + +This script demonstrates the essential steps to create a side chain in the aelf ecosystem. The developer must approve some ELF tokens, request the side chain creation, get approval from the parliament organization, and finally release the proposal to create the side chain. Ensure to set the proper configurations and values as per your blockchain environment. + +```javascript +const AElf = require("aelf-sdk"); +const Wallet = AElf.wallet; + +const { sha256 } = AElf.utils; + +// set the private key of the block producer +const defaultPrivateKey = + "e119487fea0658badc42f089fbaa56de23d8c0e8d999c5f76ac12ad8ae897d76"; +const defaultPrivateKeyAddress = + "HEtBQStfqu53cHVC3PxJU6iGP3RGxiNUfQGvAPTjfrF3ZWH3U"; + +const wallet = Wallet.getWalletByPrivateKey(defaultPrivateKey); + +// link to the node +const aelf = new AElf(new AElf.providers.HttpProvider("http://127.0.0.1:8000")); + +if (!aelf.isConnected()) { + console.log("Could not connect to the node."); +} + +const tokenContractName = "AElf.ContractNames.Token"; +const parliamentContractName = "AElf.ContractNames.Parliament"; +const crossChainContractName = "AElf.ContractNames.CrossChain"; + +var pollMining = async function (transactionId) { + console.log(`>> Waiting for ${transactionId} the transaction to be mined.`); + + for (i = 0; i < 10; i++) { + const currentResult = await aelf.chain.getTxResult(transactionId); + // console.log('transaction status: ' + currentResult.Status); + + if (currentResult.Status === "MINED") return currentResult; + + await new Promise((resolve) => setTimeout(resolve, 2000)).catch( + function () { + console.log("Promise Rejected"); + } + ); + } +}; + +var setAllowance = async function (tokenContract, crossChainContractAddress) { + console.log("\n>>>> Setting allowance for the cross-chain contract."); + + // set some allowance to the cross-chain contract + const approvalResult = await tokenContract.Approve({ + symbol: "ELF", + spender: crossChainContractAddress, + amount: 20000, + }); + + await pollMining(approvalResult.TransactionId); +}; + +var checkAllowance = async function (tokenContract, owner, spender) { + console.log("\n>>>> Checking the cross-chain contract's allowance"); + + const checkAllowanceTx = await tokenContract.GetAllowance.call({ + symbol: "ELF", + owner: owner, + spender: spender, + }); + + console.log( + `>> allowance to the cross-chain contract: ${checkAllowanceTx.allowance} ${checkAllowanceTx.symbol}` + ); +}; + +const createSideChain = async () => { + // get the status of the chain in order to get the genesis contract address + console.log("Starting side chain creation script\n"); + + const chainStatus = await aelf.chain.getChainStatus({ sync: true }); + const genesisContract = await aelf.chain + .contractAt(chainStatus.GenesisContractAddress, wallet) + .catch((err) => { + console.log(err); + }); + + // get the addresses of the contracts that we'll need to call + const tokenContractAddress = + await genesisContract.GetContractAddressByName.call( + sha256(tokenContractName) + ); + const parliamentContractAddress = + await genesisContract.GetContractAddressByName.call( + sha256(parliamentContractName) + ); + const crossChainContractAddress = + await genesisContract.GetContractAddressByName.call( + sha256(crossChainContractName) + ); + + // build the aelf-sdk contract object + const parliamentContract = await aelf.chain.contractAt( + parliamentContractAddress, + wallet + ); + const tokenContract = await aelf.chain.contractAt( + tokenContractAddress, + wallet + ); + const crossChainContract = await aelf.chain.contractAt( + crossChainContractAddress, + wallet + ); + + // 1. set and check the allowance, spender is the cross-chain contract + await setAllowance(tokenContract, crossChainContractAddress); + await checkAllowance( + tokenContract, + defaultPrivateKeyAddress, + crossChainContractAddress + ); + + // 2. request the creation of the side chain with the cross=chain contract + console.log("\n>>>> Requesting the side chain creation."); + const sideChainCreationRequestTx = + await crossChainContract.RequestSideChainCreation({ + indexingPrice: 1, + lockedTokenAmount: "20000", + isPrivilegePreserved: true, + sideChainTokenCreationRequest: { + sideChainTokenDecimals: 8, + sideChainTokenName: "SCATokenName", + sideChainTokenSymbol: "SCA", + sideChainTokenTotalSupply: "100000000000000000", + }, + sideChainTokenInitialIssueList: [ + { + address: "28Y8JA1i2cN6oHvdv7EraXJr9a1gY6D1PpJXw9QtRMRwKcBQMK", + amount: "1000000000000000", + }, + ], + initialResourceAmount: { CPU: 2, RAM: 4, DISK: 512, NET: 1024 }, + }); + + let sideChainCreationRequestTxResult = await pollMining( + sideChainCreationRequestTx.TransactionId + ); + + // deserialize the log to get the proposal's ID. + let deserializedLogs = parliamentContract.deserializeLog( + sideChainCreationRequestTxResult.Logs, + "ProposalCreated" + ); + console.log( + `>> side chain creation request proposal id ${JSON.stringify( + deserializedLogs[0].proposalId + )}` + ); + + // 3. Approve the proposal + console.log("\n>>>> Approving the proposal."); + + var proposalApproveTx = await parliamentContract.Approve( + deserializedLogs[0].proposalId + ); + await pollMining(proposalApproveTx.TransactionId); + + // 3. Release the side chain + console.log("\n>>>> Release the side chain."); + + var releaseResult = await crossChainContract.ReleaseSideChainCreation({ + proposalId: deserializedLogs[0].proposalId, + }); + + let releaseTxResult = await pollMining(releaseResult.TransactionId); + + // Parse the logs to get the chain id. + let sideChainCreationEvent = crossChainContract.deserializeLog( + releaseTxResult.Logs, + "SideChainCreatedEvent" + ); + console.log("Chain chain created : "); + console.log(sideChainCreationEvent); +}; + +createSideChain().then(() => { + console.log("Done."); +}); +``` + +**Note**: Replace the placeholders in the script with actual values and logic for your use case. diff --git a/docs/Tutorials/operate-a-node/run-a-side-chain/running-a-side-chain/index.md b/docs/Tutorials/operate-a-node/run-a-side-chain/running-a-side-chain/index.md new file mode 100644 index 0000000..191c35b --- /dev/null +++ b/docs/Tutorials/operate-a-node/run-a-side-chain/running-a-side-chain/index.md @@ -0,0 +1,95 @@ +--- +sidebar_position: 1 +title: Run a Side Chain +--- + + +# Running a Side Chain (After its Release) + +This tutorial explains how to run a side chain node after it has been approved by the producers and released by the creator. After creating the side chain, producers need to run a side chain node. + +## Prerequisites + +- You already have a main-chain node running. +- The creation of the side chain has been approved and released. + +## Important Note + +The key-pair (account) used for mining on the side chain must be the same as the one used on the main-chain node. Both production nodes need to be launched with the same key-pair. + +For more information about side chain creation, refer to the document in the [request-side-chain section](request-new-side-chain). + +## Side Chain Configuration + +### Configuration Files + +Two configuration files must be placed in the configuration folder of the side chain, from which you will launch the node: + +- `appsettings.json` +- `appsettings.SideChain.MainNet.json` + +### Chain ID and Settings + +After the release of the side chain creation request, the ChainId of the new side chain will be accessible in the SideChainCreatedEvent logged by the transaction that released it. + +In this example, we will set up the side chain node with ChainId `tDVV` (1866392 converted to base58), connecting to Redis `db2`, and using web API port `1235`. Don’t forget to change the `account`, `password`, and `initial miner`. + +#### appsettings.json + +```json +{ + "ChainId": "tDVV", + "ChainType": "SideChain", + "NetType": "MainNet", + "ConnectionStrings": { + "BlockchainDb": "redis://localhost:6379?db=2", + "StateDb": "redis://localhost:6379?db=2" + }, + "Account": { + "NodeAccount": "YOUR PRODUCER ACCOUNT", + "NodeAccountPassword": "YOUR PRODUCER PASSWORD" + }, + "Kestrel": { + "EndPoints": { + "Http": { + "Url": "http://*:1235/" + } + } + }, + "Consensus": { + "MiningInterval": 4000, + "StartTimestamp": 0 + } +} +``` + +#### appsettings.SideChain.MainNet.json + +```json +{ + "CrossChain": { + "Grpc": { + "ParentChainServerPort": 5010, + "ListeningPort": 5000, + "ParentChainServerIp": "127.0.0.1" + }, + "ParentChainId": "AELF" + } +} +``` + +Change `ParentChainServerIp` and `ParentChainServerPort` depending on the listening address of your mainchain node. + +## Launching the Side Chain Node + +Open a terminal and navigate to the folder where you created the side chain configuration: + +```bash +dotnet ../AElf.Launcher.dll +``` + +You can try out a few commands from another terminal to check if everything is fine, for example: + +```bash +aelf-command get-blk-height -e http://127.0.0.1:1235 +``` diff --git a/docs/Tutorials/operate-a-node/run-aelf-on-cloud/index.md b/docs/Tutorials/operate-a-node/run-aelf-on-cloud/index.md index 52d4326..ef06ddd 100644 --- a/docs/Tutorials/operate-a-node/run-aelf-on-cloud/index.md +++ b/docs/Tutorials/operate-a-node/run-aelf-on-cloud/index.md @@ -2,3 +2,55 @@ sidebar_position: 4 title: Run aelf on Cloud --- + + +# Getting Started with Google Cloud + +This guide will walk you through the steps required to run an aelf node on Google Cloud Platform (GCP). + +## Step 1: Launch aelf Image + +1. Go to the [Google Cloud Marketplace](https://console.cloud.google.com/marketplace) and search for "aelf blockchain for enterprise". + + ![image](../../../../static/img/gcp-step1.png) + +2. Find the aelf image and click on "LAUNCH ON COMPUTE ENGINE". + + ![image](../../../../static/img/gcp-step2-b.png) + +3. Keep the default settings and click "DEPLOY" at the bottom left of the page. + + ![image](../../../../static/img/gcp-deployed.png) + +## Step 2: Access and Start the Chain + +1. Login to the launched VM instance via SSH. You can do this by clicking the SSH drop-down and selecting "Open in browser window". + + ![image](../../../../static/img/gcp-ssh-select.png) + +2. In the SSH session, execute `sudo bash` to elevate your privileges. + +3. Start the chain with one of the following commands: + + - Run it in the foreground: + ```bash + cd /opt/aelf-node && docker-compose up + ``` + - Or run it in the background: + ```bash + cd /opt/aelf-node && docker-compose up -d + ``` + + ![image](../../../../static/img/gcp-docker-compose.png) + +## Step 3: Verify Chain Status + +1. To verify that the node is working, use the following command to send an HTTP request and get the current chain status: + + ```bash + curl -X GET "http://127.0.0.1:8001/api/blockChain/chainStatus" -H "accept: text/plain; v=1.0" + ``` + + ![image](../../../../static/img/gcp-curl-chain-stat.png) + +2. If everything is working normally, you should see the chain status increase with each request. diff --git a/docs/references/web-api/chain-api/index.md b/docs/references/web-api/chain-api/index.md index 82d95a4..0187ef1 100644 --- a/docs/references/web-api/chain-api/index.md +++ b/docs/references/web-api/chain-api/index.md @@ -3,11 +3,9 @@ sidebar_position: 1 title: Chain API --- -# AELF API 1.0 +# Chain API -## Chain API - -### Get information about a given block by block hash. Optionally with the list of its transactions. +## Get information about a given block by block hash. Optionally with the list of its transactions. ```http GET /api/blockChain/block @@ -18,24 +16,24 @@ GET /api/blockChain/block | `blockHash` | `string` | Block hash _(optional)_ | | | `includeTransactions` | `boolean` | Include transactions _(optional)_ | `"false"` | -#### Responses +### Responses - **200**: Success (`BlockDto`) -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Get information about a given block by block height. Optionally with the list of its transactions. +## Get information about a given block by block height. Optionally with the list of its transactions. ```http GET /api/blockChain/blockByHeight @@ -46,47 +44,47 @@ GET /api/blockChain/blockByHeight | `blockHeight` | `integer` | Block height _(optional)_ | | | `includeTransactions` | `boolean` | Include transactions _(optional)_ | `"false"` | -#### Responses +### Responses - **200**: Success (`BlockDto`) -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Get the height of the current chain. +## Get the height of the current chain. ```http GET /api/blockChain/blockHeight ``` -#### Responses +### Responses - **200**: Success (integer, int64) -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Get the current state about a given block. +## Get the current state about a given block. ```http GET /api/blockChain/blockState @@ -96,47 +94,47 @@ GET /api/blockChain/blockState | :---------- | :------- | :---------------------- | | `blockHash` | `string` | Block hash _(optional)_ | -#### Responses +### Responses - **200**: Success (`BlockStateDto`) -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Get the current status of the block chain. +## Get the current status of the block chain. ```http GET /api/blockChain/chainStatus ``` -#### Responses +### Responses - **200**: Success (`ChainStatusDto`) -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Get the protobuf definitions related to a contract. +## Get the protobuf definitions related to a contract. ```http GET /api/blockChain/contractFileDescriptorSet @@ -146,42 +144,42 @@ GET /api/blockChain/contractFileDescriptorSet | :-------- | :------- | :---------------------------- | | `address` | `string` | Contract address _(optional)_ | -#### Responses +### Responses - **200**: Success (string, byte) -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Execute a raw transaction. +## Execute a raw transaction. ```http POST /api/blockChain/executeRawTransaction ``` -#### Parameters +### Parameters | Type | Name | Schema | | :------- | :------ | :-------------------------------------- | | **Body** | `input` | `ExecuteRawTransactionDto` _(optional)_ | -#### Responses +### Responses | HTTP Code | Description | Schema | | :-------: | :---------- | :----- | | **200** | Success | string | -#### Consumes +### Consumes - `application/json-patch+json; v=1.0` - `application/json; v=1.0` @@ -189,38 +187,38 @@ POST /api/blockChain/executeRawTransaction - `application/*+json; v=1.0` - `application/x-protobuf; v=1.0` -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Call a read-only method on a contract. +## Call a read-only method on a contract. ```http POST /api/blockChain/executeTransaction ``` -#### Parameters +### Parameters | Type | Name | Schema | | :------- | :------ | :----------------------------------- | | **Body** | `input` | `ExecuteTransactionDto` _(optional)_ | -#### Responses +### Responses | HTTP Code | Description | Schema | | :-------: | :---------- | :----- | | **200** | Success | string | -#### Consumes +### Consumes - `application/json-patch+json; v=1.0` - `application/json; v=1.0` @@ -228,69 +226,69 @@ POST /api/blockChain/executeTransaction - `application/*+json; v=1.0` - `application/x-protobuf; v=1.0` -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Get the merkle path of a transaction. +## Get the merkle path of a transaction. ```http GET /api/blockChain/merklePathByTransactionId ``` -#### Parameters +### Parameters | Type | Name | Schema | | :-------: | :-------------- | :------------------ | | **Query** | `transactionId` | string _(optional)_ | -#### Responses +### Responses | HTTP Code | Description | Schema | | :-------: | :---------- | :-------------- | | **200** | Success | `MerklePathDto` | -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Creates an unsigned serialized transaction. +## Creates an unsigned serialized transaction. ```http POST /api/blockChain/rawTransaction ``` -#### Parameters +### Parameters | Type | Name | Schema | | :------- | :------ | :--------------------------------------- | | **Body** | `input` | `CreateRawTransactionInput` _(optional)_ | -#### Responses +### Responses | HTTP Code | Description | Schema | | :-------: | :---------- | :--------------------------- | | **200** | Success | `CreateRawTransactionOutput` | -#### Consumes +### Consumes - `application/json-patch+json; v=1.0` - `application/json; v=1.0` @@ -298,38 +296,38 @@ POST /api/blockChain/rawTransaction - `application/*+json; v=1.0` - `application/x-protobuf; v=1.0` -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Send a transaction. +## Send a transaction. ```http POST /api/blockChain/sendRawTransaction ``` -#### Parameters +### Parameters | Type | Name | Schema | | :------- | :------ | :------------------------------------- | | **Body** | `input` | `SendRawTransactionInput` _(optional)_ | -#### Responses +### Responses | HTTP Code | Description | Schema | | :-------: | :---------- | :------------------------- | | **200** | Success | `SendRawTransactionOutput` | -#### Consumes +### Consumes - `application/json-patch+json; v=1.0` - `application/json; v=1.0` @@ -337,36 +335,38 @@ POST /api/blockChain/sendRawTransaction - `application/*+json; v=1.0` - `application/x-protobuf; v=1.0` -#### Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -#### Tags +### Tags - **BlockChain** --- -### Broadcast a Transaction +## Broadcast a Transaction -**POST** `/api/blockChain/sendTransaction` +```http +POST /api/blockChain/sendTransaction +``` -**Parameters** +### Parameters | Type | Name | Schema | Description | Required | | -------- | ------- | ---------------------- | ----------- | -------- | | **Body** | `input` | `SendTransactionInput` | - | No | -**Responses** +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | ----------------------- | | **200** | Success | `SendTransactionOutput` | -**Consumes** +### Consumes - `application/json-patch+json; v=1.0` - `application/json; v=1.0` @@ -374,36 +374,38 @@ POST /api/blockChain/sendRawTransaction - `application/*+json; v=1.0` - `application/x-protobuf; v=1.0` -**Produces** +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -**Tags** +\*\*Tags - BlockChain --- -### Broadcast Multiple Transactions +## Broadcast Multiple Transactions -**POST** `/api/blockChain/sendTransactions` +```http +POST /api/blockChain/sendTransactions +``` -**Parameters** +### Parameters | Type | Name | Schema | Description | Required | | -------- | ------- | ----------------------- | ----------- | -------- | | **Body** | `input` | `SendTransactionsInput` | - | No | -**Responses** +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | ------------ | | **200** | Success | `` | -**Consumes** +### Consumes - `application/json-patch+json; v=1.0` - `application/json; v=1.0` @@ -411,36 +413,38 @@ POST /api/blockChain/sendRawTransaction - `application/*+json; v=1.0` - `application/x-protobuf; v=1.0` -**Produces** +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -**Tags** +### Tags - BlockChain --- -### Estimate Transaction Fee +## Estimate Transaction Fee -**POST** `/api/blockChain/calculateTransactionFee` +```http +POST /api/blockChain/calculateTransactionFee +``` -**Parameters** +### Parameters | Type | Name | Schema | Description | Required | | -------- | ------- | ------------------------------ | ----------- | -------- | | **Body** | `input` | `CalculateTransactionFeeInput` | - | No | -**Responses** +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | ------------------------------- | | **200** | Success | `CalculateTransactionFeeOutput` | -**Consumes** +### Consumes - `application/json-patch+json; v=1.0` - `application/json; v=1.0` @@ -448,74 +452,80 @@ POST /api/blockChain/sendRawTransaction - `application/*+json; v=1.0` - `application/x-protobuf; v=1.0` -**Produces** +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -**Tags** +### Tags - BlockChain --- -### Get the Current Status of a Transaction +## Get the Current Status of a Transaction -**GET** `/api/blockChain/transactionResult` +```http +GET /api/blockChain/transactionResult +``` -**Parameters** +### Parameters | Type | Name | Schema | Description | Required | | --------- | --------------- | -------- | -------------- | -------- | | **Query** | `transactionId` | `string` | Transaction ID | No | -**Responses** +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | ---------------------- | | **200** | Success | `TransactionResultDto` | -**Produces** +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -**Tags** +### Tags - BlockChain --- -### Get the Transaction Pool Status +## Get the Transaction Pool Status -**GET** `/api/blockChain/transactionPoolStatus` +```http +GET /api/blockChain/transactionPoolStatus +``` -**Responses** +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | -------------------------------- | | **200** | Success | `GetTransactionPoolStatusOutput` | -**Produces** +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -**Tags** +### Tags - BlockChain --- -### Get the Current Status of a Transaction +## Get the Current Status of a Transaction -**GET** `/api/blockChain/transactionResult` +```http +GET /api/blockChain/transactionResult +``` **Parameters** @@ -523,30 +533,32 @@ POST /api/blockChain/sendRawTransaction | --------- | ----------------- | -------------------------- | ------ | | **Query** | **transactionId** | _Optional_. Transaction ID | string | -**Responses** +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | ---------------------- | | **200** | Success | `TransactionResultDto` | -**Produces** +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -**Tags** +### Tags - BlockChain --- -### Get Multiple Transaction Results +## Get Multiple Transaction Results -**GET** `/api/blockChain/transactionResults` +```http +GET /api/blockChain/transactionResults +``` -**Parameters** +### Parameters | Type | Name | Description | Schema | Default | | --------- | ------------- | --------------------------------- | --------------- | ------- | @@ -554,610 +566,19 @@ POST /api/blockChain/sendRawTransaction | **Query** | **limit** | _Optional_. Limit results | integer (int32) | `10` | | **Query** | **offset** | _Optional_. Offset for pagination | integer (int32) | `0` | -**Responses** +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | ------------------------ | | **200** | Success | `TransactionResultDto[]` | -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Net API - -#### Get Network Information - -**GET** `/api/net/networkInfo` - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------------- | -| **200** | Success | `GetNetworkInfoOutput` | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- Net - ---- - -#### Add a Node to Connected Network Nodes - -**POST** `/api/net/peer` - -**Parameters** - -| Type | Name | Description | Schema | -| -------- | --------- | -------------------------- | -------------- | -| **Body** | **input** | _Optional_. Add peer input | `AddPeerInput` | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ------- | -| **200** | Success | boolean | - -| **401** | Unauthorized| | - -**Security** - -- Basic Authentication - -**Consumes** - -- `application/json-patch+json; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/*+json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- Net - ---- - -#### Remove a Node from Connected Network Nodes - -**DELETE** `/api/net/peer` - -**Parameters** - -| Type | Name | Description | Schema | -| --------- | ----------- | ---------------------- | ------ | -| **Query** | **address** | _Optional_. IP address | string | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ------- | -| **200** | Success | boolean | - -| **401** | Unauthorized| | - -**Security** - -- Basic Authentication - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- Net - ---- - -#### Get Peer Info about Connected Network Nodes - -**GET** `/api/net/peers` - -**Parameters** - -| Type | Name | Description | Schema | Default | -| --------- | --------------- | --------------------------- | ------- | --------- | -| **Query** | **withMetrics** | _Optional_. Include metrics | boolean | `"false"` | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ----------- | -| **200** | Success | `PeerDto[]` | - -**Produces** +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -**Tags** +### Tags - BlockChain - ---- - -## Definitions - -### AddPeerInput - -##### Description - -Represents the input parameters for adding a peer. - -#### Schema - -| Name | Description | Schema | -| --------- | ----------- | ------ | -| Address\* | IP address | string | - -### BlockBodyDto - -#### Description - -Represents the body of a block, including transactions and transaction count. - -#### Schema - -| Name | Schema | -| ----------------- | ---------------- | -| Transactions\* | < string > array | -| TransactionsCount | integer (int32) | - -### BlockDto - -#### Description - -Represents a block, including its hash, body, header, and size. - -#### Schema - -| Name | Schema | -| --------- | ---------------- | -| BlockHash | string | -| Body\* | `BlockBodyDto` | -| Header\* | `BlockHeaderDto` | -| BlockSize | integer (int32) | - -### BlockHeaderDto - -#### Description - -Represents the header of a block, including various metadata. - -#### Schema - -| Name | Schema | -| -------------------------------- | ------------------ | -| Bloom | string | -| ChainId | string | -| Extra | string | -| Height | integer (int64) | -| MerkleTreeRootOfTransactions | string | -| MerkleTreeRootOfWorldState | string | -| MerkleTreeRootOfTransactionState | string | -| PreviousBlockHash | string | -| SignerPubkey | string | -| Time | string (date-time) | - -### BlockStateDto - -#### Description - -Represents the state of a block, including hash, height, changes, deletes, and previous hash. - -#### Schema - -| Name | Schema | -| ------------ | ---------------------- | -| BlockHash | string | -| BlockHeight | integer (int64) | -| Changes\* | < string, string > map | -| Deletes\* | < string > array | -| PreviousHash | string | - -### ChainStatusDto - -#### Description - -Represents the status of a blockchain network, including chain details and block heights. - -#### Schema - -| Name | Schema | -| ----------------------------- | ------------------------------- | -| BestChainHash\* | string | -| BestChainHeight\* | integer (int64) | -| Branches\* | < string, integer (int64) > map | -| ChainId\* | string | -| GenesisBlockHash\* | string | -| GenesisContractAddress | string | -| LastIrreversibleBlockHash\* | string | -| LastIrreversibleBlockHeight\* | integer (int64) | -| LongestChainHash\* | string | -| LongestChainHeight\* | integer (int64) | -| NotLinkedBlocks\* | < string, string > map | - -### CreateRawTransactionInput - -#### Description - -Represents the input parameters for creating a raw transaction. - -#### Schema - -| Name | Description | Schema | -| ---------------- | -------------------------- | --------------- | -| From\* | From address | string | -| MethodName\* | Contract method name | string | -| Params\* | Contract method parameters | string | -| RefBlockHash\* | Reference block hash | string | -| RefBlockNumber\* | Reference block height | integer (int64) | -| To\* | To address | string | - -### CreateRawTransactionOutput - -#### Description - -Represents the output of creating a raw transaction. - -#### Schema - -| Name | Schema | -| -------------- | ------ | -| RawTransaction | string | - -### ExecuteRawTransactionDto - -#### Description - -Represents the input parameters for executing a raw transaction. - -#### Schema - -| Name | Description | Schema | -| ---------------- | --------------- | ------ | -| RawTransaction\* | Raw transaction | string | -| Signature\* | Signature | string | - -### ExecuteTransactionDto - -#### Description - -Represents the input parameters for executing a transaction. - -#### Schema - -| Name | Description | Schema | -| ---------------- | --------------- | ------ | -| RawTransaction\* | Raw transaction | string | - -### GetNetworkInfoOutput - -#### Description - -Represents the output of getting network information. - -#### Schema - -| Name | Description | Schema | -| ----------------- | ----------------- | --------------- | -| Connections\* | Total connections | integer (int32) | -| ProtocolVersion\* | Network protocol | integer (int32) | -| Version\* | Node version | string | - -### GetTransactionPoolStatusOutput - -#### Description - -Represents the output of getting transaction pool status. - -#### Schema - -| Name | Schema | -| ----------- | --------------- | -| Queued\* | integer (int32) | -| Validated\* | integer (int32) | - -### LogEventDto - -#### Description - -Represents a log event. - -#### Schema - -| Name | Schema | -| ------------ | ---------------- | -| Address\* | string | -| Indexed\* | < string > array | -| Name\* | string | -| NonIndexed\* | string | - -### MerklePathDto - -#### Description - -Represents a Merkle path. - -#### Schema - -| Name | Schema | -| ----------------- | ----------------------------- | -| MerklePathNodes\* | < `MerklePathNodeDto` > array | - -### MerklePathNodeDto - -#### Description - -Represents a node in a Merkle path. - -#### Schema - -| Name | Schema | -| ----------------- | ------- | -| Hash\* | string | -| IsLeftChildNode\* | boolean | - -### MinerInRoundDto - -#### Description - -Represents information about a miner in a round. - -#### Schema - -| Name | Schema | -| ------------------------------ | ---------------------------- | -| ActualMiningTimes\* | < string (date-time) > array | -| ExpectedMiningTime\* | string (date-time) | -| ImpliedIrreversibleBlockHeight | integer (int64) | -| InValue\* | string | -| MissedBlocks\* | integer (int64) | -| Order\* | integer (int32) | -| OutValue\* | string | -| PreviousInValue\* | string | -| ProducedBlocks\* | integer (int64) | -| ProducedTinyBlocks\* | integer (int32) | - -### PeerDto - -#### Description - -Represents information about a peer node. - -#### Schema - -| Name | Schema | -| ---------------------------- | ------------------------- | -| BufferedAnnouncementsCount\* | integer (int32) | -| BufferedBlocksCount\* | integer (int32) | -| BufferedTransactionsCount\* | integer (int32) | -| ConnectionTime\* | integer (int64) | -| Inbound\* | boolean | -| IpAddress\* | string | -| ProtocolVersion\* | integer (int32) | -| RequestMetrics\* | < `RequestMetric` > array | -| ConnectionStatus\* | string | -| NodeVersion\* | string | - -### RequestMetric - -#### Description - -Represents metrics for a request. - -#### Schema - -| Name | Schema | -| --------------- | --------------- | -| Info\* | string | -| MethodName\* | string | -| RequestTime\* | `Timestamp` | -| RoundTripTime\* | integer (int64) | - -### RoundDto - -#### Description - -Represents a round in the blockchain. - -#### Schema - -| Name | Schema | -| --------------------------------------- | --------------------------------- | -| ConfirmedIrreversibleBlockHeight\* | integer (int64) | -| ConfirmedIrreversibleBlockRoundNumber\* | integer (int64) | -| ExtraBlockProducerOfPreviousRound\* | string | -| IsMinerListJustChanged\* | boolean | -| RealTimeMinerInformation\* | < string, `MinerInRoundDto` > map | -| RoundId\* | integer (int64) | -| RoundNumber\* | integer (int64) | -| TermNumber\* | integer (int64) | - -### SendRawTransactionInput - -#### Description - -Represents the input parameters for sending a raw transaction. - -#### Schema - -| Name | Description | Schema | -| ------------------- | --------------- | ------- | -| ReturnTransaction\* | Return detail | boolean | -| Signature\* | Signature | string | -| Transaction\* | Raw transaction | string | - -### SendRawTransactionOutput - -#### Description - -Represents the output of sending a raw transaction. - -#### Schema - -| Name | Schema | -| --------------- | ---------------- | -| Transaction | `TransactionDto` | -| TransactionId\* | string | - -### SendTransactionInput - -#### Description - -Represents the input parameters for sending a transaction. - -#### Schema - -| Name | Description | Schema | -| ---------------- | --------------- | ------ | -| RawTransaction\* | Raw transaction | string | - -### SendTransactionOutput - -#### Description - -Represents the output of sending a transaction. - -#### Schema - -| Name | Schema | -| --------------- | ------ | -| TransactionId\* | string | - -### SendTransactionsInput - -#### Description - -Represents the input parameters for sending multiple transactions. - -#### Schema - -| Name | Description | Schema | -| ----------------- | ---------------- | ------ | -| RawTransactions\* | Raw transactions | string | - -### TaskQueueInfoDto - -#### Description - -Represents information about a task queue. - -#### Schema - -| Name | Schema | -|--------- - -|-----------------| -| Count* | integer (int32) | -| Time* | string (date-time)| - -### Timestamp - -#### Description - -Represents a timestamp. - -#### Schema - -| Name | Schema | -| --------- | --------------- | -| Seconds\* | integer (int64) | -| Nanos\* | integer (int32) | - -### TransactionDto - -#### Description - -Represents a transaction. - -#### Schema - -| Name | Schema | -| ----------------- | ------------------ | -| Hash\* | string | -| Height\* | integer (int64) | -| MethodName\* | string | -| Params\* | string | -| Receiver\* | string | -| RefBlockNumber\* | integer (int64) | -| Sender\* | string | -| Time\* | string (date-time) | -| TransactionSize\* | integer (int32) | -| TxStatus\* | string | - -### TransactionResultDto - -#### Description - -Represents the result of a transaction. - -#### Schema - -| Name | Description | Schema | -| --------------- | ------------------------------ | ----------------------- | -| BlockHash | Block hash (optional) | string | -| BlockNumber | Block number (optional) | integer (int64) | -| Bloom | Bloom filter (optional) | string | -| Error | Error message (optional) | string | -| Logs | Logs (optional) | < `LogEventDto` > array | -| ReturnValue | Return value (optional) | string | -| Status | Transaction status (optional) | string | -| Transaction | Transaction details (optional) | `TransactionDto` | -| TransactionId | Transaction ID (optional) | string | -| TransactionSize | Transaction size (optional) | integer (int32) | - -### CalculateTransactionFeeInput - -#### Description - -Represents the input parameters for calculating transaction fees. - -#### Schema - -| Name | Description | Schema | -| -------------- | ------------------------------- | ------ | -| RawTransaction | Raw transaction data (optional) | string | - -### CalculateTransactionFeeOutput - -#### Description - -Represents the output of calculating transaction fees. - -#### Schema - -| Name | Description | Schema | -| -------------- | ---------------------------------- | ------------------------ | -| Success | Success flag (optional) | bool | -| TransactionFee | Transaction fee details (optional) | Dictionary`` | -| ResourceFee | Resource fee details (optional) | Dictionary` `| diff --git a/docs/references/web-api/net-api/index.md b/docs/references/web-api/net-api/index.md index f74482d..95e683c 100644 --- a/docs/references/web-api/net-api/index.md +++ b/docs/references/web-api/net-api/index.md @@ -1,645 +1,30 @@ --- -sidebar_position: 4 +sidebar_position: 2 title: Net API --- -# AELF API 1.0 - -## Chain API - -### Get information about a given block by block hash. Optionally with the list of its transactions. - -```http -GET /api/blockChain/block -``` - -**Parameters** - -| Type | Name | Description | Schema | Default | -| --------- | --------------------- | ------------ | ------- | ------- | -| **Query** | `blockHash` | block hash | string | | -| | _optional_ | | | | -| **Query** | `includeTransactions` | include | boolean | "false" | -| | | transactions | | | -| | _optional_ | or not | | | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------- | -| **200** | Success | `BlockDto` | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Get information about a given block by block height. Optionally with the list of its transactions. - -```http -GET /api/blockChain/blockByHeight -``` - -**Parameters** - -| Type | Name | Description | Schema | Default | -| --------- | --------------------- | ------------ | ------- | ------- | -| **Query** | `blockHeight` | block height | integer | | -| | _optional_ | | (int64) | | -| **Query** | `includeTransactions` | include | boolean | "false" | -| | | transactions | | | -| | _optional_ | or not | | | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------- | -| **200** | Success | `BlockDto` | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Get the height of the current chain. - -```http -GET /api/blockChain/blockHeight -``` - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | --------------- | -| **200** | Success | integer (int64) | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Get the current state about a given block - -```http -GET /api/blockChain/blockState -``` - -**Parameters** - -| Type | Name | Description | Schema | -| --------- | ----------- | ----------- | ------ | -| **Query** | `blockHash` | block hash | string | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | --------------- | -| **200** | Success | `BlockStateDto` | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Get the current status of the block chain. - -```http -GET /api/blockChain/chainStatus -``` - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------- | -| **200** | Success | `ChainStatusDto` | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Get the protobuf definitions related to a contract - -```http -GET /api/blockChain/contractFileDescriptorSet -``` - -**Parameters** - -| Type | Name | Description | Schema | -| --------- | --------- | ---------------- | ------ | -| **Query** | `address` | contract address | string | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ------ | -| **200** | Success | byte | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Execute a raw transaction - -```http -POST /api/blockChain/executeRawTransaction -``` - -**Parameters** - -| Type | Name | Schema | -| -------- | ------- | -------------------------- | -| **Body** | `input` | `ExecuteRawTransactionDto` | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ------ | -| **200** | Success | string | - -**Consumes** - -- `application/json-patch+json; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/*+json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Call a read-only method on a contract - -```http -POST /api/blockChain/executeTransaction -``` - -**Parameters** - -| Type | Name | Schema | -| -------- | ------- | ----------------------- | -| **Body** | `input` | `ExecuteTransactionDto` | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ------ | -| **200** | Success | string | - -**Consumes** - -- `application/json-patch+json; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/*+json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Get the merkle path of a transaction - -```http -GET /api/blockChain/merklePathByTransactionId -``` - -**Parameters** - -| Type | Name | Schema | -| --------- | --------------- | ------ | -| **Query** | `transactionId` | string | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | --------------- | -| **200** | Success | `MerklePathDto` | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -### Create an unsigned serialized transaction - -```http -POST /api/blockChain/rawTransaction -``` - -**Parameters** - -| Type | Name | Schema | -| -------- | ------- | --------------------------- | -| **Body** | `input` | `CreateRawTransactionInput` | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------------------- | -| **200** | Success | `CreateRawTransactionOutput` | - -**Consumes** - -- `application/json-patch+json; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/*+json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -# Get the Current Status of a Transaction - -**GET** `/api/blockChain/transactionResult` - -**Parameters** - -| Type | Name | Schema | Description | Required | -| --------- | --------------- | -------- | -------------- | -------- | -| **Query** | `transactionId` | `string` | Transaction ID | No | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------------- | -| **200** | Success | `TransactionResultDto` | - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -# Send a Transaction - -**POST** `/api/blockChain/sendRawTransaction` - -**Parameters** - -| Type | Name | Schema | -| -------- | --------- | -------------------------------------------------------- | -| **Body** | **input** | `SendRawTransactionInput <#sendrawtransactioninput>`\_\_ | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------------------------------------------------- | -| **200** | Success | `SendRawTransactionOutput <#sendrawtransactionoutput>`\_\_ | - -**Consumes** - -- `application/json-patch+json; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/*+json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -# Broadcast a Transaction - -**POST** `/api/blockChain/sendTransaction` - -**Parameters** - -| Type | Name | Schema | -| -------- | --------- | -------------------------------------------------- | -| **Body** | **input** | `SendTransactionInput <#sendtransactioninput>`\_\_ | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------------------------------------------- | -| **200** | Success | `SendTransactionOutput <#sendtransactionoutput>`\_\_ | - -**Consumes** - -- `application/json-patch+json; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/*+json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -# Broadcast Multiple Transactions - -**POST** `/api/blockChain/sendTransactions` - -**Parameters** - -| Type | Name | Schema | -| -------- | --------- | ---------------------------------------------------- | -| **Body** | **input** | `SendTransactionsInput <#sendtransactionsinput>`\_\_ | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------- | -| **200** | Success | `` array | - -**Consumes** - -- `application/json-patch+json; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/*+json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -# Estimate Transaction Fee - -**POST** `/api/blockChain/calculateTransactionFee` - -**Parameters** - -| Type | Name | Schema | Default | -| -------- | --------- | ------------------------------------------------------------------ | ------- | -| **Body** | **Input** | `CalculateTransactionFeeInput <#calculatetransactionfeeinput>`\_\_ | - | - -**Responses** - -| HTTP Code | Description | Schema | -| --------- | ----------- | -------------------------------------------------------------------- | -| **200** | Success | `CalculateTransactionFeeOutput <#calculatetransactionfeeoutput>`\_\_ | - -**Consumes** - -- `application/json-patch+json; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/*+json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Produces** - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -**Tags** - -- BlockChain - ---- - -# Get the Current Status of a Transaction - -**GET** `/api/blockChain/transactionResult` - -## Parameters - -| Type | Name | Schema | Description | Required | -| --------- | --------------- | -------- | -------------- | -------- | -| **Query** | `transactionId` | `string` | Transaction ID | No | - -## Responses - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------------- | -| **200** | Success | `TransactionResultDto` | - -## Produces - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -## Tags - -- BlockChain - ---- - -# Get Task Queue Status - -**GET** `/api/blockChain/taskQueueStatus` - -## Responses - -| HTTP Code | Description | Schema | -| --------- | ----------- | ------------------------ | -| **200** | Success | `TaskQueueInfoDto` array | - -## Produces - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -## Tags - -- BlockChain - ---- - -# Get Transaction Pool Status - -**GET** `/api/blockChain/transactionPoolStatus` - -## Responses - -| HTTP Code | Description | Schema | -| --------- | ----------- | -------------------------------- | -| **200** | Success | `GetTransactionPoolStatusOutput` | - -## Produces - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -## Tags - -- BlockChain - ---- - -# Get Multiple Transaction Results - -**GET** `/api/blockChain/transactionResults` - -## Parameters - -| Type | Name | Description | Schema | Default | -| --------- | ----------- | ----------- | --------------- | ------- | -| **Query** | `blockHash` | block hash | string | | -| **Query** | `limit` | limit | integer (int32) | `10` | -| **Query** | `offset` | offset | integer (int32) | `0` | - -## Responses - -| HTTP Code | Description | Schema | -| --------- | ----------- | ---------------------------- | -| **200** | Success | `TransactionResultDto` array | - -## Produces - -- `text/plain; v=1.0` -- `application/json; v=1.0` -- `text/json; v=1.0` -- `application/x-protobuf; v=1.0` - -## Tags - -- BlockChain - ---- - # Net API ## Get Network Information -**GET** `/api/net/networkInfo` +```http +GET /api/net/networkInfo +``` -## Responses +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | ---------------------- | | **200** | Success | `GetNetworkInfoOutput` | -## Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -## Tags +### Tags - Net @@ -647,26 +32,28 @@ POST /api/blockChain/rawTransaction ## Add Peer -**POST** `/api/net/peer` +```http +POST /api/net/peer +``` -## Parameters +#### Parameters | Type | Name | Schema | | -------- | ------- | -------------- | | **Body** | `input` | `AddPeerInput` | -## Responses +### Responses | HTTP Code | Description | Schema | | --------- | ------------ | ------- | | **200** | Success | boolean | | **401** | Unauthorized | | -## Security +### Security - Basic Authentication -## Consumes +### Consumes - `application/json-patch+json; v=1.0` - `application/json; v=1.0` @@ -674,14 +61,14 @@ POST /api/blockChain/rawTransaction - `application/*+json; v=1.0` - `application/x-protobuf; v=1.0` -## Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -## Tags +### Tags - Net @@ -691,31 +78,31 @@ POST /api/blockChain/rawTransaction **DELETE** `/api/net/peer` -## Parameters +### Parameters | Type | Name | Description | Schema | | --------- | --------- | ----------- | ------ | | **Query** | `address` | ip address | string | -## Responses +### Responses | HTTP Code | Description | Schema | | --------- | ------------ | ------- | | **200** | Success | boolean | | **401** | Unauthorized | | -## Security +### Security - Basic Authentication -## Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -## Tags +### Tags - Net @@ -725,61 +112,61 @@ POST /api/blockChain/rawTransaction **GET** `/api/net/peers` -## Parameters +### Parameters | Type | Name | Description | Schema | Default | | --------- | ------------- | ----------- | ------ | --------- | | **Query** | `withMetrics` | boolean | | `"false"` | -## Responses +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | --------------- | | **200** | Success | `PeerDto` array | -## Produces +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -## Tags +### Tags - BlockChain --- -### Get the Current Status of a Transaction +## Get the Current Status of a Transaction **GET** `/api/blockChain/transactionResult` -**Parameters** +### Parameters | Type | Name | Schema | Description | Required | | --------- | --------------- | -------- | -------------- | -------- | | **Query** | `transactionId` | `string` | Transaction ID | No | -**Responses** +### Responses | HTTP Code | Description | Schema | | --------- | ----------- | ---------------------- | | **200** | Success | `TransactionResultDto` | -**Produces** +### Produces - `text/plain; v=1.0` - `application/json; v=1.0` - `text/json; v=1.0` - `application/x-protobuf; v=1.0` -**Tags** +### Tags - BlockChain --- -### Definitions +## Definitions #### AddPeerInput @@ -1127,7 +514,7 @@ This structure should provide a clear overview of each variable's name, schema, --- -### CalculateTransactionFeeOutput +#### CalculateTransactionFeeOutput **Name:** CalculateTransactionFeeOutput diff --git a/docs/understanding-aelf/cross-chain/cross-chain-transfer/index.md b/docs/understanding-aelf/cross-chain/cross-chain-transfer/index.md index e4842c3..6f0f17b 100644 --- a/docs/understanding-aelf/cross-chain/cross-chain-transfer/index.md +++ b/docs/understanding-aelf/cross-chain/cross-chain-transfer/index.md @@ -3,11 +3,13 @@ sidebar_position: 5 title: Cross Chain Transfer --- + # Cross Chain Transfer Cross chain transfer is one of the most commonly used cases when it comes to cross chain verification. AElf already supports cross chain transfer functionality in its contract. This section will explain how to transfer tokens across chains. It assumes a side chain is already deployed and has been indexed by the main chain. The transfer process will always use the same contract methods and follow these two steps: + - **Initiate the transfer** - **Receive the tokens** @@ -19,65 +21,65 @@ Let's say you want to transfer token **FOO** from chain **A** to chain **B**. Be - **Validate `Token Contract` address on chain A** - Send transaction `tx_1` to the `Genesis Contract` with the method `ValidateSystemContractAddress`. You need to provide `system_contract_hash_name` and the address of the `Token Contract`. `tx_1` should be successfully packed in the block. + Send transaction `tx_1` to the `Genesis Contract` with the method `ValidateSystemContractAddress`. You need to provide `system_contract_hash_name` and the address of the `Token Contract`. `tx_1` should be successfully packed in the block. - ```protobuf - rpc ValidateSystemContractAddress(ValidateSystemContractAddressInput) returns (google.protobuf.Empty){} + ```protobuf + rpc ValidateSystemContractAddress(ValidateSystemContractAddressInput) returns (google.protobuf.Empty){} - message ValidateSystemContractAddressInput { - aelf.Hash system_contract_hash_name = 1; - aelf.Address address = 2; - } - ``` + message ValidateSystemContractAddressInput { + aelf.Hash system_contract_hash_name = 1; + aelf.Address address = 2; + } + ``` - **Register the token contract address of chain A on chain B** - Create a proposal for the `RegisterCrossChainTokenContractAddress` for the default parliament organization on chain B. Refer to the [Parliament contract documentation](../../reference/smart-contract-api/parliament) for more details. Apart from cross chain verification context, you also need to provide the origin data of `tx_1` and the `Token Contract` address on chain A. + Create a proposal for the `RegisterCrossChainTokenContractAddress` for the default parliament organization on chain B. Refer to the [Parliament contract documentation](../../reference/smart-contract-api/parliament) for more details. Apart from cross chain verification context, you also need to provide the origin data of `tx_1` and the `Token Contract` address on chain A. - ```protobuf - rpc RegisterCrossChainTokenContractAddress (RegisterCrossChainTokenContractAddressInput) returns (google.protobuf.Empty) {} + ```protobuf + rpc RegisterCrossChainTokenContractAddress (RegisterCrossChainTokenContractAddressInput) returns (google.protobuf.Empty) {} - message RegisterCrossChainTokenContractAddressInput { - int32 from_chain_id = 1; - int64 parent_chain_height = 2; - bytes transaction_bytes = 3; - aelf.MerklePath merkle_path = 4; - aelf.Address token_contract_address = 5; - } - ``` + message RegisterCrossChainTokenContractAddressInput { + int32 from_chain_id = 1; + int64 parent_chain_height = 2; + bytes transaction_bytes = 3; + aelf.MerklePath merkle_path = 4; + aelf.Address token_contract_address = 5; + } + ``` - **Validate `TokenInfo` of FOO on chain A** - Send transaction `tx_2` to the `Token Contract` with the method `ValidateTokenInfoExists` on chain A. You need to provide `TokenInfo` of FOO. `tx_2` should be successfully packed in the block. + Send transaction `tx_2` to the `Token Contract` with the method `ValidateTokenInfoExists` on chain A. You need to provide `TokenInfo` of FOO. `tx_2` should be successfully packed in the block. - ```protobuf - rpc ValidateTokenInfoExists(ValidateTokenInfoExistsInput) returns (google.protobuf.Empty){} + ```protobuf + rpc ValidateTokenInfoExists(ValidateTokenInfoExistsInput) returns (google.protobuf.Empty){} - message ValidateTokenInfoExistsInput { - string symbol = 1; - string token_name = 2; - int64 total_supply = 3; - int32 decimals = 4; - aelf.Address issuer = 5; - bool is_burnable = 6; - int32 issue_chain_id = 7; - } - ``` + message ValidateTokenInfoExistsInput { + string symbol = 1; + string token_name = 2; + int64 total_supply = 3; + int32 decimals = 4; + aelf.Address issuer = 5; + bool is_burnable = 6; + int32 issue_chain_id = 7; + } + ``` - **Create token FOO on chain B** - Send transaction `tx_3` to the `Token Contract` with the method `CrossChainCreateToken` on chain B. You need to provide the origin data of `tx_2` and the cross chain verification context of `tx_2`. + Send transaction `tx_3` to the `Token Contract` with the method `CrossChainCreateToken` on chain B. You need to provide the origin data of `tx_2` and the cross chain verification context of `tx_2`. - ```protobuf - rpc CrossChainCreateToken(CrossChainCreateTokenInput) returns (google.protobuf.Empty) {} + ```protobuf + rpc CrossChainCreateToken(CrossChainCreateTokenInput) returns (google.protobuf.Empty) {} - message CrossChainCreateTokenInput { - int32 from_chain_id = 1; - int64 parent_chain_height = 2; - bytes transaction_bytes = 3; - aelf.MerklePath merkle_path = 4; - } - ``` + message CrossChainCreateTokenInput { + int32 from_chain_id = 1; + int64 parent_chain_height = 2; + bytes transaction_bytes = 3; + aelf.MerklePath merkle_path = 4; + } + ``` ## Initiate the Transfer @@ -87,23 +89,23 @@ On the token contract of the source chain, the `CrossChainTransfer` method is us rpc CrossChainTransfer (CrossChainTransferInput) returns (google.protobuf.Empty) { } message CrossChainTransferInput { - aelf.Address to = 1; + aelf.Address to = 1; string symbol = 2; sint64 amount = 3; string memo = 4; - int32 to_chain_id = 5; + int32 to_chain_id = 5; int32 issue_chain_id = 6; } ``` ### The fields of the input: -- **to**: the target address to receive the token -- **symbol**: the symbol of the token to be transferred -- **amount**: the amount of the token to be transferred -- **memo**: a memo field for this transfer -- **to_chain_id**: the destination chain ID where the tokens will be received -- **issue_chain_id**: the chain ID where the token was issued +- `to`: the target address to receive the token +- `symbol`: the symbol of the token to be transferred +- `amount`: the amount of the token to be transferred +- `memo`: a memo field for this transfer +- `to_chain_id`: the destination chain ID where the tokens will be received +- `issue_chain_id`: the chain ID where the token was issued ## Receive on the Destination Chain @@ -131,13 +133,13 @@ message CrossChainMerkleProofContext { ### The fields of the input: -- **from_chain_id**: the source chain ID from which the cross chain transfer was launched +- `from_chain_id`: the source chain ID from which the cross chain transfer was launched -- **parent_chain_height**: the height of the block on the main chain that contains the `CrossChainTransfer` transaction (for main chain to side chain transfer). For side chain to side chain or side chain to main chain transfer, it is the result of `GetBoundParentChainHeightAndMerklePathByHeight` (input is the height of the `CrossChainTransfer`), accessible in the `bound_parent_chain_height` field. +- `parent_chain_height`: the height of the block on the main chain that contains the `CrossChainTransfer` transaction (for main chain to side chain transfer). For side chain to side chain or side chain to main chain transfer, it is the result of `GetBoundParentChainHeightAndMerklePathByHeight` (input is the height of the `CrossChainTransfer`), accessible in the `bound_parent_chain_height` field. -- **transfer_transaction_bytes**: the serialized form of the `CrossChainTransfer` transaction. +- `transfer_transaction_bytes`: the serialized form of the `CrossChainTransfer` transaction. -- **merkle_path**: obtained from the source chain. The construction of merkle path data differs among cases: +- `merkle_path`: obtained from the source chain. The construction of merkle path data differs among cases: - **Main chain to side chain transfer**: merkle path from the main chain’s web API `GetMerklePathByTransactionIdAsync` (with `CrossChainTransfer` transaction ID as input). - **Side chain to side chain or side chain to main chain transfer**: - merkle path from the source chain’s web API `GetMerklePathByTransactionIdAsync` (with `CrossChainTransfer` transaction ID as input). diff --git a/docs/understanding-aelf/cross-chain/cross-chain-verification/index.md b/docs/understanding-aelf/cross-chain/cross-chain-verification/index.md index aa8205b..c63d670 100644 --- a/docs/understanding-aelf/cross-chain/cross-chain-verification/index.md +++ b/docs/understanding-aelf/cross-chain/cross-chain-verification/index.md @@ -1,4 +1,45 @@ --- sidebar_position: 3 title: Cross Chain Verification ---- \ No newline at end of file +--- + + +# Cross Chain Verification + +Verification is the key feature that enables side chains. Because side chains do not have direct knowledge about other side chains, they need a way to verify information from other chains. Side chains need the ability to verify that a transaction was included in another side chain's block. + +## Indexing + +- The role of the main chain node is to index all the side chains' blocks. + - This way, it knows exactly the current state of all the side chains. + - Side chains also index main chain blocks, which is how they gain knowledge about the inclusion of transactions in other chains. +- Indexing is a continuous process: + - The main chain permanently gathers information from the side chains. + - The side chains permanently gather information from the main chain. +- When a side chain wants to verify a transaction from another side chain, it must wait until the correct main chain block has been indexed. + +## Merkle Tree + +- A Merkle tree is a basic binary tree structure. + - For cross-chain in AElf, the leaf value is the hash from transaction data. + - The node value (which is not a leaf node) is the hash calculated from its children's values up to the tree root. + +![Merkle Tree](../../../../static/img/merkle.png) + +## Merkle Root + +- When a transaction is included in a side chain's block, the block will also include a Merkle root of the transactions in this block. + - This root is local to this side chain's blockchain and, by itself, of little value to other side chains because they follow a different protocol. + - Communication between side chains goes through the main chain in the form of a Merkle path. + - During the indexing process, the main chain calculates the root with the data from side chains, and side chains in turn get the root in future indexing. + - This root is used for the final check in cross-chain transaction verification. + +## Merkle Path + +- A Merkle path is the node collection for one leaf node to calculate to the root. + - A correct Merkle path is necessary to complete any work related to cross-chain verification. +- For the transaction **tx** from chain **A**: + - You need the whole Merkle path root for **tx** to calculate the final root if you want to verify the existence of this transaction on other chains. + - Verify the root by checking whether it is equal to the one obtained from indexing before. + +![Merkle Path](../../../../static/img/merkle-path.png) \ No newline at end of file diff --git a/docs/understanding-aelf/cross-chain/verify/index.md b/docs/understanding-aelf/cross-chain/verify/index.md index 8e02aed..4ba269a 100644 --- a/docs/understanding-aelf/cross-chain/verify/index.md +++ b/docs/understanding-aelf/cross-chain/verify/index.md @@ -3,6 +3,7 @@ sidebar_position: 4 title: Verify --- + # Cross Chain Transaction Verification This section provides guidance on verifying transactions across different blockchain chains, assuming that a side chain has already been deployed and indexed by the main chain. @@ -33,7 +34,7 @@ message VerifyTransactionInput { The **VerifyTransaction** method is used for verification and returns whether the transaction was mined and indexed by the destination chain. The method is the same for both scenarios; only the input values differ. -### Verifying a Main Chain Transaction +## Verifying a Main Chain Transaction To verify a main chain transaction on a side chain, use the **VerifyTransaction** method on the side chain with the following input values: @@ -44,7 +45,7 @@ To verify a main chain transaction on a side chain, use the **VerifyTransaction* You can retrieve the Merkle path of a transaction in a block by using the chain's API method **GetMerklePathByTransactionIdAsync**. -### Verifying a Side Chain Transaction +## Verifying a Side Chain Transaction For verifying a side chain transaction: