> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/reference/sdk/walrus.md).

# Walrus Storage and Shared Wallet

**Audience:** Rust application and Tool developers using external blob storage.

**Area:** Shared wallet, Walrus storage, references, and execution data limits.

**Generated from:** Nexus SDK tagged source `v2.1.1`, commit `08bfe76e726922ce512d623fbc1d2e1bd786bcd4`, `sdk/src/nexus/wallet.rs`, `sdk/src/walrus`, `sdk/src/execution_limits.rs`, and `walrus/src/lib.rs`.

### Dependencies and wallet

The SDK `full` feature includes readers and protocol references. Wallet-funded uploads and ownership management use the separate `nexus-walrus` adapter, distributed through Git because its upstream Walrus dependencies are not on crates.io. Use published `nexus-sdk = "=2.1.1"` from crates.io and add the adapter to the existing dependency table. No SDK source override or registry patch is required. Follow [Native Walrus storage setup](/guides/getting-started/setup.md#native-walrus-storage) for the SDK features and add:

```toml
nexus-walrus = { git = "https://github.com/Talus-Network/nexus-sdk", tag = "v2.1.1" }
```

The adapter needs a C++ compiler and libclang. `nexus::wallet::WalletClient` owns one signing key and RPC connection. Obtain it from `NexusClient::wallet()`, or connect a standalone wallet with `WalletClient::connect(rpc_url, key)` and share it with `NexusClient::builder().with_wallet(wallet)`. The SDK does not create a second key store or invoke a wallet executable. Keep signing in the application's protected service boundary.

```rust
use nexus_walrus::{UploadOptions, WalrusStorage};

// Inside an async function with a configured, signing NexusClient named client.
let storage = WalrusStorage::new(client.wallet()?.clone(), None).await?;
let stored = storage.upload(
    serde_json::to_vec(&result)?,
    UploadOptions { epochs: 5, ..Default::default() },
).await?;
let output_port = stored.nexus_data()?;
```

The connected Sui chain selects Testnet or Mainnet. The wallet pays WAL for storage and SUI for gas and owns the Blob object. `max_storage_cost_frost` checks an estimate before transaction construction; the actual WAL charge may differ as prices change. `gas_budget_mist` bounds each Sui transaction. Uploads are permanent until expiry unless explicitly deletable. Only the owner can extend a Blob or delete a deletable Blob.

### Upload lifecycle and recovery

The adapter prepares and encodes bytes, registers storage, uploads to storage nodes, certifies the blob on Sui, and verifies aggregator readback before returning `StoredBlob`.

| API or value                          | Application responsibility                                         |
| ------------------------------------- | ------------------------------------------------------------------ |
| `prepare` / `PreparedUpload`          | Validate bytes and review the storage quote.                       |
| `registration` / `UploadRegistration` | Persist the signed registration before submitting it.              |
| `register` / `PendingUpload`          | Persist the confirmed registration before completing upload.       |
| `finish` / `StoredBlob`               | Complete certification and readback, then save the reference.      |
| `upload` / `UploadError`              | Convenience path; retain returned recovery information on failure. |

Applications that can restart or cancel an operation should persist each phase themselves. An uncertain submission must retry or reconcile the saved signed transaction, not construct another registration. Saved signatures are checked before submission. This avoids purchasing storage twice while preserving transaction identity.

`WalrusReference` is a portable local receipt containing network/chain identity, cardinality, blob IDs, digests, sizes, owner/object IDs, expiry epochs, and deletion policy. It carries no endpoint or wallet configuration. Only `NexusValue::WalrusData` blob IDs and digests enter Nexus protocol inputs and outputs. A reference does not guarantee that storage has not expired or been deleted.

#### Upload succeeded but the invocation failed

A completed paid upload survives a Tool timeout, rejected result, or failed Task submission. The Toolkit performs no automatic Blob cleanup. Preserve the `StoredBlob` or portable reference and upload recovery records, then inspect content, owner, expiry, and the Invocation outcome before retrying. Reuse retained data when the application can safely do so instead of assuming the failed invocation removed it.

Before cleanup, establish that no scheduled occurrence or accepted result still depends on the Blob. Its owner may delete it only if it was uploaded as deletable; otherwise it remains until expiry. Do not infer an Invocation refund or storage refund from a Tool failure. See [Walrus CLI](/reference/cli/walrus.md) for inspection and owner operations.

### Reads, task planning, and limits

`WalrusReader` needs an aggregator but no signing key. It bounds downloads and verifies SHA256. Resolving a reference produces transient execution bytes while preserving the exact commitment, including JSON whitespace. `TaskInputPlan` validates selectors and port shapes, supplies preflight inputs, verifies reusable references, and checks that uploaded results commit to the intended bytes. Call `Scheduler::preflight_task_inputs` against the published DAG before materializing uploads.

| Constant                                    | Value  | Scope                                                                              |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------- |
| `execution_limits::MAX_RESOLVED_DATA_BYTES` | 8 MiB  | One invocation's complete input set or complete output set, with separate budgets. |
| `execution_limits::MAX_INVOKE_BODY_BYTES`   | 12 MiB | Default HTTP request admission, including base64 and metadata.                     |

Every inline or downloaded byte counts, including each value of a `Many` port; object IDs count as 32 bytes. The budget is per invocation, not per DAG. An explicit Toolkit HTTP limit is preserved and does not change the resolved-data budget. Published Move inline, port, and encoded-output bounds remain unchanged. Sui Tools must still fit transaction limits.

For large Tool outputs, upload before returning and override `NexusTool::encode_output` to expose protocol ports; see [Toolkit Rust](/reference/toolkit/rust.md#explicit-output-encoding-and-failure-boundaries). The Leader reads and validates references; it does not upload or own the blob. Upgrade receiving Tool runtimes before sending the exact-byte transport used by large or formatting-sensitive values.

Storage expiry is independent of Task lifetime. Retain data for all future occurrences and extend it before expiry. Walrus is public storage, not encryption. Next, inspect a saved reference with the [Walrus CLI](/reference/cli/walrus.md) before creating dependent work.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.talus.network/reference/sdk/walrus.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.