Add batch-transfer example app (TypeScript + Go)

examples/README.md

@@ -0,0 +1,33 @@
+# Aptos SDK Examples
+
+Standalone sample applications that demonstrate Aptos SDK features across multiple languages. Each
+example is self-contained, runnable, and designed to be a starting point you can expand.
+
+## Examples
+
+| Example                             | Description                                | Languages      |
+| ----------------------------------- | ------------------------------------------ | -------------- |
+| [batch-transfer](./batch-transfer/) | Send N transactions in parallel with retry | TypeScript, Go |
+
+## Design Principles
+
+Each example:
+
+- **Runs end-to-end** against devnet (no mocks)
+- **Shows real patterns** (sequence number management, gas estimation, retry)
+- **Has configurable parameters** (transaction count, network)
+- **Produces structured output** (JSON summary for easy comparison across SDKs)
+
+## Adding a New Example
+
+1. Create `examples/<name>/` directory
+2. Add `examples/<name>/README.md` explaining the scenario
+3. Implement in each target language under `examples/<name>/<language>/`
+4. Each language directory must be runnable with a single command
+
+## Adding a New Language to an Existing Example
+
+1. Create `examples/<name>/<language>/`
+2. Follow the same 4-phase structure: Setup → Batch Submit → Track & Confirm → Verify & Report
+3. Use the same CLI flags (`--count`, `--network`) for consistency
+4. Output the same JSON summary schema for cross-SDK comparison

examples/batch-transfer/README.md

@@ -0,0 +1,110 @@
+# Batch Transfer Example
+
+Demonstrates sending **N APT transfers in parallel** using a single funded sender account.
+
+This example showcases:
+
+- Account generation and faucet funding
+- Gas price estimation
+- **Sequence number pre-fetching** — fetch once, increment locally (avoids N round-trips)
+- Building and signing all transactions **locally** before any network calls
+- Parallel submission via goroutines / Promise.allSettled
+- Retry with exponential backoff on confirmation
+- Structured JSON output for cross-SDK comparison
+
+## The Core Pattern: Sequence Number Management
+
+The naive approach to batch transactions fetches the account's sequence number _per transaction_:
+
+```
+for each tx:
+  fetch seq_num from chain  ← N network round-trips!
+  build tx with seq_num
+  submit
+```
+
+This example uses the efficient approach:
+
+```
+fetch seq_num from chain once
+for each tx (local, no network):
+  build tx with (seq_num + i)
+  sign tx
+submit all in parallel
+```
+
+This reduces N round-trips to 1 and enables true parallel submission.
+
+## Implementations
+
+| Language   | Directory                    | Command           |
+| ---------- | ---------------------------- | ----------------- |
+| TypeScript | [typescript/](./typescript/) | `bun src/main.ts` |
+| Go         | [go/](./go/)                 | `go run main.go`  |
+
+## Expected Output
+
+```
+Aptos Batch Transfer Example (TypeScript)
+==========================================
+Network:      devnet
+Transactions: 10
+
+[1/4] Setup
+  ✓ Generated sender:  0x3f2a...
+  ✓ Generated 10 recipient accounts
+  ✓ Funded sender with 1 APT (tx: 0xabc...)
+  ✓ Sender balance: 100,000,000 octas
+
+[2/4] Batch Submission (10 transactions)
+  ✓ Gas price estimate: 100 octas/gas
+  ✓ Starting sequence number: 1
+  ✓ Built & signed 10 transactions locally in 45ms
+  ✓ Submitted 10/10 in 312ms
+
+[3/4] Tracking Confirmations
+  ✓ Confirmed: 10/10
+
+[4/4] Verify & Report
+  ✓ Final balance: 99,978,000 octas
+  ✓ Total spent (transfers + gas): 22,000 octas
+
+=== Summary ===
+{
+  "network": "devnet",
+  "timestamp": "2026-02-21T12:00:00Z",
+  "transactions": {
+    "requested": 10,
+    "submitted": 10,
+    "confirmed": 10,
+    "failed": 0
+  },
+  "performance": {
+    "build_and_sign_ms": 45,
+    "submit_ms": 312
+  },
+  "economics": {
+    "initial_balance_octas": 100000000,
+    "final_balance_octas": 99978000,
+    "total_spent_octas": 22000,
+    "avg_cost_per_tx_octas": 2200
+  }
+}
+```
+
+## CLI Options
+
+```
+--count N       Number of transactions to send (default: 10)
+--network NAME  Network: devnet, testnet, or mainnet (default: devnet)
+```
+
+## Extending This Example
+
+This is intentionally simple to serve as a starting point. Consider adding:
+
+- **Simulate before submit**: Call the simulation API to get exact gas estimates
+- **Retry on sequence number error**: Refetch and rebuild if a tx is rejected for invalid seq num
+- **Concurrent senders**: Split N transactions across M sender accounts for higher throughput
+- **Token transfers**: Replace APT coin transfers with fungible asset or NFT transfers
+- **Wait strategies**: Implement polling vs. long-poll vs. webhook confirmation patterns

examples/batch-transfer/go/go.mod

