Build with AI

These docs are written to be read by AI coding agents as well as people. The dStorage SDK is new and its API changes between versions, so an agent working from what it remembers will often get it wrong. Point it at these docs instead, and it works from the current API.

Point your agent at the docs

Every page is also published as plain Markdown for agents:

llms.txt — an index of every page, with links to their Markdown versions. Start here.
llms-full.txt — the whole docs in one file, for agents that work best with everything in context at once.
A Markdown copy of each page — the page URL with .md instead of .html, e.g. /docs/guide/mock-adapters.md.

Some agents' fetch tools can't read the .md copies. If yours can't, give it the normal page URL or llms-full.txt instead.

Add the docs to your project's agent instructions

Most coding agents read a project instructions file on every run: AGENTS.md (Codex, Cursor and others), CLAUDE.md (Claude Code) or .cursor/rules. Add this to yours, so the agent checks these docs whenever it touches dStorage code, without you having to remind it:

## dStorage SDK

This project uses @dstorage-tech/dstorage-sdk. Its API changes between versions, so don't rely
on prior knowledge of it. Before writing or changing dStorage code, read the docs:

- Docs index: https://dstorage.pro/docs/llms.txt
- Full docs in one file: https://dstorage.pro/docs/llms-full.txt

Check the SDK version installed in package.json, and flag anything in the docs that doesn't
match it.

Ask about any page

The Copy page for AI button in the top bar copies the current page as Markdown. Its menu can also open the page in Claude or ChatGPT, ready for you to ask questions about it — handy for the FAQ and Features pages.

A prompt for every guide

Each guide starts with a ready-made prompt that has your agent follow it in your own project, ending with a check that it worked. They're collected here in the same order as the guides, each building on the one before:

Use the dStorage SDK docs as your source of truth, not prior knowledge: the SDK is new and its API changes between versions. The docs index is https://dstorage.pro/docs/llms.txt and the full docs are in https://dstorage.pro/docs/llms-full.txt.

Read the "Mock Adapters" guide at https://dstorage.pro/docs/guide/mock-adapters.md (if that URL can't be fetched, use the HTML page at https://dstorage.pro/docs/guide/mock-adapters.html or the full docs in https://dstorage.pro/docs/llms-full.txt instead), then follow it in my current project:

1. Install @dstorage-tech/dstorage-sdk (requires Node.js 22 or later).
2. Configure DStorage with MockStorageAdapter, MockChainAdapter and PasswordEncryptionAdapter, exactly as the guide shows.
3. Add a small script that calls init(), stores the string "hello, dStorage", retrieves it with retrieveByRefId(), prints the decoded result, and calls destroy().
4. Run the script and confirm it prints "hello, dStorage".

If anything in my project conflicts with the guide (module system, Node.js version, existing dStorage setup), explain the conflict before changing anything.

Use the dStorage SDK docs as your source of truth, not prior knowledge: the SDK is new and its API changes between versions. The docs index is https://dstorage.pro/docs/llms.txt and the full docs are in https://dstorage.pro/docs/llms-full.txt.

Read the "Core Concepts" guide at https://dstorage.pro/docs/guide/core-concepts.md (if that URL can't be fetched, use the HTML page at https://dstorage.pro/docs/guide/core-concepts.html or the full docs in https://dstorage.pro/docs/llms-full.txt instead), then look at how my current project uses the dStorage SDK and explain, in terms of my own code:

1. Which encryptionAdapters protect each upload's DEK, and which of them could unlock my data on their own.
2. Where my code gets a refId and where it gets a storageId, and whether I'm storing the right one for later retrieval.
3. Which storageAdapters and chainAdapters I've configured, in what fallback order, and whether I'm in storage-only mode.
4. Exactly what my uploads put on-chain and what they put on the storage network.

Point to file and line for each answer. Don't change any code; if something looks wrong against the guide, list it at the end as a suggestion.

