From 4a42b0d93dca22fb880ec5dfc3d471e07615be92 Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Fri, 3 Apr 2026 18:39:09 +0100 Subject: [PATCH 1/8] Update docs for client and node drift Re-audit the latest ant-client, ant-node, saorsa-core, and saorsa-transport changes, update the affected docs, refresh verification blocks, and adjust the native Rust and node guidance to match current merged truth. --- docs/architecture/system-overview.md | 27 +++++++----- docs/cli-reference/ant-core-library.md | 42 ++++++++++++++++++- docs/cli-reference/command-reference.md | 4 +- docs/cli-reference/overview.md | 4 +- docs/core-concepts/data-types.md | 4 +- docs/core-concepts/overview.md | 4 +- docs/core-concepts/payment-model.md | 24 ++++++++--- .../post-quantum-cryptography.md | 4 +- .../getting-started/build-directly-in-rust.md | 4 +- docs/getting-started/install.md | 7 ++++ docs/getting-started/introduction.md | 4 +- docs/getting-started/using-ant-client.md | 4 +- docs/github.md | 24 +++++------ docs/glossary.md | 23 ++++++---- docs/how-to-guides/deploy-to-mainnet.md | 4 +- docs/how-to-guides/embed-a-node.md | 20 ++++++--- docs/how-to-guides/manage-keys.md | 4 +- docs/how-to-guides/setup-local-network.md | 7 ++++ docs/how-to-guides/test-your-application.md | 11 ++++- docs/how-to-guides/use-external-signers.md | 4 +- docs/index.md | 4 +- docs/rust-reference/overview.md | 4 +- 22 files changed, 167 insertions(+), 70 deletions(-) diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md index 0b3a819..33b96c1 100644 --- a/docs/architecture/system-overview.md +++ b/docs/architecture/system-overview.md @@ -10,29 +10,29 @@ @@ -93,6 +93,14 @@ async fn main() -> Result<(), Box> { } ``` +## External signer flows + +The native Rust path now exposes both wave-batch and Merkle-batch external payment helpers. + +For wave-batch uploads, `data_prepare_upload`, `file_prepare_upload`, and `finalize_upload` prepare the upload, collect quotes, and later store the chunks after an external signer returns transaction hashes. + +For Merkle batches, `prepare_merkle_batch_external` builds the batch data needed for the on-chain call, and `finalize_merkle_batch` turns the winning pool hash back into per-chunk proofs. + ## Key types | Type | Description | @@ -103,6 +111,36 @@ async fn main() -> Result<(), Box> { | `ant_core::data::DataMap` | Private retrieval map for uploaded data | | `ant_core::data::LocalDevnet` | Local development helper | | `ant_core::data::Wallet` | EVM wallet used for paid operations | +| `ant_core::data::PreparedUpload` | Two-phase upload state used by external-signer flows | +| `ant_core::data::ExternalPaymentInfo` | External payment details for prepared uploads | +| `ant_core::data::PreparedMerkleBatch` | Prepared Merkle batch data for external signing | + +## External signer example + +```rust +use ant_core::data::{Client, ClientConfig, ExternalPaymentInfo}; +use bytes::Bytes; +use std::collections::HashMap; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?; + let prepared = client.data_prepare_upload(Bytes::from("hello autonomi")).await?; + + match &prepared.payment_info { + ExternalPaymentInfo::WaveBatch { payment_intent, .. } => { + println!("Need to pay {} atto", payment_intent.total_amount); + } + ExternalPaymentInfo::Merkle { prepared_batch, .. } => { + println!("Merkle depth: {}", prepared_batch.depth); + } + } + + let tx_hashes: HashMap<_, _> = HashMap::new(); + let _ = tx_hashes; + Ok(()) +} +``` ## Error handling diff --git a/docs/cli-reference/command-reference.md b/docs/cli-reference/command-reference.md index b8a8fca..58ac17f 100644 --- a/docs/cli-reference/command-reference.md +++ b/docs/cli-reference/command-reference.md @@ -3,8 +3,8 @@ diff --git a/docs/cli-reference/overview.md b/docs/cli-reference/overview.md index 2ef6477..9e49899 100644 --- a/docs/cli-reference/overview.md +++ b/docs/cli-reference/overview.md @@ -3,8 +3,8 @@ diff --git a/docs/core-concepts/data-types.md b/docs/core-concepts/data-types.md index ad4d25d..38fd8d1 100644 --- a/docs/core-concepts/data-types.md +++ b/docs/core-concepts/data-types.md @@ -10,8 +10,8 @@ diff --git a/docs/core-concepts/overview.md b/docs/core-concepts/overview.md index bdaa040..30d980e 100644 --- a/docs/core-concepts/overview.md +++ b/docs/core-concepts/overview.md @@ -10,8 +10,8 @@ + -Autonomi uses a pay-once storage model. You pay in ANT when you upload data, then retrieve it later without ongoing storage charges or a separate retrieval payment flow in the current developer tooling. +Autonomi uses a pay-once storage model. You pay in ANT token when you upload data, then retrieve it later without ongoing storage charges or download fees. ## Why it matters @@ -36,6 +43,8 @@ The tools use different wallet inputs: Without wallet configuration, write endpoints either fail or switch into an external-signer preparation flow. +In the direct Rust and CLI path, quote collection and payment construction now use on-chain market prices from the payment vault when preparing uploads. That keeps the client-side payment proofs aligned with the prices nodes verify on receipt. + ### EVM network choices The `ant` CLI exposes these EVM network values: @@ -44,7 +53,7 @@ The `ant` CLI exposes these EVM network values: - `arbitrum-sepolia` - `local` -The daemon-side external-signer flow also exposes `EVM_RPC_URL`, `EVM_PAYMENT_TOKEN_ADDRESS`, and `EVM_DATA_PAYMENTS_ADDRESS` as part of the network configuration it needs to prepare payments. +The daemon-side external-signer flow also exposes the RPC URL and payment contract addresses the signer needs to submit the transaction for the selected network. ### Cost estimation @@ -67,6 +76,8 @@ The supported payment modes are: In `ant-core`, the Merkle threshold is `64` chunks. +Nodes verify the payment proof that arrives with each write. In the current `ant-node` implementation, that includes signature checks, on-chain payment verification, and record-level validation before content is accepted into the node's chunk store. + ### What happens on retrieval The current download flows do not expose a separate payment step for retrieval. The payment surfaces in these repos are tied to storing data, chunks, files, directories, or node-management operations that require wallet context. @@ -92,10 +103,11 @@ curl -X POST http://localhost:8082/v1/data/public \ 2. Upload directly with `ant` ```bash -SECRET_KEY=0x... ant file upload my_data.bin --public --merkle \ +SECRET_KEY=0x... ant \ --devnet-manifest /tmp/devnet.json \ --allow-loopback \ - --evm-network local + --evm-network local \ + file upload my_data.bin --public --merkle ``` Both paths pay as part of the upload flow, but the daemon path exposes explicit cost-estimation endpoints while the CLI path emphasizes direct upload flags and wallet setup. diff --git a/docs/core-concepts/post-quantum-cryptography.md b/docs/core-concepts/post-quantum-cryptography.md index 88fbc33..0d94e14 100644 --- a/docs/core-concepts/post-quantum-cryptography.md +++ b/docs/core-concepts/post-quantum-cryptography.md @@ -10,8 +10,8 @@ diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md index 55eb512..224d6a3 100644 --- a/docs/getting-started/install.md +++ b/docs/getting-started/install.md @@ -7,6 +7,13 @@ verified_date: 2026-04-02 verification_mode: current-merged-truth --> + Use this path when you want to build on Autonomi through language SDKs and a local daemon. `antd` runs on your machine, talks to the network for you, and exposes REST and gRPC so your application can work through a stable local API. diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 15f1d8c..dc13103 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -10,8 +10,8 @@ diff --git a/docs/github.md b/docs/github.md index 45607f0..ffaf2e8 100644 --- a/docs/github.md +++ b/docs/github.md @@ -10,29 +10,29 @@ + diff --git a/docs/how-to-guides/embed-a-node.md b/docs/how-to-guides/embed-a-node.md index 33f97d1..6d97c6d 100644 --- a/docs/how-to-guides/embed-a-node.md +++ b/docs/how-to-guides/embed-a-node.md @@ -3,8 +3,8 @@ @@ -22,10 +22,12 @@ Use the current `ant-node` API when your Rust application needs to own a node ru ```toml [dependencies] -ant-node = "0.9.0" +ant-node = "0.10.0-rc.1" tokio = { version = "1", features = ["full"] } ``` +The current crate enables its `logging` feature by default. If you opt into `default-features = false`, add `features = ["logging"]` explicitly when you still want tracing output from the node runtime. + ### 2. Build a node with the current API For local or development embedding, start from the development preset: @@ -61,16 +63,24 @@ tokio::spawn(async move { ### 4. Configure production settings explicitly -`NodeConfig::default()` is production-oriented and expects real rewards configuration. The current config also exposes fields such as: +`NodeConfig::default()` is production-oriented and expects real rewards configuration. The current config includes fields such as: - `root_dir` - `port` +- `ipv4_only` - `bootstrap` - `network_mode` +- `testnet` +- `upgrade` - `payment.rewards_address` - `payment.evm_network` +- `bootstrap_cache` +- `storage` +- `close_group_cache_dir` +- `max_message_size` +- `log_level` -Use those directly instead of assuming the looser development defaults. +Treat that list as a current snapshot rather than a permanent exhaustive contract. Use the upstream crate API when you need the full config surface. ## Verify it worked diff --git a/docs/how-to-guides/manage-keys.md b/docs/how-to-guides/manage-keys.md index 493d1da..8bab04d 100644 --- a/docs/how-to-guides/manage-keys.md +++ b/docs/how-to-guides/manage-keys.md @@ -10,8 +10,8 @@ + Use the current `ant-dev` workflow to start a local devnet plus `antd` on your machine. diff --git a/docs/how-to-guides/test-your-application.md b/docs/how-to-guides/test-your-application.md index 889e39c..37e88ce 100644 --- a/docs/how-to-guides/test-your-application.md +++ b/docs/how-to-guides/test-your-application.md @@ -10,8 +10,15 @@ + diff --git a/docs/how-to-guides/use-external-signers.md b/docs/how-to-guides/use-external-signers.md index 7e55f58..1ca7bc2 100644 --- a/docs/how-to-guides/use-external-signers.md +++ b/docs/how-to-guides/use-external-signers.md @@ -92,7 +92,9 @@ The `address` field is only present when `store_data_map` is `true`. ### 5. Know the current SDK limitation -The Python, Node.js / TypeScript, and Rust SDKs include helper methods for prepare/finalize, but their finalize wrappers do not currently expose the full raw REST response shape. If you need `store_data_map` or the returned `data_map`, use the REST API directly for now. +The Python, Node.js / TypeScript, and Rust daemon SDKs include helper methods for prepare/finalize, but their finalize wrappers do not currently expose the full raw REST response shape. If you need `store_data_map` or the returned `data_map`, use the REST API directly for now. + +If you are building directly in Rust without the daemon, `ant-core` now exposes native external-payment helpers such as `data_prepare_upload`, `file_prepare_upload`, `prepare_merkle_batch_external`, and `finalize_merkle_batch`. ## Verify it worked diff --git a/docs/index.md b/docs/index.md index 67b222d..af5a84a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,8 +10,8 @@ diff --git a/docs/rust-reference/overview.md b/docs/rust-reference/overview.md index 25fcbb1..85f08df 100644 --- a/docs/rust-reference/overview.md +++ b/docs/rust-reference/overview.md @@ -3,8 +3,8 @@ -Autonomi uses a pay-once storage model. You pay in ANT token when you upload data, then retrieve it later without ongoing storage charges or download fees. +Autonomi uses a pay-once storage model. You pay in Autonomi Network Token (ANT) when you upload data, then retrieve it later without ongoing storage charges or download fees. ## Why it matters @@ -32,7 +32,7 @@ You cannot treat uploads as fire-and-forget writes. The daemon and direct-networ ### Pay once on upload -Autonomi is designed around immutable storage rather than renewable storage leases. In practice, that means the payment event happens when you upload data. The current developer tooling does not expose recurring storage fees or a separate retrieval payment step. +Autonomi is designed around immutable storage rather than renewable storage leases. In practice, that means the payment event happens when you upload data. There are no recurring storage fees or separate retrieval payments in the documented developer flows. ### Wallet-backed writes @@ -43,7 +43,7 @@ The tools use different wallet inputs: Without wallet configuration, write endpoints either fail or switch into an external-signer preparation flow. -In the direct Rust and CLI path, quote collection and payment construction now use on-chain market prices from the payment vault when preparing uploads. That keeps the client-side payment proofs aligned with the prices nodes verify on receipt. +When you use the CLI or build in Rust with ant-core, quote collection and payment construction use on-chain market prices from the payment vault when preparing uploads. That keeps the client-side payment proofs aligned with the prices nodes verify on receipt. ### EVM network choices @@ -76,11 +76,11 @@ The supported payment modes are: In `ant-core`, the Merkle threshold is `64` chunks. -Nodes verify the payment proof that arrives with each write. In the current `ant-node` implementation, that includes signature checks, on-chain payment verification, and record-level validation before content is accepted into the node's chunk store. +Nodes verify the payment proof that arrives with each write. That includes signature checks, on-chain payment verification, and record-level validation before content is accepted into the chunk store. ### What happens on retrieval -The current download flows do not expose a separate payment step for retrieval. The payment surfaces in these repos are tied to storing data, chunks, files, directories, or node-management operations that require wallet context. +Downloads do not require a separate payment step. In the documented tools, payments are tied to storing data, chunks, files, directories, or node-management operations that require wallet context. ## Practical example @@ -110,7 +110,7 @@ SECRET_KEY=0x... ant \ file upload my_data.bin --public --merkle ``` -Both paths pay as part of the upload flow, but the daemon path exposes explicit cost-estimation endpoints while the CLI path emphasizes direct upload flags and wallet setup. +In both examples, payment happens as part of the upload flow, but the daemon example exposes explicit cost-estimation endpoints while the CLI example emphasizes direct upload flags and wallet setup. ## Related pages diff --git a/docs/core-concepts/post-quantum-cryptography.md b/docs/core-concepts/post-quantum-cryptography.md index 0d94e14..cfc5f02 100644 --- a/docs/core-concepts/post-quantum-cryptography.md +++ b/docs/core-concepts/post-quantum-cryptography.md @@ -22,17 +22,17 @@ verification_mode: current-merged-truth --> -The current post-quantum cryptography stack in scope centers on `saorsa-pqc`, transport documentation built around ML-KEM-768 and ML-DSA-65, and `ant-keygen` release-signing with ML-DSA-65. +The post-quantum cryptography stack in scope centers on `saorsa-pqc`, transport documentation built around ML-KEM-768 and ML-DSA-65, and `ant-keygen` release-signing with ML-DSA-65. ## Why it matters -If you are reasoning about security, transport identity, or release authenticity, you need to know which cryptographic primitives the current repos actually document and expose today. +If you are reasoning about security, transport identity, or release authenticity, you need to know which cryptographic primitives the relevant repos actually document and expose. ## How it works ### saorsa-pqc -The current `saorsa-pqc` README describes a broader PQC library that includes: +The `saorsa-pqc` README describes a broader PQC library that includes: - ML-KEM key encapsulation variants - ML-DSA signature variants @@ -43,7 +43,7 @@ So the library itself is broader than any single Autonomi-facing transport choic ### saorsa-transport -The current `saorsa-transport` README describes its transport layer as pure post-quantum and highlights this pair for transport use: +The `saorsa-transport` README describes its transport layer as pure post-quantum and highlights this pair for transport use: - ML-KEM-768 for key exchange - ML-DSA-65 for signatures @@ -52,7 +52,7 @@ That repo frames the transport surface as no classical fallback in its documente ### ant-keygen -`ant-keygen` is the concrete current CLI in scope that uses ML-DSA-65 today. It generates release-signing keypairs, signs files, verifies signatures, and supports a signing context for domain separation. +`ant-keygen` is the CLI in scope that uses ML-DSA-65 for release signing. It generates release-signing keypairs, signs files, verifies signatures, and supports a signing context for domain separation. ## Practical example diff --git a/docs/core-concepts/self-encryption.md b/docs/core-concepts/self-encryption.md index 380c64d..6ffdf14 100644 --- a/docs/core-concepts/self-encryption.md +++ b/docs/core-concepts/self-encryption.md @@ -16,13 +16,13 @@ This is the layer that makes uploads content-addressed and client-side encrypted ## How it works -The current crate surface revolves around a few core operations: +The crate surface revolves around a few core operations: - `encrypt(bytes)` returns `(DataMap, Vec)` - `decrypt(data_map, chunks)` reconstructs the original content - `stream_encrypt(...)` and `streaming_decrypt(...)` support streaming flows for files and large payloads -The current implementation uses: +The implementation uses: - BLAKE3 for chunk hashing - ChaCha20-Poly1305 for authenticated encryption @@ -30,10 +30,10 @@ The current implementation uses: Chunk addresses are derived from the encrypted content. That is why the higher-level storage model is content-addressed: if the content changes, the resulting encrypted chunks and their addresses change too. -Important current limits from the crate itself: +Important limits from the crate itself: -- `MIN_ENCRYPTABLE_BYTES` is currently `3` -- `MAX_CHUNK_SIZE` is currently `4_190_208` bytes +- `MIN_ENCRYPTABLE_BYTES` is `3` +- `MAX_CHUNK_SIZE` is `4_190_208` bytes The crate stores chunk metadata in a `DataMap`, and the `DataMap` can be shrunk recursively when it grows beyond the immediate chunk set. In the higher-level SDK and CLI workflows, that `DataMap` is what turns a set of encrypted chunks back into retrievable content. diff --git a/docs/getting-started/build-directly-in-rust.md b/docs/getting-started/build-directly-in-rust.md index 08455c0..e9be1eb 100644 --- a/docs/getting-started/build-directly-in-rust.md +++ b/docs/getting-started/build-directly-in-rust.md @@ -1,4 +1,4 @@ -# Build Directly in Rust +# Build in Rust with ant-core -Use this path when you want native, daemon-free Rust access to the Autonomi network through `ant-core`. It is the most direct programmatic route for applications that want to control networking, uploads, and payments in Rust. +Use `ant-core` when you want native, daemon-free Rust access to the Autonomi network. It is the most direct programmatic route for applications that want to control networking, uploads, and payments in Rust. ## Prerequisites diff --git a/docs/getting-started/hello-world.md b/docs/getting-started/hello-world.md index 94ac0a4..42776cc 100644 --- a/docs/getting-started/hello-world.md +++ b/docs/getting-started/hello-world.md @@ -16,7 +16,7 @@ In this guide, you use `antd`, the local daemon used by the SDKs, to store a sma - For write operations: start `antd` with `AUTONOMI_WALLET_KEY` set, or use `ant dev start` for a local devnet - Optional: Python, Node.js, or Rust toolchain if you want to use the SDK examples -If you would rather use shell commands or direct Rust instead, see [Use the ant CLI](using-ant-client.md) and [Build Directly in Rust](build-directly-in-rust.md). +If you would rather use shell commands or direct Rust instead, see [Use the ant CLI](using-ant-client.md) and [Build in Rust with ant-core](build-directly-in-rust.md). Featured examples on this page use cURL, Python, Node.js / TypeScript, and Rust. Other SDK languages are available in the [Language Bindings](../sdk-reference/language-bindings/overview.md) section. diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md index 224d6a3..b4b6f79 100644 --- a/docs/getting-started/install.md +++ b/docs/getting-started/install.md @@ -15,7 +15,7 @@ verification_mode: current-merged-truth --> -Use this path when you want to build on Autonomi through language SDKs and a local daemon. `antd` runs on your machine, talks to the network for you, and exposes REST and gRPC so your application can work through a stable local API. +Use the SDKs when you want to build on Autonomi through language bindings and a local daemon. `antd` runs on your machine, talks to the network for you, and exposes REST and gRPC so your application can work through a stable local API. This is usually the best starting point if you are building in Python, Node.js / TypeScript, Go, Rust, Java, C#, Kotlin, Swift, Ruby, PHP, Dart, Zig, or another SDK language. @@ -27,7 +27,7 @@ This is usually the best starting point if you are building in Python, Node.js / - For write operations on the default network: a wallet private key exported as `AUTONOMI_WALLET_KEY` - For a fully local devnet: Python 3.10+ and a sibling `ant-node` checkout if you plan to use `ant dev start` -The SDK path is available in many languages. This guide focuses on cURL, Python, Node.js / TypeScript, and Rust in the featured examples. For the full list, see [Language Bindings Overview](../sdk-reference/language-bindings/overview.md). +The SDKs are available in many languages. This guide focuses on cURL, Python, Node.js / TypeScript, and Rust in the featured examples. For the full list, see [Language Bindings Overview](../sdk-reference/language-bindings/overview.md). ## Steps @@ -81,7 +81,7 @@ On the first run, `ant dev start` can take longer than usual while local compone ### 3. Confirm the gateway responds -The current default REST endpoint is `http://localhost:8082`: +The default REST endpoint is `http://localhost:8082`: ```bash curl http://localhost:8082/health @@ -98,7 +98,7 @@ Expected response: If you started a local devnet, the `network` value is `local`. -### 4. Know what this path gives you +### 4. Know what the SDKs give you By default, `antd` provides: @@ -107,7 +107,7 @@ By default, `antd` provides: On startup, `antd` also writes a `daemon.port` file. SDKs can use that file to discover non-default ports automatically. -This path is useful when you want: +This approach is useful when you want: - a single local process that multiple apps or tools can share - SDK ergonomics in non-Rust languages diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index dc13103..7ab7ed6 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -22,7 +22,7 @@ verification_mode: current-merged-truth --> -Autonomi is a decentralized peer-to-peer network for permanent, immutable data storage. Data is encrypted client-side before upload, and the network's transport and security model use post-quantum cryptography. You pay in ANT token when you upload data, and the storage model is designed around pay-once uploads rather than ongoing storage fees. +Autonomi is a decentralized peer-to-peer network for permanent, immutable data storage. Data is encrypted client-side before upload, and the network's transport and security model uses post-quantum cryptography. You pay in Autonomi Network Token (ANT) when you upload data, and the storage model is designed around pay-once uploads rather than ongoing storage fees. ## What makes it different @@ -43,17 +43,17 @@ This is the easiest starting point for most developers. - it exposes REST and gRPC endpoints - language SDKs talk to that daemon for you -Choose this path if you want to build in Python, Node.js / TypeScript, Go, Rust, Java, C#, Kotlin, Swift, Ruby, PHP, Dart, Zig, or another supported SDK language. +Choose the SDKs if you want to build in Python, Node.js / TypeScript, Go, Rust, Java, C#, Kotlin, Swift, Ruby, PHP, Dart, Zig, or another supported SDK language. ### 2. Use the ant CLI -This path gives you direct command-line access to uploads, downloads, chunk operations, wallet inspection, and node-management workflows. +The CLI gives you direct command-line access to uploads, downloads, chunk operations, wallet inspection, and node-management workflows. Choose it when you want shell access, automation scripts, or a daemon-free operational workflow. -### 3. Build directly in Rust +### 3. Build in Rust with ant-core -This path uses `ant-core` directly instead of going through the daemon. +This route uses `ant-core` instead of going through the daemon. Choose it when you want native Rust control over networking, payment flows, and upload logic. @@ -71,4 +71,4 @@ You do not need to understand every network detail before storing and retrieving - [Build with the SDKs](install.md) - [Use the ant CLI](using-ant-client.md) -- [Build Directly in Rust](build-directly-in-rust.md) +- [Build in Rust with ant-core](build-directly-in-rust.md) diff --git a/docs/getting-started/using-ant-client.md b/docs/getting-started/using-ant-client.md index 496b14b..0f2018f 100644 --- a/docs/getting-started/using-ant-client.md +++ b/docs/getting-started/using-ant-client.md @@ -16,7 +16,7 @@ Use the `ant` CLI when you want direct command-line access to the Autonomi netwo - `SECRET_KEY` set for uploads and wallet commands - A file to upload for the quickstart example below -If you want to build an application in another language, start with [Build with the SDKs](install.md). If you want daemon-free programmatic Rust access, see [Build Directly in Rust](build-directly-in-rust.md). +If you want to build an application in another language, start with [Build with the SDKs](install.md). If you want daemon-free programmatic Rust access, see [Build in Rust with ant-core](build-directly-in-rust.md). ## Steps @@ -93,4 +93,4 @@ echo "hello autonomi" | SECRET_KEY=0x... ant \ - [CLI Overview](../cli-reference/overview.md) - [CLI Command Reference](../cli-reference/command-reference.md) - [Developing in Rust](../rust-reference/overview.md) -- [Build Directly in Rust](build-directly-in-rust.md) +- [Build in Rust with ant-core](build-directly-in-rust.md) diff --git a/docs/github.md b/docs/github.md index ffaf2e8..f6dcd4c 100644 --- a/docs/github.md +++ b/docs/github.md @@ -62,7 +62,7 @@ This documentation is assembled from several upstream GitHub repositories. If yo ## WithAutonomi - [`WithAutonomi`](https://github.com/WithAutonomi) — Main GitHub organization for the current Autonomi developer-facing repos -- [`ant-sdk`](https://github.com/WithAutonomi/ant-sdk) — SDK path: `antd`, language SDKs, local dev tooling, and `antd-mcp` +- [`ant-sdk`](https://github.com/WithAutonomi/ant-sdk) — `antd`, language SDKs, local dev tooling, and `antd-mcp` - [`ant-client`](https://github.com/WithAutonomi/ant-client) — Direct CLI and native Rust path: `ant`, `ant-core`, and local devnet tooling - [`ant-node`](https://github.com/WithAutonomi/ant-node) — Node runtime, chunk storage, payment verification, and replication behavior - [`self_encryption`](https://github.com/WithAutonomi/self_encryption) — Client-side self-encryption crate used for content processing before network storage diff --git a/docs/glossary.md b/docs/glossary.md index 1bac48c..f536aeb 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -64,9 +64,9 @@ Canonical terms used throughout this docs set. **antd** — Local daemon that exposes REST on `http://localhost:8082` and gRPC on `localhost:50051` by default. -**ANT token** — Token used for storage payments in the current wallet-backed upload flows. +**Autonomi Network Token (ANT)** — Token used for storage payments. -**Arbitrum** — EVM network family referenced by the current payment tooling and CLI network selection. +**Arbitrum** — EVM network family used by payment tooling and CLI network selection. **Autonomi** — The network these repos target for decentralized storage and retrieval. @@ -74,11 +74,11 @@ Canonical terms used throughout this docs set. ## B -**BLAKE3** — Hash function used in current content-addressing and self-encryption flows. +**BLAKE3** — Hash function used in content addressing and self-encryption flows. ## C -**ChaCha20-Poly1305** — Authenticated encryption primitive used in the current self-encryption crate. +**ChaCha20-Poly1305** — Authenticated encryption primitive used in self-encryption. **chunk** — Low-level stored unit of encrypted content. @@ -116,13 +116,13 @@ Canonical terms used throughout this docs set. ## P -**pay-once** — Current docs shorthand for wallet-backed upload payment rather than an ongoing subscription model. +**pay-once** — Storage payment model where you pay when you upload and do not pay ongoing storage fees. **post-quantum cryptography** — Cryptographic approach centered here on `saorsa-pqc`, `saorsa-transport`, and `ant-keygen`. ## Q -**QUIC** — Transport protocol used by the current network transport layer for peer connections, NAT traversal coordination, and relay-assisted connectivity. +**QUIC** — UDP-based transport protocol used for peer connections, NAT traversal coordination, and relay-assisted connectivity. ## S diff --git a/docs/how-to-guides/deploy-to-mainnet.md b/docs/how-to-guides/deploy-to-mainnet.md index fe6312c..81f2b35 100644 --- a/docs/how-to-guides/deploy-to-mainnet.md +++ b/docs/how-to-guides/deploy-to-mainnet.md @@ -72,7 +72,7 @@ curl -X POST http://127.0.0.1:8082/v1/data/public \ -d "{\"data\":\"$DATA_B64\"}" ``` -### 5. Verify the direct-network CLI path separately if you use it +### 5. Verify the CLI separately if you use it The `ant` CLI expects bootstrap peers and an EVM network setting for mainnet-style writes: diff --git a/docs/how-to-guides/embed-a-node.md b/docs/how-to-guides/embed-a-node.md index 6d97c6d..bb8291c 100644 --- a/docs/how-to-guides/embed-a-node.md +++ b/docs/how-to-guides/embed-a-node.md @@ -8,7 +8,7 @@ verification_mode: current-merged-truth --> -Use the current `ant-node` API when your Rust application needs to own a node runtime directly. +Use the `ant-node` API when your Rust application needs to own a node runtime directly. ## Prerequisites @@ -26,9 +26,9 @@ ant-node = "0.10.0-rc.1" tokio = { version = "1", features = ["full"] } ``` -The current crate enables its `logging` feature by default. If you opt into `default-features = false`, add `features = ["logging"]` explicitly when you still want tracing output from the node runtime. +The crate enables its `logging` feature by default. If you opt into `default-features = false`, add `features = ["logging"]` explicitly when you still want tracing output from the node runtime. -### 2. Build a node with the current API +### 2. Build a node with the API For local or development embedding, start from the development preset: @@ -48,7 +48,7 @@ async fn main() -> Result<(), Box> { ### 3. Subscribe to node events -The current `RunningNode` surface exposes event subscriptions. +`RunningNode` exposes event subscriptions. ```rust let mut node = NodeBuilder::new(NodeConfig::development()).build().await?; @@ -63,7 +63,7 @@ tokio::spawn(async move { ### 4. Configure production settings explicitly -`NodeConfig::default()` is production-oriented and expects real rewards configuration. The current config includes fields such as: +`NodeConfig::default()` is production-oriented and expects real rewards configuration. The config includes fields such as: - `root_dir` - `port` @@ -80,7 +80,7 @@ tokio::spawn(async move { - `max_message_size` - `log_level` -Treat that list as a current snapshot rather than a permanent exhaustive contract. Use the upstream crate API when you need the full config surface. +Treat that list as a practical overview rather than a complete contract. For the full config surface, see the [upstream ant-node API](https://github.com/WithAutonomi/ant-node). ## Verify it worked diff --git a/docs/how-to-guides/handle-payments.md b/docs/how-to-guides/handle-payments.md index f254ca7..e66977f 100644 --- a/docs/how-to-guides/handle-payments.md +++ b/docs/how-to-guides/handle-payments.md @@ -10,7 +10,7 @@ In this guide, you use `antd`, the local daemon used by the SDKs, to check balances, approve token spend, estimate uploads, and choose a payment mode. -If you want to work from the command line instead, see [Use the ant CLI](../getting-started/using-ant-client.md). If you want direct Rust access, see [Build Directly in Rust](../getting-started/build-directly-in-rust.md). +If you want to work from the command line instead, see [Use the ant CLI](../getting-started/using-ant-client.md). If you want direct Rust access, see [Build in Rust with ant-core](../getting-started/build-directly-in-rust.md). Featured examples on this page use cURL, Python, Node.js / TypeScript, and Rust. Other SDK languages are available in the [Language Bindings](../sdk-reference/language-bindings/overview.md) section. @@ -82,7 +82,7 @@ async fn main() -> Result<(), Box> { {% endtab %} {% endtabs %} -The current wallet balance response returns token balance as atto tokens and gas balance as wei. +The wallet balance response returns token balance as atto tokens and gas balance as wei. ### 2. Approve token spend diff --git a/docs/how-to-guides/store-and-retrieve-data.md b/docs/how-to-guides/store-and-retrieve-data.md index 702e529..64ec91a 100644 --- a/docs/how-to-guides/store-and-retrieve-data.md +++ b/docs/how-to-guides/store-and-retrieve-data.md @@ -10,7 +10,7 @@ In this guide, you use `antd`, the local daemon used by the SDKs, to store public data, private data, files, and directories through language SDKs. -If you want direct shell access instead, see [Use the ant CLI](../getting-started/using-ant-client.md). If you want direct programmatic Rust access without the daemon, see [Build Directly in Rust](../getting-started/build-directly-in-rust.md). +If you want direct shell access instead, see [Use the ant CLI](../getting-started/using-ant-client.md). If you want direct programmatic Rust access without the daemon, see [Build in Rust with ant-core](../getting-started/build-directly-in-rust.md). Featured examples on this page use cURL, Python, Node.js / TypeScript, and Rust. Other SDK languages are available in the [Language Bindings](../sdk-reference/language-bindings/overview.md) section. diff --git a/docs/how-to-guides/test-your-application.md b/docs/how-to-guides/test-your-application.md index 37e88ce..4eb1a90 100644 --- a/docs/how-to-guides/test-your-application.md +++ b/docs/how-to-guides/test-your-application.md @@ -124,7 +124,7 @@ describe("integration", () => { ### 3. Use the built-in example smoke tests -The current `ant-dev` CLI can run example programs from the repo: +The `ant-dev` CLI can run example programs from the repo: ```bash ant dev example connect @@ -186,7 +186,7 @@ Your local integration environment is healthy when `ant dev status` reports a ru **Health check never turns green**: Inspect `ant dev logs`. -**Wrong daemon API shape in tests**: Update tests to the current JSON/base64 `antd` surface. +**Wrong daemon API shape in tests**: Update tests to the JSON/base64 `antd` surface. **Local wallet issues**: Recreate the environment with `ant dev reset` or `ant dev stop` followed by `ant dev start`. diff --git a/docs/how-to-guides/use-external-signers.md b/docs/how-to-guides/use-external-signers.md index 1ca7bc2..b844857 100644 --- a/docs/how-to-guides/use-external-signers.md +++ b/docs/how-to-guides/use-external-signers.md @@ -8,7 +8,7 @@ verification_mode: current-merged-truth --> -Use the current two-phase upload flow when your application signs EVM payment transactions outside `antd`. +Use the two-phase upload flow when your application signs EVM payment transactions outside `antd`. ## Prerequisites @@ -92,9 +92,9 @@ The `address` field is only present when `store_data_map` is `true`. ### 5. Know the current SDK limitation -The Python, Node.js / TypeScript, and Rust daemon SDKs include helper methods for prepare/finalize, but their finalize wrappers do not currently expose the full raw REST response shape. If you need `store_data_map` or the returned `data_map`, use the REST API directly for now. +The Python, Node.js / TypeScript, and Rust daemon SDKs include helper methods for prepare/finalize, but their finalize wrappers do not expose the full raw REST response shape. If you need `store_data_map` or the returned `data_map`, use the REST API directly. -If you are building directly in Rust without the daemon, `ant-core` now exposes native external-payment helpers such as `data_prepare_upload`, `file_prepare_upload`, `prepare_merkle_batch_external`, and `finalize_merkle_batch`. +If you are building in Rust with ant-core instead of the daemon, the library exposes native external-payment helpers such as `data_prepare_upload`, `file_prepare_upload`, `prepare_merkle_batch_external`, and `finalize_merkle_batch`. ## Verify it worked diff --git a/docs/index.md b/docs/index.md index af5a84a..ade872d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,13 +15,13 @@ verification_mode: current-merged-truth --> -Autonomi is a decentralized peer-to-peer network for permanent, immutable data storage. Data is encrypted client-side before upload, and the network's transport and security model use post-quantum cryptography. You pay once in ANT token when you upload data, then retrieve it later with a public address or a DataMap. +Autonomi is a decentralized peer-to-peer network for permanent, immutable data storage. Data is encrypted client-side before upload, and the network's transport and security model uses post-quantum cryptography. You pay once in Autonomi Network Token (ANT) when you upload data, then retrieve it later with a public address or a DataMap. ## Choose your path ### Build an app with the SDKs -Use the SDK path if you want a local daemon plus SDKs in Python, Node.js / TypeScript, Go, Rust, Java, C#, Kotlin, Swift, Ruby, PHP, Dart, Zig, and other supported languages. `antd` runs on your machine and exposes REST and gRPC so your application can talk to Autonomi through a stable local API. +Use the SDKs if you want a local daemon plus SDKs in Python, Node.js / TypeScript, Go, Rust, Java, C#, Kotlin, Swift, Ruby, PHP, Dart, Zig, and other supported languages. `antd` runs on your machine and exposes REST and gRPC so your application can talk to Autonomi through a stable local API. Start with [Build with the SDKs](getting-started/install.md), then [Your First Upload with the SDKs](getting-started/hello-world.md). @@ -31,11 +31,11 @@ Use the CLI when you want direct shell access to the network for uploads, downlo Start with [Use the ant CLI](getting-started/using-ant-client.md). -### Build directly in Rust +### Build in Rust with ant-core -Use the direct Rust path when you want daemon-free, programmatic control over networking, payments, and uploads with `ant-core`. +Build in Rust with `ant-core` when you want daemon-free, programmatic control over networking, payments, and uploads. -Start with [Build Directly in Rust](getting-started/build-directly-in-rust.md). +Start with [Build in Rust with ant-core](getting-started/build-directly-in-rust.md). ## Core ideas diff --git a/docs/rust-reference/overview.md b/docs/rust-reference/overview.md index 85f08df..56ccc4e 100644 --- a/docs/rust-reference/overview.md +++ b/docs/rust-reference/overview.md @@ -17,13 +17,13 @@ Rust gives you two supported ways to build on Autonomi. -## Choose your Rust path +## Choose your Rust route ### Rust through the SDK daemon Use the Rust SDK when you want Rust code to talk to `antd` just like the other SDK languages do. -Choose this path if you want: +Choose the Rust SDK if you want: - the same daemon-based model used by Python, Node.js / TypeScript, Go, and the other SDKs - REST or gRPC access through a stable local gateway @@ -35,13 +35,13 @@ See [Rust SDK](../sdk-reference/language-bindings/rust.md). Use `ant-core` when you want direct, daemon-free Rust access to networking, uploads, and payment flows. -Choose this path if you want: +Choose native Rust with ant-core if you want: - direct control over the network client in Rust - no daemon process between your code and the network - access to native Rust types and local devnet helpers -See [Build Directly in Rust](../getting-started/build-directly-in-rust.md) and [Rust Library Reference](../cli-reference/ant-core-library.md). +See [Build in Rust with ant-core](../getting-started/build-directly-in-rust.md) and [Rust Library Reference](../cli-reference/ant-core-library.md). ## How the two Rust paths differ @@ -59,6 +59,6 @@ See [Build Directly in Rust](../getting-started/build-directly-in-rust.md) and [ ## Related pages -- [Build Directly in Rust](../getting-started/build-directly-in-rust.md) +- [Build in Rust with ant-core](../getting-started/build-directly-in-rust.md) - [Rust SDK](../sdk-reference/language-bindings/rust.md) - [Rust Library Reference](../cli-reference/ant-core-library.md) diff --git a/docs/sdk-reference/grpc-services.md b/docs/sdk-reference/grpc-services.md index 81bf04f..c477c5b 100644 --- a/docs/sdk-reference/grpc-services.md +++ b/docs/sdk-reference/grpc-services.md @@ -130,7 +130,7 @@ Streams client events from the daemon. ## Common messages -The current proto files define these shared shapes: +The proto files define these shared shapes: | Message | Fields | |------|--------| diff --git a/docs/sdk-reference/language-bindings/java.md b/docs/sdk-reference/language-bindings/java.md index 22aedd7..fd098e8 100644 --- a/docs/sdk-reference/language-bindings/java.md +++ b/docs/sdk-reference/language-bindings/java.md @@ -29,7 +29,7 @@ try (var client = new AntdClient()) { } ``` -The current README also documents `AsyncAntdClient` and `GrpcAntdClient`. +The upstream README also documents `AsyncAntdClient` and `GrpcAntdClient`. ## Store and retrieve data diff --git a/docs/sdk-reference/language-bindings/kotlin.md b/docs/sdk-reference/language-bindings/kotlin.md index 9a46194..311fc4c 100644 --- a/docs/sdk-reference/language-bindings/kotlin.md +++ b/docs/sdk-reference/language-bindings/kotlin.md @@ -18,7 +18,7 @@ dependencies { } ``` -The current upstream README notes that, until published, you should use the project as a local dependency or composite build. +The upstream README notes that, until published, you should use the project as a local dependency or composite build. ## Connect to the daemon diff --git a/docs/sdk-reference/language-bindings/rust.md b/docs/sdk-reference/language-bindings/rust.md index 13b607a..1aa7cf9 100644 --- a/docs/sdk-reference/language-bindings/rust.md +++ b/docs/sdk-reference/language-bindings/rust.md @@ -8,7 +8,7 @@ verification_mode: current-merged-truth --> -The current daemon-binding Rust crate in `ant-sdk` is `antd-client`. It is separate from the direct-network `ant-client` repo documented elsewhere in this docs set. +The daemon-binding Rust crate in `ant-sdk` is `antd-client`. It is separate from the native Rust `ant-core` route documented elsewhere in this docs set. ## Install diff --git a/docs/sdk-reference/language-bindings/swift.md b/docs/sdk-reference/language-bindings/swift.md index 69f41ab..aa853ff 100644 --- a/docs/sdk-reference/language-bindings/swift.md +++ b/docs/sdk-reference/language-bindings/swift.md @@ -18,7 +18,7 @@ dependencies: [ ] ``` -The current upstream README says to use a local package dependency until the package is published. +The upstream README says to use a local package dependency until the package is published. ## Connect to the daemon diff --git a/docs/sdk-reference/mcp-server.md b/docs/sdk-reference/mcp-server.md index c53ac1b..3e255de 100644 --- a/docs/sdk-reference/mcp-server.md +++ b/docs/sdk-reference/mcp-server.md @@ -26,7 +26,7 @@ Runs the MCP server in SSE mode for web-based clients. ## Installation -The current upstream setup is: +The upstream setup is: ```bash pip install "antd[rest]" diff --git a/docs/sdk-reference/overview.md b/docs/sdk-reference/overview.md index a7e6d06..178e829 100644 --- a/docs/sdk-reference/overview.md +++ b/docs/sdk-reference/overview.md @@ -8,7 +8,7 @@ verification_mode: current-merged-truth --> -The SDK path for Autonomi centers on `antd`, a local gateway daemon that exposes REST and gRPC APIs, plus language SDKs and local developer tooling around that daemon. +The Autonomi SDKs center on `antd`, a local gateway daemon that exposes REST and gRPC APIs, plus language SDKs and local developer tooling around that daemon. ## Architecture @@ -68,7 +68,7 @@ The `antd` REST surface groups into these areas: | Wallet | `/v1/wallet/address`, `/v1/wallet/balance`, `/v1/wallet/approve` | | External signer flow | `/v1/data/prepare`, `/v1/upload/prepare`, `/v1/upload/finalize` | -The current proto directory contains `health.proto`, `data.proto`, `chunks.proto`, `files.proto`, and `events.proto`. +The proto directory contains `health.proto`, `data.proto`, `chunks.proto`, `files.proto`, and `events.proto`. ## Language SDKs From 9e9753c44bf7826a9e552dc5c5428e8229134315 Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Sat, 4 Apr 2026 08:36:22 +0100 Subject: [PATCH 3/8] Repin ant-client to latest merged commit Refresh all ant-client verification blocks to the latest merged SHA after the recent bootstrap-peer and version bump commits, and keep the drift-pass branch aligned with the newest merged truth used in weekend verification. --- docs/architecture/system-overview.md | 4 ++-- docs/cli-reference/ant-core-library.md | 4 ++-- docs/cli-reference/command-reference.md | 4 ++-- docs/cli-reference/overview.md | 4 ++-- docs/core-concepts/data-types.md | 4 ++-- docs/core-concepts/overview.md | 4 ++-- docs/core-concepts/payment-model.md | 4 ++-- docs/getting-started/build-directly-in-rust.md | 4 ++-- docs/getting-started/introduction.md | 4 ++-- docs/getting-started/using-ant-client.md | 4 ++-- docs/github.md | 4 ++-- docs/glossary.md | 4 ++-- docs/how-to-guides/deploy-to-mainnet.md | 4 ++-- docs/how-to-guides/manage-keys.md | 4 ++-- docs/how-to-guides/test-your-application.md | 4 ++-- docs/index.md | 4 ++-- docs/rust-reference/overview.md | 4 ++-- 17 files changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md index 972a934..45e0a97 100644 --- a/docs/architecture/system-overview.md +++ b/docs/architecture/system-overview.md @@ -10,8 +10,8 @@ diff --git a/docs/cli-reference/command-reference.md b/docs/cli-reference/command-reference.md index 58ac17f..529406f 100644 --- a/docs/cli-reference/command-reference.md +++ b/docs/cli-reference/command-reference.md @@ -3,8 +3,8 @@ diff --git a/docs/cli-reference/overview.md b/docs/cli-reference/overview.md index 3ac1d3b..091eb78 100644 --- a/docs/cli-reference/overview.md +++ b/docs/cli-reference/overview.md @@ -3,8 +3,8 @@ diff --git a/docs/core-concepts/data-types.md b/docs/core-concepts/data-types.md index 633a0f6..822bf68 100644 --- a/docs/core-concepts/data-types.md +++ b/docs/core-concepts/data-types.md @@ -10,8 +10,8 @@ diff --git a/docs/core-concepts/overview.md b/docs/core-concepts/overview.md index 1cf8716..608d661 100644 --- a/docs/core-concepts/overview.md +++ b/docs/core-concepts/overview.md @@ -10,8 +10,8 @@ diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 7ab7ed6..8bc99c2 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -10,8 +10,8 @@ diff --git a/docs/github.md b/docs/github.md index f6dcd4c..9e49ab0 100644 --- a/docs/github.md +++ b/docs/github.md @@ -10,8 +10,8 @@ diff --git a/docs/how-to-guides/manage-keys.md b/docs/how-to-guides/manage-keys.md index 8bab04d..aaa7834 100644 --- a/docs/how-to-guides/manage-keys.md +++ b/docs/how-to-guides/manage-keys.md @@ -10,8 +10,8 @@ diff --git a/docs/rust-reference/overview.md b/docs/rust-reference/overview.md index 56ccc4e..45c06b5 100644 --- a/docs/rust-reference/overview.md +++ b/docs/rust-reference/overview.md @@ -3,8 +3,8 @@ -In the repos in scope, key derivation appears as a generic cryptographic primitive in `saorsa-pqc` and as domain-separated signing contexts in `ant-keygen`. +In the repos covered here, key derivation appears as a generic cryptographic primitive in `saorsa-pqc` and as domain-separated signing contexts in `ant-keygen`. ## Why it matters -This page is narrower than the earlier draft version. The sources in scope support HKDF and signing-context separation, but they do not document one Autonomi-wide master-key hierarchy for storage, signing, and payments. +This page is narrower than the earlier draft version. The sources covered here support HKDF and signing-context separation, but they do not document one Autonomi-wide master-key hierarchy for storage, signing, and payments. ## How it works diff --git a/docs/core-concepts/overview.md b/docs/core-concepts/overview.md index 608d661..8870a0f 100644 --- a/docs/core-concepts/overview.md +++ b/docs/core-concepts/overview.md @@ -45,7 +45,7 @@ Read more in [Self-Encryption](self-encryption.md). ## Post-quantum cryptography -The cryptography stack in scope uses ML-DSA-65 for signatures and ML-KEM-768 for key encapsulation. Those algorithms matter most when you are reasoning about network identity, transport security, or the broader security model. +The cryptography stack uses ML-DSA-65 for signatures and ML-KEM-768 for key encapsulation. Those algorithms matter most when you are reasoning about network identity, transport security, or the broader security model. Read more in [Post-Quantum Cryptography](post-quantum-cryptography.md). diff --git a/docs/core-concepts/payment-model.md b/docs/core-concepts/payment-model.md index 7d7a8e3..8aef208 100644 --- a/docs/core-concepts/payment-model.md +++ b/docs/core-concepts/payment-model.md @@ -26,13 +26,13 @@ Autonomi uses a pay-once storage model. You pay in Autonomi Network Token (ANT) ## Why it matters -You cannot treat uploads as fire-and-forget writes. The daemon and direct-network tooling both require wallet context for paid storage operations, and the interfaces differ in where they expose cost estimation, wallet approval, and payment-mode control. +You cannot treat uploads as fire-and-forget writes. The daemon, CLI, and native Rust library all require wallet context for paid storage operations, and they differ in where they expose cost estimation, wallet approval, and payment-mode control. ## How it works ### Pay once on upload -Autonomi is designed around immutable storage rather than renewable storage leases. In practice, that means the payment event happens when you upload data. There are no recurring storage fees or separate retrieval payments in the documented developer flows. +Autonomi is designed around immutable storage rather than renewable storage leases. In practice, that means the payment event happens when you upload data. There are no recurring storage fees or separate retrieval payments. ### Wallet-backed writes @@ -80,7 +80,7 @@ Nodes verify the payment proof that arrives with each write. That includes signa ### What happens on retrieval -Downloads do not require a separate payment step. In the documented tools, payments are tied to storing data, chunks, files, directories, or node-management operations that require wallet context. +Downloads do not require a separate payment step. Payments are tied to storing data, chunks, files, directories, or node-management operations that require wallet context. ## Practical example diff --git a/docs/core-concepts/post-quantum-cryptography.md b/docs/core-concepts/post-quantum-cryptography.md index cfc5f02..43c002d 100644 --- a/docs/core-concepts/post-quantum-cryptography.md +++ b/docs/core-concepts/post-quantum-cryptography.md @@ -22,11 +22,11 @@ verification_mode: current-merged-truth --> -The post-quantum cryptography stack in scope centers on `saorsa-pqc`, transport documentation built around ML-KEM-768 and ML-DSA-65, and `ant-keygen` release-signing with ML-DSA-65. +The post-quantum cryptography described here centers on `saorsa-pqc`, transport documentation built around ML-KEM-768 and ML-DSA-65, and `ant-keygen` release-signing with ML-DSA-65. ## Why it matters -If you are reasoning about security, transport identity, or release authenticity, you need to know which cryptographic primitives the relevant repos actually document and expose. +If you are reasoning about security, transport identity, or release authenticity, you need to know which cryptographic primitives the stack uses. ## How it works @@ -48,11 +48,11 @@ The `saorsa-transport` README describes its transport layer as pure post-quantum - ML-KEM-768 for key exchange - ML-DSA-65 for signatures -That repo frames the transport surface as no classical fallback in its documented model. +The transport documentation describes this surface as having no classical fallback. ### ant-keygen -`ant-keygen` is the CLI in scope that uses ML-DSA-65 for release signing. It generates release-signing keypairs, signs files, verifies signatures, and supports a signing context for domain separation. +`ant-keygen` is the release-signing CLI that uses ML-DSA-65. It generates release-signing keypairs, signs files, verifies signatures, and supports a signing context for domain separation. ## Practical example diff --git a/docs/getting-started/build-directly-in-rust.md b/docs/getting-started/build-directly-in-rust.md index 59ecc37..626a027 100644 --- a/docs/getting-started/build-directly-in-rust.md +++ b/docs/getting-started/build-directly-in-rust.md @@ -1,4 +1,4 @@ -# Build in Rust with ant-core +# Build in Rust without the daemon -Use `ant-core` when you want native, daemon-free Rust access to the Autonomi network. It is the most direct programmatic route for applications that want to control networking, uploads, and payments in Rust. +You can build on Autonomi in Rust without running the local daemon. This approach uses the Rust library `ant-core` and gives your application direct access to networking, uploads, and payments. ## Prerequisites @@ -37,7 +37,7 @@ bytes = "1" tokio = { version = "1", features = ["full"] } ``` -### 2. Start a local devnet and upload data directly from Rust +### 2. Start a local devnet and upload data from Rust Replace `src/main.rs` with: @@ -72,7 +72,7 @@ This example starts a local Autonomi development network, creates a funded Rust ## What happened -Your Rust application talked to the network through `ant-core` directly, without `antd` or a CLI wrapper. `ant-core` started a local devnet, created a funded client, handled self-encryption and payment, and gave you direct access to the upload and download results in Rust. +Your Rust application talked to the network through `ant-core`, without `antd` or a CLI wrapper. `ant-core` started a local devnet, created a funded client, handled self-encryption and payment, and gave you direct access to the upload and download results in Rust. ## Next steps From fd2ebaddabff4879075d81a2f6cfb65d6b8873c4 Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Sat, 4 Apr 2026 09:40:09 +0100 Subject: [PATCH 5/8] Remove remaining provenance wording Replace the last ordinary-prose uses of upstream-style provenance language, add an explicit CLAUDE.md rule for it, and include the lingering core concepts payment-summary fix on the drift pass branch. --- CLAUDE.md | 1 + docs/cli-reference/ant-core-library.md | 2 +- docs/cli-reference/overview.md | 2 +- docs/core-concepts/overview.md | 2 +- docs/how-to-guides/embed-a-node.md | 2 +- docs/sdk-reference/language-bindings/java.md | 2 +- docs/sdk-reference/language-bindings/kotlin.md | 2 +- docs/sdk-reference/language-bindings/python.md | 2 +- docs/sdk-reference/language-bindings/swift.md | 2 +- docs/sdk-reference/mcp-server.md | 2 +- 10 files changed, 10 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 45ea328..5768bf6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -94,6 +94,7 @@ All documentation work follows `source audit -> draft -> verify`. Follow the det - Avoid time-relative or changelog-style wording in rendered docs unless the page is explicitly comparing versions. Prefer direct statements of fact over words like `current`, `now`, `currently`, or phrases such as `in the current implementation`. - Use `path` language only on pages where the reader is explicitly choosing between routes. In normal prose, prefer phrases like "using the SDKs", "using the CLI", or "building in Rust with ant-core". - Prefer system behavior and user-facing tool names over repo names in ordinary explanatory prose. +- Avoid provenance terms such as `upstream` and `downstream` in rendered prose unless the page is explicitly about source repositories, contribution workflow, or source verification. - Expand important acronyms on first use when that helps a first-time reader. - See [Audience and objectives](#audience-and-objectives) for reader assumptions diff --git a/docs/cli-reference/ant-core-library.md b/docs/cli-reference/ant-core-library.md index f0a7498..ed2c314 100644 --- a/docs/cli-reference/ant-core-library.md +++ b/docs/cli-reference/ant-core-library.md @@ -12,7 +12,7 @@ ## Install -The upstream README documents `ant-core` as a local dependency from an `ant-client` checkout: +The README documents `ant-core` as a local dependency from an `ant-client` checkout: ```toml [dependencies] diff --git a/docs/cli-reference/overview.md b/docs/cli-reference/overview.md index 091eb78..076e639 100644 --- a/docs/cli-reference/overview.md +++ b/docs/cli-reference/overview.md @@ -44,7 +44,7 @@ It also accepts global flags such as: ## Installation -The upstream README documents install scripts for Linux, macOS, and Windows, plus source builds from the repo. +The README documents install scripts for Linux, macOS, and Windows, plus source builds from the repo. ```bash curl -fsSL https://raw.githubusercontent.com/WithAutonomi/ant-client/main/install.sh | bash diff --git a/docs/core-concepts/overview.md b/docs/core-concepts/overview.md index 8870a0f..39d8d4d 100644 --- a/docs/core-concepts/overview.md +++ b/docs/core-concepts/overview.md @@ -51,7 +51,7 @@ Read more in [Post-Quantum Cryptography](post-quantum-cryptography.md). ## Payment model -Autonomi is designed around pay-once, immutable storage. Upload flows are wallet-backed writes: you pay when you store data, then retrieve it later without a separate retrieval payment flow in the documented developer tools. +Autonomi is designed around pay-once, immutable storage. Uploads are wallet-backed writes: you pay when you store data, then retrieve it later without recurring storage fees or retrieval payments. Read more in [Payment Model](payment-model.md). diff --git a/docs/how-to-guides/embed-a-node.md b/docs/how-to-guides/embed-a-node.md index bb8291c..6ebe77c 100644 --- a/docs/how-to-guides/embed-a-node.md +++ b/docs/how-to-guides/embed-a-node.md @@ -80,7 +80,7 @@ tokio::spawn(async move { - `max_message_size` - `log_level` -Treat that list as a practical overview rather than a complete contract. For the full config surface, see the [upstream ant-node API](https://github.com/WithAutonomi/ant-node). +Treat that list as a practical overview rather than a complete contract. For the full config surface, see the [ant-node API](https://github.com/WithAutonomi/ant-node). ## Verify it worked diff --git a/docs/sdk-reference/language-bindings/java.md b/docs/sdk-reference/language-bindings/java.md index fd098e8..3cffd1e 100644 --- a/docs/sdk-reference/language-bindings/java.md +++ b/docs/sdk-reference/language-bindings/java.md @@ -29,7 +29,7 @@ try (var client = new AntdClient()) { } ``` -The upstream README also documents `AsyncAntdClient` and `GrpcAntdClient`. +The README also documents `AsyncAntdClient` and `GrpcAntdClient`. ## Store and retrieve data diff --git a/docs/sdk-reference/language-bindings/kotlin.md b/docs/sdk-reference/language-bindings/kotlin.md index 311fc4c..11bc849 100644 --- a/docs/sdk-reference/language-bindings/kotlin.md +++ b/docs/sdk-reference/language-bindings/kotlin.md @@ -18,7 +18,7 @@ dependencies { } ``` -The upstream README notes that, until published, you should use the project as a local dependency or composite build. +The README notes that, until published, you should use the project as a local dependency or composite build. ## Connect to the daemon diff --git a/docs/sdk-reference/language-bindings/python.md b/docs/sdk-reference/language-bindings/python.md index ff81c6e..842f22e 100644 --- a/docs/sdk-reference/language-bindings/python.md +++ b/docs/sdk-reference/language-bindings/python.md @@ -83,7 +83,7 @@ except AntdError as error: print(error) ``` -REST and gRPC share the same high-level API, but the upstream README notes that wallet operations and `payment_mode` are REST-only today. +REST and gRPC share the same high-level API, but the README notes that wallet operations and `payment_mode` are REST-only today. ## Full API reference diff --git a/docs/sdk-reference/language-bindings/swift.md b/docs/sdk-reference/language-bindings/swift.md index aa853ff..f4b7f3b 100644 --- a/docs/sdk-reference/language-bindings/swift.md +++ b/docs/sdk-reference/language-bindings/swift.md @@ -18,7 +18,7 @@ dependencies: [ ] ``` -The upstream README says to use a local package dependency until the package is published. +The README says to use a local package dependency until the package is published. ## Connect to the daemon diff --git a/docs/sdk-reference/mcp-server.md b/docs/sdk-reference/mcp-server.md index 3e255de..fb863f8 100644 --- a/docs/sdk-reference/mcp-server.md +++ b/docs/sdk-reference/mcp-server.md @@ -26,7 +26,7 @@ Runs the MCP server in SSE mode for web-based clients. ## Installation -The upstream setup is: +Use this setup: ```bash pip install "antd[rest]" From d6a48d415c0562cb5e402e8d4cc2e38f00340c8a Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Sat, 4 Apr 2026 09:57:19 +0100 Subject: [PATCH 6/8] State docs facts directly Add a CLAUDE.md rule against narrating evidence in rendered prose and replace the remaining README/provenance-style statements in the docs with direct user-facing instructions and facts. --- CLAUDE.md | 1 + docs/cli-reference/ant-core-library.md | 2 +- docs/cli-reference/overview.md | 2 +- docs/core-concepts/key-derivation.md | 4 ++-- docs/core-concepts/post-quantum-cryptography.md | 6 +++--- docs/sdk-reference/language-bindings/kotlin.md | 2 +- docs/sdk-reference/language-bindings/python.md | 2 +- docs/sdk-reference/language-bindings/swift.md | 2 +- docs/sdk-reference/overview.md | 2 +- 9 files changed, 12 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5768bf6..852abec 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -95,6 +95,7 @@ All documentation work follows `source audit -> draft -> verify`. Follow the det - Use `path` language only on pages where the reader is explicitly choosing between routes. In normal prose, prefer phrases like "using the SDKs", "using the CLI", or "building in Rust with ant-core". - Prefer system behavior and user-facing tool names over repo names in ordinary explanatory prose. - Avoid provenance terms such as `upstream` and `downstream` in rendered prose unless the page is explicitly about source repositories, contribution workflow, or source verification. +- Do not narrate the evidence in rendered prose. Avoid phrases like `the README says`, `the README notes`, `the README documents`, `the documentation describes`, `the relevant repos`, or `the sources covered here`. State the system, tool, or workflow directly and confidently. If a claim is not strong enough to state directly, re-audit it or remove it. - Expand important acronyms on first use when that helps a first-time reader. - See [Audience and objectives](#audience-and-objectives) for reader assumptions diff --git a/docs/cli-reference/ant-core-library.md b/docs/cli-reference/ant-core-library.md index ed2c314..efb7d54 100644 --- a/docs/cli-reference/ant-core-library.md +++ b/docs/cli-reference/ant-core-library.md @@ -12,7 +12,7 @@ ## Install -The README documents `ant-core` as a local dependency from an `ant-client` checkout: +Use `ant-core` as a local dependency from an `ant-client` checkout: ```toml [dependencies] diff --git a/docs/cli-reference/overview.md b/docs/cli-reference/overview.md index 076e639..44ea50d 100644 --- a/docs/cli-reference/overview.md +++ b/docs/cli-reference/overview.md @@ -44,7 +44,7 @@ It also accepts global flags such as: ## Installation -The README documents install scripts for Linux, macOS, and Windows, plus source builds from the repo. +Install scripts are available for Linux, macOS, and Windows, and you can also build the CLI from source. ```bash curl -fsSL https://raw.githubusercontent.com/WithAutonomi/ant-client/main/install.sh | bash diff --git a/docs/core-concepts/key-derivation.md b/docs/core-concepts/key-derivation.md index 261981d..6dbdb8a 100644 --- a/docs/core-concepts/key-derivation.md +++ b/docs/core-concepts/key-derivation.md @@ -19,13 +19,13 @@ In the repos covered here, key derivation appears as a generic cryptographic pri ## Why it matters -This page is narrower than the earlier draft version. The sources covered here support HKDF and signing-context separation, but they do not document one Autonomi-wide master-key hierarchy for storage, signing, and payments. +This page focuses on the parts of key derivation that are actually documented in the current stack. Autonomi uses HKDF primitives and signing-context separation, but it does not define one unified key hierarchy for storage, signing, and payments. ## How it works ### HKDF in saorsa-pqc -The `saorsa-pqc` README documents HKDF-SHA3-256 and HKDF-SHA3-512 as available key-derivation primitives. +`saorsa-pqc` provides HKDF-SHA3-256 and HKDF-SHA3-512 as key-derivation primitives. That means the crypto library can derive new key material from shared secrets or existing key material, but the repo does not by itself define how application-level Autonomi keys should be organized. diff --git a/docs/core-concepts/post-quantum-cryptography.md b/docs/core-concepts/post-quantum-cryptography.md index 43c002d..543167e 100644 --- a/docs/core-concepts/post-quantum-cryptography.md +++ b/docs/core-concepts/post-quantum-cryptography.md @@ -32,7 +32,7 @@ If you are reasoning about security, transport identity, or release authenticity ### saorsa-pqc -The `saorsa-pqc` README describes a broader PQC library that includes: +`saorsa-pqc` is a broader PQC library that includes: - ML-KEM key encapsulation variants - ML-DSA signature variants @@ -43,12 +43,12 @@ So the library itself is broader than any single Autonomi-facing transport choic ### saorsa-transport -The `saorsa-transport` README describes its transport layer as pure post-quantum and highlights this pair for transport use: +`saorsa-transport` describes its transport layer as pure post-quantum and highlights this pair for transport use: - ML-KEM-768 for key exchange - ML-DSA-65 for signatures -The transport documentation describes this surface as having no classical fallback. +The transport layer has no classical fallback. ### ant-keygen diff --git a/docs/sdk-reference/language-bindings/kotlin.md b/docs/sdk-reference/language-bindings/kotlin.md index 11bc849..2a2d966 100644 --- a/docs/sdk-reference/language-bindings/kotlin.md +++ b/docs/sdk-reference/language-bindings/kotlin.md @@ -18,7 +18,7 @@ dependencies { } ``` -The README notes that, until published, you should use the project as a local dependency or composite build. +Until the package is published, use the project as a local dependency or composite build. ## Connect to the daemon diff --git a/docs/sdk-reference/language-bindings/python.md b/docs/sdk-reference/language-bindings/python.md index 842f22e..f79cdb8 100644 --- a/docs/sdk-reference/language-bindings/python.md +++ b/docs/sdk-reference/language-bindings/python.md @@ -83,7 +83,7 @@ except AntdError as error: print(error) ``` -REST and gRPC share the same high-level API, but the README notes that wallet operations and `payment_mode` are REST-only today. +REST and gRPC share the same high-level API, but wallet operations and `payment_mode` are REST-only. ## Full API reference diff --git a/docs/sdk-reference/language-bindings/swift.md b/docs/sdk-reference/language-bindings/swift.md index f4b7f3b..d2edfad 100644 --- a/docs/sdk-reference/language-bindings/swift.md +++ b/docs/sdk-reference/language-bindings/swift.md @@ -18,7 +18,7 @@ dependencies: [ ] ``` -The README says to use a local package dependency until the package is published. +Use a local package dependency until the package is published. ## Connect to the daemon diff --git a/docs/sdk-reference/overview.md b/docs/sdk-reference/overview.md index 178e829..21d502d 100644 --- a/docs/sdk-reference/overview.md +++ b/docs/sdk-reference/overview.md @@ -45,7 +45,7 @@ The daemon defaults are: - REST: `http://localhost:8082` - gRPC: `localhost:50051` -On startup, `antd` writes a `daemon.port` file with the resolved REST and gRPC ports. The repo README documents these default locations: +On startup, `antd` writes a `daemon.port` file with the resolved REST and gRPC ports. The default locations are: | Platform | `daemon.port` location | |------|------| From bbd16352b79a5866cae97c195704d6ef9ad5f1a5 Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Sat, 4 Apr 2026 10:05:58 +0100 Subject: [PATCH 7/8] Clean up Java binding wording Replace the last README-narration sentence in the Java binding page with a direct statement about the SDK surface so it matches the updated documentation style rules. --- docs/sdk-reference/language-bindings/java.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk-reference/language-bindings/java.md b/docs/sdk-reference/language-bindings/java.md index 3cffd1e..9864966 100644 --- a/docs/sdk-reference/language-bindings/java.md +++ b/docs/sdk-reference/language-bindings/java.md @@ -29,7 +29,7 @@ try (var client = new AntdClient()) { } ``` -The README also documents `AsyncAntdClient` and `GrpcAntdClient`. +The SDK also provides `AsyncAntdClient` and `GrpcAntdClient`. ## Store and retrieve data From 248bc8d2375f2691b30df4eccd4a3c7e54e75079 Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Sat, 4 Apr 2026 10:59:03 +0100 Subject: [PATCH 8/8] Fix final drift review findings Add the missing ant-client verification block to the external signers guide and soften the relay/NAT wording in the system overview and glossary so it matches the transport sources more precisely. --- docs/architecture/system-overview.md | 4 ++-- docs/glossary.md | 4 ++-- docs/how-to-guides/use-external-signers.md | 7 +++++++ 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md index 382bf4e..dcbb21b 100644 --- a/docs/architecture/system-overview.md +++ b/docs/architecture/system-overview.md @@ -93,13 +93,13 @@ In the repos used for this page, `ant-node` documents chunk storage as its activ ## Routing and transport -`saorsa-core` provides the P2P node, DHT, bootstrap handling, trust system, and routing-table logic around typed addresses and peer identity. `saorsa-transport` provides QUIC transport, NAT traversal, address discovery, and relay-assisted connectivity for peers that cannot rely on direct hole punching alone. +`saorsa-core` provides the P2P node, DHT, bootstrap handling, trust system, and routing-table logic around typed addresses and peer identity. `saorsa-transport` provides QUIC transport, NAT traversal, address discovery, and relay fallback where direct hole punching is not enough. The transport story includes: - observed-address discovery and address propagation across the network - peer-ID-based hole-punch coordination -- relay-assisted connectivity for difficult NAT cases, including symmetric NAT +- relay fallback for some CGNAT cases - QUIC-based post-quantum transport centered on ML-KEM-768 and ML-DSA-65 ## Data path diff --git a/docs/glossary.md b/docs/glossary.md index d50451d..fc93037 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -112,7 +112,7 @@ Canonical terms used throughout this docs set. ## N -**NAT traversal** — Observed-address discovery, hole punching, and relay-assisted connectivity used by the transport layer to keep peers reachable across NAT boundaries, including harder cases such as symmetric NAT. +**NAT traversal** — Observed-address discovery and hole punching used to keep peers reachable across NAT boundaries. Relay fallback may be needed for some CGNAT cases. ## P @@ -122,7 +122,7 @@ Canonical terms used throughout this docs set. ## Q -**QUIC** — UDP-based transport protocol used for peer connections, NAT traversal coordination, and relay-assisted connectivity. +**QUIC** — UDP-based transport protocol used for peer connections and NAT traversal coordination. ## S diff --git a/docs/how-to-guides/use-external-signers.md b/docs/how-to-guides/use-external-signers.md index b844857..12f6670 100644 --- a/docs/how-to-guides/use-external-signers.md +++ b/docs/how-to-guides/use-external-signers.md @@ -7,6 +7,13 @@ verified_date: 2026-04-02 verification_mode: current-merged-truth --> + Use the two-phase upload flow when your application signs EVM payment transactions outside `antd`.