@@ -0,0 +1,16 @@
+module github.com/aptos-labs/aptos-sdk-examples/batch-transfer
+
+go 1.24.0
+
+require github.com/aptos-labs/aptos-go-sdk v1.11.0
+
+require (
+	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/coder/websocket v1.8.14 // indirect
+	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hasura/go-graphql-client v0.14.4 // indirect
+	github.com/hdevalence/ed25519consensus v0.2.0 // indirect
+	golang.org/x/crypto v0.42.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+)

examples/batch-transfer/go/go.sum

@@ -0,0 +1,44 @@
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+github.com/aptos-labs/aptos-go-sdk v1.11.0 h1:vIL1hpjECUiu7zMl9Wz6VV8ttXsrDqKUj0HxoeaIER4=
+github.com/aptos-labs/aptos-go-sdk v1.11.0/go.mod h1:8YvYwRg93UcG6pTStCpZdYiscCtKh51sYfeLgIy/41c=
+github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
+github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
+github.com/cucumber/gherkin/go/v26 v26.2.0 h1:EgIjePLWiPeslwIWmNQ3XHcypPsWAHoMCz/YEBKP4GI=
+github.com/cucumber/gherkin/go/v26 v26.2.0/go.mod h1:t2GAPnB8maCT4lkHL99BDCVNzCh1d7dBhCLt150Nr/0=
+github.com/cucumber/godog v0.15.1 h1:rb/6oHDdvVZKS66hrhpjFQFHjthFSrQBCOI1LwshNTI=
+github.com/cucumber/godog v0.15.1/go.mod h1:qju+SQDewOljHuq9NSM66s0xEhogx0q30flfxL4WUk8=
+github.com/cucumber/messages/go/v21 v21.0.1 h1:wzA0LxwjlWQYZd32VTlAVDTkW6inOFmSM+RuOwHZiMI=
+github.com/cucumber/messages/go/v21 v21.0.1/go.mod h1:zheH/2HS9JLVFukdrsPWoPdmUtmYQAQPLk7w5vWsk5s=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/decred/dcrd/crypto/blake256 v1.1.0 h1:zPMNGQCm0g4QTY27fOCorQW7EryeQ/U0x++OzVrdms8=
+github.com/decred/dcrd/crypto/blake256 v1.1.0/go.mod h1:2OfgNZ5wDpcsFmHmCK5gZTPcCXqlm2ArzUIkw9czNJo=
+github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 h1:NMZiJj8QnKe1LgsbDayM4UoHwbvwDRwnI3hwNaAHRnc=
+github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
+github.com/gofrs/uuid v4.4.0+incompatible h1:3qXRTX8/NbyulANqlc0lchS1gqAVxRgsuW1YrTJupqA=
+github.com/gofrs/uuid v4.4.0+incompatible/go.mod h1:b2aQJv3Z4Fp6yNu3cdSllBxTCLRxnplIgP/c0N/04lM=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hashicorp/go-immutable-radix v1.3.1 h1:DKHmCUm2hRBK510BaiZlwvpD40f8bJFeZnpfm2KLowc=
+github.com/hashicorp/go-immutable-radix v1.3.1/go.mod h1:0y9vanUI8NX6FsYoO3zeMjhV/C5i9g4Q3DwcSNZ4P60=
+github.com/hashicorp/go-memdb v1.3.5 h1:b3taDMxCBCBVgyRrS1AZVHO14ubMYZB++QpNhBg+Nyo=
+github.com/hashicorp/go-memdb v1.3.5/go.mod h1:8IVKKBkVe+fxFgdFOYxzQQNjz+sWCyHCdIC/+5+Vy1Y=
+github.com/hashicorp/golang-lru v1.0.2 h1:dV3g9Z/unq5DpblPpw+Oqcv4dU/1omnb4Ok8iPY6p1c=
+github.com/hashicorp/golang-lru v1.0.2/go.mod h1:iADmTwqILo4mZ8BN3D2Q6+9jd8WM5uGBxy+E8yxSoD4=
+github.com/hasura/go-graphql-client v0.14.4 h1:bYU7/+V50T2YBGdNQXt6l4f2cMZPECPUd8cyCR+ixtw=
+github.com/hasura/go-graphql-client v0.14.4/go.mod h1:jfSZtBER3or+88Q9vFhWHiFMPppfYILRyl+0zsgPIIw=
+github.com/hdevalence/ed25519consensus v0.2.0 h1:37ICyZqdyj0lAZ8P4D1d1id3HqbbG1N3iBb1Tb4rdcU=
+github.com/hdevalence/ed25519consensus v0.2.0/go.mod h1:w3BHWjwJbFU29IRHL1Iqkw3sus+7FctEyM4RqDxYNzo=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+golang.org/x/crypto v0.42.0 h1:chiH31gIWm57EkTXpwnqf8qeuMUi0yekh6mT2AvFlqI=
+golang.org/x/crypto v0.42.0/go.mod h1:4+rDnOTJhQCx2q7/j6rAN5XDw8kPjeaXEUR2eL94ix8=
+golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
+golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=