diff --git a/docs/cli/command-reference.md b/docs/cli/command-reference.md index 295e41a..4704156 100644 --- a/docs/cli/command-reference.md +++ b/docs/cli/command-reference.md @@ -3,8 +3,8 @@ @@ -171,6 +171,8 @@ Retrieves a single chunk by address. |------|------|----------|-------------| | `ADDRESS` | string | Yes | Hex-encoded chunk address (64 hex characters) | | `-o, --output ` | path | No | Write the chunk to a file instead of stdout | +| `--all-peers` | boolean | No | Diagnostic mode: try every selected closest peer and print ranked per-peer results. Chunk bytes are only written when `-o`/`--output` is also supplied. | +| `--peer-count ` | integer | No | Diagnostic mode only. Number of closest peers to try with `--all-peers`. Requires `--all-peers`. | **Example:** @@ -178,6 +180,12 @@ Retrieves a single chunk by address. ant chunk get -o chunk.bin ``` +Diagnostic example (try all closest peers and rank results): + +```bash +ant chunk get --all-peers --peer-count 5 +``` + ## Wallet commands ### `ant wallet address` @@ -291,12 +299,16 @@ Adds one or more nodes to the registry. | `--version ` | string | No | Download a specific node version | | `--url ` | string | No | Download a node archive from a URL | | `--bootstrap ` | string list | No | Bootstrap peers for the node binary itself | +| `--upgrade-channel ` | string | No | Release channel the node tracks for automatic upgrades: `stable` or `beta` | | `--env ` | string list | No | Node environment variables | **Example:** ```bash ant node add --rewards-address 0xYourWallet --count 1 + +# Pin the node to the stable upgrade channel: +ant node add --rewards-address 0xYourWallet --count 1 --upgrade-channel stable ``` ### `ant node start` diff --git a/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md b/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md index a341206..6343c2b 100644 --- a/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md +++ b/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md @@ -3,15 +3,15 @@ @@ -85,6 +85,172 @@ Fetches a chunk by address. Stores a raw chunk. +### PrepareChunk + +**Signature:** `PrepareChunk(PrepareChunkRequest) -> PrepareChunkResponse` + +Phase 1 of the external-signer single-chunk upload flow. Mirrors `POST /v1/chunks/prepare`. Single-chunk publishes always use the wave-batch payment shape. + +When the chunk is already on-network, `already_stored` is `true`, the payment fields are empty, and no finalize call is needed. + +**Request fields:** + +| Name | Type | Description | +|------|------|-------------| +| `data` | bytes | Raw chunk bytes (at most one ant-protocol chunk) | + +**Response fields:** + +| Name | Type | Description | +|------|------|-------------| +| `address` | string | Content-addressed BLAKE3 hash of the chunk bytes (hex with `0x` prefix) | +| `already_stored` | bool | `true` if the chunk was already on-network; all payment fields are empty when `true` | +| `upload_id` | string | Opaque token to pass to `FinalizeChunk`; empty when `already_stored` is `true` | +| `payment_type` | string | Always `"wave_batch"` for single-chunk publishes; empty when `already_stored` is `true` | +| `payments` | repeated PaymentEntry | Per-quote payment entries for `payForQuotes()` | +| `total_amount` | string | Total amount to pay in atto tokens | +| `payment_vault_address` | string | Payment vault contract address (hex with `0x` prefix) | +| `payment_token_address` | string | Payment token contract address (hex with `0x` prefix) | +| `rpc_url` | string | EVM RPC URL for submitting transactions | + +### FinalizeChunk + +**Signature:** `FinalizeChunk(FinalizeChunkRequest) -> FinalizeChunkResponse` + +Phase 2 of the external-signer single-chunk upload flow. Mirrors `POST /v1/chunks/finalize`. Call this after the external EVM payment has landed on-chain. + +**Request fields:** + +| Name | Type | Description | +|------|------|-------------| +| `upload_id` | string | The `upload_id` returned from `PrepareChunk` | +| `tx_hashes` | map\ | Map of `quote_hash` (hex) to `tx_hash` (hex) from the on-chain payment | + +**Response fields:** + +| Name | Type | Description | +|------|------|-------------| +| `address` | string | Network address of the stored chunk (hex with `0x` prefix) | + +## Upload Service + +The Upload Service is the external-signer flow for files and in-memory data. It mirrors the REST `/v1/upload/prepare`, `/v1/data/prepare`, and `/v1/upload/finalize` surface. + +The flow is two-phase: submit a prepare request, receive payment details and an `upload_id`, submit the EVM payment externally, then call `FinalizeUpload` with the resulting transaction artefacts. + +- Files with fewer than 64 chunks use `payment_type = "wave_batch"` and `payForQuotes()`. +- Files with 64 or more chunks use `payment_type = "merkle"` and `payForMerkleTree2()`. + +### PrepareFileUpload + +**Signature:** `PrepareFileUpload(PrepareFileUploadRequest) -> PrepareUploadResponse` + +Phase 1 for a local file. Returns payment details and an `upload_id`. + +**Request fields:** + +| Name | Type | Description | +|------|------|-------------| +| `path` | string | Local filesystem path on the daemon host | +| `visibility` | string | `"private"` (default) or `"public"`. `"public"` bundles the DataMap chunk into the payment batch; `data_map_address` is populated in the finalize response | + +### PrepareDataUpload + +**Signature:** `PrepareDataUpload(PrepareDataUploadRequest) -> PrepareUploadResponse` + +Phase 1 for in-memory bytes. Same two-phase flow as `PrepareFileUpload` but accepts raw bytes rather than a filesystem path. + +**Request fields:** + +| Name | Type | Description | +|------|------|-------------| +| `data` | bytes | Raw bytes to upload | +| `visibility` | string | `"private"` (default) or `"public"` | + +### PrepareUploadResponse (shared) + +Both prepare RPCs return `PrepareUploadResponse`: + +| Name | Type | Description | +|------|------|-------------| +| `upload_id` | string | Opaque token to pass to `FinalizeUpload` | +| `payment_type` | string | `"wave_batch"` or `"merkle"` | +| `payments` | repeated PaymentEntry | Wave-batch: per-quote entries for `payForQuotes()` | +| `depth` | uint32 | Merkle: tree depth (1–8) | +| `pool_commitments` | repeated PoolCommitmentEntry | Merkle: pool commitments for `payForMerkleTree2()`; each entry has exactly 16 candidate nodes | +| `merkle_payment_timestamp` | uint64 | Merkle: unix timestamp for the payment | +| `total_amount` | string | Total amount in atto tokens (`"0"` for Merkle) | +| `payment_vault_address` | string | Payment vault contract address (hex with `0x` prefix) | +| `payment_token_address` | string | Payment token contract address (hex with `0x` prefix) | +| `rpc_url` | string | EVM RPC URL for submitting transactions | + +### FinalizeUpload + +**Signature:** `FinalizeUpload(FinalizeUploadRequest) -> FinalizeUploadResponse` + +Phase 2 for both file and data uploads. Call after the external EVM payment lands. + +**Request fields:** + +| Name | Type | Description | +|------|------|-------------| +| `upload_id` | string | The `upload_id` returned from a prepare RPC | +| `tx_hashes` | map\ | Wave-batch: map of `quote_hash` (hex) to `tx_hash` (hex). Must be empty for Merkle | +| `winner_pool_hash` | string | Merkle: winner pool hash (hex with `0x` prefix) from the `MerklePaymentMade` event. Must be empty for wave-batch | +| `store_data_map` | bool | If `true`, stores the DataMap via the daemon's internal wallet and returns its address in `address` | + +**Response fields:** + +| Name | Type | Description | +|------|------|-------------| +| `data_map` | string | Hex-encoded serialized DataMap. Always returned | +| `address` | string | Network address of the stored DataMap; only set when `store_data_map` is `true` | +| `data_map_address` | string | Network address of the bundled DataMap chunk; only set when the upload was prepared with `visibility = "public"` | +| `chunks_stored` | uint64 | Number of chunks stored on the network | + +## Wallet Service + +The Wallet Service mirrors the REST `/v1/wallet/*` surface. All three RPCs require the daemon to have been started with `AUTONOMI_WALLET_KEY`. When the wallet is absent, the daemon returns `failed_precondition`. + +External-signer flows do not use this service — they use `UploadService` and `ChunkService.PrepareChunk`/`FinalizeChunk` instead. + +### GetAddress + +**Signature:** `GetAddress(GetWalletAddressRequest) -> GetWalletAddressResponse` + +Returns the wallet's on-chain address. + +**Response fields:** + +| Name | Type | Description | +|------|------|-------------| +| `address` | string | Wallet address (hex with `0x` prefix) | + +### GetBalance + +**Signature:** `GetBalance(GetWalletBalanceRequest) -> GetWalletBalanceResponse` + +Returns the wallet's token and gas balances. + +**Response fields:** + +| Name | Type | Description | +|------|------|-------------| +| `balance` | string | Token balance in atto tokens as a decimal string | +| `gas_balance` | string | Gas (native EVM token) balance in atto tokens as a decimal string | + +### Approve + +**Signature:** `Approve(WalletApproveRequest) -> WalletApproveResponse` + +Approves the wallet to spend tokens on the payment vault contract. Safe to call repeatedly; idempotent once approval is in place. + +**Response fields:** + +| Name | Type | Description | +|------|------|-------------| +| `approved` | bool | `true` if the approve transaction succeeded | + ## File Service ### Put diff --git a/docs/sdk/reference/language-bindings/python.md b/docs/sdk/reference/language-bindings/python.md index 0fea2dc..1643140 100644 --- a/docs/sdk/reference/language-bindings/python.md +++ b/docs/sdk/reference/language-bindings/python.md @@ -3,8 +3,8 @@ @@ -91,7 +91,7 @@ except AntdError as error: print(error) ``` -REST and gRPC share the same high-level API. Wallet operations and external-signer tools are REST-only; `payment_mode` is available on both transports. +REST and gRPC share the same high-level API, including wallet operations and external-signer prepare/finalize methods. `payment_mode` is available on both transports. ## Full API reference