diff --git a/apps/nextra/pages/en/build/guides/_meta.tsx b/apps/nextra/pages/en/build/guides/_meta.tsx index 1c7d9f259..c00537122 100644 --- a/apps/nextra/pages/en/build/guides/_meta.tsx +++ b/apps/nextra/pages/en/build/guides/_meta.tsx @@ -37,6 +37,9 @@ export default { "sponsored-transactions": { title: "Sponsored Transactions", }, + "orderless-transactions": { + title: "Orderless Transactions", + }, "transaction-management": { title: "Transaction Management", }, diff --git a/apps/nextra/pages/en/build/guides/orderless-transactions.mdx b/apps/nextra/pages/en/build/guides/orderless-transactions.mdx new file mode 100644 index 000000000..9b3803c4a --- /dev/null +++ b/apps/nextra/pages/en/build/guides/orderless-transactions.mdx @@ -0,0 +1,36 @@ +# Orderless Transactions + +As outlined +in [AIP-123](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-123.md), +orderless transactions allow for transactions to be executed out of order, which +is particularly useful in scenarios where multiple machines need to sign for a +single sending account, but the order in which they sign does not affect the +outcome of the transaction or matter to the creator. Replay is protected by a +nonce, which is a unique identifier for a transaction. This allows for the +transaction to be executed at any time within the expiration time, regardless of +the order in which the machines sign the transaction, but not be able to be +replayed after the nonce has expired. The maximum expiration time is 60 seconds +for orderless transactions, which is not the same for sequence number +transactions. + +## Process Overview + +Orderless transactions are dependent on the transaction payload specified in +[AIP-129](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-129.md). +The process for building and executing an orderless transaction is as follows: + +1. Build a transaction with a `replayProtectionNonce` and a `TransactionPayload::TransactionPayloadPayload` that defines the operation to be executed. +2. Sign and submit the transaction as any other transaction, but with the +`replayProtectionNonce` set. Ideally, the nonce should be a random u64 value. + +Note, that the behavior of the `replayProtectionNonce` is similar to a sequence +number, but it does not guarantee ordered execution of transactions. Instead, it +ensures that the transaction is unique and cannot be replayed (executed twice) +with the same nonce. + +## SDK Support + +These are demonstrations of sponsored transactions: + +- The [TypeScript SDK](../sdks/ts-sdk/building-transactions/orderless-transactions.mdx) has documentation +- The [Go SDK](https://github.com/aptos-labs/aptos-go-sdk/tree/main/examples/orderless_transaction) has an example diff --git a/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions.mdx b/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions.mdx index 675330bdf..8c5daaa0c 100644 --- a/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions.mdx +++ b/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions.mdx @@ -200,8 +200,9 @@ Building and sending transactions on-chain involves the following 5 steps: Transactions have a couple of additional features which let them adapt to your needs which you can learn about here: -1. [Multi-Agent Signatures](building-transactions/multi-agent-transactions.mdx) - Allowing multiple accounts to be used for a single contract. -2. [Sponsoring Transactions](building-transactions/sponsoring-transactions.mdx) - Have another account pay gas fees for this transaction. -3. [Batch Submit Transactions](building-transactions/batching-transactions.mdx) - How to send multiple transactions quickly from a single account. -4. [Binary Canonical Serialization (BCS)](building-transactions/bcs-format.mdx) - The format used to serialize data for Aptos transactions. -5. [Composing multiple Move calls with ScriptComposer](building-transactions/script-composer.mdx) - (Experimental) Building more complex transaction payload that calls into multiple Move functions dynamically. +1. [Multi-Agent Transactions](building-transactions/multi-agent-transactions.mdx) - Allowing multiple accounts to interact with a single transaction. +2. [Orderless Transactions](building-transactions/orderless-transactions.mdx) - Allowing for transactions to be executed out of order for easier management. +3. [Sponsoring Transactions](building-transactions/sponsoring-transactions.mdx) - Have another account pay gas fees for this transaction. +4. [Batch Submit Transactions](building-transactions/batching-transactions.mdx) - How to send multiple transactions quickly from a single account. +5. [Binary Canonical Serialization (BCS)](building-transactions/bcs-format.mdx) - The format used to serialize data for Aptos transactions. +7. [Composing multiple Move calls with ScriptComposer](building-transactions/script-composer.mdx) - (Experimental) Building more complex transaction payload that calls into multiple Move functions dynamically. diff --git a/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions/_meta.tsx b/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions/_meta.tsx index 9f82fd6ab..dec829ace 100644 --- a/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions/_meta.tsx +++ b/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions/_meta.tsx @@ -5,6 +5,9 @@ export default { "multi-agent-transactions": { title: "Multi-Agent Transactions", }, + "orderless-transactions": { + title: "Orderless Transactions", + }, "sponsoring-transactions": { title: "Sponsoring Transactions", }, diff --git a/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions/orderless-transactions.mdx b/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions/orderless-transactions.mdx new file mode 100644 index 000000000..0853bee7e --- /dev/null +++ b/apps/nextra/pages/en/build/sdks/ts-sdk/building-transactions/orderless-transactions.mdx @@ -0,0 +1,95 @@ +--- +title: "Orderless Transactions" +--- + +import { Callout } from 'nextra/components' + +# Orderless Transactions + +Orderless transactions allow you to create transactions that do not specify a +order of execution between them. This is particularly useful +in scenarios where multiple machines need to sign a transaction, but the order +in which they sign does not affect the outcome of the transaction or matter to +the creator. + +## Building Orderless Transactions + +Creating and executing a multi-agent transaction follows a similar flow to the +[simple transaction flow](../building-transactions.mdx), and the +[multi-agent transaction flow](./multi-agent-transactions.mdx). + + + Instead of providing a `sequenceNumber` (or no sequence number at all), a + `Replay Protection Nonce` is used to ensure that the transaction is unique and + cannot be replayed (i.e., executed multiple times with the same nonce). + + +For example, to create a single signer transaction that uses orderless transactions, +specify the `nonce` in the `build.simple` method like so: + +```ts filename="build-a-transaction.ts" +const transaction = await aptos.transaction.build.simple({ + sender: sender.accountAddress, + data: { + // All transactions on Aptos are implemented via smart contracts. + function: "0x1::aptos_account::transfer", + functionArguments: [destination.accountAddress, 100], + }, + options: { + replayProtectionNonce: 12345, // This is the nonce that will be used to ensure the transaction is unique. + } +}); +``` + +Similarly, if you are building a multi-agent transaction, you can specify the +`replayProtectionNonce` in the `build.multiAgent` method: + +```ts filename="build-a-transaction.ts" +const transaction = await aptos.transaction.build.multiAgent({ + sender: sender.accountAddress, + secondarySignerAddresses: [bob.accountAddress], // List of secondary signers + data: { + // All transactions on Aptos are implemented via smart contracts. + function: "0x1::aptos_account::transfer", + functionArguments: [destination.accountAddress, 100], + }, + options: { + replayProtectionNonce: 12345, // This is the nonce that will be used to ensure the transaction is unique. + } +}); +``` + +And the same if you are building a sponsored transaction, you can specify the +`replayProtectionNonce` in the `build.multiAgent` method: +```ts filename="build-a-transaction.ts" +const transaction = await aptos.transaction.build.multiAgent({ + sender: sender.accountAddress, + withFeePayer: true, // This indicates that the transaction will be sponsored. + data: { + // All transactions on Aptos are implemented via smart contracts. + function: "0x1::aptos_account::transfer", + functionArguments: [destination.accountAddress, 100], + }, + options: { + replayProtectionNonce: 12345, // This is the nonce that will be used to ensure the transaction is unique. + } +}); +``` + + + For orderless transactions, the `replayProtectionNonce` must be unique for + each transaction. Additionally, the expiration time of the transaction is + maximum 60 seconds from the time it is submitted. If the transaction is not + executed within that time, it will be considered expired and will not be + executed. + + +After that, simply follow the same steps as you would for a simple transaction: +1. [**Simulate** the transaction (optional)](./simulating-transactions). +2. **Sign** the transaction. +3. **Submit** the transaction to the network. +4. **Wait** for the transaction to be executed. + +### Examples + +* [TS SDK Example](https://github.com/aptos-labs/aptos-ts-sdk/blob/main/examples/typescript/simple_orderless_transfer.ts)