diff --git a/docs/core-concepts/data-types.md b/docs/core-concepts/data-types.md index b612f6c..0bbdb9e 100644 --- a/docs/core-concepts/data-types.md +++ b/docs/core-concepts/data-types.md @@ -3,15 +3,15 @@ @@ -77,7 +77,9 @@ curl http://localhost:8082/v1/data/public/
Private retrieval through the daemon: ```bash -curl "http://localhost:8082/v1/data/private?data_map=" +curl -X POST http://localhost:8082/v1/data/get \ + -H "Content-Type: application/json" \ + -d '{"data_map":""}' ``` The private retrieval response is JSON with the content returned as base64 in the `data` field. diff --git a/docs/guides/estimate-costs-and-handle-upload-payments.md b/docs/guides/estimate-costs-and-handle-upload-payments.md index 064ae6b..237ff7c 100644 --- a/docs/guides/estimate-costs-and-handle-upload-payments.md +++ b/docs/guides/estimate-costs-and-handle-upload-payments.md @@ -3,8 +3,8 @@ @@ -94,21 +94,21 @@ Retrieves text from the network by address or DataMap. ### Upload a File -**Tool:** `upload_file(path, payment_mode="auto")` +**Tool:** `upload_file(path, private=False, payment_mode="auto")` -Uploads a local file as public content. +Uploads a local file to the network. When `private=True`, the returned `address` is the caller-held DataMap and is not stored on-network. When `private=False` (default), the DataMap is stored on-network and `address` is the public retrieval address. ### Download a File -**Tool:** `download_file(address, dest_path)` +**Tool:** `download_file(address, dest_path, private=False)` -Downloads a public file to a local path. +Downloads a file to a local path. Pass the on-network address when `private=False` (default) or the caller-held DataMap when `private=True`. ### Estimate Cost -**Tool:** `get_cost(text=None, file_path=None)` +**Tool:** `get_cost(text=None, file_path=None, payment_mode="auto")` -Estimates storage cost for text or a local file path. +Estimates storage cost for text or a local file path. Pass `payment_mode` to reflect the cost of a specific payment strategy. Provide exactly one of `text` or `file_path`. @@ -248,7 +248,8 @@ Example `store_data` response: ```json { "address": "abc123...", - "cost": "1000000", + "chunks_stored": 1, + "payment_mode_used": "auto", "network": "local" } ``` diff --git a/docs/sdk/how-to-guides/store-and-retrieve-data.md b/docs/sdk/how-to-guides/store-and-retrieve-data.md index ffc6dc8..f7c1413 100644 --- a/docs/sdk/how-to-guides/store-and-retrieve-data.md +++ b/docs/sdk/how-to-guides/store-and-retrieve-data.md @@ -3,8 +3,8 @@ @@ -64,12 +64,14 @@ main().catch((error) => { {% endtab %} {% tab title="Rust" %} ```rust -use antd_client::{Client, DEFAULT_BASE_URL}; +use antd_client::{Client, DEFAULT_BASE_URL, PaymentMode}; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::new(DEFAULT_BASE_URL); - let result = client.data_put_public(b"Hello, Autonomi!", None).await?; + let result = client + .data_put_public(b"Hello, Autonomi!", PaymentMode::Auto) + .await?; println!("{}", result.address); Ok(()) @@ -132,14 +134,14 @@ The REST response uses base64 in the `data` field. The Python, Node.js / TypeScr ### 3. Store private data -Private uploads return a serialized DataMap instead of a public address. +Private uploads return a serialized DataMap. The DataMap is not stored on-network; keep it to retrieve the data later. {% tabs %} {% tab title="cURL" %} ```bash DATA_B64=$(printf 'Secret message' | base64) -curl -X POST http://localhost:8082/v1/data/private \ +curl -X POST http://localhost:8082/v1/data \ -H "Content-Type: application/json" \ -d "{\"data\":\"$DATA_B64\"}" ``` @@ -158,9 +160,9 @@ Expected response shape: from antd import AntdClient client = AntdClient() -result = client.data_put_private(b"Secret message") +result = client.data_put(b"Secret message") -data_map = result.address +data_map = result.data_map print(data_map) ``` {% endtab %} @@ -170,8 +172,8 @@ import { createClient } from "antd"; async function main() { const client = createClient(); - const result = await client.dataPutPrivate(Buffer.from("Secret message")); - const dataMap = result.address; + const result = await client.dataPut(Buffer.from("Secret message")); + const dataMap = result.dataMap; console.log(dataMap); } @@ -183,14 +185,14 @@ main().catch((error) => { {% endtab %} {% tab title="Rust" %} ```rust -use antd_client::{Client, DEFAULT_BASE_URL}; +use antd_client::{Client, DEFAULT_BASE_URL, PaymentMode}; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::new(DEFAULT_BASE_URL); - let result = client.data_put_private(b"Secret message", None).await?; + let result = client.data_put(b"Secret message", PaymentMode::Auto).await?; - let data_map = result.address; + let data_map = result.data_map; println!("{}", data_map); Ok(()) } @@ -198,14 +200,16 @@ async fn main() -> Result<(), Box> { {% endtab %} {% endtabs %} -In the Python, Node.js / TypeScript, and Rust SDKs, the returned private `data_map` is surfaced through `PutResult.address`. +The Python and Rust SDKs surface the DataMap through `DataPutResult.data_map`; the Node.js / TypeScript SDK uses `DataPutResult.dataMap`. ### 4. Retrieve private data {% tabs %} {% tab title="cURL" %} ```bash -curl "http://localhost:8082/v1/data/private?data_map=" +curl -X POST http://localhost:8082/v1/data/get \ + -H "Content-Type: application/json" \ + -d '{"data_map":""}' ``` {% endtab %} {% tab title="Python" %} @@ -213,7 +217,7 @@ curl "http://localhost:8082/v1/data/private?data_map=" from antd import AntdClient client = AntdClient() -data = client.data_get_private("") +data = client.data_get("") print(data.decode()) ``` @@ -224,7 +228,7 @@ import { createClient } from "antd"; async function main() { const client = createClient(); - const data = await client.dataGetPrivate(""); + const data = await client.dataGet(""); console.log(data.toString()); } @@ -241,7 +245,7 @@ use antd_client::{Client, DEFAULT_BASE_URL}; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::new(DEFAULT_BASE_URL); - let data = client.data_get_private("").await?; + let data = client.data_get("").await?; println!("{}", String::from_utf8_lossy(&data)); Ok(()) @@ -257,11 +261,11 @@ These endpoints work on paths visible to the machine running `antd`. {% tabs %} {% tab title="cURL" %} ```bash -curl -X POST http://localhost:8082/v1/files/upload/public \ +curl -X POST http://localhost:8082/v1/files/public \ -H "Content-Type: application/json" \ -d '{"path":"/absolute/path/to/document.pdf"}' -curl -X POST http://localhost:8082/v1/files/download/public \ +curl -X POST http://localhost:8082/v1/files/public/get \ -H "Content-Type: application/json" \ -d '{"address":"<64_hex_address>","dest_path":"/absolute/path/to/downloaded-document.pdf"}' ``` @@ -271,8 +275,8 @@ curl -X POST http://localhost:8082/v1/files/download/public \ from antd import AntdClient client = AntdClient() -result = client.file_upload_public("/absolute/path/to/document.pdf") -client.file_download_public(result.address, "/absolute/path/to/downloaded-document.pdf") +result = client.file_put_public("/absolute/path/to/document.pdf") +client.file_get_public(result.address, "/absolute/path/to/downloaded-document.pdf") print(result.address) ``` @@ -283,8 +287,8 @@ import { createClient } from "antd"; async function main() { const client = createClient(); - const result = await client.fileUploadPublic("/absolute/path/to/document.pdf"); - await client.fileDownloadPublic(result.address, "/absolute/path/to/downloaded-document.pdf"); + const result = await client.filePutPublic("/absolute/path/to/document.pdf"); + await client.fileGetPublic(result.address, "/absolute/path/to/downloaded-document.pdf"); console.log(result.address); } @@ -296,16 +300,16 @@ main().catch((error) => { {% endtab %} {% tab title="Rust" %} ```rust -use antd_client::{Client, DEFAULT_BASE_URL}; +use antd_client::{Client, DEFAULT_BASE_URL, PaymentMode}; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::new(DEFAULT_BASE_URL); let result = client - .file_upload_public("/absolute/path/to/document.pdf", None) + .file_put_public("/absolute/path/to/document.pdf", PaymentMode::Auto) .await?; client - .file_download_public(&result.address, "/absolute/path/to/downloaded-document.pdf") + .file_get_public(&result.address, "/absolute/path/to/downloaded-document.pdf") .await?; println!("{}", result.address); diff --git a/docs/sdk/reference/grpc-services.md b/docs/sdk/reference/grpc-services.md index bcc331d..c1030a4 100644 --- a/docs/sdk/reference/grpc-services.md +++ b/docs/sdk/reference/grpc-services.md @@ -3,8 +3,8 @@ @@ -35,41 +35,41 @@ Checks daemon health and network selection. ## Data Service -### Get Public +### Put -**Signature:** `GetPublic(GetPublicDataRequest) -> GetPublicDataResponse` +**Signature:** `Put(PutDataRequest) -> PutDataResponse` -Fetches public data by address. +Stores private data. The DataMap is returned to the caller and is not stored on-network. ### Put Public **Signature:** `PutPublic(PutPublicDataRequest) -> PutPublicDataResponse` -Stores public data. +Stores public data. The DataMap is stored on-network as an additional chunk. -### Stream Public +### Get -**Signature:** `StreamPublic(StreamPublicDataRequest) -> stream DataChunk` +**Signature:** `Get(GetDataRequest) -> GetDataResponse` -This RPC is exposed, but the handler returns `UNIMPLEMENTED`. +Fetches private data using a caller-held `data_map` string. -### Get Private +### Get Public -**Signature:** `GetPrivate(GetPrivateDataRequest) -> GetPrivateDataResponse` +**Signature:** `GetPublic(GetPublicDataRequest) -> GetPublicDataResponse` -Fetches private data using a `data_map` string. +Fetches public data by address. -### Put Private +### Stream Public -**Signature:** `PutPrivate(PutPrivateDataRequest) -> PutPrivateDataResponse` +**Signature:** `StreamPublic(StreamPublicDataRequest) -> stream DataChunk` -Stores private data and returns a `data_map` string. +This RPC is exposed, but the handler returns `UNIMPLEMENTED`. -### Get Cost +### Cost -**Signature:** `GetCost(DataCostRequest) -> Cost` +**Signature:** `Cost(DataCostRequest) -> antd.v1.Cost` -Estimates storage cost for a byte payload. +Estimates storage cost for a byte payload. Accepts an optional `payment_mode` field (`"auto"`, `"merkle"`, or `"single"`). ## Chunk Service @@ -87,25 +87,37 @@ Stores a raw chunk. ## File Service -### Upload Public +### Put + +**Signature:** `Put(PutFileRequest) -> PutFileResponse` + +Uploads a local file privately. The DataMap is returned to the caller and is not stored on-network. + +### Put Public + +**Signature:** `PutPublic(PutFileRequest) -> PutFilePublicResponse` + +Uploads a local file publicly. Also stores the DataMap on-network as an additional chunk. -**Signature:** `UploadPublic(UploadFileRequest) -> UploadPublicResponse` +`PutFilePublicResponse` returns `address`, `storage_cost_atto`, `gas_cost_wei`, `chunks_stored`, and `payment_mode_used`. -Uploads a local file path. +### Get + +**Signature:** `Get(GetFileRequest) -> GetFileResponse` -`UploadPublicResponse` returns `address`, `storage_cost_atto`, `gas_cost_wei`, `chunks_stored`, and `payment_mode_used`. +Downloads a private file using a caller-held DataMap. -### Download Public +### Get Public -**Signature:** `DownloadPublic(DownloadPublicRequest) -> DownloadResponse` +**Signature:** `GetPublic(GetFilePublicRequest) -> GetFileResponse` -Downloads a public file to a local destination path. +Downloads a public file to a local destination path using its on-network DataMap address. -### Get File Cost +### Cost -**Signature:** `GetFileCost(FileCostRequest) -> Cost` +**Signature:** `Cost(FileCostRequest) -> antd.v1.Cost` -Estimates file upload cost. +Estimates file upload cost. `is_public` toggles between the public and private payment shape (public bundles an extra DataMap chunk into the estimate). Accepts an optional `payment_mode` field (`"auto"`, `"merkle"`, or `"single"`). ## Event Service @@ -130,11 +142,17 @@ The proto files define these shared shapes: | Message | Fields | |------|--------| -| `Cost` | `atto_tokens` | +| `Cost` | `atto_tokens`, `file_size`, `chunk_count`, `estimated_gas_cost_wei`, `payment_mode` | | `HealthCheckResponse` | `status`, `network`, `version`, `evm_network`, `uptime_seconds`, `build_commit`, `payment_token_address`, `payment_vault_address` | | `PutPublicDataResponse` | `cost`, `address` | -| `PutPrivateDataResponse` | `cost`, `data_map` | -| `UploadPublicResponse` | `address`, `storage_cost_atto`, `gas_cost_wei`, `chunks_stored`, `payment_mode_used` | +| `PutDataResponse` | `cost`, `data_map` | +| `PutFileRequest` | `path`, `payment_mode` | +| `PutFilePublicResponse` | `address`, `storage_cost_atto`, `gas_cost_wei`, `chunks_stored`, `payment_mode_used` | +| `PutFileResponse` | `data_map`, `storage_cost_atto`, `gas_cost_wei`, `chunks_stored`, `payment_mode_used` | +| `GetFilePublicRequest` | `address`, `dest_path` | +| `GetFileRequest` | `data_map`, `dest_path` | +| `GetDataRequest` | `data_map` | +| `FileCostRequest` | `path`, `is_public`, `payment_mode` | ## Related pages diff --git a/docs/sdk/reference/language-bindings/go.md b/docs/sdk/reference/language-bindings/go.md index b23fbfd..677bf49 100644 --- a/docs/sdk/reference/language-bindings/go.md +++ b/docs/sdk/reference/language-bindings/go.md @@ -3,8 +3,8 @@ @@ -65,7 +65,11 @@ func main() { client := antd.NewClient(antd.DefaultBaseURL) ctx := context.Background() - result, err := client.DataPutPublic(ctx, []byte("Hello from Go!")) + result, err := client.DataPutPublic( + ctx, + []byte("Hello from Go!"), + antd.PaymentModeAuto, + ) if err != nil { log.Fatal(err) } @@ -84,7 +88,13 @@ func main() { | Autonomi type | Go type | |------|------| | `HealthStatus` | `antd.HealthStatus` | -| `PutResult` | `antd.PutResult` | +| `PutResult` | `antd.PutResult` for chunk writes | +| `DataPutPublicResult` | `antd.DataPutPublicResult` | +| `DataPutResult` | `antd.DataPutResult` | +| `FilePutPublicResult` | `antd.FilePutPublicResult` | +| `FilePutResult` | `antd.FilePutResult` | +| `PaymentMode` | `antd.PaymentMode` | +| `UploadCostEstimate` | `antd.UploadCostEstimate` | | `WalletAddress` | `antd.WalletAddress` | | `WalletBalance` | `antd.WalletBalance` | | `PrepareUploadResult` | `antd.PrepareUploadResult` | diff --git a/docs/sdk/reference/language-bindings/javascript.md b/docs/sdk/reference/language-bindings/javascript.md index d4d9a06..55207d8 100644 --- a/docs/sdk/reference/language-bindings/javascript.md +++ b/docs/sdk/reference/language-bindings/javascript.md @@ -3,8 +3,8 @@ @@ -65,8 +65,12 @@ main().catch((error) => { | Autonomi type | JavaScript type | |------|------| | `HealthStatus` | object with `ok`, `network`, `version`, `evmNetwork`, `uptimeSeconds`, `buildCommit`, `paymentTokenAddress`, and `paymentVaultAddress` | -| `PutResult` | `{ cost: string, address: string }` | -| `FileUploadResult` | `{ address: string, storageCostAtto: string, gasCostWei: string, chunksStored: number, paymentModeUsed: string }` | +| `PutResult` | `{ cost: string, address: string }` for chunk writes | +| `DataPutPublicResult` | `{ address: string, chunksStored: number, paymentModeUsed: string }` | +| `DataPutResult` | `{ dataMap: string, chunksStored: number, paymentModeUsed: string }` | +| `FilePutPublicResult` | `{ address: string, storageCostAtto: string, gasCostWei: string, chunksStored: number, paymentModeUsed: string }` | +| `FilePutResult` | `{ dataMap: string, storageCostAtto: string, gasCostWei: string, chunksStored: number, paymentModeUsed: string }` | +| `PaymentMode` | string values: `auto`, `merkle`, or `single` | | `WalletAddress` | `{ address: string }` | | `WalletBalance` | `{ balance: string, gasBalance: string }` | | `PaymentInfo` | `{ quoteHash: string, rewardsAddress: string, amount: string }` | diff --git a/docs/sdk/reference/language-bindings/python.md b/docs/sdk/reference/language-bindings/python.md index ae51465..759e392 100644 --- a/docs/sdk/reference/language-bindings/python.md +++ b/docs/sdk/reference/language-bindings/python.md @@ -3,8 +3,8 @@ @@ -61,7 +61,13 @@ print(data.decode()) | Autonomi type | Python type | |------|------| | `HealthStatus` | `antd.HealthStatus` | -| `PutResult` | `antd.PutResult` | +| `PutResult` | `antd.PutResult` for chunk writes | +| `DataPutPublicResult` | `antd.DataPutPublicResult` | +| `DataPutResult` | `antd.DataPutResult` | +| `FilePutPublicResult` | `antd.FilePutPublicResult` | +| `FilePutResult` | `antd.FilePutResult` | +| `PaymentMode` | `antd.PaymentMode` | +| `UploadCostEstimate` | `antd.UploadCostEstimate` | | `WalletAddress` | `antd.WalletAddress` | | `WalletBalance` | `antd.WalletBalance` | | `PrepareUploadResult` | `antd.PrepareUploadResult` | @@ -85,7 +91,7 @@ except AntdError as error: print(error) ``` -REST and gRPC share the same high-level API, but wallet operations and `payment_mode` are REST-only. +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. ## Full API reference diff --git a/docs/sdk/reference/language-bindings/rust.md b/docs/sdk/reference/language-bindings/rust.md index 91d066e..32a597d 100644 --- a/docs/sdk/reference/language-bindings/rust.md +++ b/docs/sdk/reference/language-bindings/rust.md @@ -3,8 +3,8 @@ @@ -40,7 +40,7 @@ For gRPC, the current crate also exports `GrpcClient` and `DEFAULT_GRPC_ENDPOINT For upload examples in this section, start `antd` in a write-enabled mode first. On the default network, that means wallet plus EVM payment configuration. On a local devnet, `ant dev start` provisions that for you. ```rust -use antd_client::{Client, DEFAULT_BASE_URL}; +use antd_client::{Client, DEFAULT_BASE_URL, PaymentMode}; #[tokio::main] async fn main() -> Result<(), Box> { @@ -49,7 +49,9 @@ async fn main() -> Result<(), Box> { let health = client.health().await?; assert!(health.ok); - let result = client.data_put_public(b"Hello from Rust!", None).await?; + let result = client + .data_put_public(b"Hello from Rust!", PaymentMode::Auto) + .await?; println!("{}", result.address); let data = client.data_get_public(&result.address).await?; @@ -63,7 +65,13 @@ async fn main() -> Result<(), Box> { | Autonomi type | Rust type | |------|------| | `HealthStatus` | `antd_client::HealthStatus` | -| `PutResult` | `antd_client::PutResult` | +| `PutResult` | `antd_client::PutResult` for chunk writes | +| `DataPutPublicResult` | `antd_client::DataPutPublicResult` | +| `DataPutResult` | `antd_client::DataPutResult` | +| `FilePutPublicResult` | `antd_client::FilePutPublicResult` | +| `FilePutResult` | `antd_client::FilePutResult` | +| `PaymentMode` | `antd_client::PaymentMode` | +| `UploadCostEstimate` | `antd_client::UploadCostEstimate` | | `WalletAddress` | `antd_client::WalletAddress` | | `WalletBalance` | `antd_client::WalletBalance` | | `PrepareUploadResult` | `antd_client::PrepareUploadResult` | diff --git a/docs/sdk/reference/language-bindings/typescript.md b/docs/sdk/reference/language-bindings/typescript.md index b0f3eb5..0545285 100644 --- a/docs/sdk/reference/language-bindings/typescript.md +++ b/docs/sdk/reference/language-bindings/typescript.md @@ -3,8 +3,8 @@ @@ -34,11 +34,13 @@ const directClient = new RestClient(options); ## Store and retrieve data ```typescript -import { createClient, type PutResult } from "antd"; +import { createClient, type DataPutPublicResult } from "antd"; async function main(): Promise { const client = createClient(); - const result: PutResult = await client.dataPutPublic(Buffer.from("Hello from TypeScript!")); + const result: DataPutPublicResult = await client.dataPutPublic( + Buffer.from("Hello from TypeScript!"), + ); console.log(result.address); const data: Buffer = await client.dataGetPublic(result.address); @@ -56,8 +58,12 @@ main().catch((error) => { | Autonomi type | TypeScript type | |------|------| | `HealthStatus` | `{ ok: boolean; network: string; version: string; evmNetwork: string; uptimeSeconds: number; buildCommit: string; paymentTokenAddress: string; paymentVaultAddress: string }` | -| `PutResult` | `{ cost: string; address: string }` | -| `FileUploadResult` | `{ address: string; storageCostAtto: string; gasCostWei: string; chunksStored: number; paymentModeUsed: string }` | +| `PutResult` | `{ cost: string; address: string }` for chunk writes | +| `DataPutPublicResult` | `{ address: string; chunksStored: number; paymentModeUsed: string }` | +| `DataPutResult` | `{ dataMap: string; chunksStored: number; paymentModeUsed: string }` | +| `FilePutPublicResult` | `{ address: string; storageCostAtto: string; gasCostWei: string; chunksStored: number; paymentModeUsed: string }` | +| `FilePutResult` | `{ dataMap: string; storageCostAtto: string; gasCostWei: string; chunksStored: number; paymentModeUsed: string }` | +| `PaymentMode` | `"auto"`, `"merkle"`, or `"single"` | | `WalletAddress` | `{ address: string }` | | `WalletBalance` | `{ balance: string; gasBalance: string }` | | `PaymentInfo` | `{ quoteHash: string; rewardsAddress: string; amount: string }` | diff --git a/docs/sdk/reference/overview.md b/docs/sdk/reference/overview.md index 77bbeb7..c34f93b 100644 --- a/docs/sdk/reference/overview.md +++ b/docs/sdk/reference/overview.md @@ -3,8 +3,8 @@ @@ -62,9 +62,9 @@ The `antd` REST surface groups into these areas: | Group | Routes | |------|------| | Health | `/health` | -| Data | `/v1/data/public`, `/v1/data/private`, `/v1/data/cost` | -| Chunks | `/v1/chunks`, `/v1/chunks/prepare`, `/v1/chunks/finalize` | -| Files | `/v1/files/upload/public`, `/v1/files/download/public`, `/v1/files/cost` | +| Data | `/v1/data/public`, `/v1/data`, `/v1/data/get`, `/v1/data/cost` | +| Chunks | `/v1/chunks`, `/v1/chunks/{addr}`, `/v1/chunks/prepare`, `/v1/chunks/finalize` | +| Files | `/v1/files/public`, `/v1/files/public/get`, `/v1/files`, `/v1/files/get`, `/v1/files/cost` | | Wallet | `/v1/wallet/address`, `/v1/wallet/balance`, `/v1/wallet/approve` | | External signer flow | `/v1/chunks/prepare`, `/v1/chunks/finalize`, `/v1/data/prepare`, `/v1/upload/prepare`, `/v1/upload/finalize` | diff --git a/docs/sdk/reference/rest-api.md b/docs/sdk/reference/rest-api.md index 17fde9e..ad2d59c 100644 --- a/docs/sdk/reference/rest-api.md +++ b/docs/sdk/reference/rest-api.md @@ -3,8 +3,8 @@ @@ -124,9 +124,9 @@ curl -N http://localhost:8082/v1/data/public//stream ### Store Private Data -**Endpoint:** `POST /v1/data/private` +**Endpoint:** `POST /v1/data` -Stores private data and returns a serialized DataMap instead of a public address. +Stores private data. The DataMap is returned to the caller and is not stored on-network. **Parameters:** @@ -150,22 +150,22 @@ Stores private data and returns a serialized DataMap instead of a public address ```bash DATA_B64=$(printf 'Secret message' | base64) -curl -X POST http://localhost:8082/v1/data/private \ +curl -X POST http://localhost:8082/v1/data \ -H "Content-Type: application/json" \ -d "{\"data\":\"$DATA_B64\"}" ``` ### Get Private Data -**Endpoint:** `GET /v1/data/private` +**Endpoint:** `POST /v1/data/get` -Retrieves private data using the returned DataMap. +Retrieves private data using a caller-held DataMap. Uses POST so the hex-encoded DataMap (which can be many KB) goes in the request body rather than a URL query string. **Parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| -| `data_map` | query | Yes | Hex-encoded serialized DataMap | +| `data_map` | string | Yes | Hex-encoded serialized DataMap | **Response:** @@ -178,7 +178,9 @@ Retrieves private data using the returned DataMap. **Example:** ```bash -curl "http://localhost:8082/v1/data/private?data_map=" +curl -X POST http://localhost:8082/v1/data/get \ + -H "Content-Type: application/json" \ + -d '{"data_map":""}' ``` ### Estimate Data Cost @@ -192,6 +194,7 @@ Estimates the storage cost for a data payload without uploading it. | Name | Type | Required | Description | |------|------|----------|-------------| | `data` | string | Yes | Base64-encoded payload | +| `payment_mode` | string | No | `auto`, `merkle`, or `single` | **Response:** @@ -364,9 +367,9 @@ These endpoints work on paths visible to the machine running `antd`. ### Upload a Public File -**Endpoint:** `POST /v1/files/upload/public` +**Endpoint:** `POST /v1/files/public` -Uploads a local file and stores its DataMap publicly. +Uploads a local file publicly. Also stores the DataMap on-network as an additional chunk and returns its network address. **Parameters:** @@ -390,22 +393,22 @@ Uploads a local file and stores its DataMap publicly. **Example:** ```bash -curl -X POST http://localhost:8082/v1/files/upload/public \ +curl -X POST http://localhost:8082/v1/files/public \ -H "Content-Type: application/json" \ -d '{"path":"/absolute/path/to/document.pdf"}' ``` ### Download a Public File -**Endpoint:** `POST /v1/files/download/public` +**Endpoint:** `POST /v1/files/public/get` -Downloads a file to a local destination path. +Downloads a public file using its on-network DataMap address. **Parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| -| `address` | string | Yes | 64-character hex file address | +| `address` | string | Yes | 64-character hex on-network DataMap address | | `dest_path` | string | Yes | Local destination path | **Response:** HTTP `200 OK` with no JSON body @@ -413,11 +416,67 @@ Downloads a file to a local destination path. **Example:** ```bash -curl -X POST http://localhost:8082/v1/files/download/public \ +curl -X POST http://localhost:8082/v1/files/public/get \ -H "Content-Type: application/json" \ -d '{"address":"<64_hex_address>","dest_path":"/absolute/path/to/downloaded.pdf"}' ``` +### Upload a Private File + +**Endpoint:** `POST /v1/files` + +Uploads a local file privately. The DataMap is returned to the caller and is not stored on-network. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | Local file path | +| `payment_mode` | string | No | `auto`, `merkle`, or `single` | + +**Response:** + +```json +{ + "data_map": "", + "storage_cost_atto": "", + "gas_cost_wei": "", + "chunks_stored": 42, + "payment_mode_used": "auto" +} +``` + +**Example:** + +```bash +curl -X POST http://localhost:8082/v1/files \ + -H "Content-Type: application/json" \ + -d '{"path":"/absolute/path/to/document.pdf"}' +``` + +### Download a Private File + +**Endpoint:** `POST /v1/files/get` + +Downloads a file using a caller-held DataMap (no address lookup required). + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `data_map` | string | Yes | Hex-encoded serialized DataMap | +| `dest_path` | string | Yes | Local destination path | + +**Response:** HTTP `200 OK` with no JSON body + +**Example:** + +```bash +curl -X POST http://localhost:8082/v1/files/get \ + -H "Content-Type: application/json" \ + -d '{"data_map":"","dest_path":"/absolute/path/to/downloaded.pdf"}' +``` + ### Estimate File Cost **Endpoint:** `POST /v1/files/cost` @@ -430,6 +489,7 @@ Estimates upload cost for a local file. |------|------|----------|-------------| | `path` | string | Yes | Local file path | | `is_public` | boolean | No | Defaults to `true` | +| `payment_mode` | string | No | `auto`, `merkle`, or `single` | **Response:** diff --git a/docs/sdk/store-data-on-the-network.md b/docs/sdk/store-data-on-the-network.md index 60a2fae..8c5c084 100644 --- a/docs/sdk/store-data-on-the-network.md +++ b/docs/sdk/store-data-on-the-network.md @@ -3,8 +3,8 @@ @@ -130,12 +130,14 @@ main().catch((error) => { {% endtab %} {% tab title="Rust" %} ```rust -use antd_client::{Client, DEFAULT_BASE_URL}; +use antd_client::{Client, DEFAULT_BASE_URL, PaymentMode}; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::new(DEFAULT_BASE_URL); - let result = client.data_put_public(b"Hello, Autonomi!", None).await?; + let result = client + .data_put_public(b"Hello, Autonomi!", PaymentMode::Auto) + .await?; println!("{}", result.address); Ok(()) @@ -255,13 +257,13 @@ main().catch((error) => { {% endtab %} {% tab title="Rust" %} ```rust -use antd_client::{Client, DEFAULT_BASE_URL}; +use antd_client::{Client, DEFAULT_BASE_URL, PaymentMode}; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::new(DEFAULT_BASE_URL); let original = b"Hello, Autonomi!"; - let result = client.data_put_public(original, None).await?; + let result = client.data_put_public(original, PaymentMode::Auto).await?; let retrieved = client.data_get_public(&result.address).await?; assert_eq!(retrieved, original); diff --git a/skills/start/CHANGELOG.md b/skills/start/CHANGELOG.md index 3a9b813..59b0e24 100644 --- a/skills/start/CHANGELOG.md +++ b/skills/start/CHANGELOG.md @@ -4,6 +4,20 @@ All notable changes to this skill are recorded here. ## [Unreleased] +## [0.1.6-draft] - 2026-05-26 + +### Changed +- Updated shared daemon surfaces: `POST /v1/data/private` renamed to `POST /v1/data`; `GET /v1/data/private` replaced by `POST /v1/data/get` (DataMap now in request body, not query parameter); `POST /v1/files/upload/public` renamed to `POST /v1/files/public`; `POST /v1/files/download/public` renamed to `POST /v1/files/public/get`; added `POST /v1/files` (private file upload) and `POST /v1/files/get` (private file download). +- Corrected the "keep these rules straight" bullet points to reflect the endpoint renames. + +### Verified Against +- ant-sdk: 7a113b390522d76d28b8f3e5b4078f9c9418d46f +- ant-client: e67472424f94acd4b9188a342271210d4ab9f94d +- ant-node: 2a8b91deada5506c72b7d234655119b2ab803d92 +- ant-protocol: 83b6b4e2b12c217fe2728cd6bd9d923e50b86708 +- self_encryption: 0deb040084f94bea2ebb53bda20fa23464bbcfe0 +- evmlib: 225acbb1af613193bcc8264b6ede4d7e4a7ac607 + ## [0.1.5-draft] - 2026-05-16 ### Changed diff --git a/skills/start/SKILL.md b/skills/start/SKILL.md index 74dfd93..406c2b4 100644 --- a/skills/start/SKILL.md +++ b/skills/start/SKILL.md @@ -8,7 +8,7 @@ description: | in Rust with `ant-core`, or expose Autonomi through an MCP-compatible client. Do not use for Autonomi 1.0, the MaidSafe-era network, `ant-quic`, or general EVM work that is not part of building on Autonomi. -version: 0.1.5-draft +version: 0.1.6-draft license: MIT repository: https://github.com/WithAutonomi/autonomi-developer-docs homepage: https://docs.autonomi.com/developers @@ -29,13 +29,13 @@ keywords: - read-only # Verification block. Re-verify before changing stable claims or examples. -verified_date: "2026-05-18" +verified_date: "2026-05-26" verification_mode: current-merged-truth verified_commits: - ant-sdk: a3cf4e40052e3af8d1e8029ca0b3c97281d14108 - ant-client: 3df6764298b10dcc51287f43b1b5742a25785bff - ant-node: f38fdcacbeb3318e4524f4534e2d5bd87dcca467 - ant-protocol: cbaf710dc51c7e436120ced5d60f07b0aa14a8ee + ant-sdk: 7a113b390522d76d28b8f3e5b4078f9c9418d46f + ant-client: e67472424f94acd4b9188a342271210d4ab9f94d + ant-node: 2a8b91deada5506c72b7d234655119b2ab803d92 + ant-protocol: 83b6b4e2b12c217fe2728cd6bd9d923e50b86708 self_encryption: 0deb040084f94bea2ebb53bda20fa23464bbcfe0 evmlib: 225acbb1af613193bcc8264b6ede4d7e4a7ac607 @@ -149,9 +149,13 @@ Current shared daemon surfaces you can rely on at this commit: - `GET /health` - `POST /v1/data/public` - `GET /v1/data/public/{addr}` -- `POST /v1/data/private` -- `GET /v1/data/private` +- `POST /v1/data` +- `POST /v1/data/get` - `POST /v1/data/cost` +- `POST /v1/files/public` +- `POST /v1/files/public/get` +- `POST /v1/files` +- `POST /v1/files/get` - `POST /v1/files/cost` - `GET /v1/wallet/address` - `GET /v1/wallet/balance` @@ -178,8 +182,8 @@ Keep these rules straight: - REST binary payloads are base64 inside JSON. - `POST /v1/data/public` returns a public address. -- `POST /v1/data/private` returns a serialized `DataMap`. -- `GET /v1/data/private` needs the `data_map` query parameter. +- `POST /v1/data` returns a serialized `DataMap` (the DataMap is not stored on-network). +- `POST /v1/data/get` retrieves private data; pass `data_map` in the JSON body (not a query parameter). - read-only daemon work does not require `AUTONOMI_WALLET_KEY` Current documented binding entry points: diff --git a/skills/start/version.json b/skills/start/version.json index b11bb27..2d69fb5 100644 --- a/skills/start/version.json +++ b/skills/start/version.json @@ -1,17 +1,17 @@ { "skill": "start", - "version": "0.1.5-draft", - "published_date": "2026-05-16", + "version": "0.1.6-draft", + "published_date": "2026-05-26", "status": "draft", "canonical_skill_url": "https://raw.githubusercontent.com/WithAutonomi/autonomi-developer-docs/main/skills/start/SKILL.md", "canonical_docs_url": "https://docs.autonomi.com/developers", "repository": "https://github.com/WithAutonomi/autonomi-developer-docs", "verification_mode": "current-merged-truth", "verified_commits": { - "ant-sdk": "a3cf4e40052e3af8d1e8029ca0b3c97281d14108", - "ant-client": "3df6764298b10dcc51287f43b1b5742a25785bff", - "ant-node": "f38fdcacbeb3318e4524f4534e2d5bd87dcca467", - "ant-protocol": "cbaf710dc51c7e436120ced5d60f07b0aa14a8ee", + "ant-sdk": "7a113b390522d76d28b8f3e5b4078f9c9418d46f", + "ant-client": "e67472424f94acd4b9188a342271210d4ab9f94d", + "ant-node": "2a8b91deada5506c72b7d234655119b2ab803d92", + "ant-protocol": "83b6b4e2b12c217fe2728cd6bd9d923e50b86708", "self_encryption": "0deb040084f94bea2ebb53bda20fa23464bbcfe0", "evmlib": "225acbb1af613193bcc8264b6ede4d7e4a7ac607" },