Use the dStorage SDK docs as your source of truth, not prior knowledge: the SDK is new and its API changes between versions. The docs index is https://dstorage.pro/docs/llms.txt and the full docs are in https://dstorage.pro/docs/llms-full.txt.

Read the "Local & Simulator Adapters" guide at https://dstorage.pro/docs/guide/local-simulator-adapters.md (if that URL can't be fetched, use the HTML page at https://dstorage.pro/docs/guide/local-simulator-adapters.html or the full docs in https://dstorage.pro/docs/llms-full.txt instead), then follow it in my current project:

1. Make sure arlocal is running on port 1984 (Docker or npx, as the guide shows).
2. Replace MockStorageAdapter with ArweaveLocalStorageAdapter.createWithTestWallet() and MockChainAdapter with MidnightSimulatorChainAdapter. Keep PasswordEncryptionAdapter as it is.
3. Run the init() / store() / retrieveByRefId() round trip with the string "hello, dStorage" and confirm it prints that string back.
4. Show me the chainRefId and storageId you got, and confirm that the chainRefId is a 32-byte hex ID.

Before running anything, check whether the local services the guide needs are already running and tell me which ones you need me to start. If anything in my project conflicts with the guide (module system, Node.js version, existing dStorage setup), explain the conflict before changing anything.

Use the dStorage SDK docs as your source of truth, not prior knowledge: the SDK is new and its API changes between versions. The docs index is https://dstorage.pro/docs/llms.txt and the full docs are in https://dstorage.pro/docs/llms-full.txt.

Read the "Managed Payments Service" guide at https://dstorage.pro/docs/guide/managed-payments-service.md (if that URL can't be fetched, use the HTML page at https://dstorage.pro/docs/guide/managed-payments-service.html or the full docs in https://dstorage.pro/docs/llms-full.txt instead), then follow it in my current project, starting from the Local & Simulator Adapters setup:

1. Make sure arlocal is running on port 1984.
2. Create a single managedPayment config object (signingServerUrl "https://portal.dstorage.pro", testMode: true) and pass it to both ArweaveLocalStorageAdapter.createWithTestWallet() and MidnightSimulatorChainAdapter.
3. Run the init() / store() / retrieveByRefId() round trip with the string "hello, dStorage" and confirm it prints that string back.
4. Tell me to check the dStorage Pro portal, where this store() should show up as two TEST payments: one for storage and one for the chain.

Don't hard-code my dStorage Pro token: read it from an environment variable, add a placeholder for it to .env.example, and make sure the real .env file is git-ignored. If the token isn't set, stop and ask me for it. Before running anything, check whether the local services the guide needs are already running and tell me which ones you need me to start. If anything in my project conflicts with the guide (module system, Node.js version, existing dStorage setup), explain the conflict before changing anything.

Use the dStorage SDK docs as your source of truth, not prior knowledge: the SDK is new and its API changes between versions. The docs index is https://dstorage.pro/docs/llms.txt and the full docs are in https://dstorage.pro/docs/llms-full.txt.

Read the "Midnight Network Adapter" guide at https://dstorage.pro/docs/guide/midnight-network-adapter.md (if that URL can't be fetched, use the HTML page at https://dstorage.pro/docs/guide/midnight-network-adapter.html or the full docs in https://dstorage.pro/docs/llms-full.txt instead), then follow it in my current project. This guide runs in the browser with Vite:

1. Make sure arlocal is running on port 1984, and start the Midnight proof server Docker image on port 6300 with the exact image tag the guide uses.
2. Copy the SDK's DataRegistry keys/ and zkir/ folders into public/, as the guide shows, and add a script so this happens on every dev run.
3. Import from @dstorage-tech/dstorage-sdk/browser and configure MidnightChainAdapter in "connector" mode for the preprod network. Keep ArweaveLocalStorageAdapter and PasswordEncryptionAdapter.
4. Wire init() / store() / retrieveByRefId() to a Run button, logging the contract address and the decoded "hello, dStorage" result.
5. Make the contract address configurable, so I can paste the one from my first run and reconnect to that contract instead of deploying a new one.

