From e8073e9d3402d2222b4e7f3448c77e12badfbe7e Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sat, 3 Dec 2022 12:36:49 -0800 Subject: [PATCH 01/12] [docs] bring back system-integrators-guide * rename system-integrators-guide to aptos-apis * resurrect the last full version of system-integrators-guide * update with new links stripping basics- from many docs todo: * cleanup system-integrators-guide with links to updated documentation * add more content to system-integrators-guide covering FAQs --- developer-docs-site/docs/guides/aptos-apis.md | 408 ++++++++++++++++++ .../docs/guides/system-integrators-guide.md | 133 +++++- developer-docs-site/docs/reference/index.md | 4 +- developer-docs-site/sidebars.js | 3 +- 4 files changed, 543 insertions(+), 5 deletions(-) create mode 100644 developer-docs-site/docs/guides/aptos-apis.md diff --git a/developer-docs-site/docs/guides/aptos-apis.md b/developer-docs-site/docs/guides/aptos-apis.md new file mode 100644 index 0000000000000..47e4c122385c6 --- /dev/null +++ b/developer-docs-site/docs/guides/aptos-apis.md @@ -0,0 +1,408 @@ +--- +title: "Use Aptos API" +slug: "aptos-api" +--- + +# Use the Aptos API with Your Platform + +If you provide blockchain services to your customers and wish to add the Aptos blockchain to your platform, then this guide is for you. This system integrators guide will walk you through all you need to integrate the Aptos blockchain into your platform. + +## Overview + +This document will guide you through the following tasks to integrate with Aptos: +1. Prepare an environment for testing. +1. Create an account on the blockchain. +1. Exchange account identifiers with another entity on the blockchain, for example, to perform swaps. +1. Create a transaction. +1. Obtain a gas estimate and validate the transaction for correctness. +1. Submit the transaction to the blockchain. +1. Wait for the outcome of the transaction. +1. Query historical transactions and interactions for a given account with a specific account, i.e., withdraws and deposits. + +## Networks + +There are three well-supported networks for integrating with the Aptos blockchain: + +1. Local testnet -- our standalone tool for local development against a known version of the codebase with no external network. +1. Devnet -- a shared resource for the community, data resets weekly, weekly update from aptos-core main branch. +1. Testnet -- a shared resource for the community, data will be preserved, network configuration will mimic Mainnet. + +See [Aptos Blockchain Deployments](../nodes/aptos-deployments.md) for full details on each environment. + +### Local testnet + +There are two options to run a local testnet: +* Directly [run a local testnet](../nodes/local-testnet/run-a-local-testnet.md) using either the [Aptos-core source code](/nodes/local-testnet/run-a-local-testnet/#using-the-aptos-core-source-code) or a [Docker image](/nodes/local-testnet/run-a-local-testnet/#using-docker). These paths are useful for testing changes to the Aptos-core codebase or framework, or for building services on top of the Aptos blockchain, respectively. +* [Install the Aptos CLI](/cli-tools/aptos-cli-tool/install-aptos-cli) and 2) start a [local node with a faucet](/nodes/local-testnet/using-cli-to-run-a-local-testnet#starting-a-local-testnet-with-a-faucet). This path is useful for developing on the Aptos blockchain, debugging Move contracts, and testing node operations. + +Either of these methods will expose a REST API service at `http://127.0.0.1:8080/v1` and a Faucet service at `http://127.0.0.1:8000` for option 1 or `http://127.0.0.1:8081` for option 2. The applications will output the location of the services. + +### Aptos Devnet + +* Faucet service: https://faucet.devnet.aptoslabs.com +* REST API service: https://fullnode.devnet.aptoslabs.com/v1 + +### Access Testnet + +* Faucet service: https://faucet.testnet.aptoslabs.com +* REST API service: https://fullnode.testnet.aptoslabs.com/v1 + +### SDKs + +Aptos currently provides three SDKs: +1. [Typescript](/sdks/ts-sdk/index) +2. [Python](/sdks/python-sdk) +3. [Rust](/sdks/rust-sdk) + + +### Other tools + +* [Using the CLI](../cli-tools/aptos-cli-tool/use-aptos-cli) which includes creating accounts, transferring coins, and publishing modules +* [REST API spec](https://fullnode.devnet.aptoslabs.com/v1/spec#/) +* [Local testnet development flow](/guides/local-testnet-dev-flow) + +## Viewing current and historical state + +Most integrations into the Aptos blockchain benefit from a holistic and comprehensive overview of the current and historical state of the blockchain. Aptos provides historical transactions, state, and events, all the result of transaction execution. + +* Historical transactions specify the execution status, output, and tie to related events. Each transaction has a unique version number associated with it that dictates its global sequential ordering in the history of the blockchain ledger. +* The state is the representation of all transaction outputs up to a specific version. In other words, a state version is the accumulation of all transactions inclusive of that transaction version. +* As transactions execute, they may emit events. [Events](/concepts/events) are hints about changes in on-chain data. + +The storage service on a node employs two forms of pruning that erase data from nodes: + +* state +* events, transactions, and everything else + +While either of these may be disabled, storing the state versions is not particularly sustainable. + +Events and transactions pruning can be disabled via setting the [`enable_ledger_pruner`](https://github.com/aptos-labs/aptos-core/blob/cf0bc2e4031a843cdc0c04e70b3f7cd92666afcf/config/src/config/storage_config.rs#L141) to `false`. This is default behavior in Mainnet. In the near future, Aptos will provide indexers that mitigate the need to directly query from a node. + +The REST API offers querying transactions and events in these ways: + +* [Transactions for an account](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_account_transactions) +* [Transactions by version](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_transaction_by_version) +* [Events by event handle](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_events_by_event_handle) + +## Exchanging and tracking coins + +Aptos has a standard [Coin type](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/coin.move). Different types of coins can be represented in this type through the use of distinct structs that represent the type parameter or generic for `Coin`. + +Coins are stored within an account under the resource `CoinStore`. At account creation, each user has the resource `CoinStore<0x1::aptos_coin::AptosCoin>` or `CoinStore`, for short. Within this resource is the Aptos coin: `Coin`. + +### Transferring coins between users + +Coins can be transferred between users via the [`coin::transfer`](https://github.com/aptos-labs/aptos-core/blob/36a7c00b29a457469264187d8e44070b2d5391fe/aptos-move/framework/aptos-framework/sources/coin.move#L307) function for all coins and [`aptos_account::transfer`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L18) for Aptos coins. The advantage of the latter function is that it creates the destination account if it does not exist. + +:::caution +It is important to note that if an account has not registered a `CoinStore` for a given `T`, then any transfer of type `T` to that account will fail. +::: + +### Current balance for a coin + +The current balance for a `Coin` where `T` is the Aptos coin is available at the account resources URL: `https://{rest_api_server}/accounts/{address}/resource/0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>`. The balance is stored within `coin::amount`. The resource also contains the total number of deposit and withdraw events, and the `counter` value within `deposit_events` and `withdraw_events`, respectively. + +``` +{ + "type": "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>", + "data": { + "coin": { + "value": "3927" + }, + "deposit_events": { + "counter": "1", + "guid": { + "id": { + "addr": "0xcb2f940705c44ba110cd3b4f6540c96f2634938bd5f2aabd6946abf12ed88457", + "creation_num": "2" + } + } + }, + "withdraw_events": { + "counter": "1", + "guid": { + "id": { + "addr": "0xcb2f940705c44ba110cd3b4f6540c96f2634938bd5f2aabd6946abf12ed88457", + "creation_num": "3" + } + } + } + } +} +``` + +### Querying transactions + +In Aptos, each transaction is committed as a distinct version to the blockchain. This allows for the convenience of sharing committed transactions by their version number; to do so, query: `https://{rest_server_api}/transactions/by_version/{version}` + +Transactions submitted by an account can also be queried via the following URL where the `sequence_number` matches the sequence number of the transaction: `https://{rest_server_api}/account/{address}/transactions?start={sequence_number}&limit=1` + +A transfer transaction would appear as follows: + +``` +{ + "version": "13629679", + "gas_used": "4", + "success": true, + "vm_status": "Executed successfully", + "changes": [ + { + "address": "0xb258b91eee04111039320a85b0c24a2dd433909e14a6b5c32ee722e0fdecfddc", + "data": { + "type": "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>", + "data": { + "coin": { + "value": "1000" + }, + "deposit_events": { + "counter": "1", + "guid": { + "id": { + "addr": "0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", + "creaton_num": "2", + } + } + }, + ... + } + }, + "type": "write_resource" + }, + ... + ], + "sender": "0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b", + "sequence_number": "0", + "max_gas_amount": "2000", + "gas_unit_price": "1", + "expiration_timestamp_secs": "1660616127", + "payload": { + "function": "0x1::coin::transfer", + "type_arguments": [ + "0x1::aptos_coin::AptosCoin" + ], + "arguments": [ + "0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", + "1000" + ], + "type": "entry_function_payload" + }, + "events": [ + { + "key": "0x0300000000000000810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b", + "guid": { + "id": { + "addr": "0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b", + "creation_num": "3" + } + } + }, + "sequence_number": "0", + "type": "0x1::coin::WithdrawEvent", + "data": { + "amount": "1000" + } + }, + { + "key": "0x02000000000000005098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", + guid": { + "id": { + "addr": "0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", + "creation_num": "2" + } + } + }, + "sequence_number": "0", + "type": "0x1::coin::DepositEvent", + "data": { + "amount": "1000" + } + } + ], + "timestamp": "1660615531147935", + "type": "user_transaction" +} + +``` + +Here is a breakdown of the information in a transaction: +* `version` indicates the globally unique identifier for this transaction, its ordered position in all the committed transactions on the blockchain +* `sender` is the account address of the entity that submitted the transaction +* `gas_used` is the units paid for executing the transaction +* `success` and `vm_status` indicate whether or not the transaction successfully executed and any reasons why it might not have +* `changes` include the final values for any state resources that have been modified during the execution of the transaction +* `events` contain all the events emitted during the transaction execution +* `timetstamp` is the near real-time timestamp of the transaction's execution + +If `success` is false, then `vm_status` will contain an error code or message that resulted in the transaction failing to succeed. When `success` is false, `changes` will be limited to gas deducted from the account and the sequence number incrementing. There will be no `events`. + +Each event in `events` is differentiated by a `key`. The `key` is derived from the `guid` in `changes`. Specifically, the `key` is a 40-byte hex string where the first eight bytes (or 16 characters) are the little endian representation of the `creation_num` in the `guid` of the `changes` event, and the remaining characters are the account address. + +As events do not dictate what emitted them, it is imperative to track the path in `changes` to determine the source of an event. In particular, each `CoinStore` has both a `WithdrawEvent` and a `DepositEvent`, based upon the type of coin. In order to determine which coin type is used in a transaction, an indexer can compare the `guid::creation_num` in a `changes` event combined with the address to the `key` for events in `events`. + +Using the above example, `events[1].guid` is equivalent to `changes[0].data.data.deposit_events.guid`, which is `{"addr": "0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", "creation_num": "2"}`. + +:::tip +The `key` field will be going away in favor of `guid` +::: + +### Querying events + +Aptos provides clear and canonical events for all withdraw and deposit of coins. This can be used in coordination with the associated transactions to present to a user the change of their account balance over time, when that happened, and what caused it. With some amount of additional parsing, metadata such as the transaction type and the other parties involved can also be shared. + +Query events by handle URL: `https://{rest_api_server}/accounts/{address}/events/0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>/withdraw_events` + +``` +[ + { + "version":"13629679", + "key": "0x0300000000000000cb2f940705c44ba110cd3b4f6540c96f2634938bd5f2aabd6946abf12ed88457", + "guid": { + "id": { + "addr": "0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b", + "creation_num": "3" + } + } + }, + "sequence_number": "0", + "type": "0x1::coin::WithdrawEvent", + "data": { + "amount": "1000" + } + } +] +``` + +Gather more information from the transaction that generated the event by querying `https://{rest_server_api}/transactions/by_version/{version}` where `{version}` is the same value as the `{version}` in the event query. + +:::tip + +When tracking full movement of coins, normally events are sufficient. `0x1::aptos_coin::AptosCoin`, however, requires considering `gas_used` for each transaction sent from the given account since it represents gas in Aptos. To reduce unnecessary overhead, extracting gas fees due to transactions does not emit an event. All transactions for an account can be retrieved from this API: `https://{rest_server_api}/accounts/{address}/transactions` + +::: + +### Tracking coin balance changes + +Consider the transaction from the earlier section, but now with an arbitrary coin `0x1337::my_coin::MyCoin` and some gas parameters changed: +``` +{ + "version": "13629679", + "gas_used": "20", + "success": true, + "vm_status": "Executed successfully", + "changes": [ + { + "address": "0xb258b91eee04111039320a85b0c24a2dd433909e14a6b5c32ee722e0fdecfddc", + "data": { + "type": "0x1::coin::CoinStore<0x1337::my_coin::MyCoin>", + "data": { + "coin": { + "value": "1000" + }, + "deposit_events": { + "counter": "1", + "guid": { + "id": { + "addr": "0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", + "creaton_num": "2", + } + } + }, + ... + } + }, + "type": "write_resource" + }, + ... + ], + "sender": "0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b", + "sequence_number": "0", + "max_gas_amount": "2000", + "gas_unit_price": "110", + "expiration_timestamp_secs": "1660616127", + "payload": { + "function": "0x1::coin::transfer", + "type_arguments": [ + "0x1337::my_coin::MyCoin" + ], + "arguments": [ + "0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", + "1000" + ], + "type": "entry_function_payload" + }, + "events": [ + { + "key": "0x0300000000000000810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b", + "guid": { + "id": { + "addr": "0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b", + "creation_num": "3" + } + } + }, + "sequence_number": "0", + "type": "0x1::coin::WithdrawEvent", + "data": { + "amount": "1000" + } + }, + { + "key": "0x02000000000000005098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", + guid": { + "id": { + "addr": "0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e", + "creation_num": "2" + } + } + }, + "sequence_number": "0", + "type": "0x1::coin::DepositEvent", + "data": { + "amount": "1000" + } + } + ], + "timestamp": "1660615531147935", + "type": "user_transaction" +} +``` + +There are three balance changes in this transaction: +1. A withdrawal of `1000` of `0x1337::my_coin::MyCoin` from the transaction sending account `0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b` +2. A deposit of `1000` of `0x1337::my_coin::MyCoin` to receiving account `0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e` +3. A gas fee `2200` of `0x1::aptos_coin::AptosCoin` from the sending account `0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b` + +To retrieve the withdrawal information: +1. Scan the `changes` for `0x1::coin::CoinStore`. Note the `CoinType` is a generic signifying which coin is stored in the store. In this example, the `CoinType` is `0x1337::my_coin::MyCoin`. +2. Retrieve the `guid` for `withdraw_events`. In this example, the `guid` contains `addr` `0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b` and `creation_num` `3`. +3. Scan for events with this `guid` and extract the event associated with it. In this example, it is the `0x1::coin::WithdrawEvent`. +4. Note the `amount` field will be the number of `CoinType` removed from the account in the `guid`. In this example, it is `1000`. + +To retrieve the deposit information, it's the same as withdrawal except: +1. The `guid` used is under `deposit_events` +2. The `amount` will be a positive increase on the account's balance. +3. The event's name will be: `0x1::coin::DepositEvent` + +To retrieve the gas fee: +1. The `gas_used` field must be multiplied times the `gas_unit_price`. In this example, `gas_used=20` and `gas_unit_price=110` so the total gas coins withdrawn is `2200`. +2. Gas is always: `0x1::aptos_coin::AptosCoin` + +To retrieve information about the number of decimals of the coin: +1. You can retrieve the number of decimals for a coin via its: `0x1::coin::CoinInfo` +2. This will be located at the address of the coin type. In this example, you would need to look up `0x1::coin::CoinInfo<0x1337::my_coin::MyCoin>` at address `0x1337`. + +:::tip +If you always use the events in this manner, you won't miss any balance changes for an account. +By monitoring the events, you will find all balance changes in the `0x1::coin::CoinStore`: +1. Coin mints +2. Coin burns +3. Coin transfers +4. Staking coins +5. Withdrawing staked coins +6. Transfers not derived from `coin::transfer` + +::: + +To create some sample data to explore, conduct ["Your first transaction"](../tutorials/your-first-transaction). + +To learn more about coin creation, make ["Your First Coin"](../tutorials/your-first-coin). diff --git a/developer-docs-site/docs/guides/system-integrators-guide.md b/developer-docs-site/docs/guides/system-integrators-guide.md index de430153f9cdd..1628bc727b6ca 100644 --- a/developer-docs-site/docs/guides/system-integrators-guide.md +++ b/developer-docs-site/docs/guides/system-integrators-guide.md @@ -1,9 +1,9 @@ --- -title: "Use Aptos API" +title: "Integrate Aptos" slug: "system-integrators-guide" --- -# Use the Aptos API with Your Platform +# Integrate Aptos with Your Platform If you provide blockchain services to your customers and wish to add the Aptos blockchain to your platform, then this guide is for you. This system integrators guide will walk you through all you need to integrate the Aptos blockchain into your platform. @@ -61,6 +61,135 @@ Aptos currently provides three SDKs: * [REST API spec](https://fullnode.devnet.aptoslabs.com/v1/spec#/) * [Local testnet development flow](/guides/local-testnet-dev-flow) +## Accounts on Aptos + +An [account](/concepts/accounts) represents a resource on the Aptos blockchain that can send transactions. Each account is identified by a particular 32-byte account address and is a container for Move modules and Move resources. On Aptos, accounts must be created on-chain prior to any blockchain operations involving that account. The Aptos framework supports implicitly creating accounts when transferring Aptos coin via [`aptos_account::transfer`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L18) or explicitly via [`aptos_account::create_account`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L13). + +At creation, an [Aptos account](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/account.move#L23) contains: +* A [resource containing Aptos Coin](https://github.com/aptos-labs/aptos-core/blob/60751b5ed44984178c7163933da3d1b18ad80388/aptos-move/framework/aptos-framework/sources/coin.move#L50) and deposit and withdrawal of coins from that resource. +* An authentication key associated with their current public, private key(s). +* A strictly increasing sequence number that represents the account's next transaction's sequence number to prevent replay attacks. +* A strictly increasing number that represents the next distinct GUID creation number. +* An event stream for all new types of coins added to the account. +* An event stream for all key rotations for the account. + +### Account identifiers + +Currently, Aptos supports only a single, unified identifier for an account. Accounts on Aptos are universally represented as a 32-byte hex string. A hex string shorter than 32-bytes is also valid: in those scenarios, the hex string is padded with leading zeroes, e.g., `0x1` => `0x0000000000000...01`. + +### Creating an account address + +[Account addresses](../concepts/accounts.md#account-address) are defined at creation time as a one-way function from the public key(s) and signature algorithm used for authentication for the account. + +:::tip Read more +This is covered in depth in the [Accounts](../concepts/accounts.md) documentation and demonstrated in the [Typescript SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_account.ts#L66) and [Python SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/account_address.py#L43). Note that currently these SDKs demonstrate only how to generate an address from an Ed25519 single signer. +::: + +### Rotating the keys + +An Account on Aptos has the ability to rotate keys so that potentially compromised keys cannot be used to access the accounts. Keys can be rotated via the [`account::rotate_authentication_key`](https://github.com/aptos-labs/aptos-core/blob/60751b5ed44984178c7163933da3d1b18ad80388/aptos-move/framework/aptos-framework/sources/account.move#L183) function. + +Refreshing the keys is generally regarded as good hygiene in the security field. However, this presents a challenge for system integrators who are used to using a mnemonic to represent both a private key and its associated account. To simplify this for the system integrators, Aptos provides an on-chain mapping via `aptos account lookup-address`. The on-chain data maps an effective account address as defined by the current mnemonic to the actual account address. + +### Preventing replay attacks + +When the Aptos blockchain processes the transaction, it looks at the sequence number in the transaction and compares it with the sequence number in the sender’s account (as stored on the blockchain at the current ledger version). The transaction is executed only if the sequence number in the transaction is the same as the sequence number for the sender account, and the transaction is rejected if those two numbers do not match. In this way past transactions, which necessarily contain older sequence numbers, cannot be replayed, hence preventing replay attacks. + +:::tip Read more +See more on [Account sequence numbering](/concepts/accounts#account-sequence-number). +::: + +## Transactions + +Aptos [transactions](/concepts/txns-states) are encoded in [Binary Canonical Serialization (BCS)](https://github.com/diem/bcs). Transactions contain information such as the sender’s account address, authentication from the sender, the desired operation to be performed on the Aptos blockchain, and the amount of gas the sender is willing to pay to execute the transaction. + +### Transaction states + +A transaction may end in one of the following states: + +* Committed on the blockchain and executed. This is considered as a successful transaction. +* Committed on the blockchain and aborted. The abort code indicates why the transaction failed to execute. +* Discarded during transaction submission due to a validation check such as insufficient gas, invalid transaction format, or incorrect key. +* Discarded after transaction submission but before attempted execution. This could be caused by timeouts or insufficient gas due to other transactions affecting the account. + +The sender’s account will be charged gas for any committed transactions. + +During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise. + +A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted. + +The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream. + +On the Aptos devnet, the time between submission and confirmation is within seconds. + +:::tip Read more +See [Life of a Transaction](/guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle. +::: + +### Constructing a transaction + +Aptos supports two methods for constructing transactions: + +- Constructing JSON-encoded objects and interacting with the Web API to generate native transactions. +- Using the Aptos client libraries to generate native transactions. + +#### JSON-encoded transactions + +JSON-encoded transactions can be generated via the [REST API](https://fullnode.devnet.aptoslabs.com/v1/spec#/), following these steps: + +1. First construct an appropriate JSON payload for the `/transactions/encode_submission` endpoint as demonstrated in the [Python SDK](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L128). +1. The output of the above contains an object containing a `message` that must be signed with the sender’s private key locally. +1. Extend the original JSON payload with the signature information and post it to the `/transactions` [endpoint](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L142). This will return a transaction submission result that, if successful, contains a transaction hash in the `hash` [field](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L145). + +JSON-encoded transactions allow for rapid development and support seamless ABI conversions of transaction arguments to native types. However, most system integrators prefer to generate transactions within their own tech stack. Both the [TypeScript SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.ts#L259) and [Python SDK](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L100) support generating BCS transactions. + +#### BCS-encoded transactions + +BCS-encoded transactions can be submitted to the `/transactions` endpoint but must specify `Content-Type: application/x.aptos.signed_transaction+bcs` in the HTTP headers. This will return a transaction submission result that, if successful, contains a transaction hash in the `hash` [field](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/client.py#L138). + +### Types of transactions + +Within a given transaction, the target of execution can be one of two types: + +- An entry point (formerly known as script function) +- A script (payload) + +Currently the SDKs [Python](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L249) and [Typescript](https://github.com/aptos-labs/aptos-core/blob/76b654b54dcfc152de951a728cc1e3f9559d2729/ecosystem/typescript/sdk/src/aptos_client.test.ts#L98) support the generation of transactions that target entry points only. This guide points out many of those entry points, such as `coin::transfer` and `aptos_account::create_account`. + +All operations on the Aptos blockchain should be available via entry point calls. While one could submit multiple transactions calling entry points in series, many such operations may benefit from being called atomically from a single transaction. A script payload transaction can call any entry point or public function defined within any module. + +:::tip Move book +Currently there are no tutorials in this guide on script payloads, but the [Move book](https://move-language.github.io/move/modules-and-scripts.html?highlight=script#scripts) does go in some depth. +::: + +:::tip Read more + +See the following documentation for generating valid transactions: + +- [JSON-encoded transactions](http://aptos.dev/tutorials/your-first-transaction) via Typescript, Python, and Rust. +- [Python example of BCS-encoded coin transfers](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/client.py#L240). +- [Typescript example of BCS-encoded coin transfers](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.test.ts#L122). +- [CLI-based transaction publishing](http://aptos.dev/cli-tools/aptos-cli-tool/use-aptos-cli#publishing-a-move-package-with-a-named-address). +- [Publish your first Move module](https://aptos.dev/tutorials/first-move-module) via Typescript, Python, and Rust. + +::: + +### Status of a transaction + +Obtain transaction status by querying the API [`/transactions/by_hash/{hash}`](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_transaction_by_hash) with the hash returned during the submission of the transaction. + +A reasonable strategy for submitting transactions is to limit their lifetime to 30 to 60 seconds, and polling that API at regular intervals until success or several seconds after that time has elapsed. If there is no commitment on-chain, the transaction was likely discarded. + +### Testing transactions or transaction pre-execution + +To facilitate evaluation of transactions, Aptos supports a simulation API that does not require and should not contain valid signatures on transactions. + +The simulation API works identically to the transaction submission API, except that it executes the transaction and returns the results along with the gas used. The simulation API can be accessed by submitting a transaction to [`/transactions/simulate`](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/simulate_transaction). + +:::tip Read more +Here's an [example showing how to use the simulation API in the Typescript SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.ts#L413). Note that the gas use may change based upon the state of the account. We recommend that the maximum gas amount be larger than the amount quoted by this API. +::: + ## Viewing current and historical state Most integrations into the Aptos blockchain benefit from a holistic and comprehensive overview of the current and historical state of the blockchain. Aptos provides historical transactions, state, and events, all the result of transaction execution. diff --git a/developer-docs-site/docs/reference/index.md b/developer-docs-site/docs/reference/index.md index f1d13313c6e82..db93bbcbf75f3 100644 --- a/developer-docs-site/docs/reference/index.md +++ b/developer-docs-site/docs/reference/index.md @@ -17,7 +17,7 @@ You can try out APIs for different networks here: - ### [Testnet](https://fullnode.testnet.aptoslabs.com/v1/spec#/) - ### [Mainnet](https://fullnode.mainnet.aptoslabs.com/v1/spec#/) -Read [Use Aptos API](../guides/system-integrators-guide.md) to integrate Aptos into your platform. +Read [System Integrators Guide](../guides/system-integrators-guide.md) to integrate Aptos into your platform. ## Aptos SDKs @@ -30,4 +30,4 @@ Read [Use Aptos API](../guides/system-integrators-guide.md) to integrate Aptos i * *Aptos tokens* - [main](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/overview.md), [testnet](https://github.com/aptos-labs/aptos-core/blob/testnet/aptos-move/framework/aptos-token/doc/overview.md), [devnet](https://github.com/aptos-labs/aptos-core/blob/devnet/aptos-move/framework/aptos-token/doc/overview.md) * *Aptos framework* - [main](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/doc/overview.md), [testnet](https://github.com/aptos-labs/aptos-core/blob/testnet/aptos-move/framework/aptos-framework/doc/overview.md), [devnet](https://github.com/aptos-labs/aptos-core/blob/devnet/aptos-move/framework/aptos-framework/doc/overview.md) * *Aptos stdlib* - [main](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/doc/overview.md), [testnet](https://github.com/aptos-labs/aptos-core/blob/testnet/aptos-move/framework/aptos-stdlib/doc/overview.md), [devnet](https://github.com/aptos-labs/aptos-core/blob/devnet/aptos-move/framework/aptos-stdlib/doc/overview.md) -* *Move stdlib* - [main](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/move-stdlib/doc/overview.md), [testnet](https://github.com/aptos-labs/aptos-core/blob/testnet/aptos-move/framework/move-stdlib/doc/overview.md), [devnet](https://github.com/aptos-labs/aptos-core/blob/devnet/aptos-move/framework/move-stdlib/doc/overview.md) \ No newline at end of file +* *Move stdlib* - [main](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/move-stdlib/doc/overview.md), [testnet](https://github.com/aptos-labs/aptos-core/blob/testnet/aptos-move/framework/move-stdlib/doc/overview.md), [devnet](https://github.com/aptos-labs/aptos-core/blob/devnet/aptos-move/framework/move-stdlib/doc/overview.md) diff --git a/developer-docs-site/sidebars.js b/developer-docs-site/sidebars.js index 40f6d6320bf43..3c359f0856259 100644 --- a/developer-docs-site/sidebars.js +++ b/developer-docs-site/sidebars.js @@ -69,6 +69,7 @@ const sidebars = { "cli-tools/install-move-prover", ], }, + "guides/system-integrators-guide", { type: "html", value: "Build Apps", @@ -87,7 +88,7 @@ const sidebars = { label: "Read Blockchain Data", collapsible: true, collapsed: true, - items: ["guides/system-integrators-guide", "guides/indexing"], + items: ["guides/aptos-apis", "guides/indexing"], }, { type: "category", From 026ce3cc17d870307c735d1584e77f25e1e22795 Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sat, 3 Dec 2022 20:31:17 -0800 Subject: [PATCH 02/12] [docs] update resources * I thought we agreed that we'd not use any special formatting in the docs, why are we line breaking paragraphs? we really need to standardize this :) * Add a section on addressing and full definitions. * Merge How resources are stored and parallel processing they say the same thing redundantly. The argument for indexing doesn't really make sense in this context. I think there's an attempt to get into an advanced topic but it really falls flat. --- .../docs/concepts/resources.md | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/developer-docs-site/docs/concepts/resources.md b/developer-docs-site/docs/concepts/resources.md index a95986b873b7d..86bec01729a18 100644 --- a/developer-docs-site/docs/concepts/resources.md +++ b/developer-docs-site/docs/concepts/resources.md @@ -5,16 +5,11 @@ id: "resources" # Resources -On Aptos, smart contract states are sharded by accounts. All on-chain states have to be organized into resources and associated -with specific accounts. This is different from other blockchains, such as Ethereum, where each smart contract maintains -their own storage space. Accounts on Aptos can contain associated modules and resources. [Events](./events.md) are stored -inside resources. -See [Accounts](./accounts.md) for more details on accounts. +On Aptos, on-chain state is organized into resources and modules. These are then stored within the individual accounts. This is different from other blockchains, such as Ethereum, where each smart contract maintains their own storage space. Additionally, [event handles](./events.md) are defined within resources. See [Accounts](./accounts.md) for more details on accounts. ## Resources vs Objects -Resources refer to top-level objects that are stored directly with an account on the blockchain. Objects can be resources but -can also be individual units of state that are stored inside a resource. An example here is how the APT coin is stored: CoinStore -is the resource that contains the APT coin while the Coin itself is an object: + +Resources refer to top-level objects that are stored directly with an account on the blockchain. Both resources and object are instances of structs. Objects can be resources but can also be individual units of state that are stored inside a resource. An example here is how the APT coin is stored: CoinStore is the resource that contains the APT coin while the Coin itself is an object: ```rust /// A holder of a specific coin types and associated event handles. @@ -30,8 +25,7 @@ struct Coin has store { } ``` -The Coin object can be taken out of CoinStore with the owning account's permission and easily transferred to another CoinStore -resource. It can also be kept in any other custom resource, if the definition allows, for example: +The Coin object can be taken out of CoinStore with the owning account's permission and easily transferred to another CoinStore resource. It can also be kept in any other custom resource, if the definition allows, for example: ```rust struct CustomCoinBox has key { @@ -39,30 +33,36 @@ struct CustomCoinBox has key { } ``` +## Resource and Object Definition + +All objects and resources are defined within a module that is stored at an address. For example `0x1234::coin::Coin<0x1234::coin::SomeCoin>` would be represented as: + +``` +module 0x1234::coin { + struct CoinStore has key { + coin: Coin, + } + + struct SomeCoin { } +} +``` + +In this example, `0x1234` is the address, `coin` is the module, `Coin` is a struct that can be stored as a resource, and `SomeCoin` is a struct that is unlikely to ever be represented as an object. The use of the phantom type allows for there to exist many distinct types of `CoinStore` resources with different `CoinType` parameters. + ## Dual ownership of objects, including resources + Objects (including resources) on Aptos are owned by both: 1. The account where the object is stored, and 2. The module that defines the object. -Creating a new resource and storing it into an account requires both the owning account's signature and the module's code. -But modifying and deleting the resource/object requires only the module's code and the owning account's address. The fields of -an object also can be read only directly by the module's code, which can be offered as public utilities for other modules. +Creating a new resource and storing it into an account requires both the owning account's signature and the module's code. But modifying and deleting the resource/object requires only the module's code and the owning account's address. The fields of an object also can be read only directly by the module's code, which can be offered as public utilities for other modules. This dual-ownership design is one of the bases of state safety in Aptos Move and enables powerful but safe functionalities to be built around resources and objects. ## Viewing a resource -Resources are stored within specific accounts. To locate a resource, the owning account must first be identified. -Resources can be viewed on the [Aptos Explorer](https://explorer.aptoslabs.com/) by searching for the owning account or be directly -fetched from a fullnode's API. See [Interacting with the blockchain](../guides/interacting-with-the-blockchain.md) for more information. + +Resources are stored within specific accounts. Resources can be located by searching within the owners account for the resource at its full query path inclusive of its address and module. Resources can be viewed on the [Aptos Explorer](https://explorer.aptoslabs.com/) by searching for the owning account or be directly fetched from a fullnode's API. See [Interacting with the blockchain](../guides/interacting-with-the-blockchain.md) for more information. ## How resources are stored -It's up to the smart contract developers to decide how and where a specific state is stored. For example, events for depositing -a token can be stored in the receiver account where the deposit happens or in the account the token module is deployed at. -In general, storing data in individual user accounts enables a higher level of execution efficiency as there would be no -state read/write conflicts among transactions, and they can be executed in parallel. - -## Parallel processing -Sharding of state across accounts via resources allows efficient processing of transactions on the Aptos blockchain. The more -developers neatly organize resources in end user accounts, the more efficiency the network gains collectively. The only trade-off -of sharding is that it's more difficult when data is needed from multiple different accounts. This problem can be solved through -[indexing](../guides/indexing.md). + +It's up to the smart contract developers to decide how and where a specific state is stored. For example, events for depositing a token can be stored in the receiver account where the deposit happens or in the account the token module is deployed at. In general, storing data in individual user accounts enables a higher level of execution efficiency as there would be no state read/write conflicts among transactions, and they can be executed in parallel. From e443c0de32adb78d28c3dfaf23231305ac18d4ab Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sat, 3 Dec 2022 20:54:40 -0800 Subject: [PATCH 03/12] [docs] txn-states * Merge paragraphs into a single line in some cases -- this one was mixed * Improve readability of transactions by moving high level together before getting into the components and guts of a transaction * Move the txn state diagram to the end where it is discussed * Separate the content between txns, state, and txn+state * Delete "(fomerly known a script functions)" they haven't been known as that since my last craziness right before testnet freeze :D * Removed some duplicated content --- .../docs/concepts/txns-states.md | 132 ++++++------------ 1 file changed, 46 insertions(+), 86 deletions(-) diff --git a/developer-docs-site/docs/concepts/txns-states.md b/developer-docs-site/docs/concepts/txns-states.md index 66042ae75f1fb..02ca9ced8806d 100755 --- a/developer-docs-site/docs/concepts/txns-states.md +++ b/developer-docs-site/docs/concepts/txns-states.md @@ -13,25 +13,36 @@ The two fundamental concepts at the heart of the Aptos blockchain are transactio * **Transactions**: Transactions represent the exchange of data (e.g., Aptos Coins or NFTs) between accounts on the Aptos blockchain. * **States**: The state, i.e., the Aptos blockchain ledger state, represents the state of all the accounts in the Aptos blockchain. -:::tip Executing a transaction changes the ledger state -When a transaction is executed, the state of the Aptos blockchain changes. Nothing else can alter the state. +:::tip +Only executing transactions can change the ledger state. ::: - - ## Transactions -Aptos transactions are encoded in Binary Canonical Serialization (BCS). Transactions contain information such as -the sender’s account address, authentication from the sender, the desired operation to be performed on the Aptos blockchain, -and the amount of gas the sender is willing to pay to execute the transaction. +Aptos transactions contain information such as the sender’s account address, authentication from the sender, the desired operation to be performed on the Aptos blockchain, and the amount of gas the sender is willing to pay to execute the transaction. + +### Transaction states + +A transaction may end in one of the following states: + +* Committed on the blockchain and executed. This is considered as a successful transaction. +* Committed on the blockchain and aborted. The abort code indicates why the transaction failed to execute. +* Discarded during transaction submission due to a validation check such as insufficient gas, invalid transaction format, or incorrect key. +* Discarded after transaction submission but before attempted execution. This could be caused by timeouts or insufficient gas due to other transactions affecting the account. + +The sender’s account will be charged gas for any committed transactions. + +During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise. + +A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted. + +The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream. + +:::tip Read more +See [Life of a Transaction](../guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle. +::: -When a client submits a transaction to the Aptos blockchain, then, if the transaction is successful the ledger state is updated. +### Contents of a Transaction A [signed transaction](../guides/sign-a-transaction.md) on the blockchain contains the following information: @@ -47,10 +58,10 @@ A [signed transaction](../guides/sign-a-transaction.md) on the blockchain contai - **Sequence number**: This is an unsigned integer that must be equal to the sender's account [sequence number](./accounts#account-sequence-number) at the time of execution. - **Expiration time**: A timestamp after which the transaction ceases to be valid (i.e., expires). -## Types of transactions +### Types of transactions Within a given transaction, the target of execution can be one of two types: -- An entry point (formerly known as script function) +- An entry point - A script (payload) Currently the SDKs [Python](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L249) and [Typescript](https://github.com/aptos-labs/aptos-core/blob/76b654b54dcfc152de951a728cc1e3f9559d2729/ecosystem/typescript/sdk/src/aptos_client.test.ts#L98) support the generation of transactions that target entry points only. This guide points out many of those entry points, such as `coin::transfer` and `aptos_account::create_account`. @@ -62,39 +73,20 @@ Currently there are no tutorials in this guide on script payloads, but the [Move ::: :::tip Read more +See the tutorial on [Your First Transaction](../tutorials/first-transaction.md) for generating valid transactions. +::: -See the following documentation for generating valid transactions: - -- [JSON-encoded transactions](../tutorials/first-transaction.md) via Typescript, Python, and Rust. -- [Python example of BCS-encoded coin transfers](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/client.py#L240). -- [Typescript example of BCS-encoded coin transfers](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.test.ts#L122). -- [CLI-based transaction publishing](../cli-tools/aptos-cli-tool/use-aptos-cli#publishing-a-move-package-with-a-named-address). -- [Publish your first Move module](../tutorials/first-move-module) via Typescript, Python, and Rust. - -## Transaction states - -A transaction may end in one of the following states: - -* Committed on the blockchain and executed. This is considered as a successful transaction. -* Committed on the blockchain and aborted. The abort code indicates why the transaction failed to execute. -* Discarded during transaction submission due to a validation check such as insufficient gas, invalid transaction format, or incorrect key. -* Discarded after transaction submission but before attempted execution. This could be caused by timeouts or insufficient gas due to other transactions affecting the account. - -The sender’s account will be charged gas for any committed transactions. - -During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise. - -A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted. +:::note Transaction generation +The Aptos REST API supports generating BCS encoded transactions from JSON. This is useful for rapid prototyping, but be cautious using it in Mainnet as this places a lot of trust on the fullnode generating the transaction. +::: -The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream. +## States -On the Aptos devnet, the time between submission and confirmation is within seconds. +The Aptos blockchain's ledger state, or global state, represents the state of all accounts in the Aptos blockchain. Each validator node in the blockchain must know the latest version of the global state to execute any transaction. -:::tip Read more -See [Life of a Transaction](../guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle. -::: +Anyone can submit a transaction to the Aptos blockchain to modify the ledger state. Upon execution of a transaction, a transaction output is generated. A transaction output contains zero or more operations to manipulate the ledger state, called **write sets**: a vector of resulting events, the amount of gas consumed, and the executed transaction status. -## Proofs +### Proofs The Aptos blockchain uses proof to verify the authenticity and correctness of the blockchain data. @@ -106,25 +98,23 @@ All operations executed by the blockchain and all account states can be verified - The validator nodes agree on the state. - The client does not need to trust the entity from which it is receiving data. For example, if a client fetches the last **n** transactions from an account, a proof can attest that no transactions were added, omitted or modified in the response. The client may also query for the state of an account, ask whether a specific transaction was processed, and so on. -## Ledger state - -The Aptos blockchain's ledger state, or global state, represents the state of all accounts in the Aptos blockchain. -Each validator node in the blockchain must know the latest version of the global state to execute any transaction. +### Versioned database -Anyone can submit a transaction to the Aptos blockchain to modify the ledger state. Upon execution of a transaction, -a transaction output is generated. A transaction output contains zero or more operations to manipulate the ledger state, -called **write sets**: a vector of resulting events, the amount of gas consumed, and the executed transaction status. - -## Versioned database - -The ledger state is versioned using an unsigned 64-bit integer corresponding to the number of transactions the system has executed. -This versioned database allows the validator nodes to: +The ledger state is versioned using an unsigned 64-bit integer corresponding to the number of transactions the system has executed. This versioned database allows the validator nodes to: - Execute a transaction against the ledger state at the latest version. - Respond to client queries about ledger history at both current and previous versions. ## Transactions change ledger state + + The above figure shows how executing transaction T*i* changes the state of the Aptos blockchain from S*i-1* to S*i*. In the figure: @@ -134,33 +124,3 @@ In the figure: - **T*i*** : This is the *i*-th transaction executed on the blockchain. In this example, it represents Alice sending 10 APT to Bob. - **Apply()**: This is a deterministic function that always returns the same final state for a specific initial state and a specific transaction. If the current state of the blockchain is **S*i-1***, and transaction **T*i*** is executed on the state **S*i-1***, then the new state of the blockchain is always **S*i***. The Aptos blockchain uses the [Move language](https://move-language.github.io/move/) to implement the deterministic execution function **Apply()**. - **S*i*** : This is the *i*-the state of the blockchain. When the transaction **T*i*** is applied to the blockchain, it generates the new state **S*i*** (an outcome of applying **Apply(S*i-1*, T*i*)** to **S*i-1*** and **T*i***). This causes Alice’s account balance to be reduced by 10 to 100 APT and Bob’s account balance to be increased by 10 to 62 APT. The new state **S*i*** shows these updated balances. - -## Transactions - -When a client submits a transaction to the Aptos blockchain, then, if the transaction is successful the ledger state is updated. - -A [signed transaction](../guides/sign-a-transaction.md) on the blockchain contains the following information: - -- **Signature**: The sender uses a digital signature to verify that they signed the transaction (i.e., authentication). -- **Sender address**: The sender's [account address](./accounts#account-address). -- **Sender public key**: The public authentication key that corresponds to the private authentication key used to sign the transaction. -- **Program**: The program comprises: - - A Move module and function name or a move bytecode transaction script. - - An optional list of inputs to the script. For a peer-to-peer transaction, these inputs contain the recipient's information and the amount transferred to them. - - An optional list of Move bytecode modules to publish. -- **Gas price** (in specified gas units): This is the amount the sender is willing to pay per unit of [gas](./gas-txn-fee.md) to execute the transaction. [Gas](./gas-txn-fee.md) is a way to pay for computation and storage. A gas unit is an abstract measurement of computation with no inherent real-world value. -- **Maximum gas amount**: The [maximum gas amount](./gas-txn-fee#gas-and-transaction-fee-on-the-aptos-blockchain) is the maximum gas units the transaction is allowed to consume. -- **Sequence number**: This is an unsigned integer that must be equal to the sender's account [sequence number](./accounts#account-sequence-number) at the time of execution. -- **Expiration time**: A timestamp after which the transaction ceases to be valid (i.e., expires). - -## Proofs - -The Aptos blockchain uses proof to verify the authenticity and correctness of the blockchain data. - -All data in the Aptos blockchain is stored in a single-version distributed database. Each validator and fullnode's [storage](./validator-nodes#storage) is responsible for persisting the agreed upon blocks of transactions and their execution results to the database. - -The blockchain is represented as an ever-growing [Merkle tree](../reference/glossary#merkle-trees), where each leaf appended to the tree represents a single transaction executed by the blockchain. - -All operations executed by the blockchain and all account states can be verified cryptographically. These cryptographic proofs ensure that: -- The validator nodes agree on the state. -- The client does not need to trust the entity from which it is receiving data. For example, if a client fetches the last **n** transactions from an account, a proof can attest that no transactions were added, omitted or modified in the response. The client may also query for the state of an account, ask whether a specific transaction was processed, and so on. From 9fc9fe5984f28d74e913389b92bbf13febae7cc9 Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sat, 3 Dec 2022 21:21:42 -0800 Subject: [PATCH 04/12] [docs] gas * Mosty good newlines, yay * The text was a little repititious here and there, so I streamlined it a bit * Added in additional context about simulation * Information about prioritization buckets --- .../docs/concepts/gas-txn-fee.md | 32 ++++++++----------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/developer-docs-site/docs/concepts/gas-txn-fee.md b/developer-docs-site/docs/concepts/gas-txn-fee.md index bd2a19c4b89f8..9535d83209c4a 100755 --- a/developer-docs-site/docs/concepts/gas-txn-fee.md +++ b/developer-docs-site/docs/concepts/gas-txn-fee.md @@ -5,8 +5,6 @@ slug: "gas-txn-fee" # Gas and Transaction Fees -## Concept - To conduct any transaction with the Aptos blockchain on the mainnet, you are required to pay a processing fee. This fee is derived from transactions with a client application, stake owner, node operator, or voter. The processing fee you are required to pay is based on the computing and storage resources you use on the blockchain to: 1. Process your transactions on the blockchain. @@ -17,32 +15,26 @@ To conduct any transaction with the Aptos blockchain on the mainnet, you are req Conceptually, this fee can be thought of as quite similar to how we pay for our home electric or water utilities. ::: -### Prioritizing your transaction - -You can even bump up your transaction to a higher priority level on the blockchain by paying a larger processing fee. In your transaction, you can commit to paying a gas price that is higher than the market gas price. This is one way you can move your transaction higher in the priority list and have it processed more quickly. - -### Unit of gas +## Unit of gas -You can make a simple and inexpensive transaction or a complicated transaction that requires the blockchain to perform much computation and distributed storage. In either case, you will be required to spend a processing fee sufficient to complete the transaction. This is where the notion of **gas** becomes clear. Here is how it works: - -In the Aptos blockchain a **unit of gas** represents a basic unit of resource consumption. A single unit of gas is a combined representation of: +Transactions can range from simple and inexpensive to complicated based upon the amount of computation and fetches from and writes to storage. In the Aptos blockchain, a **unit of gas** represents a basic unit of resource consumption for both - Computation resource, and - Storage resource. -When your transaction is executed on the blockchain, instead of separately presenting you an account of each unit of the specific resource consumed, the blockchain simply presents an account of the number of units of gas being consumed by the transaction. - See [How Base Gas Works](./base-gas.md) for a detailed description of gas fee types and available optimizations. -### Gas price +## Gas price and prioritizing transactions In the Aptos network, the Aptos governance sets the minimum gas unit price. However, the market determines the actual minimum gas unit price. See [Ethereum Gas Tracker](https://etherscan.io/gastracker), for example, which shows the market price movements of Ethereum gas price. +By specifying a higher gas unit price than the current market price, you can **increase** the priority level for your transaction on the blockchain by paying. While in most cases, this is unnecessary, if the network is under load, this can ensure that your transaction can be processed more quickly. + :::tip Unit of gas 👉 A **unit of gas** is a dimensionless number, expressed as an integer. The total gas units consumed by your transaction depends on the complexity of your transaction. The **gas price**, on the other hand, is expressed in terms of Aptos blockchain’s native coin (Octas). Also see [Transactions and States](/concepts/txns-states) for how a transaction submitted to the Aptos blockchain looks like. ::: -## Gas and transaction fee on the Aptos blockchain +## Specifying gas fees within a transaction When a transaction is submitted to the Aptos blockchain, the transaction must contain the following mandatory gas fields: @@ -90,11 +82,9 @@ If, let's say, you transfer all the money out of your account so that you have n In a transaction, for example, transaction A, you are transferring 1000 coins from one account to another account. In a second transaction B, with the same gas field values of transaction A, you now transfer 100,000 coins from one account to another one account. Assuming that both the transactions A and B are sent roughly at the same time, then the gas costs for transactions A and B would be near-identical. -## Estimating the gas units - -The gas used for a transaction can be estimated by simulating the transaction. When simulating the transaction, the simulation results represent the **exact** amount that is needed at the **exact** state of the blockchain at the time of simulation. These gas units used may change based on the state of the chain. For this reason, any amount coming out of the simulation is only an estimate, and when setting the max gas amount, it should be increased above by an amount you’re comfortable with. +## Estimating the gas units via simulation -## Simulating the transaction to estimate the gas +The gas used for a transaction can be estimated by simulating the transaction. When simulating the transaction, the simulation results represent the **exact** amount that is needed at the **exact** state of the blockchain at the time of simulation. These gas units used may change based on the state of the chain. For this reason, any amount coming out of the simulation is only an estimate, and when setting the max gas amount, it should include an appropriate amount of headroom based upon your comfort-level and historical behaviors. Setting the max gas amount too low will result in the transaction aborting and the account being charged for whatever gas was consumed. Transactions can be simulated with the [`SimulateTransaction`](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/simulate_transaction) API. This API will run the exact transaction that you plan to run. @@ -118,4 +108,8 @@ The simulation steps for finding the correct amount of gas for a transaction are 5. At this point you now have your `gas_unit_price` and `max_gas_amount` to submit your transaction as follows: 1. `gas_unit_price` from the returned simulated transaction. 2. `max_gas_amount` as the minimum of the `gas_used` * `a safety factor` or the `max_gas_amount` from the transaction. -6. If you feel the need to prioritize or deprioritize your transaction, adjust the `gas_unit_price` of the transaction. Increase the value for higher priority, and decrease the value for lower priority. \ No newline at end of file +6. If you feel the need to prioritize or deprioritize your transaction, adjust the `gas_unit_price` of the transaction. Increase the value for higher priority, and decrease the value for lower priority. + +::: tip +Prioritization is based upon buckets of `gas_unit_price`. The buckets are defined [here](https://github.com/aptos-labs/aptos-core/blob/30b385bf38d3dc8c4e8ee0ff045bc5d0d2f67a85/config/src/config/mempool_config.rs#L8). The current buckets are `[0, 150, 300, 500, 1000, 3000, 5000, 10000, 100000, 1000000]`. Therefore a `gas_unit_price` of 150 and 299 would be priortized nearly the same. +::: From e4ea5545480aebd4069615e91ef0ccd0d4ec6c2a Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sat, 3 Dec 2022 21:52:43 -0800 Subject: [PATCH 05/12] [docs] blocks some tweaks -- I ninja landed a larger change due to some obviously questionable text --- developer-docs-site/docs/concepts/blocks.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/developer-docs-site/docs/concepts/blocks.md b/developer-docs-site/docs/concepts/blocks.md index 9b176de823fab..9b42a8706264e 100644 --- a/developer-docs-site/docs/concepts/blocks.md +++ b/developer-docs-site/docs/concepts/blocks.md @@ -7,9 +7,10 @@ id: "blocks" Aptos is a per-transaction versioned database. When transactions are executed, the resulting state of each transaction is stored separately and thus allows for more granular data access. This is different from other blockchains where only the resulting state of a block (a group of transactions) is stored. -However, blocks still exist on Aptos and offer a way to efficiently organize and execute transactions together. Blocks on Aptos can be thought of as *batches* of transactions. The exact number of transactions in a block varies depending on network activity and a configurable maximum block size limit. As the blockchain becomes busier and more optimized, the block size limit will increase, leading to a higher transaction throughput limit. +Blocks are still a fundamental unit within Aptos. Transactions are batched and executed together in a block. In addition, the [proofs](../concepts/txns-states/#proofs) within storage are at the block-level granularity. The number of transactions within a block varies depending on network activity and a configurable maximum block size limit. As the blockchain becomes busier, blocks will likely contain more transactions. ## System transactions + Each Aptos block contains both user transactions and special system transactions to *mark* the beginning and end of the transaction batch. Specifically, there are two system transactions: 1. `BlockMetadataTransaction` - is inserted at the beginning of the block. A `BlockMetadata` transaction can also mark the end of an [epoch](#epoch) and trigger reward distribution to validators. 2. `StateCheckpointTransaction` - is appended at the end of the block and is used as a checkpoint milestone. From cd12be563d909d13730e5e42a303bdf806043873 Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sat, 3 Dec 2022 22:03:09 -0800 Subject: [PATCH 06/12] [docs] life of txn This has morphed more into a deep dive of Aptos since it now contains two major sections. We might want to divide this into two sections. At any rate, I did some editing here to make it a bit more cohesive: * Merged assumptions into the beginning of the story * Renamed the lifecycle to journey since it was repititious with the title of the article / section * Moved client submits to after the overview of the story --- developer-docs-site/docs/concepts/index.md | 2 +- developer-docs-site/docs/concepts/staking.md | 2 +- .../docs/concepts/txns-states.md | 2 +- .../docs/guides/basics-life-of-txn.md | 62 +++++++++---------- .../docs/guides/system-integrators-guide.md | 2 +- 5 files changed, 34 insertions(+), 36 deletions(-) diff --git a/developer-docs-site/docs/concepts/index.md b/developer-docs-site/docs/concepts/index.md index ad99fecb965e2..e0047d271f06e 100644 --- a/developer-docs-site/docs/concepts/index.md +++ b/developer-docs-site/docs/concepts/index.md @@ -15,6 +15,6 @@ Start here to get into the core concepts of the Aptos blockchain. - ### [Transactions and States](./txns-states.md) - ### [Gas and Transaction Fees](./gas-txn-fee.md) - ### [Blocks](./blocks.md) -- ### [Life of a Transaction](../guides/basics-life-of-txn.md) +- ### [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn.md) - ### [Staking](./staking) - ### [Governance](./governance) diff --git a/developer-docs-site/docs/concepts/staking.md b/developer-docs-site/docs/concepts/staking.md index 35341410629ee..246faa81fc3ae 100644 --- a/developer-docs-site/docs/concepts/staking.md +++ b/developer-docs-site/docs/concepts/staking.md @@ -8,7 +8,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; # Staking :::tip Consensus -We strongly recommend that you read the consensus section of the [Life of a Transaction](../guides/basics-life-of-txn#consensus) before proceeding further. +We strongly recommend that you read the consensus section of [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn#consensus) before proceeding further. ::: In a distributed system like blockchain, executing a transaction is distinct from updating the state of the ledger and persisting the results in storage. An agreement, i.e., consensus, must be reached by a quorum of validators on the ordering of transactions and their execution results before the results are persisted in storage and the state of the ledger is updated. diff --git a/developer-docs-site/docs/concepts/txns-states.md b/developer-docs-site/docs/concepts/txns-states.md index 02ca9ced8806d..504d3d83cd305 100755 --- a/developer-docs-site/docs/concepts/txns-states.md +++ b/developer-docs-site/docs/concepts/txns-states.md @@ -39,7 +39,7 @@ A transaction that is successfully submitted but ultimately discarded may have n The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream. :::tip Read more -See [Life of a Transaction](../guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle. +See [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle. ::: ### Contents of a Transaction diff --git a/developer-docs-site/docs/guides/basics-life-of-txn.md b/developer-docs-site/docs/guides/basics-life-of-txn.md index 9392c53f7eb18..31afa223a8151 100755 --- a/developer-docs-site/docs/guides/basics-life-of-txn.md +++ b/developer-docs-site/docs/guides/basics-life-of-txn.md @@ -1,18 +1,16 @@ --- -title: "Life of a Transaction" +title: "Aptos Blockchain Deep Dive" slug: "basics-life-of-txn" --- import ThemedImage from '@theme/ThemedImage'; import useBaseUrl from '@docusaurus/useBaseUrl'; -# Life of a Transaction +# Aptos Blockchain Deep Dive For a deeper understanding of the lifecycle of an Aptos transaction (from an operational perspective), we will follow a transaction on its journey, from being submitted to an Aptos fullnode, to being committed to the Aptos blockchain. We will then focus on the logical components of Aptos nodes and take a look how the transaction interacts with these components. -## Assumptions - -For the purpose of this doc, we will assume that: +## Life of a Transaction * Alice and Bob are two users who each have an [account](/reference/glossary#account) on the Aptos blockchain. * Alice's account has 110 Aptos Coins. @@ -22,27 +20,7 @@ For the purpose of this doc, we will assume that: * An Aptos client submits Alice's transaction to a REST service on an Aptos Fullnode. The fullnode forwards this transaction to a validator fullnode which in turn forwards it to validator V1. * Validator V1 is a proposer/leader for the current round. -## Client submits a transaction - -An Aptos **client constructs a raw transaction** (let's call it Traw5) to transfer 10 Aptos Coins from Alice’s account to Bob’s account. The Aptos client signs the transaction with Alice's private key. The signed transaction T5 includes the following: - -* The raw transaction. -* Alice's public key. -* Alice's signature. - -The raw transaction includes the following fields: - -| Fields | Description | -| ------ | ----------- | -| [Account address](/reference/glossary#account-address) | Alice's account address | -| Move module | A module (or program) that indicates the actions to be performed on Alice's behalf. In this case, it contains:
- A Move bytecode peer-to-peer [transaction script](/reference/glossary#transaction-script)
- A list of inputs to the script (for this example the list would contain Bob's account address and the payment amount in Aptos Coins). | -| [Maximum gas amount](/reference/glossary#maximum-gas-amount) | The maximum gas amount Alice is willing to pay for this transaction. Gas is a way to pay for computation and storage. A gas unit is an abstract measurement of computation. | -| [Gas price](/reference/glossary#gas-price) | The amount (in Aptos Coins) Alice is willing to pay per unit of gas, to execute the transaction. | -| [Expiration time](/reference/glossary#expiration-time) | Expiration time of the transaction. | -| [Sequence number](/reference/glossary#sequence-number) | The sequence number (5, in this example) for an account indicates the number of transactions that have been submitted and committed on-chain from that account. In this case, 5 transactions have been submitted from Alice’s account, including Traw5. Note: a transaction with sequence number 5 can only be committed on-chain if the account sequence number is 5. | -| [Chain ID](https://github.com/aptos-labs/aptos-core/blob/main/types/src/chain_id.rs) | An identifier that distinguishes the Aptos network deployments (to prevent cross-network attacks). | - -## Lifecycle of the transaction +### The Journey In this section, we will describe the lifecycle of transaction T5, from when the client submits it to when it is committed to the Aptos blockchain. @@ -72,7 +50,27 @@ The lifecycle of a transaction has five stages: We've described what happens in each stage below, along with links to the corresponding Aptos node component interactions. -## Accepting the transaction +### Client submits a transaction + +An Aptos **client constructs a raw transaction** (let's call it Traw5) to transfer 10 Aptos Coins from Alice’s account to Bob’s account. The Aptos client signs the transaction with Alice's private key. The signed transaction T5 includes the following: + +* The raw transaction. +* Alice's public key. +* Alice's signature. + +The raw transaction includes the following fields: + +| Fields | Description | +| ------ | ----------- | +| [Account address](/reference/glossary#account-address) | Alice's account address | +| Move module | A module (or program) that indicates the actions to be performed on Alice's behalf. In this case, it contains:
- A Move bytecode peer-to-peer [transaction script](/reference/glossary#transaction-script)
- A list of inputs to the script (for this example the list would contain Bob's account address and the payment amount in Aptos Coins). | +| [Maximum gas amount](/reference/glossary#maximum-gas-amount) | The maximum gas amount Alice is willing to pay for this transaction. Gas is a way to pay for computation and storage. A gas unit is an abstract measurement of computation. | +| [Gas price](/reference/glossary#gas-price) | The amount (in Aptos Coins) Alice is willing to pay per unit of gas, to execute the transaction. | +| [Expiration time](/reference/glossary#expiration-time) | Expiration time of the transaction. | +| [Sequence number](/reference/glossary#sequence-number) | The sequence number (5, in this example) for an account indicates the number of transactions that have been submitted and committed on-chain from that account. In this case, 5 transactions have been submitted from Alice’s account, including Traw5. Note: a transaction with sequence number 5 can only be committed on-chain if the account sequence number is 5. | +| [Chain ID](https://github.com/aptos-labs/aptos-core/blob/main/types/src/chain_id.rs) | An identifier that distinguishes the Aptos network deployments (to prevent cross-network attacks). | + +### Accepting the transaction | Description | Aptos Node Component Interactions | | ------------------------------------------------------------ | ---------------------------------------------------------- | @@ -81,21 +79,21 @@ We've described what happens in each stage below, along with links to the corres | 3. **Mempool → Virtual Machine (VM)**: Mempool will use the virtual machine (VM) component to perform transaction validation, such as signature verification, account balance verification and replay resistance using the sequence number. | [4. Mempool](#4-mempool--vm), [3. Virtual Machine](#3-mempool--virtual-machine) | -## Sharing the transaction with other validator nodes +### Sharing the transaction with other validator nodes | Description | Aptos Node Component Interactions | | ------------------------------------------------------------ | -------------------------------- | | 4. **Mempool**: The mempool will hold T5 in an in-memory buffer. Mempool may already contain multiple transactions sent from Alice's address. | [Mempool](#mempool) | | 5. **Mempool → Other Validators**: Using the shared-mempool protocol, V1 will share the transactions (including T5) in its mempool with other validator nodes and place transactions received from them into its own (V1) mempool. | [2. Mempool](#2-mempool--other-validator-nodes) | -## Proposing the block +### Proposing the block | Description | Aptos Node Component Interactions | | ------------------------------------------------------------ | ---------------------------------------- | | 6. **Consensus → Mempool**: — As validator V1 is a proposer/leader for this transaction, it will pull a block of transactions from its mempool and replicate this block as a proposal to other validator nodes via its consensus component. | [1. Consensus](#1-consensus--mempool), [3. Mempool](#3-consensus--mempool) | | 7. **Consensus → Other Validators**: The consensus component of V1 is responsible for coordinating agreement among all validators on the order of transactions in the proposed block. | [2. Consensus](#2-consensus--other-validators) | -## Executing the block and reaching consensus +### Executing the block and reaching consensus | Description | Aptos Node Component Interactions | | ------------------------------------------------------------ | ------------------------------------------------ | @@ -104,7 +102,7 @@ We've described what happens in each stage below, along with links to the corres | 10. **Consensus → Execution**: After executing the transactions in the block, the execution component appends the transactions in the block (including T5) to the [Merkle accumulator](/reference/glossary#merkle-accumulator) (of the ledger history). This is an in-memory/temporary version of the Merkle accumulator. The necessary part of the proposed/speculative result of executing these transactions is returned to the consensus component to agree on. The arrow from "consensus" to "execution" indicates that the request to execute transactions was made by the consensus component. | [3. Consensus](#3-consensus--execution-consensus--other-validators), [1. Execution](#1-consensus--execution) | | 11. **Consensus → Other Validators**: V1 (the consensus leader) attempts to reach consensus on the proposed block's execution result with the other validator nodes participating in consensus. | [3. Consensus](#3-consensus--execution-consensus--other-validators) | -## Committing the block +### Committing the block | Description | Aptos Node Component Interactions | | ------------------------------------------------------------ | ------------------------------------------------------------ | @@ -114,7 +112,7 @@ Alice's account will now have 100 Aptos Coins, and its sequence number will be 6 ## Aptos node component interactions -In the [previous section](#lifecycle-of-the-transaction), we described the typical lifecycle of a transaction (from transaction submission to transaction commit). Now let's look at the inter-component interactions of Aptos nodes as the blockchain processes transactions and responds to queries. This information will be most useful to those who: +In the [previous section](#life-of-a-transaction), we described the typical lifecycle of a transaction (from transaction submission to transaction commit). Now let's look at the inter-component interactions of Aptos nodes as the blockchain processes transactions and responds to queries. This information will be most useful to those who: * Would like to get an idea of how the system works under the covers. * Are interested in eventually contributing to the Aptos blockchain. diff --git a/developer-docs-site/docs/guides/system-integrators-guide.md b/developer-docs-site/docs/guides/system-integrators-guide.md index 1628bc727b6ca..ef039aadbd51d 100644 --- a/developer-docs-site/docs/guides/system-integrators-guide.md +++ b/developer-docs-site/docs/guides/system-integrators-guide.md @@ -123,7 +123,7 @@ The submitter can try to increase the gas cost by a trivial amount to help make On the Aptos devnet, the time between submission and confirmation is within seconds. :::tip Read more -See [Life of a Transaction](/guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle. +See [Aptos Blockchain Deep Dive](/guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle. ::: ### Constructing a transaction From 51df194aec715c87b6713eefec7e7156f0060fa3 Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sat, 3 Dec 2022 22:28:27 -0800 Subject: [PATCH 07/12] [docs] minor tweaks to staking --- developer-docs-site/docs/concepts/staking.md | 58 +++++++++----------- 1 file changed, 27 insertions(+), 31 deletions(-) diff --git a/developer-docs-site/docs/concepts/staking.md b/developer-docs-site/docs/concepts/staking.md index 246faa81fc3ae..858829a2a9b10 100644 --- a/developer-docs-site/docs/concepts/staking.md +++ b/developer-docs-site/docs/concepts/staking.md @@ -11,14 +11,15 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; We strongly recommend that you read the consensus section of [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn#consensus) before proceeding further. ::: -In a distributed system like blockchain, executing a transaction is distinct from updating the state of the ledger and persisting the results in storage. An agreement, i.e., consensus, must be reached by a quorum of validators on the ordering of transactions and their execution results before the results are persisted in storage and the state of the ledger is updated. +In a distributed system like blockchain, executing a transaction is distinct from updating the state of the ledger and persisting the results in storage. An agreement, i.e., consensus, must be reached by a quorum of validators on the ordering of transactions and their execution results before these results are persisted in storage and the state of the ledger is updated. -A validator can participate in the consensus process. However, the validator can acquire the voting power only when they stake, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is made proportionate to the amount of validator's stake. In exchange, the validator is rewarded in proportion to the amount of validator's stake. Hence, the performance of the network, i.e., consensus, is aligned with the validator's interest, i.e., rewards. +Anyone can participate in the Aptos consensus process, if they stake sufficient utility coin, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is proportional to the amount of validator's stake. In exchange, the validator is rewarded proportionally to the amount staked. Hence, the performance of the Blockchain is aligned with the validator's interest, i.e., rewards. -Note that currently no slashing is implemented. See the data currently on-chain at: -https://mainnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::staking_config::StakingConfig +:::note +Currently slashing is not implemented. +::: -With the configuration set in [staking_config.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move). +The current on-chain data can be found [here](https://mainnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::staking_config::StakingConfig). With the configuration set defined in [staking_config.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move). The rest of this document presents how staking works on the Aptos blockchain. See [Supporting documentation](#supporting-documentation) at the bottom for related resources. @@ -36,8 +37,6 @@ Below is a summary flow diagram of how staking on the Aptos blockchain works. Th /> ---> -### How a custodian can stake on Aptos - The Aptos staking module defines a capability that represents ownership. :::tip Ownership @@ -49,6 +48,7 @@ The `OwnerCapability` resource can be used to control the stake pool. Three pers - Operator - Voter + Using this owner-operator-voter model, a custodian can assume the owner persona and stake on the Aptos blockchain and participate in the Aptos governance. This model allows delegations and staking services to be built as it separates the account that is control of the funds from the other accounts (operator, voter), hence allows secure delegations of responsibilities. This section describes how this works, using Bob and Alice in the example. @@ -86,13 +86,12 @@ This document describes staking. See [Governance](./governance.md) for how to pa ## Validation on the Aptos blockchain -The following is a high-level description of how validation works on the Aptos blockchain: +Throughout the duration of an epoch, the following flow of events occurs several times (thousands of times): -- Throughout the duration of an epoch, the following flow of events occurs several times (thousands of times): - - A validator leader is selected by a deterministic formula based on the validator reputation determined by validator's performance (including whether the validator has voted in the past or not) and stake. **This leader selection is not done by voting.** - - The selected leader sends a proposal containing the collected quorum votes of the previous proposal and the leader's proposed order of transactions for the new block. - - All the validators from the validator set will vote on the leader's proposal for the new block. Once consensus is reached the block can be finalized. Hence the actual list of votes to achieve consensus is a subset of all the validators in the validator set. This leader validator is rewarded. **Rewards are given only to the leader validators, not to the voter validators.** - - The above flow repeats with the selection of another validator leader and repeating the steps for the next new block. Rewards are given at the end of the epoch. +- A validator leader is selected by a deterministic formula based on the validator reputation determined by validator's performance (including whether the validator has voted in the past or not) and stake. **This leader selection is not done by voting.** +- The selected leader sends a proposal containing the collected quorum votes of the previous proposal and the leader's proposed order of transactions for the new block. +- All the validators from the validator set will vote on the leader's proposal for the new block. Once consensus is reached the block can be finalized. Hence the actual list of votes to achieve consensus is a subset of all the validators in the validator set. This leader validator is rewarded. **Rewards are given only to the leader validators, not to the voter validators.** +- The above flow repeats with the selection of another validator leader and repeating the steps for the next new block. Rewards are given at the end of the epoch. ## Validator state and stake state @@ -111,15 +110,7 @@ States are defined for a validator and the stake. These stake states are applicable for the existing validators in the validator set adding or removing their stake. -### Validator state - -See the validator states in the below diagram. - -### Validator state edge cases - -There are two edge cases to call out: -1. A validator can be moved from active state directly to the inactive state during an epoch change if their stake drops below the required minimum. This happens during an epoch change. -2. Aptos governance can also directly remove validators from the active set. **Note that governance proposals will always trigger an epoch change.** +### Validator states - -The below ruleset is applicable during the changes of a state: - -### Ruleset - -- Voting power can only change (increase or decrease) on epoch boundary. -- A validator’s consensus key and the validator and validator fullnode network addresses can only change on epoch boundary. -- Pending inactive stake cannot be moved into inactive (and thus withdrawable) until before lockup expires. -- No validators in the active validator set can have their stake below the minimum required stake. +There are two edge cases to call out: +1. A validator can be moved from active state directly to the inactive state during an epoch change if their stake drops below the required minimum. This happens during an epoch change. +2. Aptos governance can also directly remove validators from the active set. **Note that governance proposals will always trigger an epoch change.** ### Stake state +The state of stake has more granularity than that of the validator, additional stake can be added and a portion of stake removed from an active validator. + +### Validator Ruleset + +The below ruleset is applicable during the changes of state: + +- Voting power can only change (increase or decrease) on epoch boundary. +- A validator’s consensus key and the validator and validator fullnode network addresses can only change on epoch boundary. +- Pending inactive stake cannot be moved into inactive (and thus withdrawable) until before lockup expires. +- No validators in the active validator set can have their stake below the minimum required stake. + ## Validator flow :::tip Staking pool operations From d705e3cfbc83d48fe747d95b555bc03b4ca4e54c Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sat, 3 Dec 2022 22:43:10 -0800 Subject: [PATCH 08/12] [docs] governance cleanups --- .../docs/concepts/governance.md | 23 +++++++------------ 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/developer-docs-site/docs/concepts/governance.md b/developer-docs-site/docs/concepts/governance.md index d517dd8013e32..83e18b350b04d 100644 --- a/developer-docs-site/docs/concepts/governance.md +++ b/developer-docs-site/docs/concepts/governance.md @@ -12,7 +12,7 @@ The Aptos on-chain governance is a process by which the Aptos community members - Changes to the blockchain parameters, for example, the epoch duration, and the minimum required and maximum allowed validator stake. - Changes to the core blockchain code. - Upgrades to the Aptos Framework modules for fixing bugs or for adding or enhancing the Aptos blockchain functionality. -- Deploying new framework modules (at the address 0x1). +- Deploying new framework modules (at the address `0x1` - `0xa`). ## How a proposal becomes ready to be resolved @@ -26,12 +26,10 @@ sources={{ }} /> -- The Aptos community can suggest an Aptos Improvement Proposal (AIP) in community forums, channels and discuss them off-chain. -- When an off-chain AIP acquires sufficient importance, then an on-chain proposal can be created for the AIP via the `AptosGovernance` module. -- Voters can then vote on this proposal on-chain via the `AptosGovernance` module. When the voting period is over, the proposal can be resolved. -- The proposal contains an early expiration threshold that is set to 50% of the total supply of Aptos Coins. This allows for emergency bug fixes **without waiting for the full voting period**, assuming that the votes of the 50% of the total supply are cast quickly. - - If the number of YES votes exceed this threshold, the proposal is ready to be resolved. - - If the number of NO votes exceed this threshold, the proposal is considered failed. +- The Aptos community can suggest an Aptos Improvement Proposal (AIP) in [GitHub](https://github.com/aptos-foundation/aip). +- When appropriate, an on-chain proposal can be created for the AIP via the `AptosGovernance` module. +- Voters can then vote on this proposal on-chain via the `AptosGovernance` module. If there is sufficient support for a proposal, then it can be resolved. +- Governance requires a minimal number of votes to be cast by an expiration threshold. However, if sufficient votes, more than 50% of th total supply, are accumulated prior to that threshold, the proposal can be executed **without waiting for the full voting period**. ## Who can propose @@ -42,13 +40,8 @@ sources={{ ## Who can vote - To vote, you must stake, though you are not required to run a validator node. Your voting power is derived from the backing stake pool. - - :::tip - - Each stake pool can only be used to vote on each proposal exactly once. - ::: - - Voting power is calculated based on the current epoch's active stake of the proposer or voter's backing stake pool. In addition, the stake pool's lockup must be at least as long as the proposal's duration. - - +:::tip +Each stake pool can only be used to vote on each proposal exactly once. +::: From fdc2a7c081399bc715858ebc4a7f96d96c7cbc8e Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sun, 4 Dec 2022 18:33:04 -0800 Subject: [PATCH 09/12] [docs] nodes -- remove the note around what not to do I'm sure there was a reason for adding that at some point, but this belongs in an FAQ not at the end of a description about different networks --- developer-docs-site/docs/nodes/aptos-deployments.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/developer-docs-site/docs/nodes/aptos-deployments.md b/developer-docs-site/docs/nodes/aptos-deployments.md index c39a97294a449..deaa433c5a8a4 100755 --- a/developer-docs-site/docs/nodes/aptos-deployments.md +++ b/developer-docs-site/docs/nodes/aptos-deployments.md @@ -8,12 +8,6 @@ hide_table_of_contents: true You can connect to the Aptos blockchain in a few ways. See the below table: -:::tip What not to do - -Make sure to see the row describing [**What not to do**](#what-not-to-do). - -::: - |Description | Mainnet | Devnet | Long-lived Testnet | Aptos Incentivized Testnet (AIT)| |---|---|---|---|---| |
**Chain ID**
| 1 |[On Aptos Explorer **select Devnet from top right**](https://explorer.aptoslabs.com/?network=Devnet).| 2| Available during AIT program.| @@ -30,5 +24,3 @@ Make sure to see the row describing [**What not to do**](#what-not-to-do). |**Network status**| Always live. |Mostly live, with brief interruptions during regular updates. |Mostly live, with brief interruptions during regular updates. | Live only during Incentivized Testnet drives. | |**Type of nodes** |Validators and validator fullnodes. |Validators and public fullnodes. | Validators and public fullnodes. | Validators and validator fullnodes.| |**How to run a node**| See [Validators](/nodes/validator-node/validators) and [Public Fullnode](/nodes/full-node/public-fullnode) sections. |N/A, run by Aptos Labs team. |See [Validators](/nodes/validator-node/validators) and [Public Fullnode](/nodes/full-node/public-fullnode) sections. | See the node deployment guides published during AIT program.| -|**What not to do**||Do not attempt to sync your local AIT fullnode or AIT validator node with devnet. | |Make sure you deploy your local AIT fullnode, AIT validator node and AIT validator fullnode in the test mode, and follow the instructions in the node deployment guides published during AIT program.| - From 7770addc6a47464c92f4916f8e3690d707d805db Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sun, 4 Dec 2022 20:50:42 -0800 Subject: [PATCH 10/12] [docs] cleanup system-integrators-guide This leverage a lot of Kevin's work to move content around and make this more of an index for the first chunk of content. --- .../docs/guides/system-integrators-guide.md | 154 +++++++----------- 1 file changed, 62 insertions(+), 92 deletions(-) diff --git a/developer-docs-site/docs/guides/system-integrators-guide.md b/developer-docs-site/docs/guides/system-integrators-guide.md index ef039aadbd51d..3760f585097fb 100644 --- a/developer-docs-site/docs/guides/system-integrators-guide.md +++ b/developer-docs-site/docs/guides/system-integrators-guide.md @@ -3,6 +3,9 @@ title: "Integrate Aptos" slug: "system-integrators-guide" --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Integrate Aptos with Your Platform If you provide blockchain services to your customers and wish to add the Aptos blockchain to your platform, then this guide is for you. This system integrators guide will walk you through all you need to integrate the Aptos blockchain into your platform. @@ -19,119 +22,102 @@ This document will guide you through the following tasks to integrate with Aptos 1. Wait for the outcome of the transaction. 1. Query historical transactions and interactions for a given account with a specific account, i.e., withdraws and deposits. -## Networks +## Getting Started + +In order to get started you'll need to select a network and pick your set of tools. There are also a handful of SDKs to help accelerate development. + +### Choosing a network -There are three well-supported networks for integrating with the Aptos blockchain: +There are four well-supported networks for integrating with the Aptos blockchain: 1. Local testnet -- our standalone tool for local development against a known version of the codebase with no external network. 1. Devnet -- a shared resource for the community, data resets weekly, weekly update from aptos-core main branch. 1. Testnet -- a shared resource for the community, data will be preserved, network configuration will mimic Mainnet. +1. Mainnet -- a production network with real assets. See [Aptos Blockchain Deployments](../nodes/aptos-deployments.md) for full details on each environment. -### Local testnet +### Running a Local Testnet -There are two options to run a local testnet: +There are two options for running a local testnet: * Directly [run a local testnet](../nodes/local-testnet/run-a-local-testnet.md) using either the [Aptos-core source code](/nodes/local-testnet/run-a-local-testnet/#using-the-aptos-core-source-code) or a [Docker image](/nodes/local-testnet/run-a-local-testnet/#using-docker). These paths are useful for testing changes to the Aptos-core codebase or framework, or for building services on top of the Aptos blockchain, respectively. * [Install the Aptos CLI](/cli-tools/aptos-cli-tool/install-aptos-cli) and 2) start a [local node with a faucet](/nodes/local-testnet/using-cli-to-run-a-local-testnet#starting-a-local-testnet-with-a-faucet). This path is useful for developing on the Aptos blockchain, debugging Move contracts, and testing node operations. -Either of these methods will expose a REST API service at `http://127.0.0.1:8080/v1` and a Faucet service at `http://127.0.0.1:8000` for option 1 or `http://127.0.0.1:8081` for option 2. The applications will output the location of the services. - -### Aptos Devnet - -* Faucet service: https://faucet.devnet.aptoslabs.com -* REST API service: https://fullnode.devnet.aptoslabs.com/v1 - -### Access Testnet - -* Faucet service: https://faucet.testnet.aptoslabs.com -* REST API service: https://fullnode.testnet.aptoslabs.com/v1 - -### SDKs +Either of these methods will expose a REST API service at `http://127.0.0.1:8080` and a Faucet API service at `http://127.0.0.1:8000` for option 1 or `http://127.0.0.1:8081` for option 2. The applications will output the location of the services. + +### Production network access + + + + + + + + + + + + + +### SDKs and Tools Aptos currently provides three SDKs: 1. [Typescript](/sdks/ts-sdk/index) 2. [Python](/sdks/python-sdk) 3. [Rust](/sdks/rust-sdk) - -### Other tools - -* [Using the CLI](../cli-tools/aptos-cli-tool/use-aptos-cli) which includes creating accounts, transferring coins, and publishing modules -* [REST API spec](https://fullnode.devnet.aptoslabs.com/v1/spec#/) -* [Local testnet development flow](/guides/local-testnet-dev-flow) +Almost all developers will benefit from exploring the CLI. [Using the CLI](../cli-tools/aptos-cli-tool/use-aptos-cli) demonstrates how the CLI can be used to which includes creating accounts, transferring coins, and publishing modules. ## Accounts on Aptos -An [account](/concepts/accounts) represents a resource on the Aptos blockchain that can send transactions. Each account is identified by a particular 32-byte account address and is a container for Move modules and Move resources. On Aptos, accounts must be created on-chain prior to any blockchain operations involving that account. The Aptos framework supports implicitly creating accounts when transferring Aptos coin via [`aptos_account::transfer`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L18) or explicitly via [`aptos_account::create_account`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L13). +An [account](/concepts/accounts) represents an entity on the Aptos blockchain that can send transactions. Each account is identified by a particular 32-byte account address and is a container for [Move modules and resources](/concepts/resources). On Aptos, accounts must be created on-chain prior to any blockchain operations involving that account. The Aptos framework supports implicitly creating accounts when transferring Aptos coin via [`aptos_account::transfer`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L18) or explicitly via [`aptos_account::create_account`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L13). At creation, an [Aptos account](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/account.move#L23) contains: * A [resource containing Aptos Coin](https://github.com/aptos-labs/aptos-core/blob/60751b5ed44984178c7163933da3d1b18ad80388/aptos-move/framework/aptos-framework/sources/coin.move#L50) and deposit and withdrawal of coins from that resource. * An authentication key associated with their current public, private key(s). -* A strictly increasing sequence number that represents the account's next transaction's sequence number to prevent replay attacks. +* A strictly increasing [sequence number](/concepts/accounts#account-sequence-number) that represents the account's next transaction's sequence number to prevent replay attacks. * A strictly increasing number that represents the next distinct GUID creation number. -* An event stream for all new types of coins added to the account. -* An event stream for all key rotations for the account. - -### Account identifiers - -Currently, Aptos supports only a single, unified identifier for an account. Accounts on Aptos are universally represented as a 32-byte hex string. A hex string shorter than 32-bytes is also valid: in those scenarios, the hex string is padded with leading zeroes, e.g., `0x1` => `0x0000000000000...01`. +* An [event handle](/concepts/events) for all new types of coins added to the account. +* An event handle for all key rotations for the account. -### Creating an account address - -[Account addresses](../concepts/accounts.md#account-address) are defined at creation time as a one-way function from the public key(s) and signature algorithm used for authentication for the account. - -:::tip Read more -This is covered in depth in the [Accounts](../concepts/accounts.md) documentation and demonstrated in the [Typescript SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_account.ts#L66) and [Python SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/account_address.py#L43). Note that currently these SDKs demonstrate only how to generate an address from an Ed25519 single signer. -::: - -### Rotating the keys - -An Account on Aptos has the ability to rotate keys so that potentially compromised keys cannot be used to access the accounts. Keys can be rotated via the [`account::rotate_authentication_key`](https://github.com/aptos-labs/aptos-core/blob/60751b5ed44984178c7163933da3d1b18ad80388/aptos-move/framework/aptos-framework/sources/account.move#L183) function. - -Refreshing the keys is generally regarded as good hygiene in the security field. However, this presents a challenge for system integrators who are used to using a mnemonic to represent both a private key and its associated account. To simplify this for the system integrators, Aptos provides an on-chain mapping via `aptos account lookup-address`. The on-chain data maps an effective account address as defined by the current mnemonic to the actual account address. - -### Preventing replay attacks - -When the Aptos blockchain processes the transaction, it looks at the sequence number in the transaction and compares it with the sequence number in the sender’s account (as stored on the blockchain at the current ledger version). The transaction is executed only if the sequence number in the transaction is the same as the sequence number for the sender account, and the transaction is rejected if those two numbers do not match. In this way past transactions, which necessarily contain older sequence numbers, cannot be replayed, hence preventing replay attacks. - -:::tip Read more -See more on [Account sequence numbering](/concepts/accounts#account-sequence-number). -::: +Read more in [Accounts](/concepts/accounts). ## Transactions -Aptos [transactions](/concepts/txns-states) are encoded in [Binary Canonical Serialization (BCS)](https://github.com/diem/bcs). Transactions contain information such as the sender’s account address, authentication from the sender, the desired operation to be performed on the Aptos blockchain, and the amount of gas the sender is willing to pay to execute the transaction. - -### Transaction states - -A transaction may end in one of the following states: - -* Committed on the blockchain and executed. This is considered as a successful transaction. -* Committed on the blockchain and aborted. The abort code indicates why the transaction failed to execute. -* Discarded during transaction submission due to a validation check such as insufficient gas, invalid transaction format, or incorrect key. -* Discarded after transaction submission but before attempted execution. This could be caused by timeouts or insufficient gas due to other transactions affecting the account. - -The sender’s account will be charged gas for any committed transactions. - -During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise. +Aptos [transactions](/concepts/txns-states) are encoded in [Binary Canonical Serialization (BCS)](https://github.com/diem/bcs). Transactions contain information such as the sender’s account address, authentication from the sender, the desired operation to be performed on the Aptos blockchain, and the amount of gas the sender is willing to pay to execute the transaction. -A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted. +Read more in [Transactions and States](/concepts/txn-states). -The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream. +### Generating Transactions -On the Aptos devnet, the time between submission and confirmation is within seconds. +Aptos supports two methods for constructing transactions: -:::tip Read more -See [Aptos Blockchain Deep Dive](/guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle. -::: +- Using the Aptos client libraries to generate native bcs transactions. +- Constructing JSON-encoded objects and interacting with the REST API to generate native transactions. -### Constructing a transaction +The preferred approach is to directly generate native bcs transactions. Generating them via the REST API enables rapid development at the cost of trusting the fullnode to generate the transaction correctly. -Aptos supports two methods for constructing transactions: +#### BCS-encoded transactions -- Constructing JSON-encoded objects and interacting with the Web API to generate native transactions. -- Using the Aptos client libraries to generate native transactions. +BCS-encoded transactions can be submitted to the `/transactions` endpoint but must specify `Content-Type: application/x.aptos.signed_transaction+bcs` in the HTTP headers. This will return a transaction submission result that, if successful, contains a transaction hash in the `hash` [field](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/client.py#L138). #### JSON-encoded transactions @@ -143,10 +129,6 @@ JSON-encoded transactions can be generated via the [REST API](https://fullnode. JSON-encoded transactions allow for rapid development and support seamless ABI conversions of transaction arguments to native types. However, most system integrators prefer to generate transactions within their own tech stack. Both the [TypeScript SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.ts#L259) and [Python SDK](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L100) support generating BCS transactions. -#### BCS-encoded transactions - -BCS-encoded transactions can be submitted to the `/transactions` endpoint but must specify `Content-Type: application/x.aptos.signed_transaction+bcs` in the HTTP headers. This will return a transaction submission result that, if successful, contains a transaction hash in the `hash` [field](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/client.py#L138). - ### Types of transactions Within a given transaction, the target of execution can be one of two types: @@ -162,18 +144,6 @@ All operations on the Aptos blockchain should be available via entry point calls Currently there are no tutorials in this guide on script payloads, but the [Move book](https://move-language.github.io/move/modules-and-scripts.html?highlight=script#scripts) does go in some depth. ::: -:::tip Read more - -See the following documentation for generating valid transactions: - -- [JSON-encoded transactions](http://aptos.dev/tutorials/your-first-transaction) via Typescript, Python, and Rust. -- [Python example of BCS-encoded coin transfers](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/python/sdk/aptos_sdk/client.py#L240). -- [Typescript example of BCS-encoded coin transfers](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.test.ts#L122). -- [CLI-based transaction publishing](http://aptos.dev/cli-tools/aptos-cli-tool/use-aptos-cli#publishing-a-move-package-with-a-named-address). -- [Publish your first Move module](https://aptos.dev/tutorials/first-move-module) via Typescript, Python, and Rust. - -::: - ### Status of a transaction Obtain transaction status by querying the API [`/transactions/by_hash/{hash}`](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_transaction_by_hash) with the hash returned during the submission of the transaction. From 31d72dfab71bee9a0cd626353817ff6a70d77c93 Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sun, 4 Dec 2022 21:07:38 -0800 Subject: [PATCH 11/12] [docs] refine transactions in system integrators guide --- .../docs/guides/system-integrators-guide.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/developer-docs-site/docs/guides/system-integrators-guide.md b/developer-docs-site/docs/guides/system-integrators-guide.md index 3760f585097fb..19d60da8ff900 100644 --- a/developer-docs-site/docs/guides/system-integrators-guide.md +++ b/developer-docs-site/docs/guides/system-integrators-guide.md @@ -104,7 +104,7 @@ Read more in [Accounts](/concepts/accounts). Aptos [transactions](/concepts/txns-states) are encoded in [Binary Canonical Serialization (BCS)](https://github.com/diem/bcs). Transactions contain information such as the sender’s account address, authentication from the sender, the desired operation to be performed on the Aptos blockchain, and the amount of gas the sender is willing to pay to execute the transaction. -Read more in [Transactions and States](/concepts/txn-states). +Read more in [Transactions and States](/concepts/txns-states). ### Generating Transactions @@ -136,13 +136,9 @@ Within a given transaction, the target of execution can be one of two types: - An entry point (formerly known as script function) - A script (payload) -Currently the SDKs [Python](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L249) and [Typescript](https://github.com/aptos-labs/aptos-core/blob/76b654b54dcfc152de951a728cc1e3f9559d2729/ecosystem/typescript/sdk/src/aptos_client.test.ts#L98) support the generation of transactions that target entry points only. This guide points out many of those entry points, such as `coin::transfer` and `aptos_account::create_account`. +Both [Python](https://github.com/aptos-labs/aptos-core/blob/3973311dac6bb9348bfc81cf983c2a1be11f1b48/ecosystem/python/sdk/aptos_sdk/client.py#L256) and [Typescript](https://github.com/aptos-labs/aptos-core/blob/3973311dac6bb9348bfc81cf983c2a1be11f1b48/ecosystem/typescript/sdk/src/aptos_client.test.ts#L93) support the generation of transactions that target entry points. This guide points out many of those entry points, such as `aptos_account::transfer` and `aptos_account::create_account`. -All operations on the Aptos blockchain should be available via entry point calls. While one could submit multiple transactions calling entry points in series, many such operations may benefit from being called atomically from a single transaction. A script payload transaction can call any entry point or public function defined within any module. - -:::tip Move book -Currently there are no tutorials in this guide on script payloads, but the [Move book](https://move-language.github.io/move/modules-and-scripts.html?highlight=script#scripts) does go in some depth. -::: +Most basic operations on the Aptos blockchain should be available via entry point calls. While one could submit multiple transactions calling entry points in series, such operations benefit from being called atomically from a single transaction. A script payload transaction can call any public (entry) function defined within any module. Here's an example [Move script](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/scripts/two_by_two_transfer) that uses a MultiAgent transaction to extract funds from two accounts and deposit them into two other accounts. This is a [Python example](https://github.com/aptos-labs/aptos-core/blob/main/ecosystem/python/sdk/examples/transfer-two-by-two.py) that uses the bytecode generated by compiling that script. Currently there is limited support for script payloads in Typescript. ### Status of a transaction @@ -152,13 +148,11 @@ A reasonable strategy for submitting transactions is to limit their lifetime to ### Testing transactions or transaction pre-execution -To facilitate evaluation of transactions, Aptos supports a simulation API that does not require and should not contain valid signatures on transactions. +To facilitate evaluation of transactions as well as gas estimation, Aptos supports a simulation API that does not require and should not contain valid signatures on transactions. -The simulation API works identically to the transaction submission API, except that it executes the transaction and returns the results along with the gas used. The simulation API can be accessed by submitting a transaction to [`/transactions/simulate`](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/simulate_transaction). +The simulation API is a synchronous API that executes a transaction and returns the output inclusive of gas usage. The simulation API can be accessed by submitting a transaction to [`/transactions/simulate`](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/simulate_transaction). -:::tip Read more -Here's an [example showing how to use the simulation API in the Typescript SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.ts#L413). Note that the gas use may change based upon the state of the account. We recommend that the maximum gas amount be larger than the amount quoted by this API. -::: +Both the [Typescript SDK](https://github.com/aptos-labs/aptos-core/blob/9b85d41ed8ef4a61a9cd64f9de511654fcc02024/ecosystem/typescript/sdk/src/aptos_client.ts#L413) and [Python SDK](https://github.com/aptos-labs/aptos-core/blob/main/ecosystem/python/sdk/examples/simulate-transfer-coin.py) support the simulation API. Note the output and gas used may change based upon the state of the account. For gas estimations, we recommend that the maximum gas amount be larger than the amount quoted by this API. ## Viewing current and historical state From adc563e43d67a4bcd6a4e8345071336791c9586a Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Sun, 4 Dec 2022 21:12:53 -0800 Subject: [PATCH 12/12] [docs] slim down aptos-apis this is redundant content that likely belongs in a unified onboarding guide -- like the system-integrators-guide my concern with the aptos-apis is it is bloated and we need to think about breaking it down: Have 1 page per query type: * simple resources * transactions * events * tables In each, both the indexer and REST API. We at least need to figure that out before more editting... --- developer-docs-site/docs/guides/aptos-apis.md | 60 ++----------------- 1 file changed, 5 insertions(+), 55 deletions(-) diff --git a/developer-docs-site/docs/guides/aptos-apis.md b/developer-docs-site/docs/guides/aptos-apis.md index 47e4c122385c6..e88afc5bc3000 100644 --- a/developer-docs-site/docs/guides/aptos-apis.md +++ b/developer-docs-site/docs/guides/aptos-apis.md @@ -3,63 +3,13 @@ title: "Use Aptos API" slug: "aptos-api" --- -# Use the Aptos API with Your Platform +# Use the Aptos REST Read API -If you provide blockchain services to your customers and wish to add the Aptos blockchain to your platform, then this guide is for you. This system integrators guide will walk you through all you need to integrate the Aptos blockchain into your platform. +If you provide blockchain services to your customers and wish to add the Aptos blockchain to your platform, then this guide is for you. This guide will walk you through all you need to integrate the Aptos blockchain into your platform. -## Overview - -This document will guide you through the following tasks to integrate with Aptos: -1. Prepare an environment for testing. -1. Create an account on the blockchain. -1. Exchange account identifiers with another entity on the blockchain, for example, to perform swaps. -1. Create a transaction. -1. Obtain a gas estimate and validate the transaction for correctness. -1. Submit the transaction to the blockchain. -1. Wait for the outcome of the transaction. -1. Query historical transactions and interactions for a given account with a specific account, i.e., withdraws and deposits. - -## Networks - -There are three well-supported networks for integrating with the Aptos blockchain: - -1. Local testnet -- our standalone tool for local development against a known version of the codebase with no external network. -1. Devnet -- a shared resource for the community, data resets weekly, weekly update from aptos-core main branch. -1. Testnet -- a shared resource for the community, data will be preserved, network configuration will mimic Mainnet. - -See [Aptos Blockchain Deployments](../nodes/aptos-deployments.md) for full details on each environment. - -### Local testnet - -There are two options to run a local testnet: -* Directly [run a local testnet](../nodes/local-testnet/run-a-local-testnet.md) using either the [Aptos-core source code](/nodes/local-testnet/run-a-local-testnet/#using-the-aptos-core-source-code) or a [Docker image](/nodes/local-testnet/run-a-local-testnet/#using-docker). These paths are useful for testing changes to the Aptos-core codebase or framework, or for building services on top of the Aptos blockchain, respectively. -* [Install the Aptos CLI](/cli-tools/aptos-cli-tool/install-aptos-cli) and 2) start a [local node with a faucet](/nodes/local-testnet/using-cli-to-run-a-local-testnet#starting-a-local-testnet-with-a-faucet). This path is useful for developing on the Aptos blockchain, debugging Move contracts, and testing node operations. - -Either of these methods will expose a REST API service at `http://127.0.0.1:8080/v1` and a Faucet service at `http://127.0.0.1:8000` for option 1 or `http://127.0.0.1:8081` for option 2. The applications will output the location of the services. - -### Aptos Devnet - -* Faucet service: https://faucet.devnet.aptoslabs.com -* REST API service: https://fullnode.devnet.aptoslabs.com/v1 - -### Access Testnet - -* Faucet service: https://faucet.testnet.aptoslabs.com -* REST API service: https://fullnode.testnet.aptoslabs.com/v1 - -### SDKs - -Aptos currently provides three SDKs: -1. [Typescript](/sdks/ts-sdk/index) -2. [Python](/sdks/python-sdk) -3. [Rust](/sdks/rust-sdk) - - -### Other tools - -* [Using the CLI](../cli-tools/aptos-cli-tool/use-aptos-cli) which includes creating accounts, transferring coins, and publishing modules -* [REST API spec](https://fullnode.devnet.aptoslabs.com/v1/spec#/) -* [Local testnet development flow](/guides/local-testnet-dev-flow) +:::tip +Before starting in this guide, it might be beneficial to read the [System Integrators Guide](/guides/system-integrators-guide). +::: ## Viewing current and historical state