You can't drive my wallet extension: when it's time to click Run, tell me what to check first (wallet switched to Preprod, funded with DUST from the Preprod faucet) and what output to expect. Before running anything, check whether the local services the guide needs are already running and tell me which ones you need me to start. If anything in my project conflicts with the guide (module system, Node.js version, existing dStorage setup), explain the conflict before changing anything.

Use the dStorage SDK docs as your source of truth, not prior knowledge: the SDK is new and its API changes between versions. The docs index is https://dstorage.pro/docs/llms.txt and the full docs are in https://dstorage.pro/docs/llms-full.txt.

Read the "Passkey Encryption" guide at https://dstorage.pro/docs/guide/passkey-encryption.md (if that URL can't be fetched, use the HTML page at https://dstorage.pro/docs/guide/passkey-encryption.html or the full docs in https://dstorage.pro/docs/llms-full.txt instead), then follow it in my current project, starting from the Midnight Network Adapter browser app:

1. Check WebAuthnPrfEncryptionAdapter.isSupported() and show a clear message if PRF isn't available.
2. Call register() on the first visit and authenticate() on later visits, and persist the credentialId in localStorage as the guide shows.
3. Replace PasswordEncryptionAdapter with the passkey adapter in encryptionAdapters. Leave the storage and chain adapters unchanged.
4. Keep the existing Run button flow (init() / store() / retrieveByRefId()) working with the passkey adapter.

You can't complete passkey prompts for me: tell me when to run the app, what browser and authenticator prompts to expect, and how to test a returning visit by reloading the page. If anything in my project conflicts with the guide (module system, Node.js version, existing dStorage setup), explain the conflict before changing anything.

Use the dStorage SDK docs as your source of truth, not prior knowledge: the SDK is new and its API changes between versions. The docs index is https://dstorage.pro/docs/llms.txt and the full docs are in https://dstorage.pro/docs/llms-full.txt.

Read the "Managed Payments on Midnight" guide at https://dstorage.pro/docs/guide/managed-payments-midnight.md (if that URL can't be fetched, use the HTML page at https://dstorage.pro/docs/guide/managed-payments-midnight.html or the full docs in https://dstorage.pro/docs/llms-full.txt instead), then follow it in my current project, starting from the Midnight Network Adapter browser app:

1. Make sure arlocal (port 1984) and the Midnight proof server (port 6300) are running, as in the Midnight Network Adapter guide.
2. Add a managedPayment config object (signingServerUrl "https://portal.dstorage.pro") to MidnightChainAdapter only. Leave ArweaveLocalStorageAdapter and PasswordEncryptionAdapter unchanged.
3. Keep the existing Run button flow (init() / store() / retrieveByRefId()) working.

This app runs in the browser, so it must use a JWT token from the portal, never a ds_* secret token. If you find a ds_* token in my config, stop and warn me. Don't hard-code my dStorage Pro token: read it from an environment variable, add a placeholder for it to .env.example, and make sure the real .env file is git-ignored. If the token isn't set, stop and ask me for it. Tell me when to click Run, and point out that my wallet only needs to be on Preprod: it doesn't need any DUST or NIGHT. Before running anything, check whether the local services the guide needs are already running and tell me which ones you need me to start. If anything in my project conflicts with the guide (module system, Node.js version, existing dStorage setup), explain the conflict before changing anything.

Prefer a working app to start from? Clone dstorage-starter-template and run the prompts against it.

Tips

Review what the agent changes, especially anything touching keys, passwords or tokens.
Never paste a ds_* secret token into a prompt or browser code. Keep tokens in environment variables; in the browser, use a scoped JWT token (see Managed Payments).
Steps that need you — approving wallet prompts, passkey ceremonies, creating a dStorage Pro token — can't be done by the agent. The prompts tell it to stop and ask you at those points.

Build with AI ​

Point your agent at the docs ​

Add the docs to your project's agent instructions ​

Ask about any page ​