This is the full developer documentation for Polkadot Developers # Apps > Build Polkadot Products, sandboxed apps that run inside the Polkadot Hosts, addressed by .dot domain names, and signed by the user's phone. ## Get the Polkadot App The Polkadot App is your wallet, identity, and signer: the center of everything you build. Install it first; every path below connects through it. [App Store — Coming soon]() [Android (APK)](https://github.com/paritytech/trinity-user-agents/releases/tag/nightly-android) The Android build is a nightly APK published by Parity, so you install it from the release page rather than from Google Play. The release offers two APKs: * **`app-gp-nightly.apk`**: For devices with Google Play services. * **`app-vanilla-nightly.apk`**: For devices without Google Play services. Android blocks APKs from outside an app store by default. When prompted, allow the app you downloaded the APK with, such as your browser or file manager, to install unknown apps, then open the APK to install it. Products Devnet PCF publishes separate app builds for the Products Devnet (`devnet` preset): see [More resources](/apps/reference/resources/). ## Then Pick Your Path * **Deploy Your First Product** *** Go from nothing to a live `.dot` Product: generate one in the browser with RevX, or deploy from the terminal with the CLI. No local host setup to reach a live deployment. [→ Quick Start](/apps/quick-start/) * **Develop Locally (the Full Route)** *** Install Polkadot Desktop, pair it with your phone, and get TestNet tokens, then build your Product capability by capability. [→ Get Started](/apps/get-started/) ## What Is a Polkadot Product? *Polkadot Products* are what *you* build: third-party applications that run *inside* one of the Polkadot Apps. Products are sandboxed single-page apps (HTML / JS / CSS), addressed by `.dot` names (e.g., `awesome.dot`), registered on-chain through a decentralized name service, and they never see the user's private key. The bundle itself is published to a decentralized cloud storage provider and fetched by the Host on demand. *Polkadot Apps* are the three applications that can host Polkadot Products, collectively known as the *Polkadot Triangle*: * **[Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/)**: The workstation host. Loads Polkadot Products by their `.dot` name and runs them in a sandbox. * **[Polkadot App](/reference/apps/hosts/polkadot-app/)**: The mobile wallet and signer. Holds the user's private key and approves every signing request. * **[Polkadot Web](/reference/apps/hosts/polkadot-web/)**: The browser host at `dot.li`. Resolves `.dot` names client-side via a light client and renders the Product in a sandboxed iframe. You build Polkadot Products. They run inside one of the Polkadot Apps. This section teaches you how. ![The Polkadot Triangle: Polkadot Desktop at the top, Polkadot App at the bottom-left, Polkadot Web at the bottom-right, with Polkadot Product running inside](/images/apps/index/polkadot-triangle.svg) For the architectural breakdown covering how the Product, SDK, Host, and Polkadot infrastructure relate, see the [App Development Reference](/reference/apps/). ## Why Build a Polkadot Product? Polkadot Apps is a complete environment for building Web3 decentralized applications: **Wallet built-in**: The Polkadot App on the user's phone is the wallet for every Polkadot Product they use. No wallet integration code, no "Connect Wallet" button to design, no signing plumbing to maintain. Your Product receives a derived per-user account and asks for signatures; approvals happen on the user's phone. **Identity built-in**: Per-Product accounts are derived from the user's `.dot` identity, so there is no signup flow. With [Proof of Personhood](/reference/apps/infrastructure/pop/), you can gate features on verified-human status without seeing who the user is, a privacy-preserving humans-only access model built into the platform. Need to recognize the same user across two of your Products? Same alias system, scoped to your Product set. **Decentralized hosting**: Your bundle lives on a decentralized cloud storage provider. Your `.dot` name lives in a decentralized name service. There is no centralized hosting provider, no DNS service, no platform in the middle. Users fetch your Product directly and verify it themselves. **Product SDK**: The [Product SDK](/apps/product-sdk/) covers what you would otherwise integrate yourself: * **Chain access**: Query state and submit transactions through the Host. No RPC servers to operate; signing prompts open on the user's phone. * **Decentralized storage**: Upload files, get a permanent content-addressed URL. * **Real-time signed messaging**: Pub/sub between users of your Product via the [Statement Store](/reference/apps/infrastructure/statement-store/), every message verifiable. * **Smart contracts**: Call `pallet-revive` contracts on Asset Hub, resolved by name and typed from a manifest (deployed with the Contract Dependency Manager). * **Privacy-preserving payments**: Request, top up, track status. Built on [Coinage](/reference/apps/infrastructure/pop/pallet-coinage/). * **Chat**: Rooms, bots, interactive action buttons. * **Identity**: Derived per-Product accounts, plus optional [Proof of Personhood](/reference/apps/infrastructure/pop/) gating. * **Local storage**: Per-Product key/value, persisted on the user's device. Permissions (microphone access, outbound network requests, on-chain transaction submission, and more) are declared in your Product's [manifest](/reference/apps/hosts/polkadot-desktop/permissions/) and prompted at runtime. Users see exactly what your Product can access before they grant it. The Host enforces the boundary inside its [sandbox](/reference/apps/protocol/truapi/sandbox/), not your code. **Three Hosts, one Product**: The same `.dot` bundle runs in the mobile Polkadot App, on the workstation in Polkadot Desktop, and in any browser via Polkadot Web. You do not write three apps; the Triangle abstracts the platform. # Architecture overview On the Polkadot Products Devnet, web apps are named, published and opened through Polkadot infrastructure. People open them in the Polkadot app or through the web gateway at [dev-dot.li](https://dev-dot.li). Either way, the app runs on the user's device in a sandboxed container. This page follows one request, a user opening a `.dot` app, from the name to chain storage and back. Each subsystem has its own page with the details. ## The pieces * The network: a community-operated [Paseo](/apps/architecture/network/) relay chain plus system parachains. App developers target Asset Hub (para 1000), which runs `pallet-revive` (PolkaVM/EVM contracts, chain id `420420417`), the `pallet-assets` suite and the DotNS gateway pallet. Identity lives on the People chain (para 1004). Web-app bundles live on the Bulletin chain (para 1010). * The client tier: three native [Polkadot app](/apps/architecture/client/) clients (Android, iOS, Desktop/Web). They hold keys on the device and host dApps in a sandboxed webview, talking to them over a shared protocol, TrUAPI. * Naming: [DotNS](/apps/architecture/naming/), a set of PolkaVM contracts that turn a `.dot` domain into an owner, a resolver and a content hash. * App delivery: the [`pad` CLI](/apps/architecture/app-delivery/) uploads a static bundle to Bulletin and binds its CID to a `.dot` domain. The [dotli gateway](/apps/architecture/app-delivery/) resolves and renders it. * Storage & data: one content-addressed [Bulletin store](/apps/architecture/storage/) holds both app bundles and app runtime data (through Cloud Storage). Writes need an authorization, and reads are open. * Smart contracts: [contracts](/apps/architecture/contracts/) are PolkaVM bytecode running on `pallet-revive` on Asset Hub. * Identity & personhood: [proof-of-personhood](/apps/architecture/identity/) tiers (Lite and Full) and a precompile any contract can read. * Money: [CASH](/apps/architecture/money/), a devnet "digital dollar" spent through the privacy-preserving Coinage system on the People chain. * Discovery: [Browse](/apps/architecture/discovery/), an on-chain publisher registry of listable apps. * Messaging: [chat and calls](/apps/architecture/messaging/) carried over the People-chain statement store, with media on Bulletin and WebRTC for calls. ## System diagram ``` flowchart TD subgraph Clients["Entry points"] APP["Polkadot app
(Android / iOS / Desktop)"] GW["Web gateway
dev-dot.li"] end subgraph Dev["Developer tooling (npm)"] SDK["@parity/product-sdk"] PAD["polkadot-app-deploy (pad)"] DOTNS["@polkadot-community-foundation/dotns-cli"] end subgraph Net["Devnet"] AH["Asset Hub (1000)
pallet-revive + assets
DotNS contracts"] PEOPLE["People (1004)
identity + personhood
Coinage + statement store"] BULLETIN["Bulletin (1010)
app bundles + chat media"] end APP -->|TrUAPI| SDK GW -->|smoldot light client| AH SDK -->|host-routed RPC| AH SDK --> PEOPLE SDK --> BULLETIN PAD -->|upload bundle| BULLETIN PAD -->|register name + contenthash| AH DOTNS -->|reserve .dot| AH AH -.->|contenthash = CID| BULLETIN PEOPLE -.->|ring roots via XCM| AH ``` ## Request path: opening a `.dot` app Take a user opening `calculator.dot`. The steps are much the same on the web gateway and in the app's browser. What differs is who you have to trust. 1. Address to label. On the web, the user visits `https://calculator.dev-dot.li`, and the dotli host takes the registrable root and the label `calculator` from the subdomain. In the app, the user types `calculator.dot` into the browser bar. 2. Name to content hash. The client computes the ENS-style namehash of `calculator.dot` (`keccak256(DOT_NODE, keccak256("calculator"))`) and reads `contenthash(node)` from the DotNS ContentResolver contract on Asset Hub. The web gateway does this without trusting a server: it reads contract storage directly through an in-browser smoldot light client, so there is no RPC server in the path. 3. Content hash to CID. The `contenthash` bytes (`0xe301` + CIDv1) decode to an IPFS CID that points at the app bundle. 4. Fetch the bundle. The content comes from the Bulletin chain (through smoldot `bitswap_v1_get`, shown as verified) or from an IPFS gateway. A directory arrives as a CAR archive, which is parsed into a file map and served by a Service Worker virtual filesystem. 5. Render in a sandbox. The bundle runs inside a sandboxed iframe (web) or a platform webview (app). The host opens a TrUAPI channel to it. The gateway runs the TrUAPI core (`@parity/truapi-host`) in a Web Worker and hands the iframe a `MessagePort`, and the native apps run the same core. The Product's TrUAPI client (`@parity/truapi`, used by the Product SDK) talks over that channel. 6. App talks to the host. Over TrUAPI the dApp asks for accounts, permissions, signatures and chain connections. All chain RPC goes through the host container (the Product SDK is built to run inside it), so the app never manages its own node connections or keys. Keys on the device sign, and the user approves each signature in a native modal. From here the running app draws on the rest of the platform: it calls [contracts](/apps/architecture/contracts/) on Asset Hub, reads a caller's [personhood tier](/apps/architecture/identity/) from the precompile at `0x…0a010000`, or moves [CASH](/apps/architecture/money/). Messaging and calls run over the same [People-chain statement store](/apps/architecture/messaging/) the app already uses. ## Where to go next * New here? Start with [Get started as a developer](/apps/get-started/developers/). * Building an app? Read [App delivery](/apps/architecture/app-delivery/), then [Build & publish an app](/apps/build/build-and-publish/). * Looking for addresses and endpoints? See [Reference](/apps/reference/). # App delivery This page follows a built frontend on its way to becoming a live app on the Polkadot Products Devnet. You publish a static bundle with the `pad` CLI, the content is stored on the Bulletin chain, a `.dot` domain is bound to it, and people load it through the `dev-dot.li` gateway or the Polkadot app. No server sits between a user and an app. The content lives on-chain (Bulletin), the pointer to it lives on-chain (a `.dot` domain resolver on Asset Hub), and the loader is a program on the user's device that reads both directly. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Deploy Your App](/apps/deploy-your-app/). ## Publishing and opening Delivery has a write side (publishing) and a read side (opening). The publisher uploads a bundle and binds a name to it once. Every visitor then resolves and fetches that bundle independently. ``` flowchart TD A[Built static app] --> B[pad CLI prepares bundle] B --> C[Upload content to Bulletin] C --> D[Receive content CID] D --> E{DotNS on Asset Hub} E -->|not owned| G[register name] E -->|owned| H[use existing name] G --> I[write contenthash] H --> I I --> J[optional Browse listing] J --> K[Live: name.dot in app + https://name.dev-dot.li] ``` ## Publishing with `pad` The deploy CLI is [`@polkadot-community-foundation/polkadot-app-deploy`](https://www.npmjs.com/package/@polkadot-community-foundation/polkadot-app-deploy), which ships the `pad` binary (alongside `polkadot-app-deploy` and `polkadot-app-bootstrap`). `pad` selects a network with `--env devnet`. Once your frontend is built, publishing it is a single command over the output directory: ```bash pad ./dist my-app.dot --env devnet --mnemonic "$MNEMONIC" ``` The CLI merkleizes the build directory into a content-addressed DAG-PB archive, chunks it (\~2 MiB) and uploads the blocks to Bulletin via `TransactionStorage.store_with_cid_config`. It then writes the resulting root CID as an ENS-style `contenthash` (`0xe301` + CIDv1) into the DotNS `ContentResolver` on Asset Hub. Re-publishing the same app skips unchanged blocks and updates the name to point at the new content. ### Bulletin storage and upload authorization Content is stored on the Bulletin chain. Uploads work by authorization, not by fees: the uploading account needs an upload quota, but does not pay devnet tokens for each bundle. An authorizer grants the quota via `authorize_account`. The account that signs the deploy is the one that uploads, so that is the account that needs the quota. [Get storage authorization](/apps/build/build-and-publish/#get-storage-authorization) has the practical steps. This is separate from the token [faucet](/apps/reference/networks/#faucet), which only provides native tokens for fees. The same authorization model applies to every write to Bulletin. [Storage & data](/apps/architecture/storage/#how-storage-authorization-works) explains why writes are gated, why this Devnet keeps it open, and that authorizations are finite and expire. ### Binding the `.dot` domain Once the content CID exists, the CLI checks whether the signer owns the `.dot` name. If the name is available, it can register it. If the signer already owns it, the CLI updates the name's content hash. That one on-chain record is what turns a name into an app. [Naming (DotNS)](/apps/architecture/naming/) explains ownership and resolution. A deploy config can also publish manifest records. Product apps use those records to describe executables, labels and icons to the host. ## Opening an app through the gateway The web gateway at is a loader that runs in the browser. There is no resolution server: the host shell reads the label from the subdomain, resolves it, fetches the content and renders it in a sandboxed iframe. ``` flowchart TD U[User opens calculator.dev-dot.li] --> H[Gateway reads label] H --> R[Resolve calculator.dot] R --> C[Read contenthash] C --> D[Decode to CID] D --> IF[Render app in sandbox] IF --> FE{Fetch content} FE -->|Bulletin / light client| V[Verified path] FE -->|IPFS gateway| T[Gateway path] V --> RN[App talks to the host over TrUAPI] T --> RN ``` The rendered app talks to the host through a bridge for accounts, signing, chain connection and scoped storage. For the user, the same name works in both places: on the web it is `https://.dev-dot.li`, and in the Polkadot app it is `.dot`. ## Common blockers * **Upload fails.** The deploy account may need Bulletin storage authorization. * **The name cannot be updated.** The signer must own the `.dot` domain. * **The app opens but has stale content.** Confirm the name's content hash points to the latest CID and that the gateway is resolving the expected network. ## Learn more * [polkadot-app-deploy](https://github.com/Polkadot-Community-Foundation/polkadot-app-deploy): source for the `pad` CLI * [dotli-community](https://github.com/paritytech/dotli-community): the gateway loader * [Build & publish an app](/apps/build/build-and-publish/): publish one yourself # The Polkadot app (client tier) The Polkadot app is how people reach the Polkadot Products Devnet. It keeps keys on the user's device and brings identity, chat, payments and a browser for `.dot` apps into one app. This page covers the mobile and desktop clients, how Products run inside them over TrUAPI, and how the app decides which network to talk to. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Accounts and Signing](/apps/concepts/accounts/). ## What the clients do For users, the app is one place to hold keys, manage identity, use CASH, message other people and open `.dot` apps. For developers, it is the host your Product relies on for accounts, signing, chain access, permissions and storage. The native clients share the same features: | Client | Role | | -------------------- | ------------------------------------------------------------------------- | | Polkadot Android | Mobile app with local custody, identity, CASH, messaging, and app hosting | | Polkadot iOS | Mobile app with the same product surface for iOS users | | Polkadot Desktop/Web | Desktop app and web client for the same account and Product flows | The Desktop build also runs as a web application, and the same Products are reachable through the web gateway at [dev-dot.li](https://dev-dot.li). Download links are in [More resources](/apps/reference/resources/). ## Wallet and account management On mobile (Android and iOS), accounts are created and stored on the device, and the app is self-custodial. Keys are held in the platform's hardware-backed secure storage (the Android keystore, or the iOS Keychain). Recovery goes through the device's cloud backup: Google Drive on Android, iCloud on iOS. Signing happens on the phone. When a dApp or an in-app action needs a signature, the app shows a modal, and the key on the device signs the payload only after you approve. The desktop/web client holds no keys of its own. It is a companion: you pair it with your phone (by scanning a pairing code), and signing happens on the phone. Nothing funds a new account automatically. On devnet (non-production) builds you can top up your account with test tokens using the manual "+" (top-up) action. For native devnet tokens to pay transaction fees, use the faucet at . Identity, chat and payments each live on specific parachains. The People Chain carries your username, the chat statement store and CASH, which is held and sent through Coinage. Asset Hub holds other assets, such as pUSD and USDt, and the DotNS contracts. The Bulletin Chain serves dApp content and chat attachments. ## The app browser The in-app browser finds dApps by `.dot` domain, not by URL. It resolves the name through DotNS, fetches the referenced content archive from Bulletin or a gateway, and runs the archive in a sandboxed webview. The app then opens a TrUAPI channel, through which Products can ask the host for account, signing, chain, permission, storage, theme, notification, payment and navigation services. ``` flowchart TD U[User opens .dot domain] --> R[Resolve through DotNS] R --> A[Fetch app bundle] A --> S[Run in sandboxed webview] S --> C[TrUAPI channel] C --> H[Native host services] H --> ACC[accounts / signing] H --> CH[chain connection by genesis hash] H --> PERM[device + remote permissions] H --> PAY[payment / statement store / storage / theme / notifications] ACC -->|on-device key| K[Hardware-backed keystore] ``` Each platform embeds the webview in its own native stack, but Products see the same protocol, TrUAPI, everywhere. ## Running dApps over TrUAPI Once the webview loads, the Product talks to the host over its TrUAPI channel. The host decides which capabilities are available, checks permissions and handles sensitive actions such as signing. A typical signing flow: 1. The dApp asks the host, over TrUAPI, to sign a payload or raw bytes, or to create a transaction. 2. The native side receives the request and checks the product's granted permissions. 3. The app shows a signing modal for you to review and approve. 4. On approval the key on the device signs, and the signature goes back to the dApp. Broadcasting is gated inside the container. When you build a Product, you rarely call these primitives yourself. The [`@parity/product-sdk`](https://www.npmjs.com/package/@parity/product-sdk) wraps TrUAPI. To test a Product end to end, use the [test host](/apps/build/platform-services-sdk/#test-without-the-real-host) in [`@parity/truapi-host`](https://www.npmjs.com/package/@parity/truapi-host): it runs the real TrUAPI core, embeds your product in an iframe, signs in dev accounts (Alice, Bob) and auto-signs requests. ## Selecting the network The operators decide which network the app uses. Each client asks for the roles it needs (`people`, `bulletin`, `assetHub`), then gets the current RPC endpoints, DotNS contract addresses, gateway URLs and backend URLs from the Devnet configuration service. For users and app developers, this means Products are not expected to hardcode any of those values. ``` flowchart TD Channel["Selected Devnet channel"] --> Config["Devnet configuration"] Config --> Roles["Resolve chain roles
people / bulletin / assetHub"] Config --> Services["Resolve service URLs
gateway / identity / storage"] Roles --> App["Active app environment"] Services --> App App --> Products["Products use host + SDK
without hardcoded endpoints"] ``` If the app cannot resolve a complete environment, it stops instead of guessing. Developer tools work the same way: the CLIs select a named network preset, and the preset supplies the chain and registry addresses for that network. ## Common blockers * A Product runs outside the host: host-only APIs need the Polkadot app or the web gateway. Use the test host for local end-to-end tests. * A signing request is denied: the user must approve on the device, and the Product must have the required permission. * The app cannot resolve the Devnet: the platform supplies the network configuration, and endpoints hardcoded in Product code break easily. ## Learn more * Client source and downloads: [More resources](/apps/reference/resources/) * [Test without the real host](/apps/build/platform-services-sdk/#test-without-the-real-host): drive a Product against the TrUAPI test host in CI * [Naming (DotNS)](/apps/architecture/naming/): how the browser resolves a `.dot` domain # Smart contracts Smart contracts on the Polkadot Products Devnet run on PolkaVM (PVM) through `pallet-revive` on Asset Hub. They are PolkaVM bytecode with Solidity-style ABIs. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/). ## Where contracts run `pallet-revive` is the smart-contract environment on Asset Hub (para 1000). DotNS and application contracts run there. The EVM chain id is `420420417`, and contract tooling that speaks Ethereum JSON-RPC (Hardhat, `cast`, viem) uses the ETH-RPC endpoint listed in [Networks & endpoints](/apps/reference/networks/#ethereum-json-rpc). Contracts can also read platform state through precompiles at fixed addresses. The personhood precompile returns an account's personhood tier and a per-app alias (see [Identity & personhood](/apps/architecture/identity/)), and ERC-20-style precompiles let contracts read and transfer supported assets. An account has to be mapped to its EVM address before it can sign PolkaVM transactions on Asset Hub. An unmapped account fails on its first one. ## Calling contracts from an app At runtime, apps make typed calls with `@parity/product-sdk-contracts`, which is part of the [Product SDK](/apps/reference/packages/#product-sdk-family). You build a runtime from the Asset Hub chain client, then a contract handle from the contract's address and ABI. Read-only `.query()` calls need no account, and `.tx()` calls are signed through the host wallet. `ensureContractAccountMapped` maps an account for `pallet-revive` when a call needs it. [Use platform services from the SDK](/apps/build/platform-services-sdk/#call-smart-contracts) shows the code. Never print or commit signing seeds. Fund an account that sends contract transactions from the network faucet at . ## Common blockers * The account is not mapped: map it once with `dotns account map --env devnet`, or call `ensureContractAccountMapped` from your app. * The account has no funds: get PAS from the faucet. ## Learn more * [pallet-revive](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive): the PolkaVM contract environment * [Use platform services from the SDK](/apps/build/platform-services-sdk/#call-smart-contracts): call a contract from your app * [Identity & personhood](/apps/architecture/identity/): the personhood precompile # App discovery: Browse Browse is the app-discovery directory for the Polkadot Products Devnet. It tells people which `.dot` apps exist and how to open them, but it is not the source of truth for app metadata. The on-chain listing is deliberately small; the user-facing name, description, and icon are resolved from DotNS records and content storage at read time. The reference directory runs at [browse.dev-dot.li](https://browse.dev-dot.li), and its source is in [paritytech/browse](https://github.com/paritytech/browse). The contracts described here are unaudited prototype code. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [List Your App](/apps/list-your-app/). ## What discovery helps you do Users use Browse to find apps. Developers use it to make a published app visible after the app already has a `.dot` domain and a bundle. Browse is not a replacement for DotNS or app delivery; it sits on top of them. The system has three responsibilities: * Registry: records that a `.dot` label should appear in discovery. * Reader SDK: reads registry entries and joins them with DotNS metadata. * Client UI: renders cards and opens the selected app in the host or web gateway. ## What a listing actually holds A listing is created by publishing a `.dot` label to the Browse registry. The registry stores only the minimum needed to enumerate apps. It does **not** store the display name, description, icon, or app bundle. All display metadata lives off-chain and is joined by labelhash at read time: * The human-readable label comes from DotNS. * The app bundle and display metadata come from the name's resolver records. * The root manifest provides the card content Browse shows to users. A valid manifest needs a display name, description, and icon: ```json { "$v": 1, "displayName": "Calculator", "description": "A basic calculator.", "icon": { "cid": "bafy...", "format": "png" } } ``` ## The publish permission model Who is allowed to list an app is enforced on-chain: 1. You must own the `.dot` domain. 2. You need the required personhood status for the publish action. 3. You must be under the publish rate limit for your personhood tier. | Personhood status | Meaning | Publishes per 24h | | ----------------- | --------------------- | ----------------- | | None | Not enough to publish | 0 | | Lite | Basic personhood | 1 | | Full | Stronger personhood | 5 | Unpublishing is simpler: if you own the name, you can remove it from Browse. ``` flowchart TD A[Publish label] --> B{Own the .dot domain?} B -- no --> E1[Cannot publish] B -- yes --> C{Enough personhood?} C -- no --> E2[Complete personhood flow] C -- yes --> D{Under rate limit?} D -- no --> E3[Wait for the window] D -- yes --> R[Listing appears in Browse] ``` The `pad` deploy CLI no longer lists apps as part of a deploy. ## How a listing is consumed The client builds the directory from the registry every time it loads: 1. Enumerate: read published labels from the registry. 2. Resolve labels: turn label identifiers back into `.dot` labels. 3. Hydrate: read each name's content hash, manifest, and any available attestation or certificate data. 4. Render: build product cards from `displayName`, `description` and the icon (fetched through the host's preimage manager, not a raw gateway URL), with certificate badges. Reading the directory needs no signer and sends no transactions. To open an app, Browse hands off: inside the Polkadot app it asks the host to navigate to the `.dot` domain, and in a browser it opens the web gateway. ``` flowchart LR P["Publisher.getPublished
labelhashes"] --> L["Registrar.labelOf
labelhash to label"] L --> C["ContentResolver.contenthash
drop non-live"] C --> M["ContentResolver.text manifest
displayName/desc/icon"] M --> UI[Product cards] UI -->|host| H["host navigates to label.dot"] UI -->|browser| W["open label.dev-dot.li"] ``` The registry stores only the labelhash, the publisher and a timestamp. So to change an app's name, description or icon, you don't write to the registry at all. You update the DotNS `manifest` record, and the directory picks it up on the next hydrate. ## Common blockers * **The app has no card metadata.** Update the DotNS manifest record with a display name, description, and icon. ## Learn more * [browse](https://github.com/paritytech/browse): source for the directory and its client * [App delivery](/apps/architecture/app-delivery/): the pipeline that writes the contenthash and manifest # Identity & personhood Identity on the Polkadot Products Devnet answers two questions about an account: what name does it use, and does it belong to a distinct person? The first is the username flow. The second is proof of personhood. Apps can use both without holding the user's keys or seeing what the user does in other apps. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Identity](/apps/concepts/identity/) or [Individuality](/apps/product-sdk/individuality/). ## The moving parts Identity is spread over a few separately deployed components. The main source repositories are under [github.com/paritytech](https://github.com/paritytech). | Component | Role | Source | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `identity-backend` | Stateful HTTP backend-for-frontend (BFF) for the Polkadot app, backed by Postgres (usernames, single-use/revocable refresh tokens, a registration queue, device attestations, and invitation tickets). Issues JWT sessions, registers usernames, manages invitation tickets. Holds no user keys. | [identity-backend-community](https://github.com/paritytech/identity-backend-community) | | `people-lite` pallet | On-chain registry of *Lite* people (attested usernames) on the People chain. | [individuality-community](https://github.com/paritytech/individuality-community) | | `proof-of-ink` pallet | On-chain *Full* personhood: applications, invitations, and evidence judging. | [individuality-community](https://github.com/paritytech/individuality-community) | | `personhood` precompile | A pallet-revive precompile that lets any PolkaVM contract read an account's personhood tier and a per-app alias. | [individuality-community](https://github.com/paritytech/individuality-community) | | `attestation-protocol` | An EAS-style, permissionless attestation suite (`SchemaRegistry` + `AttestationService`) for general claims. | [attestation-protocol](https://github.com/paritytech/attestation-protocol) | ### The identity backend is centralized today Every other component above is on-chain. `identity-backend` is not: it is an operator-run HTTP service with its own database, and the Lite tier depends on it to attest devices, allocate usernames and submit the registration. It holds no user keys and cannot sign as a user, but it is a trusted party, and while it is down, username registration stops. This is a devnet shortcut. Running this role in a decentralized way is desirable future work, and the Devnet does not demonstrate it, so don't read the current setup as the final architecture. ## Sessions: proving the device, not the person Before a client can register anything, it gets a JWT through a device-attestation handshake. The backend never sees a password. It checks that the request comes from a genuine, unmodified copy of the app on a genuine device. 1. The client requests a Challenge: a stateless, self-authenticating freshness nonce that the server mints without storing anything. 2. The client produces an Attestation: Apple App Attest on iOS, Google Play Integrity or Android key attestation on Android, or a voucher secret for out-of-band enrolment. 3. The client `POST`s the Attestation and the echoed Challenge to `/api/v1/auth/token`, and receives a JWT. `/auth/token/refresh` rotates it. So a session proves the device and the app instance before the backend accepts identity actions from it. ## Usernames and the Lite tier A Lite person is an account with an attested, human-readable username. The client asks for a base name, the backend allocates an available suffixed name, and the user signs the registration. The backend accepts and queues the request (returning `202 Accepted`), and a separate worker submits the attestation to the People chain later. The backend never takes custody of the user's keys or signs as the user. Registration has limits. On iOS, Apple DeviceCheck limits the number of free registrations per device: a device that has already registered gets a `PAYMENT_REQUIRED` response on further attempts. Each new username can also be reflected into the `.dot` naming system, so the same readable identity works across the app and app discovery. Operator-run infrastructure does that mirroring, and users and Product developers normally don't interact with it directly. ``` sequenceDiagram participant App as Polkadot app (device) participant BFF as identity-backend (BFF) participant Worker as Registration worker participant People as People chain (people-lite) participant AH as Asset Hub (dotns-gateway) App->>BFF: POST /auth/token (App Attest / Play Integrity + Challenge) BFF-->>App: JWT App->>BFF: POST /usernames (base name + signed proof) BFF-->>App: 202 Accepted (registration queued) Worker->>People: Register Lite username attestation (async) People-->>Worker: finalized (Lite person registered) People-->>AH: username can be mirrored into .dot naming ``` ## Full personhood and invitation tickets The Full tier is stronger. It represents a person who has completed a personhood flow, such as an invitation or a game-based proof. The backend can help users get the tickets or proofs they need to start those flows, but the status itself is recorded on-chain. Whether the Full tier is currently active on the deployed devnet depends on operator-privileged tasks (game scheduling and related runtime configuration). Treat a `None`/`Lite` result as the safe default, and don't assume Full personhood is available. ## How apps read identity status Contracts don't ask the backend about personhood. Personhood state is reflected from the People chain to Asset Hub over XCM, and PolkaVM contracts read it there through the personhood precompile: ```solidity struct PersonhoodInfo { uint8 status; bytes32 contextAlias; } // status: 0 = None, 1 = Lite, 2 = Full function personhoodStatus(address account, bytes32 context) external view returns (PersonhoodInfo memory); ``` The returned `contextAlias` is a per-application pseudonym that protects the user's privacy. The same person gets a different alias in a different context, so apps cannot link a user's activity across applications. Front-ends that run inside the Polkadot app or the web gateway at get identity and host information through the developer packages: [`@parity/product-sdk`](https://www.npmjs.com/package/@parity/product-sdk), which talks to the host over TrUAPI ([`@parity/truapi`](https://www.npmjs.com/package/@parity/truapi)). Their own repositories define exactly what those packages expose for username and personhood status. ## General attestations Beyond personhood, the attestation protocol provides reusable claim and schema contracts on the PolkaVM Asset Hub. Use it when an app needs verifiable claims that are something other than username or personhood status. ## Common blockers * The device session is missing or expired: the app must complete device attestation before identity actions can go ahead. * The username is taken: the backend allocates a suffixed name that is still available. * Full personhood is not available in a build: treat `None` or `Lite` as the safe default unless the current Devnet flow offers Full. * An app needs identity in a contract: read personhood through the precompile or SDK-supported helpers, not by calling the backend from a contract. ## Learn more * [identity-backend-community](https://github.com/paritytech/identity-backend-community): the BFF, its routes, and `CONCEPTS.md` * [individuality-community](https://github.com/paritytech/individuality-community): `people-lite`, `proof-of-ink`, and the `personhood` precompile * [attestation-protocol](https://github.com/paritytech/attestation-protocol): `SchemaRegistry` and `AttestationService` # Messaging & calls The Polkadot app has encrypted chat and one-to-one voice and video calls, with no dedicated messaging or signaling server. Text messages and call-setup signals travel over the same on-chain channel. Media attachments are stored on a separate content chain, and live audio and video flow peer to peer over WebRTC. This page shows how those pieces fit together and what users and Product developers should expect. ## Transport: the statement store Text messages are not stored on a server, and they are not sent directly between devices either. Each message is encrypted on the sending device and published to the statement store on the People chain. Recipients subscribe to that store and decrypt messages on their own device. The same channel carries text, reactions, replies, contact events and call setup signals. That shared transport is why chat and calls live in the same part of the app. ### Encryption Messages are encrypted per peer, not with one global key. Only encrypted statements are submitted to the store, so the People chain only sees ciphertext. ## Media attachments: the Bulletin "hop" Images, video and files do not go through the statement store. Attachments are encrypted and uploaded through Bulletin-backed storage, and the chat message carries a reference that lets the recipient fetch and decrypt the file. [The network](/apps/architecture/network/) has more on Bulletin storage. ## Voice and video calls Calls use WebRTC, with no dedicated signaling server. The offer, answer, connection candidates and call-close signals are sent as encrypted chat messages over the statement store. Once the peers connect, media flows directly when possible, or through TURN when a relay is needed. ### NAT traversal (STUN and TURN) When a direct WebRTC path is not available, clients can use temporary TURN credentials. Platform infrastructure provides those credentials and they are short-lived, so Product apps should treat calling as a service the host provides and not embed TURN configuration themselves. ## Data paths at a glance ``` flowchart TD subgraph ClientA[Client A] A1[Chat UI / ChatEngine] A2[WebRTC PeerConnection] end subgraph ClientB[Client B] B1[Chat UI / ChatEngine] B2[WebRTC PeerConnection] end SS["People chain statement store"] BC["Bulletin-backed attachment storage"] TURN["STUN / TURN"] A1 -- "Encrypted statements
(text + SDP/ICE call signals)" --> SS SS -- subscription --> B1 A1 -- "chunked AES media" --> BC BC -- "fetch by HopTicket" --> B1 A2 -- "ICE / media (audio+video)" --> TURN TURN -- relay --> B2 A2 -. "direct P2P when possible" .- B2 ``` ## Desktop and device sync Voice and video calls are mobile-only today. The desktop build has no call UI and cannot start or answer calls. Desktop uses WebRTC only for device sync and peer-to-peer chat. It shares the same broad building blocks for chat and sync, but calling stays on the mobile app. ## Common blockers * A message appears delayed: the sender and recipient both depend on the statement store subscription and on decrypting locally. * An attachment does not open: the encrypted attachment reference may arrive before the content is available from Bulletin-backed storage. * A call only connects through a relay: that is expected on some networks. TURN credentials come from the platform and can change. * You want to call from desktop: calling is mobile-only today, and the desktop build has no call UI. Use the mobile app to start or answer calls. ## Learn more * [Polkadot Android](https://github.com/Polkadot-Community-Foundation/polkadot-android-community): source for the chat engine and call stack * [Messaging & calls](/apps/using-the-app/messaging-and-calls/): how to chat and call in the app # Money: CASH & funding How money works on the Polkadot Products Devnet: what CASH is in the app, why it is different from the native token used for fees, and how funds move when people use the app. ## Two balances Users see CASH in the Polkadot app. CASH is the app's name for a devnet digital-dollar asset. It is the balance users top up, earn and send to other people inside the app. The chains also have a native token, PAS, used for fees and for account existential deposits on Paseo-based chains. CASH and PAS are separate: * CASH is the spendable app balance. * PAS is the native network token used for fees. * Both are devnet-only and have no real value. Keep this in mind when something goes wrong. A user can have CASH for app payments and still need a small amount of PAS for network fees or to keep the account in existence. ## Where CASH lives CASH is built on the Polkadot asset stack, and the Polkadot app uses it through the People chain. On People, the balance is a local pUSD asset (asset id `1`) that Coinage denominates and shows as CASH. The same logical value is also represented on Asset Hub, with id `50000413`. That is a protected asset, and transfers of it on Asset Hub are gated. Day to day, people don't need to move assets between chains by hand. The app shows CASH as a single balance and does the chain-specific work for them. ``` flowchart LR App["Polkadot app
shows CASH"] --> Coinage["Coinage on People
holds and sends CASH"] Asset["pUSD local asset
People asset id 1"] --> Coinage PAS["PAS native token
fees + account existence"] -. separate .-> App AH["Asset Hub id 50000413
AH transfers gated"] -. same logical value .-> Asset ``` ## How CASH is held The app does not treat CASH like a simple account balance. It holds and spends CASH through Coinage, a People-chain system that represents value as coins. When a user sends CASH, the app prepares and submits a Coinage transfer, not a plain token transfer. This matters for developers: payment flows in your app should use the platform services that the host and SDK provide. A Product should not try to rebuild the wallet, key handling or low-level payment flow. ## How users get CASH Users get CASH inside the Polkadot app, in two ways: 1. Top up in the app. Devnet builds can offer a top-up action that funds the account and brings value into the CASH balance. 2. Earn rewards. Some app and personhood flows can reward users with value that then shows up as CASH. Once onboarding completes, the balance in the user's Pocket updates and they can spend it. ## Sending CASH Sending CASH goes through the wallet: 1. The user chooses a recipient and amount in the Polkadot app. 2. The app prepares the Coinage transfer. 3. The user approves the action on the device. 4. The app submits the transaction and waits for it to settle. ## What developers should rely on Treat CASH as a platform service that the host and SDK provide: * Ask the host for the user's account and permissions. * Use the SDK and host-provided payment and chain APIs. * Let the Polkadot app handle signing and key custody. * Show amounts clearly as devnet value. Don't hardcode operator accounts, funding assumptions or private chain configuration into an app. The Devnet operators supply the network presets, live endpoints and registry addresses. ## Learn more * [`pallet-coinage`](https://github.com/paritytech/individuality-community/blob/main/pallets/coinage/src/lib.rs): the source, showing how CASH is represented as coins, held and transferred * [paseo-network/runtimes](https://github.com/paseo-network/runtimes): the chain runtimes and asset definitions * [Get & use CASH](/apps/using-the-app/get-and-use-cash/): get and send CASH yourself # Naming: DotNS DotNS is the `.dot` naming system for the Polkadot Products Devnet. Every gateway, client and directory app needs it to answer one question: given a name like `calculator.dot`, what does it point to, and who is allowed to change it? This page covers ownership, records, resolution and the personhood rules for names. DotNS is a set of PolkaVM contracts, used by the DotNS CLI, the web gateway and Product tooling. Names are on-chain records, so when a record changes, every client that resolves the name sees the new target. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Register a `.dot` Domain](/apps/register-dot-domain/). ## The name model Each `.dot` domain has two important pieces of state: * Owner: the account or contract that controls the name. * Resolver records: the data attached to the name, including the content hash that points to an app bundle. Internally, DotNS hashes names into fixed-width identifiers so contracts can look them up efficiently. You normally don't calculate those hashes yourself: the CLI, SDK, gateway and host tooling do it. ## Resolving `name.dot` to an app bundle Resolution only reads. A client never needs a naming server: it computes the node locally and reads two contracts. 1. Form `domain = .dot` and compute `node = namehash(domain)`. 2. Read `DotnsRegistry.recordExists(node)` and `DotnsRegistry.owner(node)`. If the record does not exist or the owner is the zero address, resolution stops with an empty result. 3. Read `DotnsContentResolver.contenthash(node)`, which returns the ENS-style contenthash bytes for the name. 4. Decode those bytes to an IPFS CID. 5. Fetch the application bundle from the gateway. The web gateway at [dev-dot.li](https://dev-dot.li) follows the same path and renders the resolved bundle in a sandboxed frame. [App delivery](/apps/architecture/app-delivery/) covers how the content is uploaded and how the contenthash gets written. Because resolution is a plain contract read, you can check any name yourself with the DotNS CLI: `dotns content view --env devnet`. ## Contract topology DotNS splits ownership, records and control into separate contracts. That way parts of the protocol can be replaced without changing the basic model that clients depend on. ``` flowchart TD Controller["Registration controllers"] --> Registrar["Registrar
name ownership"] Registrar --> Registry["Registry
owner + resolver"] Registry --> Resolver["Resolvers
contenthash + records"] Rules["Name rules
length + personhood"] --> Controller Resolver --> Gateway["Gateway / app clients"] ``` * Registrar: records who owns a `.dot` domain. * Registry: connects the name to its resolver. * Resolvers: hold the records that clients read, including the content hash for an app bundle. * Name rules: decide which names are open, which are reserved and which need personhood. ## Registration The public registration path is a two-phase commit-reveal, which stops anyone from front-running a name you chose. The CLI takes you through it: 1. Validate and normalise the label (a single lowercase DNS label, at least 3 characters long; shorter labels revert with `LabelTooShort`). 2. Classify and price the label through `PopRules`, and check whether it is reserved. 3. Commit to the name without revealing the full registration. 4. Wait for the commitment window. 5. Reveal the registration, mint the name and write its initial records. Names can also be transferred (the ERC-721 token moves), and the owner of a base name can create subnames with `setSubnodeOwner`. ## Reserved and short-name gating Not every label is available on the public path. `PopRules` classifies each label by the length of its stem (the label with any trailing digits stripped) and gates it accordingly: | Tier | Condition | Effect | | -------- | ----------------------------------- | ------------------------ | | Reserved | stem ≤ 5 characters | short names are gated | | PopLite | stem 6–8, exactly 2 trailing digits | lite personhood username | | PopFull | stem 6–8, no trailing digits | full personhood username | | NoStatus | stem ≥ 9 characters | open, deposit-backed | Labels with 1 or more than 2 trailing digits are rejected. Governance-reserved and name-reserved labels revert on the public controller. A separate owner-managed whitelist (`registerReserved`) can bypass PoP pricing for specific addresses. Personhood-gated names come through a controlled path tied to the personhood system, not the public commit-reveal path. Product developers normally deal with this through the app, the CLI or DotNS services, not by calling those contracts directly. ## Learn more * [dotns](https://github.com/paritytech/dotns): the contracts * [dotns-sdk](https://github.com/paritytech/dotns-sdk): the CLI and reference UI * [Register a .dot domain](/apps/build/register-a-dot-name/): register one yourself # The network The Polkadot Products Devnet runs on the community-operated Paseo network: a Paseo relay chain plus a set of system parachains. Apps are built against three of those chains: Asset Hub, People and Bulletin. This page shows what each chain does, and how they work together when a Product is deployed and opened. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Networks](/apps/concepts/networks/). ## Topology The relay chain is the root of trust. Product flows mostly touch three system parachains: Asset Hub for contracts and assets, People for identity and money flows, and Bulletin for web-app bundle storage. ``` graph TD Relay["Paseo relay chain"] AH["Asset Hub (para 1000)
contracts / assets / DotNS"] People["People (para 1004)
identity + proof-of-personhood"] Bulletin["Bulletin (para 1010)
transaction storage (web bundles)"] Relay --> AH Relay --> People Relay --> Bulletin People -->|identity and CASH signals| AH AH -.->|contenthash points to bundle CID| Bulletin %% Per-chain colour — palette lives in diagrams.css (.relayNode etc.) classDef relayNode stroke-width:1px; classDef assethubNode stroke-width:1px; classDef peopleNode stroke-width:1px; classDef bulletinNode stroke-width:1px; class Relay relayNode class AH assethubNode class People peopleNode class Bulletin bulletinNode ``` | Chain | Para ID | Role | | --------- | ------- | ---------------------------------------------- | | Relay | — | Root of trust; anchors the system parachains | | Asset Hub | 1000 | Contracts (PolkaVM/EVM), assets, DotNS gateway | | People | 1004 | Identity and proof-of-personhood | | Bulletin | 1010 | Web-app content storage | ## Asset Hub para 1000 Asset Hub is the main chain for Product developers. It runs the contracts, assets and naming that deployed apps use. **pallet-revive** The PolkaVM smart-contract environment. DotNS and application contracts run here. **Assets + ERC-20 precompiles** On-chain assets available to contracts through ERC-20-style precompiles, so contracts can read and transfer supported assets without dealing with Substrate storage. **DotNS gateway** Connects `.dot` domains to the contract environment. See [Naming](/apps/architecture/naming/) for how names resolve to app bundles. **Personhood precompile** Contracts read a user's personhood tier through a precompile, without calling the identity backend. ## People para 1004 The People chain holds identity, proof-of-personhood and Coinage state. Usernames are attested here, personhood status is recorded here, and CASH is held and sent here through Coinage. ## Bulletin para 1010 The Bulletin chain stores published web-app bundles that the gateway serves. Bulletin uploads work by authorization, not by fees. Instead of charging tokens per upload, an authorizer (Root, sibling parachains, or registered authorizers) decides who can store data. That is why publishing an app bundle does not cost devnet tokens. ## The deployments register Addresses, endpoints and CIDs are network-specific. They change when a network is redeployed, so nothing in the platform hard-codes them. Instead, each command-line tool selects a network preset (`--env devnet` for `pad` and `dotns`), and the preset carries the endpoints and address book for that network. The addresses themselves are in [Addresses & registries](/apps/reference/addresses/). ## Deploy and serve flow Here is how the three chains work together over an app's life: ``` graph LR Dev["App developer"] Revive["pallet-revive on Asset Hub
(PolkaVM/EVM contract)"] DotNS["DotNS
.dot domain + resolver"] Store["Bulletin transaction storage
(auth-gated, CID)"] GW["Gateway dev-dot.li"] User["Polkadot app / web user"] Dev -->|deploy contract| Revive Dev -->|reserve name| DotNS Dev -->|upload web bundle| Store DotNS -->|contenthash = CID| Store GW -->|resolve .dot -> CID| DotNS User -->|https://label.dev-dot.li| GW User -->|contract calls| Revive %% Per-chain colour — palette lives in diagrams.css (.relayNode etc.) classDef developerNode stroke-width:1px; classDef assethubNode stroke-width:1px; classDef dotnsNode stroke-width:1px; classDef bulletinNode stroke-width:1px; classDef gatewayNode stroke-width:1px; classDef userNode stroke-width:1px; class Dev developerNode class Revive assethubNode class DotNS dotnsNode class Store bulletinNode class GW gatewayNode class User userNode ``` A developer deploys contracts to Asset Hub through `pallet-revive`, reserves a `.dot` name through the DotNS gateway and uploads the web bundle to Bulletin. The name's contenthash resolver is bound to the bundle's CID, and the gateway at serves the app at `https://.dev-dot.li`. The [contracts](/apps/architecture/contracts/) and [naming](/apps/architecture/naming/) pages, and the [developer guides](/apps/using-the-app/), go into more detail. ## Learn more * [paseo-network/runtimes](https://github.com/paseo-network/runtimes): the chain runtimes * [pallet-revive](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive): the PolkaVM contract environment # Storage & data Apps on the Polkadot Products Devnet keep their data in one place: the Bulletin chain (para 1010), a content-addressed on-chain store. It is how an app is meant to persist data. You give it bytes and get back a content identifier (CID), and anyone can read those bytes back by CID. Because content is addressed by its own hash, the same bytes always give the same CID, and the client can verify what it fetched. Bulletin holds two kinds of content: * App bundles: the static frontend a developer publishes. The `pad` CLI uploads the build and binds its CID to a `.dot` name. This is the write side of [app delivery](/apps/architecture/app-delivery/). * App data: anything a running app stores (documents, media, records). Apps reach it through the host's Cloud Storage service, not by talking to the chain directly. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Where to Store Data](/apps/concepts/data-placement/) or [Store Data on Chain](/apps/build/store-data-on-chain/). ## Cloud Storage: storing app data When an app needs to persist data, it uses Cloud Storage: content-addressed storage backed by Bulletin, available through TrUAPI and the [Product SDK](/apps/build/platform-services-sdk/#store-and-retrieve-data-cloud-storage). The API is small: upload bytes, get a CID, fetch by CID. ```ts const cloud = app.cloudStorage; // null if the service is disabled const uploaded = await cloud.upload(bytes); // -> Result if (uploaded.ok) { const back = await cloud.fetch(uploaded.value); // -> Result } ``` Know these before you design around it: * It is content-addressed, not a key-value store. You get back a CID for exactly the bytes you stored, and there is no "path" you can overwrite. To model state that changes, store the new version and keep the CID that points to it (for example in a `.dot` record, a contract, or another Cloud Storage object). * Reads are open and writes are authorized. Anyone can fetch a CID. Uploading needs a connected account with a storage authorization (see below). * Reads only work inside a container. The client fetches through the host/light-client path, and there is no public IPFS-gateway fallback. * Pick the right network. `cloudStorage.environment` must be `devnet` for this network. It defaults to `paseo`, a different chain that a Devnet host does not serve, so `createApp()` fails if you leave it out. The [Product SDK guide](/apps/build/platform-services-sdk/#store-and-retrieve-data-cloud-storage) has the API details and the `Result` pattern. ## How storage authorization works Bulletin storage works by authorization, not by fees. You don't pay a token fee per upload. Instead, the uploading account must hold a live authorization: an on-chain quota of bytes and transactions granted by an authorizer. Reading never needs one. Authorization limits storing, not retrieval. ``` flowchart TD AUTH[Authorizer] -->|authorize_account: bytes + tx quota| ACCT[Your account] ACCT -->|signs upload| BULLETIN[Bulletin store] READER[Any reader] -->|no authorization needed| BULLETIN ``` The account that signs an upload is the account that spends the quota, so that is the account to authorize. For publishing, it is the account that owns your `.dot` name. For Cloud Storage, it is the connected user account. Writes are gated because an unmetered public store invites spam. In production, the write gate is typically tied to proof of personhood or to an operator-run authorizer. This Devnet leaves it open on purpose: a public Storage Faucet and a shared authorizer let any developer get an allowance without a personhood check. Grant one from the Faucet tab of the [Bulletin Chain Console](https://paritytech.github.io/polkadot-bulletin-chain/) (select the **Products Devnet** network). The steps for publishing are in [Get storage authorization](/apps/build/build-and-publish/#get-storage-authorization). Authorizations are finite and expire. Each one is a limited quota with an expiry date, and the Console lists current authorizations and when each one lapses. If a deploy or upload that used to work suddenly stops at the storage step, the allowance has most likely run out or expired. Grant it again and retry. Content that is already stored is not affected: the limit only applies to new writes. ## Learn more * [App delivery](/apps/architecture/app-delivery/): publishing an app bundle to Bulletin and binding it to a `.dot` name * [Store and retrieve data (Cloud Storage)](/apps/build/platform-services-sdk/#store-and-retrieve-data-cloud-storage): the SDK API, in code * [Get storage authorization](/apps/build/build-and-publish/#get-storage-authorization): grant an allowance and publish * [polkadot-bulletin-chain](https://github.com/paritytech/polkadot-bulletin-chain): the storage pallet and quota model # Build > Build Polkadot Product capabilities with product-sdk packages for signing, on-chain reads, decentralized storage, off-chain pub/sub, and local persistence. The Build section is a cookbook of focused recipes, one per [`product-sdk`](/apps/product-sdk/) package; each recipe takes a single capability and walks you from an empty project to working Product code. They apply no matter how you started: a [Quick Start](/apps/quick-start/) deploy (RevX or CLI) or a project you [set up yourself](#set-up-your-project). Pick the capability your Product needs, in any order; the recipes are ordered by how little they ask of you, and the first one requires no account and no tokens. Go deeper on any package Each recipe walks one path through a package. For the concepts behind a package — what it is, when to use it, and its core types — see its overview in the [Product SDK](/apps/product-sdk/) section. For the complete surface (every class and method), see the [Product SDK API reference](https://paritytech.github.io/product-sdk/). Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Use platform services from the SDK](/apps/build/platform-services-sdk/). ## Set Up Your Project Every guide assumes a Product project running locally in [Polkadot Desktop](/apps/get-started/). The steps below apply no matter how you bootstrapped your Product: a [Quick Start](/apps/quick-start/) deploy (RevX or CLI) or a project created from scratch. 1. Scaffold a project. Any framework that serves on `localhost` works; this example uses Next.js: ```bash npx create-next-app@latest my-product cd my-product ``` 2. Install the [Product SDK](https://github.com/paritytech/product-sdk): ```bash npm install @parity/product-sdk ``` 3. Start the dev server: ```bash npm run dev ``` 4. Open Polkadot Desktop and click **Skip (Dev only)**. ![Polkadot Desktop showing the "Skip (Dev only)" button](/images/apps/build/start-a-local-dev-loop/start-a-local-dev-loop-01.webp) 5. Type `localhost:3000` (or your dev server's port) in the address bar and press **Enter**. Desktop recognizes `localhost` as a whitelisted origin, skips `.dot` resolution, and loads your Product directly from the local server. ![Polkadot Desktop showing a local Product loaded from localhost:3000](/images/apps/build/start-a-local-dev-loop/start-a-local-dev-loop-02.webp) Your Product is now running inside the Polkadot Desktop sandbox, served from your local machine. Live reload works through your dev server's hot module replacement: edit, save, and watch the change appear in Desktop. The sandbox and permission prompts apply exactly as they would for a published `.dot` Product, and no Proof of Personhood or funds are needed to load from `localhost`. ## Capabilities * **Read On-Chain Data** *** Your Product needs to show live balances, storage, and chain state. Reads are unsigned: no account, no tokens, no infrastructure to run. [→ Read On-Chain Data](/apps/build/read-chain-state/) * **Sign and Submit Transactions** *** Your Product needs to act on chain on the user's behalf. Derive a per-user account and request signatures; every approval happens on the user's phone. [→ Sign and Submit Transactions](/apps/build/sign-and-submit/) * **Store Data on Chain** *** Your Product needs content that outlives a session: profile photos, published posts, file uploads. Write to the [Bulletin Chain](/reference/apps/infrastructure/bulletin-chain/) and fetch from anywhere by CID. [→ Store Data on Chain](/apps/build/store-data-on-chain/) * **Publish and Subscribe to Off-Chain Data** *** Your Product needs real-time state between users: presence, typing indicators, multiplayer cursors. Signed pub/sub via the [Statement Store](/reference/apps/infrastructure/statement-store/), no fees per message. [→ Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/) * **Persist Data Locally** *** Your Product needs to remember things on this device: preferences, drafts, cached values. Per-Product key-value storage backed by the Host, with no browser `localStorage` fallback. [→ Persist Data Locally](/apps/build/persist-data-locally/) * **Add a Smart Contract to Your Product** *** Your Product needs enforced, shared on-chain logic: a leaderboard, a registry, an escrow. Deploy a PolkaVM contract to Asset Hub and call it by name from your frontend. [→ Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/) ## The `product-sdk` Packages Each guide is built around one *primary* package and weaves in *utility* packages where they are needed. The full source is at [`paritytech/product-sdk`](https://github.com/paritytech/product-sdk). Here is what each package is for: | Package | What it does | Guide | | :-----------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------: | | [`chain-client`](/apps/product-sdk/chain-client/) | A typed, host-routed client for reading on-chain storage, constants, and account state across one or more chains, with no RPC infrastructure to run. | [Read On-Chain Data](/apps/build/read-chain-state/) | | [`signer`](/apps/product-sdk/signer/) | Derives product-scoped accounts and requests signatures, routing every approval to the user's [Polkadot App](/reference/apps/hosts/polkadot-app/). Your Product signs without ever handling keys. | [Sign and Submit Transactions](/apps/build/sign-and-submit/) | | [`cloud-storage`](/apps/product-sdk/cloud-storage/) | A high-level client for the [Bulletin Chain](/reference/apps/infrastructure/bulletin-chain/), Polkadot's content-addressed storage. Uploads and retrieves data by CID, with chunking, manifests, and authorization handled for you. | [Store Data on Chain](/apps/build/store-data-on-chain/) | | [`statement-store`](/apps/product-sdk/statement-store/) | A pub/sub client for the [Statement Store](/reference/apps/infrastructure/statement-store/): publish and subscribe to signed, short-lived statements gossiped peer-to-peer off-chain. Ideal for real-time signaling between users. | [Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/) | | [`local-storage`](/apps/product-sdk/local-storage/) | A per-Product, per-device key-value store backed by the Host, for preferences, drafts, and cached values that persist across sessions. | [Persist Data Locally](/apps/build/persist-data-locally/) | | [`contracts`](/apps/product-sdk/contracts/) | Typed calls to `pallet-revive` (PolkaVM) smart contracts on Asset Hub, resolved by name from a `cdm.json` manifest, for enforced shared on-chain logic and state. | [Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/) | These packages anchor the current recipes because their surfaces are stable. Other packages in the SDK ([`keys`](/apps/product-sdk/keys/), `crypto`, [`host`](/apps/product-sdk/host/)) will get recipes of their own as their surfaces stabilize. The guides also use these utility packages where relevant: * **[`tx`](/apps/product-sdk/tx/)**: Builds, signs, and tracks the lifecycle of transactions (used alongside [`signer`](/apps/product-sdk/signer/)). * **`address`**: Encodes, decodes, and validates SS58 addresses. * **`descriptors`**: Provides typed chain metadata for the [`chain-client`](/apps/product-sdk/chain-client/) Bring Your Own Descriptors path. * **`host`**: Provides low-level access to the Host API surfaces the higher-level packages build on. ## Umbrella or Individual Packages Most guides work with either install style. Guides built on `createApp`, such as [Store Data on Chain](/apps/build/store-data-on-chain/) and [Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/), need the umbrella package, because `createApp` has no standalone package. Choose based on your needs: * **Umbrella package**: `npm install @parity/product-sdk`. One dependency that re-exports everything. Convenient when your Product uses several capabilities and bundle size is not a concern. * **Individual packages**: `npm install @parity/product-sdk-cloud-storage` (and so on). Install only what you use to keep your bundle smaller and your dependencies explicit. The import specifiers differ between the two — the umbrella exposes subpaths like `@parity/product-sdk/cloud-storage`, while the standalone package is `@parity/product-sdk-cloud-storage` — so switching styles means updating your imports. Start with the umbrella and switch to individual packages later as a bundle-size optimization. For the full tour of the SDK — `createApp`, the package family, React bindings, and testing without a Host — see the [Product SDK overview](/apps/product-sdk/). # Build & publish an app This guide takes a first Product from a Product SDK template to a live app. You build a static bundle, register a `.dot` domain and publish with the `pad` deploy CLI. When you are done, the app is reachable as `.dot` inside the Polkadot app and at `https://.dev-dot.li` on the web gateway. `pad` uploads your bundle to the Bulletin Chain and points your `.dot` domain at the result. The gateway then resolves that name in the browser and renders the bundle. [App delivery](/apps/architecture/app-delivery/) describes the whole pipeline. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Deploy Your App](/apps/deploy-your-app/). ## Prerequisites `pad` requires Node.js 22 or newer. On Node 20 it fails at startup with an unrelated-looking error (a module `SyntaxError`, or `Missing WebSocket class`), so check with `node --version` before installing. ```bash npm i -g @polkadot-community-foundation/dotns-cli@latest # dotns npm i -g @polkadot-community-foundation/polkadot-app-deploy@latest # pad, pad-bootstrap ``` Install only what you need: `pad` publishes (and can register the name for you), and `dotns` manages names in depth. Both are large. Expect a few minutes and roughly 1.5 GB across the global prefix and the npm cache, with no progress output while npm works. Always take the latest release. These CLIs carry the current contract addresses and network presets inside them, so an older copy can talk to a retired deployment and report success while nothing changes. To upgrade one you already have, re-run the same command. On some ARM64 platforms (for example Termux on Android), a transitive dependency, `node-datachannel`, ships no prebuilt binary, and its native build fails during `npm i -g`. It is only used for optional peer-to-peer CID verification, so skip the build with `--ignore-scripts`: ```bash npm i -g --ignore-scripts @polkadot-community-foundation/dotns-cli@latest ``` In this mode only the peer-to-peer verification path is unavailable. The CLI's gateway-based CID verification still works. Every command below targets the Devnet with `--env devnet`. `pad` already defaults to `devnet`, but pass the flag every time anyway, so a command never lands on another network by accident. Your signing account needs three things before the first on-chain step: 1. Native tokens on Asset Hub for fees. See [Faucet](/apps/reference/networks/#faucet). 2. A mapped EVM address. `dotns` and `pad` both sign PolkaVM transactions on Asset Hub, and an unmapped account fails on its first one. Map it once with `dotns account map --env devnet`. 3. A Bulletin storage authorization, so it can upload your bundle. See [below](#get-storage-authorization). You also need to own the `.dot` name you publish to. Step 3 covers that. ## Get storage authorization Publishing writes your app to the Bulletin Chain. Bulletin storage works by authorization, not by fees: before `pad` can upload, the uploading account needs a live authorization, which is an on-chain quota of bytes and transactions. You don't pay devnet tokens per upload, and `pad` never authorizes itself. Without an authorization it stops before uploading anything. The account that signs is the account that uploads. When you pass `--mnemonic`, `pad` uploads from that same account, so that is the account to authorize: the one that owns your `.dot` name. To grant it, open the Faucet tab of the [Bulletin Chain Console](https://paritytech.github.io/polkadot-bulletin-chain/), select the **Products Devnet** network and authorize the SS58 address you deploy with. The same page lists current authorizations and when each expires. This Storage Faucet is not the [token faucet](/apps/reference/networks/#faucet). The token faucet gives you native devnet tokens for transaction fees. The Storage Faucet grants a Bulletin storage allowance. Publishing needs both: tokens to sign the on-chain transactions, and an allowance to upload the bundle. Authorizations are finite and expire. If a deploy that used to work stops at the upload step, the allowance has most likely lapsed. Grant it again and re-run. ### Authorize from the CLI `dotns` can also grant the authorization directly, signed by the shared devnet authorizer: ```bash dotns bulletin authorize \ --transactions 1000 --bytes 104857600 --env devnet ``` This draws on a shared authorizer budget, so request only what you need. 1000 transactions and 100 MiB comfortably cover a typical app. Raising `--transactions` or `--bytes` past the shared budget fails with `InsufficientAuthorizerBudget`. Use the Storage Faucet above for larger grants. ### Deploying without your own key `pad` can also upload from a shared pool of helper accounts, which it uses when you deploy without `--mnemonic`. Those accounts are pre-authorized on the Devnet, and `pad-bootstrap` (same package, no extra install) tops them up: ```bash pad-bootstrap --env devnet --authorizer "//Eve" ``` Pass `--authorizer` explicitly. Without it, `pad-bootstrap` falls back to `//Alice`, which cannot grant here. This path does not authorize your own account, so it is only useful for CI and shared setups. A deploy that signs with `--mnemonic` still needs the authorization above. ## 1. Scaffold with the Product SDK Start from a template rather than an empty directory. The [playground-app-template](https://github.com/Polkadot-Community-Foundation/playground-app-template) is a minimal React + Vite + TypeScript app on Product SDK 0.39.0, so it speaks the hosts' TrUAPI version. It shows the app-scoped product account (SS58 and H160 addresses) and signs a message via `@parity/product-sdk-signer`. Your app runs as a Product inside the Polkadot host (mobile, desktop or the web gateway). The host lends it a signer and routes all chain RPC. You reach the platform through `@parity/product-sdk`: `createApp(config)` returns an app with wallet, chain and cloud-storage APIs, and the SDK also has contract and identity modules. See [Use platform services from the SDK](/apps/build/platform-services-sdk/). ## 2. Build the frontend Produce a static build directory. With a Vite template: ```bash npm install npm run build # emits dist/ ``` The output (`dist/`) is what you publish. ## 3. Register a .dot domain Names are `.dot` domains managed by DotNS. Check that the name is free and register it with the DotNS CLI: ```bash dotns lookup name --env devnet dotns register domain -n --env devnet ``` Pass the label without the `.dot` suffix: `my-cool-app`, not `my-cool-app.dot`. Pick a label whose stem is nine characters or longer, so it registers without a personhood check. Shorter labels are gated. Registration is a commit-reveal handshake that takes a few minutes and costs a deposit. [Register a .dot domain](/apps/build/register-a-dot-name/) has the rules and the verification step. You can skip this step if you deploy with the account that will hold the name. `pad` registers the name for you during deploy if your signing account does not already own it. ## 4. Publish with pad Point `pad` at your build directory and the target name. `pad` takes its signer explicitly. It does not read the dotns keystore: ```bash pad ./dist .dot --env devnet --mnemonic "$MNEMONIC" ``` Keep the phrase in an environment variable, and never commit or print it. `pad` can also sign in with your Polkadot app: run `pad login` and pair your phone. While you are signed in, `pad` registers and deploys with a local key, then hands the name to your app account, so your phone signs nothing. These guides use `--mnemonic` throughout. `pad` uploads the bundle to Bulletin (skipping unchanged blocks on repeat deploys), registers the name if needed and writes the content hash on Asset Hub. A successful run ends with `Verified on-chain:` and the CID it published. Check that the name points at that CID before you share it: ```bash dotns content view --env devnet ``` The app is now live at `.dot` in the Polkadot app and at `https://.dev-dot.li` on the web gateway. ### Add card metadata Browse and the Polkadot app show your Product using a product config that `pad` reads at deploy time. Without one, the app still works, but it has no name, description or icon to show. Save this as `polkadot-app-deploy.config.ts` in your project. `pad` walks up from the build directory to find it: ```ts export default { domain: "my-cool-app.dot", displayName: "My Cool App", description: "What it does, in one line.", icon: { path: "./icon.png", format: "png" }, executables: [{ kind: "app", path: "./dist", appVersion: [1, 0, 0] }], }; ``` Paths are relative to the config file, and the icon must exist. `pad` checks all of this before it uploads anything. It then uploads the icon and writes the `manifest` record on your name, plus an `executable` record on `app..dot`: ```plaintext Icon CID: bafk2bzacecqdzkvdzflim3gspebc2iaqfjxtmqbuo6lpaqmvmlfhvkqxl2klw Writing root manifest text record on my-cool-app.dot (177 B)… ✓ 2 text records written. ``` `executables` also accepts `widget` and `worker` entries, published to the `widget.` and `worker.` subnames. ## Reference apps These small apps are deployed on the Devnet. Their source is in the [browse repository](https://github.com/paritytech/browse/tree/main/apps/registry/tests/fixture-projects): | App | Open | `.dot` name | What it does | | --------------- | ------------------------------------ | --------------------- | ------------------------------------------------------ | | Calculator | | `calculator.dot` | A basic calculator | | Stopwatch | | `stopwatch.dot` | A stopwatch | | Countdown Timer | | `countdown-timer.dot` | Counts down from a time you set | | Alarm Clock | | `alarm-clock.dot` | Rings at the time you set | | Chess Clock | | `chess-clock.dot` | Two clocks for a two-player game; tap to pass the turn | | Unit Converter | | `unit-converter.dot` | Converts units, such as metres to feet | ## Learn more * [Register a .dot domain](/apps/build/register-a-dot-name/): everything you can do with names * [Use platform services from the SDK](/apps/build/platform-services-sdk/): once your app is live * [App delivery](/apps/architecture/app-delivery/): how publishing works * [How Bulletin authorization works](https://github.com/paritytech/polkadot-bulletin-chain): the storage pallet and quota model # Add a Smart Contract to Your Product > Add a PolkaVM smart contract to your Polkadot Product — deploy it to Asset Hub with the Contract Dependency Manager and call it from your frontend. ## Introduction Some Products need on-chain logic and shared state that no single user owns: a leaderboard, a registry, an escrow, a game whose rules must be enforced for everyone. That is what a smart contract gives you. This guide adds a [PolkaVM](/reference/glossary/#polkadot-virtual-machine-pvm) contract to a Product, deploys it to Asset Hub, and calls it from your frontend with the [`@parity/product-sdk-contracts`](https://paritytech.github.io/product-sdk/) package. Contracts on Polkadot run as PolkaVM bytecode through the `pallet-revive` runtime on Asset Hub. You author them in Rust or Solidity, and the [Contract Dependency Manager](https://github.com/paritytech/contract-dependency-manager) (`cdm`) builds, deploys, and registers them, the same tool the `playground` CLI runs for you when it deploys a Product that has contracts. `cdm` fills the role npm fills for libraries, but for on-chain contracts: it publishes each contract under a global name (`@scope/name`) in an on-chain registry, so your frontend resolves it by name instead of hardcoding an address. Contracts are optional Many Products never need a contract. If all you need is durable content or real-time state between users, [Store Data on Chain](/apps/build/store-data-on-chain/) and [Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/) cover those without any contract at all. Reach for a contract when you need enforced, shared on-chain logic. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Smart contracts](/apps/architecture/contracts/). ## Prerequisites Before starting, ensure you have: * A Polkadot Product project running locally. See [Set Up Your Project](/apps/build/#set-up-your-project). * PAS funds and a Bulletin Chain authorization for the account `cdm` will sign with. See [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/). Deploying a contract writes to Asset Hub (fees) and publishes metadata to the Bulletin Chain (authorization). The next two sections cover installing `cdm` and creating that account. * A workstation rather than a browser alone. Contracts compile to PolkaVM, so unlike the frontend capabilities this step needs a local toolchain. ## Install cdm Install the `cdm` binary. The installer also pulls the Rust nightly toolchain with `rust-src` and the `cargo-pvm-contract` build tool: ```bash curl -fsSL https://raw.githubusercontent.com/paritytech/contract-dependency-manager/main/install.sh | bash ``` Update an existing install with `cdm update`. `cdm` and `playground` are separate installs Installing the [`playground` CLI](/apps/quick-start/) does not give you `cdm`, and vice versa. `playground deploy` shells out to its own bundled CDM pipeline for the contract step, but running `cdm` directly, as this guide does, needs the binary on your `PATH`. ## Set Up a Signing Account `cdm` signs from the CLI with its own keypair, separate from the account your phone holds. Generate one for the network, then map it for `pallet-revive`: ```bash cdm init -n paseo cdm account map -n paseo ``` The mapping step is required before your first deploy: `pallet-revive` needs each signing account bound to its H160 address, and without it the deploy fails. Two related subcommands are useful while you work: * **`cdm account bal -n paseo`**: Prints the account's balance and its Bulletin allowances, and links to a top-up when they run low. * **`cdm account set -n paseo --mnemonic "…"`**: Imports an existing account instead of generating one. `cdm`'s `paseo` preset is Paseo Next, not the Paseo TestNet `cdm -n paseo` targets the Paseo Asset Hub preview network (para 1500), the same network the `playground` CLI deploys to. `cdm -n devnet` targets Products Devnet, the Paseo TestNet Asset Hub (para 1000) with a registry operated by the Polkadot Community Foundation (PCF). Problems with Products Devnet go to PCF, not Parity; see [Choose the Right Channel](/get-support/#choose-the-right-channel). They are different chains with different registries, so a contract deployed under one preset is not resolvable under the other. Fund the account on the network you actually target — the [faucet](/apps/get-started/get-testnet-tokens/) needs `?parachain=1500` for Paseo Next. ## How Contracts Fit Together Four things happen when you publish a contract, and `cdm` handles all of them in one flow: * **Build**: Your Rust or Solidity contract compiles to PolkaVM bytecode targeting `pallet-revive` (Solidity via `resolc`). * **Deploy**: The bytecode is instantiated on Asset Hub at a deterministic address. * **Publish metadata**: The contract's ABI and docs are uploaded to the Bulletin Chain, addressed by CID. * **Register**: The contract's global name (`@scope/name`) is recorded in the on-chain `ContractRegistry`, mapping the name to its address and metadata CID. Your frontend then reads a project-local manifest, `cdm.json`, which holds the deployed address and ABI for each contract your Product depends on. The [`@parity/product-sdk-contracts`](https://paritytech.github.io/product-sdk/) package turns that manifest into typed contract objects. The registry is append-only Registration is permanent: the first account to publish a name owns it, versions only ever increment, and nothing can be overwritten or deleted. Do not publish a name you are only testing with as your real account, and never register anything you want to keep from a shared dev account such as `//Alice`. ## Scaffold a Contract `cdm` ships example templates. Scaffold the `shared-counter` template, which defines a minimal counter contract you can adapt: ```bash cdm template shared-counter ``` That writes a Cargo workspace and a `cdm.json` manifest into `./shared-counter`. Pass a target directory to override the location, or `.` to scaffold into the current directory. The template ships three crates under `contracts/` that demonstrate a dependency graph: `counter` holds the shared count, `counter-writer` calls `counter.increment()` through a CDM reference, and `counter-reader` queries `counter.get_count()`. A fuller example `cdm template instagram` scaffolds a complete browser app rather than bare contracts, combining Product Account signing, Bulletin uploads, and `ContractManager` resolution from `cdm.json`. Reach for it when you want to read a working end-to-end Product instead of assembling one. Each crate declares its CDM package name in its own `Cargo.toml`: ```toml [package.metadata.cdm] package = "@example/counter" ``` The contract itself is a module holding a storage struct and an `impl` block, annotated with the PolkaVM contract SDK macros: ```rust #![cfg_attr(not(feature = "abi-gen"), no_main, no_std)] #[pvm_contract_sdk::contract(allocator = "pico", allocator_size = 1024)] mod counter { use pvm_contract_sdk::Lazy; pub struct Counter { // Storage slots are auto-numbered in declaration order (`count` gets slot 0). count: Lazy, } impl Counter { #[pvm_contract_sdk::constructor] pub fn new(&mut self) { self.count.set(&0); } #[pvm_contract_sdk::method] pub fn increment(&mut self) { let current = self.count.get(); self.count.set(&(current + 1)); } #[pvm_contract_sdk::method] pub fn get_count(&self) -> u32 { self.count.get() } } } ``` Note that the constructor takes `&mut self` and initializes storage in place; it does not return `Self`. Storage fields are wrapped in `Lazy` so each is read and written on demand rather than loaded wholesale. Before deploying, change *every* `[package.metadata.cdm] package = "@example/…"` entry in the workspace to a scope you control, for example `@my-app/counter`. Package names are global per registry, the scaffolded `@example` scope is a placeholder, and registration is first-writer-owns, so you want your own scope on all three crates. Prefer Solidity? `cdm` also ships Solidity templates (`foundry-counter` and `hardhat-counter`) that compile to PolkaVM via `resolc`. Scaffold one the same way, for example `cdm template foundry-counter`. The deploy and frontend steps below are identical regardless of the contract language. ## Verify the Toolchain The `cdm` installer already set up the Rust nightly, `rust-src`, and `cargo-pvm-contract` that the contract compiler needs. Confirm they are in place before your first build: ```bash cdm setup --check ``` If anything is missing or was broken by an unrelated Rust change, `cdm setup` installs or repairs it: ```bash cdm setup ``` ## Build and Deploy Deploy with `cdm deploy`, selecting the target network with `-n`. This builds the bytecode, deploys it to Asset Hub, uploads the ABI to the Bulletin Chain, and registers the name, all in one flow: ```bash cdm deploy -n paseo --suri "INSERT_ACCOUNT_SECRET_URI" ``` `cdm` signs from the CLI with the account you pass as `--suri`, or with the keypair `cdm init` generated for the network. It does not sign through the Polkadot App or a phone. The `-n` preset also selects the registry for the network, so you do not set a registry address by hand. Always pass a signer you control With no `--suri` and no `cdm init` account, `cdm` falls back to the shared `//Alice` development key. Because registration is first-writer-owns, deploying that way parks your contract name on a public key anyone can use. Pass `--suri` (or run `cdm init` first) so the name and contract belong to you. Deploying alongside your Product When you deploy the whole Product with [`playground deploy`](/apps/deploy-your-app/), the CLI runs this contract step for you. At the `did you change your smart contracts?` prompt, choose `yes` and the CLI redeploys the contracts and rebuilds the site to match. Use `cdm deploy` directly when you want to iterate on the contract on its own, without redeploying the frontend. ## Add the Contract to Your Manifest Your frontend resolves contracts from `cdm.json`, and `cdm deploy` does not write that file — `cdm install` does. After deploying, install your contract to write its address and ABI into the manifest. Installing works the same for a contract someone else published, so pass whichever `@scope/name` you need: ```bash cdm install @my-app/counter -n paseo ``` `cdm install` resolves the name against the on-chain registry, fetches the ABI from the Bulletin Chain, and writes the entry into `cdm.json`: ```json { "dependencies": { "@my-app/counter": "latest" }, "contracts": { "@my-app/counter": { "version": 1, "address": "0x…", "abi": [ /* … */ ], "metadataCid": "bafy…" } } } ``` The `shared-counter` template ships its `cdm.json` already populated for the example contracts, so you only run `cdm install` when you deploy your own contract or add someone else's. ## Call the Contract From Your Frontend Install the contracts package (or use the umbrella `@parity/product-sdk`): ```bash npm install @parity/product-sdk-contracts @parity/product-sdk-chain-client @parity/product-sdk-descriptors @parity/product-sdk-signer ``` Build a `ContractManager` from the manifest and the host-routed chain client, map your signing account once (every contract write fails with `AccountNotMapped` until you do), then get a typed handle by name. Reads use `query` (a dry run — check `.success`), and writes use `tx` (which signs through the Host — check `.ok`): ```typescript import { SignerManager } from '@parity/product-sdk-signer'; import { createChainClient } from '@parity/product-sdk-chain-client'; import { paseo_asset_hub } from '@parity/product-sdk-descriptors/paseo-asset-hub'; import { ContractManager, ensureContractAccountMapped, } from '@parity/product-sdk-contracts'; import cdmJson from './cdm.json'; async function useCounter() { // The same SignerManager setup as Sign and Submit Transactions. const signerManager = new SignerManager({ ss58Prefix: 0, dappName: 'my-app.dot' }); const connected = await signerManager.connect(); if (!connected.ok) return; const productAccount = await signerManager.getProductAccount('my-app.dot', 0); if (!productAccount.ok) return; const account = productAccount.value; const signer = account.getSigner(); const client = await createChainClient({ chains: { assetHub: paseo_asset_hub } }); const manager = ContractManager.fromClient( cdmJson, client.raw.assetHub, paseo_asset_hub, { signerManager }, ); // pallet-revive requires each signing account to be mapped once. await ensureContractAccountMapped(manager.getRuntime(), account.address, signer); const counter = manager.getContract('@my-app/counter'); // Read: a dry run. Check .success before reading .value. const count = await counter.getCount.query(); if (count.success) { console.log(count.value); } // Write: signs through the Host. Returns a Result — check .ok. const result = await counter.increment.tx({ signer }); if (!result.ok) { console.error(result.error.message); } } ``` Passing `signerManager` to `fromClient` lets the manager resolve the current account at call time, so an account switch is picked up without rebuilding it. See [Sign and Submit Transactions](/apps/build/sign-and-submit/) for the signing setup in depth. Contract writes are signed by your Product-scoped account, so they route to the user's phone for approval like any other transaction. For the full frontend surface, see [Contracts](/apps/product-sdk/contracts/). query returns a status, tx returns a Result `query` is a dry run that does not throw on a revert; branch on `.success`, because on failure `.value` holds the dispatch-error payload, not your data. `tx` returns a `Result`; check `.ok` before assuming the write landed. ## Redeploy After a Contract Change Contracts are immutable once deployed. Changing contract code means deploying a new version: run `cdm deploy -n paseo --suri ...` again (or choose `yes` at the contract prompt in `playground deploy`). The registry appends a new version under the same name; run `cdm install @my-app/counter -n paseo` afterward to refresh the address and ABI in `cdm.json` so your frontend picks up the new deployment. Because a redeploy gives your contract a new on-chain address, existing users pointed at the old address keep using the old contract until they load the new bundle. Storage does not move with it: the new instance starts empty, and the old one keeps serving whoever has not reloaded. For a contract with live users and stored state, that makes a redeploy a migration rather than an update. What it takes: * **Snapshot the old state before you redeploy.** Read it out through the old contract's `query` methods while its address is still the one in `cdm.json`, since afterward you need the previous address to reach it. * **Seed the new instance** from that snapshot, or give the contract a method that accepts it, before pointing users at the new address. * **Keep reading from the old address until the new one is populated**, so users who reload mid-migration do not see an empty contract. * **Expect a window where both are live.** Users on the old bundle keep writing to the old address until they reload, so either accept losing those writes or drain them after the fact. None of that is automated. If your contract will hold state you cannot afford to lose, design for it up front — an explicit initializer that accepts prior state costs far less than reconstructing one later. ## Where to Go Next * **Deploy Your App** *** Deploy the whole Product, contracts and frontend together, and register a `.dot` name with the `playground` CLI. [→ Deploy Your App](/apps/deploy-your-app/) * **Product SDK API Reference** *** The full `@parity/product-sdk-contracts` surface: `ContractManager`, contract handles, and the `query`, `tx`, and `prepare` methods. [→ Visit Site](https://paritytech.github.io/product-sdk/) * **Contract Dependency Manager** *** The `cdm` toolchain in depth: templates, the registry model, versioning, and installing published contracts. [→ Visit Repo](https://github.com/paritytech/contract-dependency-manager) # Persist Data Locally > Learn how to store and retrieve application data between sessions in a Polkadot Product using the @parity/product-sdk-local-storage package. ## Introduction This guide covers the `@parity/product-sdk-local-storage` package, which provides a `LocalKvStore` for storing and retrieving key-value data between sessions. Use it for device-local data like saved preferences, unsubmitted drafts, or cached responses. Data is scoped to your Product and device; it does not sync across devices or leak between Products on the same Host. Storage options for your Product Match the data to the layer built for it; see [Where to Store Data](/apps/concepts/data-placement/) for the full decision guide. * **Local storage**: Per-Product, per-device key-value for preferences, drafts, and cached values. Not synced across devices. See [Persist Data Locally](/apps/build/persist-data-locally/). * **Bulletin Chain**: Content-addressed, on-chain, retained \~2 weeks by default and renewable. Fetched later by CID: profile photos, published articles, app bundles. See [Store Data on Chain](/apps/build/store-data-on-chain/). * **Statement Store**: Gossip-distributed, short-lived (default 30s TTL), allowance-gated. Real-time signaling between users: chat, presence, typing indicators. See [Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/). ## Prerequisites Before getting started, ensure you have: * A Polkadot Product project running locally (see [Set Up Your Project](/apps/build/#set-up-your-project)) * Node.js 20 or later with ESM support (`@parity/product-sdk-local-storage` is ESM only) ## Install the SDK The SDK installs two ways. The umbrella package, `@parity/product-sdk`, is the recommended starting point: one dependency that re-exports most of the SDK. Individual packages install only what you use, which keeps your bundle smaller and your dependencies explicit, so switch to them later as a bundle-size optimization. The two use different import specifiers, so switching styles means updating your imports. See [Umbrella or Individual Packages](/apps/build/#umbrella-or-individual-packages) for the full comparison. * **Umbrella package**: The whole SDK in one dependency. ```bash npm install @parity/product-sdk ``` * **Individual package**: Only local storage. ```bash npm install @parity/product-sdk-local-storage ``` The import specifiers differ between the two. The snippets in this guide use the standalone specifier `@parity/product-sdk-local-storage`; on the umbrella, the same exports come from the `@parity/product-sdk/local-storage` subpath. The React hooks shown later are umbrella-only, under `@parity/product-sdk/react`. Code examples Each snippet in this guide is a standalone file you add to your Product's source tree. The filenames match the `title` shown in the code block header (for example, `initialize.ts`, `set-get-string.ts`). They are not meant to be concatenated; import and use each one independently wherever it fits in your Product. ## Initialize the Store `createLocalKvStore()` is an async factory. You must `await` it before performing any read or write, because the function connects to the Host storage backend before the store is usable. ```typescript import { createLocalKvStore } from '@parity/product-sdk-local-storage'; import type { LocalKvStore } from '@parity/product-sdk-local-storage'; // Connects to the Host storage backend. Must run inside a Polkadot Product; // outside a host container this throws "Host storage unavailable". const store: LocalKvStore = await createLocalKvStore(); ``` `createLocalKvStore()` accepts an optional `LocalKvStoreOptions` argument. The supported option is `prefix`, which is covered in [Namespace Keys with Prefixes](#namespace-keys-with-prefixes). ## Store String Values Use `store.set(key, value)` to write a string value for a key. Use `store.get(key)` to read it back. If the key has not been set, `get` returns `null`. ```typescript await store.set('network', 'paseo'); const network = await store.get('network'); if (network === null) { console.log('Key not found'); } else { console.log('Network:', network); } ``` ## Store JSON Values Use `store.setJSON(key, value)` to write any JSON-serializable value. The store handles serialization for you. Use `store.getJSON(key)` to read it back; the generic type parameter `T` enables type-safe retrieval. If the key does not exist, `getJSON` returns `null`. ```typescript interface UserPreferences { theme: 'light' | 'dark'; language: string; } await store.setJSON('preferences', { theme: 'dark', language: 'en', } satisfies UserPreferences); const preferences = await store.getJSON('preferences'); if (preferences === null) { console.log('No preferences found'); } else { console.log('Theme:', preferences.theme); console.log('Language:', preferences.language); } ``` ## Remove Stored Values Use `store.remove(key)` to delete a key. The method does not throw if the key does not exist, so you can call it safely without first checking whether the value is present. ```typescript await store.remove('network'); ``` ## Namespace Keys with Prefixes Within a Product, multiple features may share the same `LocalKvStore`. Prefixes partition the namespace further to avoid key collisions between those features. Pass a `prefix` option to `createLocalKvStore()` to prepend `prefix:` to every key operated on by that store instance. For example, `createLocalKvStore({ prefix: 'feature' })` stores the key `'setting'` internally as `'feature:setting'`. ```typescript import { createLocalKvStore } from '@parity/product-sdk-local-storage'; const settingsStore = await createLocalKvStore({ prefix: 'settings' }); const cacheStore = await createLocalKvStore({ prefix: 'cache' }); // Stored internally as "settings:theme" await settingsStore.set('theme', 'dark'); // Stored internally as "cache:lastBlock" await cacheStore.set('lastBlock', '21540000'); ``` The Host-enforced Product-level namespace is separate from any developer-defined prefix. The Host's Product namespace is applied on top of your `prefix`, so a key `'setting'` in a `{ prefix: 'feature' }` store ends up stored as something like `'myproduct.dot:feature:setting'`, without you needing to construct that path yourself. Prefixed stores do not share a key space `app.localStorage` is itself a prefixed store: `createApp` builds it with a prefix taken from the Host's product ID, minus the final domain suffix (`my-product.dot` becomes `my-product`). Before v0.30.0, the prefix is the `name` you passed. A store you create with a different `prefix` writes under a different path, so a key written through `createLocalKvStore({ prefix: 'feature' })` and read back through `app.localStorage` resolves to `null` rather than raising an error. Read and write each key through the same store. ## Use React Hooks If your Product is a React application, `@parity/product-sdk` provides hooks that integrate local storage directly into the React component lifecycle. The hooks read the current value on mount and re-render the component whenever it changes. Wrap your application in `ProductSDKProvider` once at the root, then call the hooks anywhere inside the tree: ```tsx 'use client'; import { ProductSDKProvider } from '@parity/product-sdk/react'; import type { ReactNode } from 'react'; export function Providers({ children }: { children: ReactNode }) { return ( Initializing SDK…} > {children} ); } ``` `useLocalStorageString` manages a plain string value. `useLocalStorage` manages a JSON-serializable value typed by `T`. Both hooks return a tuple of `[currentValue, setValue, { loading, error }]`: ```tsx 'use client'; import { useLocalStorage, useLocalStorageString, } from '@parity/product-sdk/react'; interface UserPreferences { theme: 'light' | 'dark'; language: string; } function StorageDemo() { const [network, setNetwork, { loading: networkLoading }] = useLocalStorageString('network'); const [ preferences, setPreferences, { loading: prefsLoading, error: prefsError }, ] = useLocalStorage('preferences'); return (

Network: {networkLoading ? 'loading…' : (network ?? 'not set')}

Theme: {prefsLoading ? 'loading…' : (preferences?.theme ?? 'not set')}

{prefsError &&

Error: {prefsError.message}

}

); } ``` To remove a key, access `app.localStorage` from `useProductSDK()` directly: ```tsx 'use client'; import { useProductSDK } from '@parity/product-sdk/react'; function StorageActions() { const app = useProductSDK(); async function handleRemove() { await app.localStorage.remove('network'); } return (

); } ``` There is no clear-all `LocalStorageApi` exposes `get`, `getJSON`, `set`, `setJSON`, and `remove`, and nothing else. The backing store has no way to enumerate keys, so removing everything your Product wrote means calling `remove()` on each key you know about. Track the keys yourself if you need that. ## Limitations * Storage is not synced across devices. Values written on one Host instance are not visible on another. * `app.localStorage` and every `LocalKvStore` are scoped to your Product. You cannot read or modify another Product's keys. * React hooks (`useLocalStorage`, `useLocalStorageString`) are only available via the umbrella package `@parity/product-sdk`. The standalone `@parity/product-sdk-local-storage` package exposes no React hooks. * `createLocalKvStore()` requires a Host backend. Running outside a host container, it throws `Host storage unavailable`; there is no browser `localStorage` fallback. Run your Product inside [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/) to use local storage. See [`Host storage unavailable`](/apps/troubleshooting/#uploads-are-rejected-or-host-storage-unavailable) in troubleshooting. ## Where to Go Next * **Store Data on Chain** *** When data must outlive the device and be fetchable by anyone, move it to the Bulletin Chain. [→ Store Data on Chain](/apps/build/store-data-on-chain/) * **Deploy Your Product** *** You've covered the capabilities; ship your Product to a live `.dot` name with the Quick Start deploy routes. [→ Quick Start](/apps/quick-start/) * **Product SDK API Reference** *** The full `product-sdk` surface beyond this recipe: every package, class, and method. [→ Visit Site](https://paritytech.github.io/product-sdk/) # Use platform services from the SDK Your app reaches the platform through the Product SDK (`@parity/product-sdk`). This guide covers the services most apps need first: chain access, signing, cloud storage, contract calls, and a user's identity and personhood status. [Packages & tools](/apps/reference/packages/) has the install line. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Product SDK](/apps/product-sdk/) or [Build](/apps/build/). ## Before you start The SDK is a TypeScript umbrella package. You import from its subpath entry points directly: `./chain`, `./cloud-storage`, `./contracts`, `./identity`, `./individuality`, `./nfts`, `./host`, `./wallet`, `./local-storage`, `./crypto`, `./address`, `./renderer`, `./core`, `./react`, and `./testing`. `./react` (`ProductSDKProvider`, `useChain`, `useWallet`, `useLocalStorage`, `useProductSDK`) declares `react` `^18 || ^19` as a peer dependency. In a project without React installed, only that subpath fails, with a module-not-found error. ### Your app has to run inside a host Every chain call and every storage call goes through the host container: the Polkadot app (mobile or desktop) or the web gateway at [dev-dot.li](https://dev-dot.li). Outside a container, `createApp()` itself throws before you reach any service: ```plaintext HostUnavailableError: createApp requires a host product context ``` A chain call made outside a container throws `Host provider unavailable for chain `. To run your app in CI, use the [test host](#test-without-the-real-host). ### Check results instead of catching errors Most operations that can fail return a `Result` instead of throwing. `Result` is `{ ok: true; value: T } | { ok: false; error: E }`, so check `res.ok` before you read `res.value`. `ok`, `err` and `isErrorOf` are exported from the package root. `createApp`, `getChainAPI` and the `app.wallet` helpers do throw, so wrap those in `try`/`catch`. ## Connect to the chains The chain client gives you typed PAPI access to the three platform chains: Asset Hub, the Bulletin chain, and the Individuality (People) chain. You can connect in two ways. The simplest is the preset. Call `getChainAPI(env)` and the SDK loads the right descriptors for you: ```ts import { getChainAPI } from "@parity/product-sdk/chain"; const client = await getChainAPI("devnet"); const account = await client.assetHub.query.System.Account.getValue(address); const fee = await client.bulletin.query.TransactionStorage.ByteFee.getValue(); client.individuality; // People-chain access client.raw; // lower-level PAPI handles, keyed by chain name client.destroy(); // tear the connections down when you are finished ``` `Environment` has five values: `polkadot`, `kusama`, `paseo`, `previewnet` and `devnet`. `polkadot` and `kusama` throw before connecting, because their Bulletin and Individuality chains are not live yet. Connections are cached by each chain's genesis-hash fingerprint. For a specific or pre-release chain, pass descriptors yourself. They live in `@parity/product-sdk-descriptors`. To import from it, add it as a direct dependency, as shown in [Current Devnet chain metadata](/apps/reference/packages/#current-devnet-chain-metadata): ```ts import { createChainClient } from "@parity/product-sdk/chain"; import { devnet_asset_hub } from "@parity/product-sdk-descriptors/devnet-asset-hub"; import { devnet_bulletin } from "@parity/product-sdk-descriptors/devnet-bulletin"; const client = await createChainClient({ chains: { assetHub: devnet_asset_hub, bulletin: devnet_bulletin }, }); ``` `createChainClient` is async. If you leave out the `await`, the failure only shows up on the next line you write, as a `Property 'assetHub' does not exist on type 'Promise>'` error. The descriptor chooses the chain The descriptor you pass to `createChainClient` is your network selection. Passing `paseo_asset_hub` here connects your app to Paseo Next, not this Devnet, whatever `--env` you deployed with. Nothing fails at build time: the app builds and loads, then throws `ChainNotSupportedError` at runtime. Match the descriptor prefix to your target network. ## Sign transactions Signing goes through the host wallet, so you never manage keys yourself. Connecting returns a `Result` with the available accounts. `getSigner()` returns the selected account's PAPI 3 transaction signer, but only once an account is selected: ```ts import { SignerManager } from "@parity/product-sdk/wallet"; const manager = new SignerManager(); const connected = await manager.connect(); // or connect("dev") for Alice/Bob if (!connected.ok) throw connected.error; const [account] = connected.value; if (!account) throw new Error("Host wallet returned no accounts"); manager.selectAccount(account.address); const signer = manager.getSigner(); // CommonSignerTxCreator | null ``` `connect()` reports failure in its result and does not throw. If you skip the check, you end up with a `null` signer and no error to explain it. ## Store and retrieve data (Cloud Storage) Cloud Storage is content-addressed storage backed by the Polkadot Bulletin chain, and it is how an app is meant to persist data. You store bytes, get back a root CID, and read the bytes back by CID. Uploads need a connected wallet with a selected account, and a storage authorization on that account. [Storage & data](/apps/architecture/storage/) explains the model behind it. ```ts import { createApp } from "@parity/product-sdk"; const app = await createApp({ cloudStorage: { environment: "devnet" }, }); const cloud = app.cloudStorage; if (!cloud) throw new Error("Cloud Storage is disabled"); const uploaded = await cloud.upload(bytes); if (!uploaded.ok) throw uploaded.error; const fetched = await cloud.fetch(uploaded.value); if (fetched.ok) { render(fetched.value); // Uint8Array } ``` `cloudStorage.environment` defaults to `paseo` Omit the option and the SDK targets Bulletin on Paseo, which a Devnet host does not serve, so `createApp()` fails. Pass `environment: "devnet"`. The values are `paseo`, `previewnet` and `devnet`. Passing `cloudStorage: false` turns the service off, which is why `app.cloudStorage` can be null. `cloud.computeCid(data)` computes the CID of raw bytes without uploading them (`calculateCid` from the package root does the same without an `App`). This is not the CID that `upload()` returns, which is the CID of the stored manifest. Reads only work inside a container. There is no IPFS-gateway fallback. ## Call smart contracts Contracts on the devnet are PolkaVM bytecode running on Asset Hub through `pallet-revive`, with Solidity-style ABIs. Build a runtime from a raw PAPI client, then a typed contract handle: ```ts import { createContract, createContractRuntimeFromClient, } from "@parity/product-sdk/contracts"; // client and manager as above; address and abi are your contract's. const runtime = createContractRuntimeFromClient(client.raw.assetHub, devnet_asset_hub); const contract = createContract(runtime, address, abi, { signerManager: manager }); ``` The argument order is `(runtime, address, abi)`, with the address first. The optional fourth argument supplies the signer: pass `{ signerManager }` for `.tx()` calls, which look up the selected account when you call them. Read-only `.query()` calls need no account and fall back to the keyless `QUERY_FALLBACK_ORIGIN`. `ensureContractAccountMapped(runtime, address, signer)` maps an account for `pallet-revive` when a call needs it. ## Read identity and personhood To prove a user controls a `.dot` identity, sign with the account that owns it. The wallet looks up the username's owner on the People chain and signs with that account: ```ts import { devnet_individuality } from "@parity/product-sdk-descriptors/devnet-individuality"; const proof = await app.wallet.signMessageWithDotNsIdentity({ peopleChain: devnet_individuality, username: "alice", // omit to use the user's primary .dot name message: "Sign in to my-app", }); proof.username; // username used for the lookup proof.accountId; // owning AccountId32, 0x-prefixed proof.signature; // Uint8Array ``` Usernames are matched byte for byte against the chain's records, and the `.dot` suffix is not handled for you, so pass the exact registered value. If you omit `username`, the host shows an identity-permission prompt. If your app already connects the People chain with `app.chain.connect({ … })`, the lookup reuses that connection. For an app-scoped account, or a per-context alias that cannot be linked back to the user's account, use `SignerManager.getProductAccount()` and `SignerManager.getProductAccountAlias()`. Both go through the host. `isValidDotNsName(name, suffix)` and `normalizeDotNsName(name, suffix)` validate and canonicalise a name. Pass the TLD suffix, which is `".dot"` on this Devnet. For the raw host session (login state, product accounts, ring proofs), call `getAccountsProvider()` from `@parity/product-sdk/host`. It is async and resolves to `null` outside a host container. Its methods return neverthrow `ResultAsync` values (`.isOk()`), not the SDK's own `Result`. To read a user's personhood tier on-chain, call the `personhood` `pallet-revive` precompile at the fixed address `0x000000000000000000000000000000000A010000` with a contract handle. Its `personhoodStatus(account, bytes32 context)` returns a status (`0 = None`, `1 = Lite`, `2 = Full`) and a per-application `contextAlias`. [Identity & personhood](/apps/architecture/identity/) has the full model. ## Test without the real host `@parity/truapi-host` ships a Playwright test host that runs the real host core with auto-signing dev accounts, so you can drive your app end to end in CI: ```bash npm i -D @parity/truapi-host@0.25.0 @playwright/test esbuild ``` ```ts import { test as base, expect } from "@playwright/test"; import { createTestHostFixture, type TestHost, } from "@parity/truapi-host/testing/playwright"; const test = base.extend<{ testHost: TestHost }>( createTestHostFixture({ productUrl: "http://localhost:5173", productId: "my-app.dot", // the .dot name your app signs as accounts: ["alice"], networks: [ { id: "devnet-asset-hub", name: "Devnet Asset Hub", genesisHash: "0xd6eec26135305a8ad257a20d003357284c8aa03d0bdb2b357ab0a22371e11ef2", rpcUrl: "wss://asset-hub-paseo-rpc.n.dwellir.com", tokenSymbol: "PAS", tokenDecimals: 10, }, ], }), ); test("signs a transfer", async ({ testHost }) => { await testHost.waitForConnection(); await testHost.productFrame().getByRole("button", { name: "Send" }).click(); const signed = await testHost.getSigningLog(); expect(signed.length).toBeGreaterThan(0); }); ``` The fixture embeds your product in an iframe, signs in the dev accounts, auto-signs signing requests, and proxies chain RPC to the chains you list. `switchAccount`, `getSigningLog` and the permission, notification and chat logs let tests check what the host did. Each `networks` entry's `id` suffix sets its role (`-asset-hub`, `-people`, `-bulletin`). If your app uses People or Bulletin, add entries for them from [Networks & endpoints](/apps/reference/networks/). `productId` must be the name your app signs as, because the host refuses a signing request scoped to another product. ## Learn more * [product-sdk](https://github.com/paritytech/product-sdk): SDK source * [Claude Code plugin](https://github.com/paritytech/product-sdk#claude-code-plugin): agent skills for every SDK area. See the [developer quickstart](/apps/get-started/developers/#build-with-claude-code) * [Smart contracts](/apps/architecture/contracts/): contracts on Asset Hub * [Identity & personhood](/apps/architecture/identity/): the model behind the precompile # Publish and Subscribe to Off-Chain Data > Publish and subscribe to off-chain data from a Polkadot Product using the Statement Store. Filter by topic, publish statements, and use channels. ## Introduction This guide covers the [Statement Store](/reference/apps/infrastructure/statement-store/), a pub/sub primitive on Polkadot's People Chain for real-time signaling between users of your Product. Statements are small, signed payloads that propagate peer-to-peer via the node's gossip layer without entering chain storage, making them the right tool for chat messages, presence indicators, multiplayer cursors, and typing indicators. Submissions are allowance-gated (no fees); reading is permissionless. The guide covers four steps: setting up the client, subscribing to incoming statements, publishing a typed statement, and using a channel for last-write-wins state. Storage options for your Product Match the data to the layer built for it; see [Where to Store Data](/apps/concepts/data-placement/) for the full decision guide. * **Local storage**: Per-Product, per-device key-value for preferences, drafts, and cached values. Not synced across devices. See [Persist Data Locally](/apps/build/persist-data-locally/). * **Bulletin Chain**: Content-addressed, on-chain, retained \~2 weeks by default and renewable. Fetched later by CID: profile photos, published articles, app bundles. See [Store Data on Chain](/apps/build/store-data-on-chain/). * **Statement Store**: Gossip-distributed, short-lived (default 30s TTL), allowance-gated. Real-time signaling between users: chat, presence, typing indicators. See [Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/). The Statement Store and Bulletin Chain compose well: [Polkadot App](/reference/apps/hosts/polkadot-app/)'s Chat uses the Statement Store for signaling (who's online, session handshakes) and the Bulletin Chain for the encrypted message content. Many Products follow the same split: Statement Store for ephemeral state, Bulletin Chain for content that needs to survive longer than a session. ## Prerequisites Before starting, ensure you have: * Completed [Install Desktop and Pair](/apps/get-started/) so you have a paired [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/) and a signer for product-scoped accounts * A Statement Store allowance for your account; the People Chain's `pallet-statement-store` gates submissions on a per-account allowance (`max_count` live statements and `max_size` total bytes) * A Polkadot Product project running locally (see [Set Up Your Project](/apps/build/#set-up-your-project) if you don't have one yet) Provisional: obtaining an allowance The process for obtaining a Statement Store allowance on TestNet is not yet documented. Ask in the developer community for the current access paths. Note PAS funds are not required for the Statement Store itself; submissions don't pay transaction fees. The allowance is the gating mechanism; PAS is only relevant if your Product later interacts with chains that charge fees. ## Install the SDK This guide builds on `createApp`, which only the umbrella package provides, and on `statement-store`, which has no umbrella subpath, so install both: ```bash npm install @parity/product-sdk @parity/product-sdk-statement-store ``` Versions the snippets target The snippets target `@parity/product-sdk` v0.30.0 and `@parity/product-sdk-statement-store` v0.6.11; every SDK surface they use is present on that line. If you pin an earlier release, pass `createApp` a `name` (required before v0.30.0) and check the return types first: v0.18.0 moved `StatementStoreClient.publish` and `ChannelStore.write` from `Promise` to a typed `Result`. A `Result` object is always truthy, so code written for the older shape keeps compiling and stops working. See [Umbrella or Individual Packages](/apps/build/#umbrella-or-individual-packages) for how the install styles compare. ## Set Up Your Statement Store Client Every snippet in this guide is Product code: modules placed inside the Product running at `localhost:3000` (per [Set Up Your Project](/apps/build/#set-up-your-project)), loaded by Polkadot Desktop. Signing requests route through the Host (Polkadot Desktop) to the user's paired Polkadot App on their phone, which holds the signing keys; your Product never derives, sees, or holds keys. `StatementStoreClient` is the high-level client. It wraps the People Chain node's `statement_submit` and `statement_subscribeStatement` JSON-RPC methods, handles JSON encoding of your payload, requests authentication proofs from the Host, and deduplicates incoming statements. Connect it once at the top of your Product: Start with the shared app setup, which creates the SDK app and connects the wallet. It is the same file [Store Data on Chain](/apps/build/store-data-on-chain/) uses: ```typescript import { createApp } from '@parity/product-sdk'; // The Host supplies your Product's identity: `createApp` reads the product ID // the Host loaded you under and derives the user's product account from it. // If the Host declines to derive an account, `connect()` resolves with an empty // list instead of failing, so check the list before you rely on it. export const app = await createApp(); export const { accounts } = await app.wallet.connect(); if (accounts.length === 0) { throw new Error( 'The Host returned no account for this Product. Check that you are signed in to Polkadot Desktop.', ); } ``` Then create the Statement Store client for the first connected account: ```typescript // Place this in your Product, after the setup from `setup-app.ts`. import { StatementStoreClient } from '@parity/product-sdk-statement-store'; import { accounts } from './setup-app'; // `appName` is the gossip topic this client subscribes to, not a dotNS name. export const client = new StatementStoreClient({ appName: 'my-product' }); await client.connect({ mode: 'host', accountId: [accounts[0].address, 42], // 42 = generic SS58 prefix }); console.log('Statement Store connected as', accounts[0].address); ``` `new StatementStoreClient({ appName })` creates the client. The `appName` is hashed with Blake2b-256 and used as the statement's primary topic; every submission your Product makes carries that topic, and `client.subscribe()` filters on it at the node boundary, so other instances of *your* Product see your statements while traffic from other Products on the network is dropped before it reaches your subscriber. `client.connect({ mode: 'host', accountId })` wires the client to the Host API transport and delegates proof creation to the Host; Polkadot Desktop routes the proof request to the user's paired Polkadot App, which signs and returns the proof. The `accountId` is a tuple of `[ss58Address, chainPrefix]`; `42` is the generic Substrate SS58 prefix. Delivery is best-effort The Statement Store does not retry, acknowledge, or guarantee ordering; those are network-layer guarantees the gossip protocol doesn't provide. If your Product needs to know a statement reached a peer, the peer publishes an ack statement; reliability is composed at the application layer. If the content needs to outlive the TTL, store it on the Bulletin Chain and publish a CID as the statement payload. Polkadot App's Chat is exactly this composition: Statement Store for signaling, Bulletin Chain for the encrypted message content. ## Subscribe to Incoming Statements `client.subscribe(callback, options?)` registers a topic filter with the connected node. Internally, the SDK calls `statement_subscribeStatement` with a filter scoped to your Product's `appName` topic; the node returns the current statement pool matching that filter and streams any further submissions that match. The SDK decodes the JSON payload into your typed `T` and dedupes by channel and content hash before invoking your callback: ```typescript // Place this in your Product, after the setup from `setup-statement-store.ts`. import type { ReceivedStatement } from '@parity/product-sdk-statement-store'; import { client } from './setup-statement-store'; // JSON-serialized when published; decoded back to this type on receive. interface ChatMessage { text: string; from: string; ts: number; } const subscription = client.subscribe( (statement: ReceivedStatement) => { console.log( `[${statement.signerHex?.slice(0, 10)}…] ${statement.data.from}: ${statement.data.text}`, ); }, { topic2: 'room-42' }, ); // subscription.unsubscribe() when you no longer want updates. ``` The optional `topic2` is hashed with Blake2b-256 and added to the filter; scope to a room id, a document id, or any other secondary key within your Product. The returned `Unsubscribable` exposes `unsubscribe()` to tear down the JSON-RPC subscription when you no longer need it. A subscription receives every statement on its topic, regardless of payload shape The filter matches on topics, not on your TypeScript type. A subscriber on a given `topic2` receives *all* statements published to that topic, including channel writes (the next section) and any other payload type your Product publishes there. The SDK decodes each one as your declared `T`, so a statement with a different shape arrives with `undefined` fields rather than an error. If your Product publishes more than one kind of payload (for example, chat messages *and* presence updates), either give each kind its own `topic2` (`room-42-chat` vs `room-42-presence`) or include a discriminator field in the payload and branch on it inside the callback. Reusing one `topic2` for distinct shapes will cross-deliver them. ## Publish a Typed Statement `client.publish(data, options?)` builds a `Statement`, JSON-encodes the payload, requests a proof through the Host (Polkadot Desktop forwards the request to the user's paired Polkadot App, which signs), and submits via the node's `statement_submit` JSON-RPC. Every instance of your Product subscribed to the matching topic will receive it as the gossip propagates: ```typescript // Place this in your Product, after the setup from `setup-statement-store.ts`. import { client } from './setup-statement-store'; interface ChatMessage { text: string; from: string; ts: number; } // `publish` resolves with a `Result`. A `Result` is always truthy, so check // `.ok` rather than the returned object itself. const accepted = await client.publish( { text: 'Hello, room!', from: 'alice', ts: Date.now(), }, { topic2: 'room-42', // scope to a specific room, doc, or context ttlSeconds: 60, // override the default 30s TTL }, ); if (accepted.ok) { console.log('Statement accepted into the gossip layer'); } else { console.warn(`Statement rejected: ${accepted.error.message}`); } ``` `publish` returns a `Result`. Check `.ok` rather than the returned object: a `Result` is always truthy, so `if (accepted)` passes for a rejected publish as readily as an accepted one. On failure, `.error` carries the reason — a `StatementSubmitError` when `pallet-statement-store`'s validity check rejects it (typically allowance or proof failure), a `StatementDataTooLargeError` when the JSON-encoded payload exceeds the per-statement size limit of 512 bytes, and a `StatementConnectionError` when the client is not connected. Two limits worth designing around: * **512-byte payload limit**: Measured after JSON encoding. For larger content, store it on the Bulletin Chain and publish the CID as a small statement. * **30-second default TTL**: The pallet enforces a maximum retention window. The SDK defaults to 30 seconds, and you can shorten or lengthen per-statement via `ttlSeconds` up to that cap. After expiry, the node evicts the statement from its pool. `PublishOptions` covers the common cases: `topic2` (secondary Blake2b-256 topic for room/doc scoping), `channel` (last-write-wins; see the next section), `ttlSeconds` (override the default), and `decryptionKey` (an opaque hint subscribers can match on to discover encrypted content). ## Use a Channel for Last-Write-Wins State `pallet-statement-store` supports an optional `channel` field on every statement: when a new submission carries the same `channel` as an existing live statement from the same account, the pallet replaces the older one in the node's pool. The gossip layer then propagates the replacement, and every subscribed peer drops the old statement in favor of the new one. The SDK abstracts this with `ChannelStore`; each channel name maps to a single live value: ```typescript // Place this in your Product, after the setup from `setup-statement-store.ts`. import { ChannelStore } from '@parity/product-sdk-statement-store'; import { client } from './setup-statement-store'; interface Presence { status: 'online' | 'away' | 'offline'; timestamp: number; } const channels = new ChannelStore(client, { topic2: 'room-42' }); // `write` forwards to `publish`, so it resolves with a `Result` too. const written = await channels.write('presence/alice', { status: 'online', timestamp: Date.now(), }); if (!written.ok) { console.warn(`Channel write rejected: ${written.error.message}`); } // A second write on the same channel replaces the first. await channels.write('presence/alice', { status: 'away', timestamp: Date.now(), }); // `onChange` and `readAll` key channels by their hex hash, not by the readable // name you wrote. Use `channels.read(name)` to look a channel up by name. channels.onChange((channelHash, value, previous) => { console.log( `${channelHash}: ${previous?.status ?? ''} → ${value.status}`, ); }); for (const [channelHash, value] of channels.readAll()) { console.log(`${channelHash}: ${value.status}`); } console.log(`alice is ${channels.read('presence/alice')?.status ?? 'unknown'}`); ``` `channels.write(name, value)` hashes the channel name with Blake2b-256 and publishes, forwarding `publish`'s `Result` to you; `channels.read(name)` returns the latest value seen on that channel; `channels.readAll()` returns the full map, keyed by channel hash rather than by the readable name; `channels.onChange(callback)` fires on every transition, and passes that same hash to the callback. `ChannelStore` stamps `timestamp` for you if the value omits it. Channel scope is per-account; the pallet's replacement rule only matches statements from the same signer, so one user cannot overwrite another user's channel. `ChannelStore` is the right primitive for soft state where only the latest version matters: presence indicators, multiplayer cursors, "now playing" status. For append-only events such as chat messages, action logs, social-feed posts, keep using `client.publish` directly so each event lives independently until its TTL. ## Where to Go Next * **Persist Data Locally** *** Your Product can sync state between users; next, keep device-local data (preferences, drafts, caches) across sessions. [→ Persist Data Locally](/apps/build/persist-data-locally/) * **Store Data on Chain** *** For durable, content-addressed payloads, route through the Bulletin Chain. Pair with the Statement Store by publishing the CID as a Statement. [→ Store Data on Chain](/apps/build/store-data-on-chain/) * **Product SDK API Reference** *** The full `product-sdk` surface beyond this recipe: every package, class, and method. [→ Visit Site](https://paritytech.github.io/product-sdk/) # Read On-Chain Data > Connect a Polkadot Product to one or more chains and read storage, constants, and account state using the @parity/product-sdk-chain-client package. ## Introduction This guide covers the `@parity/product-sdk-chain-client` package, which gives your Product a typed, host-aware client for reading on-chain state (account balances, storage items, and runtime constants) from inside a Polkadot host container. The SDK ships two connection paths: a zero-config Preset path (`getChainAPI`) and a Bring Your Own Descriptors (BYOD) path (`createChainClient`) for explicit descriptor control. Both produce the same client shape. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Connect to the chains](/apps/build/platform-services-sdk/#connect-to-the-chains). ## Prerequisites Before starting, ensure you have: * A Polkadot Product project running locally (see [Set Up Your Project](/apps/build/#set-up-your-project)) with a TypeScript toolchain * Node.js 20 or later with ESM support (`@parity/product-sdk-chain-client` is ESM only) * [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/) to run your Product inside a host container (see [Install Desktop and Pair](/apps/get-started/)) Note You do not need funded accounts to read chain state. Reads are unsigned and require only a running host container. ## Install the SDK The SDK installs two ways. The umbrella package, `@parity/product-sdk`, is the recommended starting point: one dependency that re-exports most of the SDK. Individual packages install only what you use, which keeps your bundle smaller and your dependencies explicit, so switch to them later as a bundle-size optimization. The two use different import specifiers, so switching styles means updating your imports. See [Umbrella or Individual Packages](/apps/build/#umbrella-or-individual-packages) for the full comparison. * **Umbrella package**: The whole SDK in one dependency. ```bash npm install @parity/product-sdk ``` * **Individual package**: Only the chain client. ```bash npm install @parity/product-sdk-chain-client ``` The import specifiers differ between the two. The snippets in this guide use the standalone specifier `@parity/product-sdk-chain-client`; on the umbrella, the same exports come from the `@parity/product-sdk/chain` subpath, which keeps the older name. `createChainClient` is also re-exported from the umbrella root, but `getChainAPI` and `destroyAll` are not. If you plan to use the BYOD path, also install the descriptors package regardless of which option above you chose: ```bash npm install @parity/product-sdk-descriptors ``` The descriptors package exposes typed `ChainDefinition` objects through subpath imports (for example, `@parity/product-sdk-descriptors/paseo-bulletin`). Each subpath corresponds to one chain. ## Connect to a Chain The SDK provides two connection paths. The Preset path (`getChainAPI`) is the fastest way to get a working client — it comes preconfigured with the descriptors for supported environments. Use the BYOD path (`createChainClient`) when you need explicit control over which chains and descriptors your Product uses. Neither path takes RPC endpoints: the Host resolves the connection from each descriptor's genesis hash. ### Connect Using a Preset `getChainAPI()` returns a client preconfigured with the descriptors for the environment the Host is on. Host discovery runs first on every call: the SDK reads the Host's chains and matches the asset hub's genesis hash against its bundled descriptors, so the no-argument call is the one that lets the Host select the network. ```typescript import { getChainAPI } from '@parity/product-sdk-chain-client'; // No argument: the Host selects the network, matched by genesis hash. // Pass one — getChainAPI('paseo') — to fail loudly if the Host is elsewhere. const client = await getChainAPI(); const fee = await client.bulletin.query.TransactionStorage.ByteFee.getValue(); const blockNumber = await client.assetHub.query.System.Number.getValue(); client.destroy(); ``` The argument is optional, and it acts as an assertion rather than a request. When the Host reports an environment that disagrees with the one you named, the call throws `EnvironmentMismatchError` instead of connecting to the environment you asked for. Pass one to pin your Product to a single environment, or when the Host reports no usable network and discovery has nothing to match against. The returned client exposes one property per chain in the preset (`assetHub`, `bulletin`, `individuality`), each typed by the underlying [polkadot-api](https://papi.how) (PAPI) descriptor. Not every environment is live The `Environment` union is `polkadot`, `kusama`, `paseo`, `previewnet`, and `devnet`. Anything else is a compile error. Of those five, `paseo`, `previewnet`, and `devnet` have all three chains live; `polkadot` and `kusama` are reserved, and `getChainAPI` throws `Chain API for "" is not yet available` for both. ### Connect Using Custom Descriptors (BYOD) Use `createChainClient` to supply your own descriptors, importing the chain descriptor objects you need directly instead of relying on a preset. `ChainClientConfig` accepts a single field, `chains`. ```typescript import { createChainClient } from '@parity/product-sdk-chain-client'; import { paseo_asset_hub, } from '@parity/product-sdk-descriptors/paseo-asset-hub'; import { paseo_bulletin, } from '@parity/product-sdk-descriptors/paseo-bulletin'; const client = await createChainClient({ chains: { assetHub: paseo_asset_hub, bulletin: paseo_bulletin, }, }); client.destroy(); ``` The keys you choose in `chains` (`assetHub`, `bulletin`) become the property names on the returned client. Pick names that read naturally in your call sites; the rest of the SDK is fully typed against them. Connections are routed through the Host at runtime, so there is no endpoint field to set. Using a different chain To connect to a chain other than `paseo_bulletin`, find its descriptor in `@parity/product-sdk-descriptors`, then add it under a new key in `chains`. The client surface (`client..query.*`) is automatically typed to match the descriptor you supplied. ## Read Storage and Constants Once you have a client, every chain you connected exposes a typed PAPI surface under `.query`, `.constants`, and the rest of the PAPI shape. The pattern is: ```text client..query...getValue(...args) ``` The following examples show common read operations. Each one maps directly to a pallet storage item and requires no transaction or signature. Byte Fee `TransactionStorage.ByteFee` returns the current cost per byte for on-chain storage on the Bulletin chain. ```typescript const fee = await client.bulletin.query.TransactionStorage.ByteFee.getValue(); console.log(`${fee} planck/byte`); ``` Block Number `System.Number` returns the current best block number for the chain. ```typescript const blockNumber = await client.assetHub.query.System.Number.getValue(); ``` Account State `System.Account` returns the full account record for an address, including nonce and balance buckets. ```typescript const address = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'; const account = await client.assetHub.query.System.Account.getValue(address); const { nonce, data: { free, reserved, frozen }, } = account; ``` ## Read Multiple Chains in Parallel Because each chain has its own connection internally, reads across chains are independent and can be issued in parallel with `Promise.all`. ```typescript const [fee, blockNumber] = await Promise.all([ client.bulletin.query.TransactionStorage.ByteFee.getValue(), client.assetHub.query.System.Number.getValue(), ]); ``` This is the recommended pattern whenever your Product needs to assemble a view from more than one storage item or chain. ## Access the Raw PAPI Client For advanced flows that the typed surface does not cover, such as raw storage subscriptions, low-level block tracking, or building a `ContractRuntime` for pallet-revive, every chain on the client exposes the underlying `PolkadotClient` under `.raw`. ```typescript // Subscribe to every new finalized block on the Bulletin chain const subscription = client.raw.bulletin.finalizedBlock$.subscribe((block) => { console.log(`Finalized block #${block.number}: ${block.hash}`); }); // Unsubscribe when done subscription.unsubscribe(); ``` Use the raw client only when you need to step outside the typed query/constants shape. Most reads should go through the typed surface above. ## Detect Whether You Are Inside a Host The SDK re-exports two helpers from `@parity/product-sdk-host` for detecting whether your Product is running inside a host container. Use these when behavior should branch, for example, showing a connection status indicator. ```typescript import { isInsideContainer, isInsideContainerSync, } from '@parity/product-sdk-chain-client'; const inContainer = await isInsideContainer(); // async, canonical const inContainerSync = isInsideContainerSync(); // sync, for top-level guards ``` Note You generally do not need to branch on this. The client routes calls correctly when inside a host container; detection is for cases where your Product itself wants to adapt its UI or telemetry. ## Clean Up Connections Each client owns one or more connections. Tear them down when your Product no longer needs them, typically on view unmount or process shutdown. ```typescript import { destroyAll } from '@parity/product-sdk-chain-client'; // Close only the connections owned by this client client.destroy(); // Global escape hatch: closes every connection the SDK has open destroyAll(); ``` Use `client.destroy()` for normal cleanup and reserve `destroyAll()` for full-process teardown. ## Limitations * The `paseo`, `previewnet`, and `devnet` environments are the presets with all three chains live. `polkadot` and `kusama` are reserved and throw at runtime. * The package is ESM only; your Product's build pipeline must support ESM imports. * Descriptors are imported by subpath (`@parity/product-sdk-descriptors/paseo-bulletin`), not from the package root. Bundlers that do not honor `exports` subpaths will fail to resolve them. * Host-routed reads require a host container; there is no direct-WebSocket fallback, so outside a Host the client [throws](/apps/troubleshooting/#connecting-to-a-chain-throws-outside-a-host). For out-of-Host development, use the SDK's testing fakes. * Reactive subscriptions (watching a storage item over time) are not covered on this page. A dedicated page on subscriptions will follow. ## Where to Go Next * **Sign and Submit Transactions** *** Your Product can read the chain; next, let it act on the user's behalf, with every approval on their phone. [→ Sign and Submit Transactions](/apps/build/sign-and-submit/) * **polkadot-api Docs** *** Reference for the typed PAPI surface that `@parity/product-sdk-chain-client` exposes per chain. [→ Visit Site](https://papi.how) * **Product SDK API Reference** *** The full `product-sdk` surface beyond this recipe: every package, class, and method. [→ Visit Site](https://paritytech.github.io/product-sdk/) # Register a .dot domain A `.dot` domain is a readable name on the Polkadot Products Devnet. It has an owner account and can point to an app bundle, so that opening `your-app.dot` in the [Polkadot app](/apps/reference/resources/) or the [web gateway](https://dev-dot.li) loads your app. You register and manage names with the DotNS CLI (`@polkadot-community-foundation/dotns-cli`). Ordinary app names follow the normal registration path, and short or reserved names have extra gates. Owning a name means owning an ERC-721 token. Binding it to an app means writing an IPFS content hash into its resolver, which clients read to fetch your bundle. [Naming (DotNS)](/apps/architecture/naming/) covers the resolution path and the contracts behind it. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Register a `.dot` Domain](/apps/register-dot-domain/). ## Install the CLI The `dotns` command ships in `@polkadot-community-foundation/dotns-cli`. [Packages & tools](/apps/reference/packages/) has the install line. Every command takes a network with `--env devnet` (or the `DOTNS_ENV` environment variable). ## Set up an account The CLI signs with its own key, separate from any account in the Polkadot app. Set one up before you register anything. ### Fastest: a throwaway account For a hackathon, you don't need to import a seed phrase or set a keystore password. Create a fresh account and pass its mnemonic to the CLIs through the environment: ```bash # One fresh BIP-39 mnemonic, generated with the crypto that ships inside the CLIs export MNEMONIC="$(NODE_PATH="$(npm root -g)/@polkadot-community-foundation/dotns-cli/node_modules" \ node -e 'const c=require("@polkadot/util-crypto");c.cryptoWaitReady().then(()=>console.log(c.mnemonicGenerate()))')" export DOTNS_MNEMONIC="$MNEMONIC" # dotns signs with this — no `dotns auth set`, no password dotns account address # the throwaway's address — fund THIS at the faucet ``` `pad` takes the same `$MNEMONIC` when it publishes (`--mnemonic "$MNEMONIC"`), so one account both owns the name and deploys to it. The phrase only lives in this shell session. Save it if you want to keep the name. If you discard it, the account really is throwaway. Set a key, or you sign as a shared account With neither `DOTNS_MNEMONIC`/`DOTNS_KEY_URI` set nor `dotns auth set` run, `dotns` falls back to a shared public dev account that anyone can control. A name registered to it is not yours, and anyone can transfer it away. `dotns` prints a warning on every command when this happens. Then check which account is active: ```bash dotns account address dotns account info --env devnet ``` ### Keep it: the encrypted keystore To reuse an account across sessions, store a mnemonic or key-uri in the password-protected `dotns` keystore instead of the environment: ```bash dotns auth set ``` The prompt first asks which kind of secret you are storing. Answer `mnemonic` or `key-uri`, then paste the value. Finally it asks you to set a keystore password. Every later `dotns` command needs that password: pass it with `--password`, or export `DOTNS_KEYSTORE_PASSWORD` so scripts don't stall on a hidden prompt. To do it in one non-interactive step instead: ```bash export DOTNS_KEYSTORE_PASSWORD="…" dotns auth set --mnemonic "…" --account my-app ``` ### Fund and map the account Registration signs a PolkaVM transaction, so your account also needs a balance for fees and a mapped EVM address. Fund it from the [faucet](/apps/reference/networks/#faucet), then: ```bash # Map your Substrate account to its EVM address (once per account) dotns account map --env devnet # Check whether an address is already mapped dotns account is-mapped

--env devnet ``` `dotns account is-mapped` checks the address you pass in. Its connection banner still shows the CLI's default signer, so it may show the shared dev account even when your keystore is set up. Trust the `mapped:` line for the address you asked about, not the banner. ## Reserved and short-name gating Not every label is open to everyone. The public commit-reveal path requires a label of at least three characters, and sorts labels by their stem (the label with any trailing digits stripped): * Reserved: stems of five characters or fewer are gated and cannot be claimed through the open path. * Personhood-gated: stems of six to eight characters need proof of personhood (the lite tier for a stem plus exactly two digits, the full tier for no digits). * Open: stems of nine characters or more register without a personhood check. The controller rejects governance-reserved and explicitly reserved names. Personhood-tier usernames are issued through the gateway path when you prove personhood in the Polkadot app, not through the CLI commands below. So if you just want a name for an app, use a label whose stem is nine characters or longer, for example `my-cool-app`. It is the only band that registers without proof of personhood, which today comes from the Polkadot app and not from the CLI. Shorter names such as `my-app` (a six-character stem) will be refused. You can't check a label's tier before committing to it, so count the stem yourself. ## Register a name Registration is a commit-reveal handshake: you commit a hashed intent, wait a minimum commitment age, then reveal and pay. The CLI runs all three steps: ```bash dotns register domain -n my-cool-app --env devnet ``` It takes several minutes, because the commitment has to finalize, then mature, then be revealed. Before the final step the CLI prints the tier and the price it is about to pay: ```plaintext name tier: NoStatus your tier: NoStatus message: Available to all price: 10 PAS ``` Useful options: * `-r, --reverse`: also set this name as your account's reverse (primary) record. * `--json`: print machine-readable output. Whatever the CLI printed, check the result on chain before you do anything else: ```bash dotns lookup owner-of my-cool-app --env devnet dotns lookup name my-cool-app --env devnet # full record view ``` You can also look the name up in the [DotNS UI](https://dotns.dev-dot.li). If the owner is your address, the name is yours and you are done. Only if it is not, resume the handshake: ```bash dotns register list --env devnet # inspect cached commitments dotns register retry my-cool-app --env devnet ``` ## Bind a name to a bundle Once you have deployed your app (see [Build & publish an app](/apps/build/build-and-publish/)), you have an IPFS CID for the bundle. Write it into the content resolver to make the name resolve to your app: ```bash # Set the content hash (IPFS CID) for a name you own dotns content set my-cool-app --env devnet # Read it back dotns content view my-cool-app --env devnet ``` After this, opening `my-cool-app.dot` in the Polkadot app or at [dev-dot.li](https://dev-dot.li) resolves the name, decodes the content hash to the CID and fetches your bundle from the gateway. ## Manage a name ```bash # Set one of your names as the primary (reverse) name for your account dotns primary set my-cool-app --env devnet dotns primary status --env devnet # Transfer ownership to another address or label dotns lookup transfer my-cool-app --destination --env devnet # Create a subname under a name you own dotns register subname --env devnet ``` ## Learn more * [Naming (DotNS)](/apps/architecture/naming/): resolution, the contracts and the naming rules * [DotNS UI](https://dotns.dev-dot.li): the same lookups in a browser * [Build & publish an app](/apps/build/build-and-publish/): bind the name to a bundle # Sign and Submit Transactions > Derive product-scoped accounts and sign transactions from a Polkadot Product using the Product SDK, with all approvals routed to the Polkadot App. ## Introduction This guide covers the `@parity/product-sdk-signer` package, which gives your Product a typed, host-aware signing interface for deriving accounts and signing payloads (raw bytes or full transactions) from inside a Polkadot host container. The SDK exposes a single orchestrator, `SignerManager`, that wraps both the production host path ([Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/)) and a deterministic dev path behind the same `Result`-typed API. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Sign transactions](/apps/build/platform-services-sdk/#sign-transactions). ## Prerequisites Before starting, ensure you have: * A Polkadot Product project running locally (see [Set Up Your Project](/apps/build/#set-up-your-project)) with a TypeScript toolchain * Node.js 20 or later with ESM support (`@parity/product-sdk-signer` is ESM only) * Polkadot Desktop to run your Product inside a host container (see [Install Desktop and Pair](/apps/get-started/)) Note To test signing without a host container, use `manager.connect('dev')`. This loads the standard Substrate dev accounts (Alice, Bob, and others) locally and does not require Polkadot Desktop. See [Test Without a Host](#test-without-a-host). Code examples The snippets in this guide are standalone; each one illustrates one concept and can be pasted into your Product independently. They are confirmed working with Polkadot Desktop and `@parity/product-sdk` v0.9.0. ## Install the SDK The SDK installs two ways. The umbrella package, `@parity/product-sdk`, is the recommended starting point: one dependency that re-exports most of the SDK. Individual packages install only what you use, which keeps your bundle smaller and your dependencies explicit, so switch to them later as a bundle-size optimization. The two use different import specifiers, so switching styles means updating your imports. See [Umbrella or Individual Packages](/apps/build/#umbrella-or-individual-packages) for the full comparison. * **Umbrella package**: The whole SDK in one dependency. ```bash npm install @parity/product-sdk ``` * **Individual package**: Only the signer. ```bash npm install @parity/product-sdk-signer ``` The import specifiers differ between the two. The snippets in this guide use the standalone specifier `@parity/product-sdk-signer`; on the umbrella, the same exports come from the `@parity/product-sdk/wallet` subpath, which keeps the older name. `SignerManager` is also re-exported from the umbrella root. ## How Product Accounts Work Every product-scoped account is identified by a `ProductAccountId` tuple: * **`dotNsIdentifier`**: The dotNS identifier of the Product requesting the account, for example the `.dot` name your Product is loaded under. * **`derivationIndex`**: A non-negative integer chosen by the Product. Index `0` is the conventional default; higher indices give you additional sub-accounts within the same Product. The same `(dotNsIdentifier, derivationIndex)` pair always yields the same public key, so your Product can reproduce the same address across sessions without persisting it. Per-Product isolation is a privacy feature `app-a.dot` and `app-b.dot` produce different addresses for the same user. This prevents passive on-chain correlation across Products. Sharing an account across Products requires explicit permission; it is never the default. ## Set Up Signer Manager Construct `SignerManager` once and hold it for the lifetime of your Product. Always set `ss58Prefix` and `dappName` explicitly. Use the `onConnect` callback to request any resources your Product needs immediately after connection; the callback fires exactly once per connect and re-fires automatically after any auto-reconnect. ```typescript import { SignerManager } from '@parity/product-sdk-signer'; const manager = new SignerManager({ ss58Prefix: 0, dappName: 'my-product', onConnect: async (_account, { requestResourceAllocation, signal }) => { try { const outcomes = await requestResourceAllocation([ { tag: 'BulletinAllowance', value: undefined }, ]); if (signal.aborted) return; if (outcomes.some((outcome) => outcome !== 'Allocated')) { // Degrade gracefully: the capability is unavailable, not fatal. } } catch (cause) { // Typed host error; the connection itself is unaffected. } }, }); ``` * **`ss58Prefix`**: The SS58 address-format prefix for the target network. Use `0` for the Polkadot relay chain. * **`dappName`**: A human-readable name for your Product, shown in Desktop UI. * **`onConnect`**: Fires once per connection transition. Request the resources your Product needs here, before any signing call is made. * **`ctx.requestResourceAllocation`**: The one call in this package that **throws** instead of returning a `Result`, so wrap it in `try`/`catch`. Each outcome is `'Allocated'`, `'Rejected'`, or `'NotAvailable'`; treat anything other than allocated as the capability being unavailable. * **`ctx.signal`**: Aborts if the user disconnects while the request is in flight. Check it before acting on the outcomes. `AutoSigning` is not grantable yet It is the resource most worth requesting and the one you cannot depend on: both the Android and iOS wallets return `NotAvailable` for it today. Keep per-transaction signing as the real path. See [Allowances and Permissions](/apps/concepts/allowances/). ## Connect to the Host Call `connect()` to establish a session with the host and discover available accounts. `connect()`, `selectAccount()`, `getProductAccount()`, and `signRaw()` all return a `Result`; always check `.ok` before accessing `.value`. (`getSigner()` returns a nullable directly, not a `Result`.) Each step below is a self-contained function over the `manager` you built above, so you can paste them one at a time. ```typescript async function connectAndSelect() { const connectResult = await manager.connect(); if (!connectResult.ok) { // HostUnavailableError when running outside Desktop console.error(connectResult.error.message); return null; } const accounts = connectResult.value; if (accounts.length === 0) { // Connected, but the host derived no accounts for this Product. return null; } // Auto-select the first account if none is already selected if (!manager.getState().selectedAccount) { const selectResult = manager.selectAccount(accounts[0].address); if (!selectResult.ok) { console.error(selectResult.error.message); return null; } } return manager.getState().selectedAccount; } ``` A successful connect can still yield zero accounts `connect()` resolves with `ok([])` — not an error — when `dappName` is unset or the host rejects the derivation, typically because the `.dot` identifier is not registered for that user. Check the length before indexing, or `accounts[0].address` throws on a path the SDK treats as normal. `connect()` defaults to the host provider. Outside a host container it returns `HostUnavailableError`; use `connect('dev')` for local testing instead. See [Test Without a Host](#test-without-a-host). ## Get a Product Account `getProductAccount` requests the product-scoped account for a given `dotNsIdentifier` from the host. This is a host-only API; it returns `HostUnavailableError` when the active provider is `'dev'`. ```typescript async function loadProductAccount() { const accountResult = await manager.getProductAccount('my-product.dot', 0); if (!accountResult.ok) { console.error(accountResult.error.message); return null; } return accountResult.value; // SignerAccount } ``` The returned `SignerAccount` exposes: * **`address`**: The SS58-encoded address for the current network. * **`publicKey`**: The raw 32-byte public key. * **`name`**: An optional display name, or `null`. ## Show a Display Name There is no built-in primitive for an in-app username, so most Products need to choose a display identity themselves. [Usernames in Your Product](/apps/concepts/identity/#usernames-in-your-product) covers the pattern to follow; this section covers the call it depends on. When the user holds a personhood tier, the platform already associates an earned name with their account. Read it with `getUserId`: ```typescript async function loadDisplayName() { const idResult = await manager.getUserId(); if (!idResult.ok) { return null; // No host, no permission, or no personhood tier } return idResult.value.primaryUsername; // e.g. 'joseph.42' } ``` When there is no earned name to read, fall back to a per-Product display name the user sets, stored in [local storage](/apps/product-sdk/local-storage/) (device-local) or [cloud storage](/apps/product-sdk/cloud-storage/) (shared) and keyed to their per-app account. Either way, treat the result as a label rather than as identity: authorization and uniqueness come from the per-app account and Proof of Personhood. `getUserId` is host-only and prompts the user `getUserId` returns `HostUnavailableError` when the active provider is `'dev'`, so a Product that renders a display name works in a Host and fails under the dev provider. It also triggers a host identity-permission prompt on first use. If your Product has its own display-name chain and does not need the platform name, skip the call rather than requesting a permission you will not use. ## Sign Arbitrary Bytes Use `signRaw` to sign an arbitrary byte payload with the currently selected account. This is useful for off-chain authentication, message proofs, and any use case that does not require a full transaction. `signRaw` returns a `Result`; it never throws. Always check `.ok` before accessing `.value`. ```typescript async function signMessage() { const account = await loadProductAccount(); if (!account) return null; const selectResult = manager.selectAccount(account.address); if (!selectResult.ok) { console.error(selectResult.error.message); return null; } const payload = new TextEncoder().encode('hello polkadot'); const result = await manager.signRaw(payload); if (!result.ok) { console.error(result.error.message); return null; } return result.value; // Uint8Array - the raw signature } ``` ## Sign and Submit a Transaction To sign a transaction, get a `PolkadotSigner` from `SignerManager` and pass it to the `signAndSubmit` method from `polkadot-api` (PAPI). The SDK handles routing the signing request to Desktop, which renders a signing modal and forwards to the [Polkadot App](/reference/apps/hosts/polkadot-app/). `@parity/product-sdk-signer` provides only the signer interface; chain connectivity uses `polkadot-api` directly. Set up your PAPI client separately: ```typescript import { createClient } from 'polkadot-api'; import { getWsProvider } from 'polkadot-api/ws-provider/web'; import { dot } from '@polkadot-api/descriptors'; const client = createClient(getWsProvider('wss://rpc.polkadot.io')); const api = client.getTypedApi(dot); ``` The `dot` descriptor is the typed API surface for the Polkadot relay chain. Run `npx papi add dot` in your project to pull or regenerate it. ```typescript async function transfer() { const recipient = 'INSERT_RECIPIENT_ADDRESS'; const account = await loadProductAccount(); if (!account) return null; const selectResult = manager.selectAccount(account.address); if (!selectResult.ok) return null; // getSigner() returns null if no account is selected const signer = manager.getSigner(); if (!signer) return null; const tx = api.tx.Balances.transfer_keep_alive({ dest: recipient, value: 1_000_000_000_000n, }); return tx.signAndSubmit(signer); } ``` ## Handle Signing Errors Two outcomes are worth handling explicitly: the user rejects the request, or the signing session times out. ```typescript import { HostRejectedError, TimeoutError, } from '@parity/product-sdk-signer'; import type { PolkadotSigner } from 'polkadot-api'; async function submitOrReport( tx: { signAndSubmit(signer: PolkadotSigner): Promise }, signer: PolkadotSigner, ) { try { return await tx.signAndSubmit(signer); } catch (error) { if (error instanceof HostRejectedError) { // The user dismissed the signing prompt on the Polkadot App return null; } if (error instanceof TimeoutError) { // The signing session expired before the user responded return null; } throw error; } } ``` * **`HostRejectedError`**: The user explicitly denied the request. Return the user to a stable state and let them retry. * **`TimeoutError`**: The signing session expired. Treat this the same as a rejection. Design for async latency Signing is asynchronous because the Polkadot App runs on a separate device. Show a non-blocking pending state rather than freezing the interface, and make sure your retry path is idempotent in case the user attempts the same action twice. There is no push notification when the phone is waiting, so a stalled-looking action is often an [unanswered prompt](/apps/troubleshooting/#the-app-seems-frozen-after-an-action). ## Test Without a Host During development, use `connect('dev')` to load the standard Substrate dev accounts (Alice, Bob, Charlie, Dave, Eve, and Ferdie) without needing Polkadot Desktop. The signing API is identical — only the provider changes. ```typescript async function devSignRaw() { const result = await manager.connect('dev'); if (!result.ok) return null; const [alice] = result.value; if (!alice) return null; const selectResult = manager.selectAccount(alice.address); if (!selectResult.ok) return null; const signResult = await manager.signRaw(new TextEncoder().encode('test')); if (!signResult.ok) return null; return signResult.value; // Uint8Array - the raw signature } ``` Four methods are host-only `getProductAccount`, `getProductAccountAlias`, `createRingVRFProof`, and `getUserId` return `HostUnavailableError` when the active provider is `'dev'`. `getUserId` is easy to miss: [Show a Display Name](#show-a-display-name) uses it to read the user's earned name, so a Product that does that renders fine in a Host and fails under the dev provider. ## Limitations * The package is ESM only; your Product's build pipeline must support ESM imports. * `SignerManager.destroy()` is terminal. After calling it, all subsequent method calls return `DestroyedError`. Use `disconnect()` for a reversible reset. * Account persistence across page reloads requires the host to expose `localStorage`. Outside a host container, persistence silently no-ops. ## Where to Go Next * **Store Data on Chain** *** Your Product can sign; next, use that signer to store content on the Bulletin Chain and fetch it from anywhere by CID. [→ Store Data on Chain](/apps/build/store-data-on-chain/) * **PAPI Docs** *** Reference for the typed PAPI signer interface that `@parity/product-sdk-signer` exposes. [→ Visit Site](https://papi.how) * **Product SDK API Reference** *** The full `product-sdk` surface beyond this recipe: every package, class, and method. [→ Visit Site](https://paritytech.github.io/product-sdk/) # Store Data on Chain > Store and retrieve Bulletin Chain data from a Polkadot Product, covering Hello World, larger files, and renewal. ## Introduction This guide covers the [Bulletin Chain](/reference/apps/infrastructure/bulletin-chain/), Polkadot's content-addressed storage layer for Products. You write data, the chain returns a Content Identifier (CID), and anyone with that CID can fetch the data back from the network. Data is retained for about two weeks by default and can be renewed. Access is gated by a per-account storage authorization, not a token balance. The guide walks through four flows in order of complexity: a Hello World store and retrieve, a larger file upload, long-lived data with renewal, and Preimage submission. Storage options for your Product Match the data to the layer built for it; see [Where to Store Data](/apps/concepts/data-placement/) for the full decision guide. * **Local storage**: Per-Product, per-device key-value for preferences, drafts, and cached values. Not synced across devices. See [Persist Data Locally](/apps/build/persist-data-locally/). * **Bulletin Chain**: Content-addressed, on-chain, retained \~2 weeks by default and renewable. Fetched later by CID: profile photos, published articles, app bundles. See [Store Data on Chain](/apps/build/store-data-on-chain/). * **Statement Store**: Gossip-distributed, short-lived (default 30s TTL), allowance-gated. Real-time signaling between users: chat, presence, typing indicators. See [Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/). Network The flows on this page target Paseo Next, the default environment in [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/) development builds. If you switched environments during setup, select the matching network from the environment selector in Polkadot Desktop. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Storage & data](/apps/architecture/storage/). ## Prerequisites Before starting, ensure you have: * Completed the [Install Desktop and Pair](/apps/get-started/) and [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/) guides; your account needs PAS funds and a Bulletin Chain authorization. If you have not obtained a Bulletin Chain authorization yet, request one from the [Bulletin Chain authorization page](https://paritytech.github.io/polkadot-bulletin-chain/authorizations) * A Polkadot Product project running locally (see [Set Up Your Project](/apps/build/#set-up-your-project)) ## Install the SDK This guide builds on `createApp`, which only the umbrella package provides, so install the umbrella: ```bash npm install @parity/product-sdk ``` Every snippet imports from `@parity/product-sdk`, including `SignerManager` and `CloudStorageClient`, which the umbrella re-exports from its root, and `parseCid` and `CidCodec`, which it re-exports from its `@parity/product-sdk/cloud-storage` subpath, so no other package is needed. The renewal example is the exception: it also uses `@ipld/dag-pb` to read chunked-upload manifests. See [Umbrella or Individual Packages](/apps/build/#umbrella-or-individual-packages) for how the install styles compare. ## Set Up Your Storage Client Every snippet in this guide is Product code: modules you place inside the Product running at `localhost:3000` (per [Set Up Your Project](/apps/build/#set-up-your-project)), loaded by Polkadot Desktop. Run nothing from a terminal; the snippets execute in the browser context Polkadot Desktop's localhost bypass loads them into. The signer for every Bulletin transaction comes from the Host (your paired account in Polkadot Desktop); your Product never derives keys. Create the SDK app and connect the wallet: ```typescript import { createApp } from '@parity/product-sdk'; // The Host supplies your Product's identity: `createApp` reads the product ID // the Host loaded you under and derives the user's product account from it. // If the Host declines to derive an account, `connect()` resolves with an empty // list instead of failing, so check the list before you rely on it. export const app = await createApp(); export const { accounts } = await app.wallet.connect(); if (accounts.length === 0) { throw new Error( 'The Host returned no account for this Product. Check that you are signed in to Polkadot Desktop.', ); } ``` `createApp()` returns an `App` with `app.wallet`, `app.localStorage`, `app.chain`, and `app.cloudStorage`, the high-level Bulletin Chain API exposing `upload()`, `fetch()`, and `computeCid()`. The exported `app` and `accounts` are reused across the simple sections that follow, and the same setup file is shared with [Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/). The Host supplies your Product's identity Since `@parity/product-sdk` v0.30.0, `createApp` takes no `name`: it derives the user's account from the product ID the Host loaded your Product under. Releases before v0.30.0 require `name` and derive the account from it instead. If the Host declines to derive an account, `wallet.connect()` resolves with *zero accounts* rather than failing, so the only symptom is an empty list. Every upload on this page needs a selected account, so guard the list before going further. See [Product SDK](/apps/product-sdk/) for the full `createApp` contract. ## Store a Hello World The simplest write: a short string, one line. ```typescript // Place this in your Product, after the setup from `setup-app.ts`. import { app } from './setup-app'; const stored = await app.cloudStorage!.upload('Hello, Bulletin!'); if (!stored.ok) throw new Error(`Upload failed: ${stored.error.message}`); console.log(`CID: ${stored.value}`); ``` `app.cloudStorage.upload(data)` accepts a string or `Uint8Array`, signs the underlying transaction with your paired account, and resolves with a `Result` whose `value` is the CID, a Blake2b-256 content hash encoded as a CIDv1 string. Internally the SDK uses the chunking pipeline with a DAG-PB manifest, so the same call shape works for any payload size; see [Store a Larger File](#store-a-larger-file) for the chunk-level controls. You should see something like: ```text CID: bafk2bzacea6wlxyalo6gbajlwuubv7w5dvss3vmfqmavlqy63e4vypth2ov6u ``` ## Retrieve Your Data The Bulletin Chain follows a "write-to-chain, read-from-network" model: the chain holds the storage commitment, and the data itself lives at collator nodes addressable by CID. Reading is permissionless. No authorization, fees, or signature are required. `app.cloudStorage.fetch(cid)` routes through the Host's preimage subscription with caching: ```typescript // Place this in your Product, after the setup from `setup-app.ts`. import { app } from './setup-app'; const CID_STRING = 'INSERT_CID'; const fetched = await app.cloudStorage!.fetch(CID_STRING); if (!fetched.ok) throw new Error(`Fetch failed: ${fetched.error.message}`); const bytes = fetched.value; console.log(`Retrieved ${bytes.length} bytes`); console.log(new TextDecoder().decode(bytes)); // Verify the fetched bytes match the CID you asked for. const recomputed = await app.cloudStorage!.computeCid(bytes); console.log(`CID verified: ${recomputed === CID_STRING}`); ``` The snippet verifies the bytes by recomputing their CID with `app.cloudStorage.computeCid(bytes)` and comparing to the CID you asked for. If the host returned the wrong bytes, the recomputed CID does not match; that is the integrity property content addressing gives you. For libp2p / Helia / Smoldot retrieval paths (when you want to fetch outside a Polkadot Desktop container), see [Retrieve Your Data](/chain-interactions/store-data/bulletin-chain/#retrieve-your-data) in the canonical tutorial. ## Store a Larger File `app.cloudStorage.upload()` chunks transparently above a 2 MiB threshold and stores a DAG-PB manifest that references each chunk's CID, returning the manifest CID. For most Products, that is all you need. Pass any `Uint8Array` to `upload()` and the SDK handles chunking, manifest generation, and the underlying transactions for you. For finer control, such as custom chunk size, per-chunk progress callbacks, or access to the individual chunk CIDs, drop one level lower to `CloudStorageClient`, which the umbrella re-exports from `@parity/product-sdk-cloud-storage`. This is also the path you use for the next two sections (authorization checks, renewal). `CloudStorageClient` needs a signer, and `App` does not expose the one `createApp` holds, so this setup builds its own with `SignerManager`. Set its `dappName` to the product ID the Host loads your Product under, so it derives the same account as `app.wallet`: ```typescript import { CloudStorageClient, SignerManager } from '@parity/product-sdk'; // `App` does not expose its signer, so the advanced sections build their own. // Unlike `createApp`, `SignerManager` does not read your Product's identity from // the Host: set `dappName` to the product ID the Host loads you under (your // `.dot` name) so it derives the same account that `app.wallet` does. const signerManager = new SignerManager({ dappName: 'my-product.dot' }); const connected = await signerManager.connect(); if (!connected.ok) throw new Error(connected.error.message); const accounts = connected.value; if (accounts.length === 0) { throw new Error( 'The Host returned no account for this Product. Check that you are signed in to Polkadot Desktop.', ); } // A real Product would render an account picker; here we pick the first one. const selected = signerManager.selectAccount(accounts[0].address); if (!selected.ok) throw new Error(selected.error.message); const signer = signerManager.getSigner(); if (!signer) throw new Error('Could not build a signer from the selected account.'); export const client = await CloudStorageClient.create({ environment: 'paseo', signer, }); export const account = selected.value; ``` `CloudStorageClient.create({ environment: 'paseo', signer })` resolves with `client.store / client.renew / client.checkAuthorization / client.fetchBytes / client.estimateAuthorization` for the high-level operations, plus `client.api` for the typed Bulletin Chain API when you need to drop one level lower still. The exported `client` and `account` are reused by the advanced sections that follow. The `client.store(...)` builder takes the same chunking pipeline `app.cloudStorage.upload` uses internally, with the controls exposed: ```typescript // Place this in your Product, after the setup from `setup-client.ts`. import { client } from './setup-client'; // e.g., a File the user dropped, an asset bundled with your Product. declare const largeFile: Uint8Array; const estimate = client.estimateAuthorization(largeFile.length); console.log( `Need ${estimate.transactions} txs / ${estimate.bytes} bytes of authorization`, ); const result = await client .store(largeFile) .withChunkSize(1024 * 1024) .withManifest(true) .withCallback((event) => { console.log(`Progress: ${JSON.stringify(event)}`); }) .send(); console.log(`Root CID (manifest): ${result.cid?.toString()}`); if (result.chunks) { console.log(`Chunks: ${result.chunks.numChunks}`); for (const [i, cid] of result.chunks.chunkCids.entries()) { console.log(` [${i}] ${cid.toString()}`); } } ``` The returned `StoreResult.cid` is the manifest CID; `StoreResult.chunks.chunkCids` lists each chunk's individual CID. `withCallback()` receives per-chunk progress events as the upload streams. The Bulletin Chain limits each transaction to 2 MiB; see [Size Limits](/reference/polkadot-hub/data-storage/#size-limits). Chunks cannot exceed that. Chunked uploads are not atomic. Each chunk is a separate transaction, and the manifest is one more on top. If chunk N fails after chunks 0..N-1 have already landed, the earlier chunks remain on chain and consume your authorization. There is no rollback. Inspect the `chunkCids` on the thrown error and either resume from the failed chunk or, if the use case demands it, abandon the partial upload. ## Get Authorization The Bulletin Chain has no token balance for storage; every account needs an explicit authorization. You should already have one from [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/); if not, request your storage quota directly from the [Bulletin Chain authorization page](https://paritytech.github.io/polkadot-bulletin-chain/authorizations). If a store is rejected, confirm the authorization is on the account that signs: see [uploads are rejected](/apps/troubleshooting/#uploads-are-rejected-or-host-storage-unavailable) in troubleshooting. Note The `authorize_account` extrinsic requires the authorizer origin: Root, or an account or parachain allowed to grant authorizations. You cannot self-authorize programmatically; on Polkadot TestNet, use the [Bulletin Chain authorization page](https://paritytech.github.io/polkadot-bulletin-chain/authorizations) before submitting any `store` extrinsic from your Product. `CloudStorageClient` (introduced in [Store a Larger File](#store-a-larger-file)) exposes `client.checkAuthorization(address)` as a pre-flight check before submitting a store: ```typescript // Place this in your Product, after the setup from `setup-client.ts`. import { client, account } from './setup-client'; // `checkAuthorization` resolves with a `Result`, so unwrap it before reading // the status. The fields live on `auth.value`, never on `auth` itself. const auth = await client.checkAuthorization(account.address); if (!auth.ok) { console.error(`Could not read the authorization: ${auth.error.message}`); } else if (!auth.value.authorized) { console.log(`No authorization found for ${account.address}`); } else { console.log(`Remaining transactions: ${auth.value.remainingTransactions}`); console.log(`Remaining bytes: ${auth.value.remainingBytes}`); console.log(`Expires at block: ${auth.value.expiration}`); } // Estimate authorization needed for a hypothetical 2 MiB payload. const estimate = client.estimateAuthorization(2 * 1024 * 1024); console.log(`To store 2 MiB you need ~${estimate.transactions} txs, ${estimate.bytes} bytes`); ``` `checkAuthorization` resolves with a `Result`, not with the status directly. Check `auth.ok` first; the status is on `auth.value`, and reading the fields off the wrapper yields `undefined` and silently takes the failure branch. On success, `auth.value` carries an `AuthorizationStatus`: * **`authorized`**: `true` when an authorization record exists for the account. * **`remainingTransactions`**: Number of `store` calls remaining in the quota. * **`remainingBytes`**: Bytes remaining across those calls (`bigint`). * **`expiration`**: The block at which any unused quota expires. `client.estimateAuthorization(dataSize)` returns the `{ transactions, bytes }` you would need to authorize a hypothetical payload of `dataSize` bytes, which is useful before requesting a quota top-up. ## Renew Long-Lived Data Stored data is retained for roughly two weeks. If your Product needs the data to outlive that window, renew it before it expires. Renewal identifies the data by its content hash, which is the multihash digest of its CID. What you renew depends on the kind of CID: * **Single-transaction CID**: The CID codec is raw (`CidCodec.Raw`, and the string starts with `bafk`). Renew that one content hash. * **Manifest CID**: The CID codec is DAG-PB (`CidCodec.DagPb`, and the string starts with `bafy`). A chunked upload stores each chunk and the manifest as separate transactions, each with its own retention period, so renew the manifest and every chunk. The manifest lists the chunk CIDs as its links. The following example takes the CID that an upload returned, collects the content hashes of the manifest and its chunks when the CID is a manifest, and registers a renewal for each one. It reads the manifest with `fetchBytes(cid, { noReassemble: true })` and decodes it with `@ipld/dag-pb`, so install that package too: ```bash npm install @ipld/dag-pb ``` ```typescript // Place this in your Product, after the setup from `setup-client.ts`. import { decode } from '@ipld/dag-pb'; import { CidCodec, parseCid } from '@parity/product-sdk/cloud-storage'; import { client } from './setup-client'; // The CID that the upload returned: a single-transaction CID, or the manifest // CID of a chunked upload. declare const cid: string; // A CID's multihash digest is the content hash the Bulletin Chain tracks. // The map is keyed by CID, so identical chunks are renewed once. const root = parseCid(cid); const contentHashes = new Map([ [root.toString(), root.multihash.digest], ]); // A DAG-PB CID is a manifest. Its links are the chunk CIDs, and each chunk is // a separately stored transaction that needs its own renewal. if (root.code === CidCodec.DagPb) { const manifest = await client.fetchBytes(cid, { noReassemble: true }); if (!manifest.ok) throw new Error(manifest.error.message); for (const link of decode(manifest.value).Links) { contentHashes.set(link.Hash.toString(), link.Hash.multihash.digest); } } // Register a one-time renewal for each stored record. for (const contentHash of contentHashes.values()) { const receipt = await client.inner.renew(contentHash).send(); console.log(`Renewal registered in block ${receipt.blockNumber}`); } ``` If you uploaded with `CloudStorageClient.store(...).send()`, `StoreResult.chunks.chunkCids` already holds the chunk CIDs as `CID` objects, so you can read each content hash from `chunkCid.multihash.digest` without fetching the manifest. `client.inner.renew(contentHash)` registers a one-time renewal. When the current retention period ends, the chain stores the data again, and it stays available for another full period. The renewal is paid from your authorization when you register it. `client.inner` is the underlying Bulletin SDK client, which `CloudStorageClient` exposes for operations beyond its own surface, and `send()` resolves with a `TransactionReceipt` that includes `blockHash`, `txHash`, and `blockNumber`. Renewals have their own byte budget. The chain counts renewed bytes separately from stored bytes, and it rejects a renewal when the bytes already renewed under your authorization, plus the size of this data, would exceed the authorization's byte allowance. The `remainingBytes` that `checkAuthorization` reports covers stored bytes only, so it does not predict whether a renewal succeeds. The underlying client also provides the following alternatives: * **`client.inner.enableAutoRenew(contentHash)`**: Renews the data at the end of every retention period, until your authorization can no longer cover a renewal. * **`client.inner.forceRenew(contentHash)`**: Stores a new copy of the data immediately, with a retention period that starts from the current block. * **`client.renew(block, index)`**: Renews by position, using the `blockNumber` and `extrinsicIndex` from a single-transaction `StoreResult`. Despite its name, `extrinsicIndex` holds the index from the `Stored` event, which is the value renewal expects. A position identifies one stored copy and stays valid only until that copy's retention period ends. After `forceRenew`, the original copy keeps its position until then, so renewing that position stores and pays for yet another copy. Prefer the content hash, which always resolves to the latest copy. The cloud storage client's typed API does not expose `RetentionPeriod`, the `Utility` pallet, or the renewal pre-flight. For those, create a `polkadot-api` client with the `paseo_bulletin` descriptor from `@parity/product-sdk-descriptors/paseo-bulletin`. It provides `query.TransactionStorage.RetentionPeriod`, the `BulletinTransactionStorageApi.can_renew(account, entry)` runtime API, which reports whether a renewal would be accepted, and the `DataRenewal` calls. To register many renewals in one transaction, pass those calls to `batchSubmitAndWatch` from `@parity/product-sdk-tx`, which wraps them in `Utility.batch_all`; see [Transactions](/apps/product-sdk/tx/). Warning Each content hash can have only one registered renewal at a time, across all accounts. Registering a renewal again before the current one takes effect fails with `RenewalAlreadyEnabled`, so register once per retention period. The Bulletin Chain does not notify your Product before data expires: either enable auto-renewal or run your own scheduler (a cron job, queue, or background worker) that registers renewals in time. ## Storage Paths at a Glance The flows in this guide target the same chain but differ in authorization, atomicity, and consumer access. Use this table to pick the right path before writing. | Path | Authorization | Atomicity | Retention | Use When | | :----------------------: | :--------------------: | :------------------------: | :-------------------: | :---------------------: | | Bulletin store (small) | Bulletin authorization | Single tx | \~2 weeks (renewable) | Most Product writes | | Bulletin store (chunked) | Bulletin authorization | Multi-tx + DAG-PB manifest | \~2 weeks (renewable) | Files larger than 2 MiB | For deeper comparison and the full pallet reference, see [Data Storage Reference](/reference/polkadot-hub/data-storage/). ## Where to Go Next * **Publish and Subscribe to Off-Chain Data** *** Your Product can store durable content; next, add real-time state between users via the Statement Store. [→ Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/) * **Read On-Chain Data** *** Pair Bulletin writes with chain reads via the Host API's PAPI provider. [→ Read On-Chain Data](/apps/build/read-chain-state/) * **Product SDK API Reference** *** The full `product-sdk` surface beyond this recipe: every package, class, and method. [→ Visit Site](https://paritytech.github.io/product-sdk/) # Concepts > Core concepts for building Polkadot Products — identity, accounts and signing, allowances, data placement, and the TestNet networks. The [Build guides](/apps/build/) and [Deploy Your App](/apps/deploy-your-app/) walk you through tasks. This section explains the ideas underneath them. * **Identity** *** The per-app account and Proof of Personhood as a user's two identities, and why your Product's own `.dot` address is not one of them. [→ Identity](/apps/concepts/identity/) * **Accounts and Signing** *** Which component holds which account — phone, Host, and CLI — and why an allowance can land on the wrong one. [→ Accounts and Signing](/apps/concepts/accounts/) * **Allowances and Permissions** *** What the grants your Product requests authorize, their scope and lifetime, and how re-approval works. [→ Allowances and Permissions](/apps/concepts/allowances/) * **Where to Store Data** *** A decision guide across contract storage, cloud storage, the statement store, and local storage. [→ Where to Store Data](/apps/concepts/data-placement/) * **Networks** *** Paseo Next v2 and Products Devnet: how they relate and the differences that affect your app. [→ Networks](/apps/concepts/networks/) # Accounts and Signing > Which component holds which account when you build a Polkadot Product — phone, Host, and CLI — and why an allowance can land on the wrong one. ## Introduction More than one account is in play when you build and deploy a Polkadot Product, and they are not always the same account. Getting them confused is the most common way to hit a `no allowance set for account` error: you fund or authorize one account, then sign with a different one. This page explains which component holds which key, which account actually signs, and how to keep them aligned. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [The Polkadot app (client tier)](/apps/architecture/client/). ## Who Holds What * **The phone (Polkadot App)**: Holds the user's root private key and the secret for every per-Product account derived from it. All signing happens here. The key never leaves the device. * **The Host (Polkadot Desktop or Web)**: Holds no keys. It relays signing requests to the paired phone and shows the result. * **The `playground` CLI**: What it holds depends on the signer mode you choose, covered next. ## The Account That Signs a Deploy `playground deploy` signs with a different account depending on the signer mode: * **`--signer phone`** (the choice to make for a deploy you intend to keep; omit the flag and `pg deploy` prompts you): The deploy is signed by a **product account derived from the phone's root key**, scoped to your Product. The CLI holds only a paired session; the secret stays on the phone, which approves each step. The CLI does not create its own account in this mode. * **`--signer dev --suri `**: The CLI signs with a **local development key** derived from the URI you pass (for example, `//Alice` or a mnemonic). This account is unrelated to the phone. No phone approvals happen. * **`--signer dev` with no `--suri`**: Falls back to a **shared, publicly known development mnemonic**. Anyone can control this account; never use it for a deploy you want to keep. Dev-signer deploys are owned by the dev account A Product deployed with `--signer dev` is owned by that development key, not by you. Use the phone signer for anything you intend to keep or hand to real users. ## Product Accounts Are Per Product A product account is derived deterministically from `["product", productId, derivationIndex]`, so the account you get depends on the `productId` and index in play: * Inside a Host, your frontend derives its `productId` from where it is loaded: `localhost` maps to `playground.dot`, a `.dot.li` gateway URL maps to `.dot`, and otherwise it falls back to `playground.dot`. The derivation index is `0`. * The CLI session derives its own product account from the identifier it was paired under. The consequence: the account your running frontend signs with, and the account the CLI deployed under, are the **same only if their `productId` and index match**. A Product loaded from `localhost` (deriving under `playground.dot`) uses a different account than the same Product loaded from `my-app.dot.li` (deriving under `my-app.dot`). See [Identity](/apps/concepts/identity/) for the full derivation model. ## Why This Causes `no allowance set for account` Storage and messaging [allowances](/apps/concepts/allowances/) are granted **per account**. A missing allowance is rejected independently of your token balance: even with enough PAS to cover fees, the service rejects the request if the signing account has no allowance. So the failure is almost always an account mismatch: you granted the allowance (or storage authorization) to one account, but the account that actually signed was a different one — a dev key instead of the phone account, or a product account derived under a different `productId` than you expected. The fix is to grant the allowance to the account that actually signs, and to keep the `productId` consistent between where you request the allowance and where you sign. See the [troubleshooting entry](/apps/troubleshooting/#no-allowance-set-for-account) for the step-by-step resolution. ## See the Signing Address Before granting an allowance, confirm which account will sign: * **From the CLI**: Run `pg status`. It prints the product account paired with your phone in both encodings — the SS58 address and its H160 (EVM) form — along with its PAS and PGAS balances and the state of its Bulletin allowance. It is read-only: it signs nothing and submits no transactions, so it is safe to run at any point. `pg login` prints the same two addresses when a session is established. * **In a Host**: A Product running inside Polkadot Desktop or Web can read its product account through the [`signer`](/apps/product-sdk/signer/) package (`getProductAccount`), which returns the account's SS58 address and its H160 (EVM) form. Surfacing that address in your Product's own UI during development is the most reliable way to know what your frontend is signing with. The two addresses are one key `pg status` reports the SS58 and the H160 as separate rows, but they are two encodings of the same product account, not two accounts. Fund and authorize the SS58 form; `pallet-revive` contracts see the H160 form as `caller()`. The CLI account is not always your frontend's account `pg status` reports the account derived under `playground.dot/0`. A Product loaded from a deployed name derives under that name instead, so its account differs from the one the CLI shows. Check both when an allowance lands somewhere unexpected. ## Where to Go Next * **Allowances and Permissions** *** What an allowance authorizes, and how to grant it to the right account. [→ Allowances and Permissions](/apps/concepts/allowances/) * **Identity** *** The per-Product account derivation model and why accounts differ across Products. [→ Identity](/apps/concepts/identity/) * **Get TestNet Tokens** *** Fund the signing account and grant it the service allowances it needs. [→ Get TestNet Tokens](/apps/get-started/get-testnet-tokens/) # Allowances and Permissions > What a Polkadot Product's allowances authorize (Statement Store, Bulletin storage, contracts, auto-signing), plus their scope, lifetime, and re-approval. ## Introduction Some capabilities let your Product act on chain on the user's behalf, so the user has to grant them first. Your Product requests these grants — *allowances*, or resource allocations — from the Host, and the user approves them. A prompt such as "sign and submit on-chain transactions on your behalf" is one of these grants. Allowances are granted **per account**. This is why they are closely tied to [Accounts and Signing](/apps/concepts/accounts/): granting an allowance to one account does nothing for a different one, and a misdirected grant surfaces as [`no allowance set for account`](/apps/troubleshooting/#no-allowance-set-for-account). Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Get storage authorization](/apps/build/build-and-publish/#get-storage-authorization). ## What Your Product Can Request Your Product requests allowances through the SDK, typically once on connect. The resource types are: | Resource | What it authorizes | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `StatementStoreAllowance` | Publishing to the [Statement Store](/apps/product-sdk/statement-store/). | | `BulletinAllowance` | Storing data on the [Bulletin Chain](/apps/product-sdk/cloud-storage/). | | `SmartContractAllowance` | Sponsoring transactions for a product account, keyed by its derivation index, for [contract](/apps/product-sdk/contracts/) calls. | | `AutoSigning` | Signing and submitting transactions on the user's behalf without a per-action prompt. | Tag spelling differs by toolchain The Host and frontend codec spells the storage tag `BulletinAllowance`. The CLI and terminal codec spells it `BulletInAllowance` (capital `I`). They are two different codecs; use the spelling that matches the surface you are calling, and do not "correct" one to the other. ## Requesting an Allowance The [`signer`](/apps/product-sdk/signer/) package requests allocations through its `onConnect` hook, which fires once per connection. Each request resolves to an outcome: * **`Allocated`**: The user granted it. * **`Rejected`**: The user declined it. * **`NotAvailable`**: The Host or wallet cannot provide it right now. Request the allowances your Product needs up front, then treat a non-`Allocated` outcome as a feature being unavailable rather than a fatal error, so a declined grant degrades gracefully. AutoSigning is not available on mobile today `AutoSigning` returns `NotAvailable` on both the Android and iOS wallets today. A Product can request it, but the wallet will not grant it yet, so do not build a flow that depends on it. Fall back to per-transaction signing, where each submission prompts the user's phone. ## Scope and Lifetime * **Scope**: An allowance authorizes one capability for one account. `AutoSigning` is the broadest — it hands your Product a signing subtree so it can sign without prompting for each action — which is why it is gated behind an explicit approval. * **Lifetime**: The exact lifetime and expiry policy of an allowance is not documented. In practice, an expired allowance surfaces as an error telling you to re-pair the wallet. Treat allowances as revocable and potentially expiring rather than permanent. ## Re-Approval Is Expected Users are prompted once, and operations covered by a granted allowance do not prompt again. Two cases where you will see a prompt again are by design, not bugs: * **Redeploys**: The CLI caches granted allowances on disk, so subsequent deploys skip most prompts. A fresh environment prompts again. * **Page reload**: A Product re-requests its allocations each time it connects. If the Host still holds the grant, this is silent; otherwise the user is prompted again. Design for re-approval: make requesting allowances idempotent, and do not treat a repeat prompt as an error state. ## Inspect and Revoke * **Inspect**: There are cached checks for whether a storage or Statement Store allowance is present (they read local state and do not prompt the wallet). There is no documented way to inspect an `AutoSigning` grant specifically, and these checks read cached state rather than querying on-chain records. * **Revoke**: There is no documented per-allowance revoke. The coarse lever is tearing down the session — signing out clears the granted state. Revoking a single allowance while keeping others is not supported. Dismissing the approval modal Declining or dismissing an approval resolves that request as `Rejected` or `NotAvailable` rather than crashing your Product. The exact outcome a dismissed modal returns is not documented, so handle both. ## Where to Go Next * **Accounts and Signing** *** Allowances are per account; make sure you grant them to the account that signs. [→ Accounts and Signing](/apps/concepts/accounts/) * **Get TestNet Tokens** *** Grant your account the Bulletin storage authorization and other service allowances. [→ Get TestNet Tokens](/apps/get-started/get-testnet-tokens/) * **Permissions Reference** *** The Host-to-Product permission model at the protocol level. [→ Reference](/reference/apps/protocol/truapi/permissions/) # Where to Store Data > A decision guide for Polkadot Products — when to use contract storage, cloud storage, the statement store, or local storage, with the tradeoffs. ## Introduction A Polkadot Product has four places to keep data, and choosing the wrong one is a common early mistake — most often, putting bulk data in a contract. Each option trades off cost, persistence, size, and who can read it. This page is a decision guide: match the data to the layer built for it. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Storage & data](/apps/architecture/storage/). ## The Options at a Glance | Layer | Best for | Persistence | Size | Readable by | | ------------------------ | ------------------------------- | -------------------- | ----------------- | -------------------------------- | | Contract storage | Enforced shared state and logic | Permanent | Small, structured | Anyone, through contract methods | | Cloud storage (Bulletin) | Files and content blobs | \~2 weeks, renewable | Large | Anyone with the CID | | Statement store | Real-time signaling | Seconds (ephemeral) | Up to 512 bytes | Subscribers to your Product | | Local storage | Per-device state | Until cleared | Small | Only this device | ## Contract Storage Use a [smart contract](/apps/product-sdk/contracts/) when data is *logic that must be enforced for everyone*: ownership records, a leaderboard's rules, an escrow's state, a registry. Contract storage is permanent and its rules are trustless, but on-chain storage is expensive per byte and every write is a transaction. Do not put bulk data in a contract — file contents, images, long text, or anything that grows. Store the bytes in cloud storage and keep only the CID (a short content hash) in the contract if the contract needs to reference them. This keeps the contract small and cheap while the heavy data lives in the layer built for it. ## Cloud Storage (Bulletin Chain) Use [cloud storage](/apps/product-sdk/cloud-storage/) for content that outlives a session: profile photos, uploads, published posts, snapshots of app state. You upload bytes and get back a CID; anyone with the CID can fetch and verify the bytes. The key tradeoff is **retention**. Stored data is kept for about two weeks by default and must be renewed to persist beyond that. Renewal works from a CID. A chunked upload is renewed chunk by chunk, and its manifest CID lists the chunk CIDs. Plan for renewal from the start; see [Store Data on Chain](/apps/build/store-data-on-chain/#renew-long-lived-data) for how to renew, and [Deploy Your App](/apps/deploy-your-app/#keep-your-app-available) for keeping a deployed app available. ## Statement Store Use the [statement store](/apps/product-sdk/statement-store/) for real-time state between users: presence, typing indicators, cursors, and announcing where a fresh snapshot lives. Statements are signed, capped at 512 bytes, and expire in seconds. They are signaling, not storage — pair them with cloud storage when the content needs to survive. ## Local Storage Use [local storage](/apps/product-sdk/local-storage/) for state that belongs to one device: preferences, drafts, and cached values. It is private to the device and instant to read, but it is not shared, not durable across devices, and not a source of truth. ## A Common Pattern Many Products combine layers rather than choosing one: * The **statement store** announces that something changed (a small, live signal). * **Cloud storage** holds the full content, addressed by CID. * A **contract** or the announcement carries the CID so others know where to look. * **Local storage** renders instantly from the device's last known state while the rest loads. The [Shared Todo App tutorial](/apps/tutorials/shared-todo-app/) builds exactly this composition end to end. ## Where to Go Next * **Store Data on Chain** *** Upload to the Bulletin Chain and fetch by CID, with authorization and renewal. [→ Store Data on Chain](/apps/build/store-data-on-chain/) * **Add a Smart Contract to Your Product** *** Put enforced shared state in a contract, and keep bulk data out of it. [→ Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/) * **Build a Shared Todo App** *** A tutorial that composes all four layers into one Product. [→ Build a Shared Todo App](/apps/tutorials/shared-todo-app/) # Identity > The two identities a user brings to a Polkadot Product, a per-app account and Proof of Personhood, and why your Product's own .dot address is not one of them. ## Introduction A user interacting with your Product carries two identities, and they are deliberately separate: * **A per-app account**: A per-Product account derived for each user. This is the identity your Product signs and transacts with. * **Proof of Personhood**: A tier, a per-app alias, and sometimes an earned name, which together attest that the user is a unique human without revealing who they are. Keeping them apart is what lets the platform give your Product a stable account, and optional proof that the user is a real person, without turning every Product into a tracking surface. A related name that is not a user identity comes up constantly: your Product's own `.dot` address, the name users type to reach it. It shares a namespace with the names the personhood gateway issues, which makes the two easy to confuse, so it is covered in [Your Product's `.dot` Address](#your-products-dot-address) below. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Identity & personhood](/apps/architecture/identity/). ## The Per-App Account When a user opens your Product, the Host derives a **product account** for that user, scoped to your Product. The same user opening `app-a.dot` and `app-b.dot` gets a *different* account in each, derived deterministically from the user's identity and the Product's `.dot` identifier. The account has two address forms, both derived from the same public key: * **SS58**: The Substrate address, used across Polkadot chains. * **H160**: The EVM-style address, used for `pallet-revive` contracts on Polkadot Hub. Derivation follows a junction path of `["product", productId, derivationIndex]` applied with sr25519 soft derivation, where `productId` is normally your `.dot` name. Because soft derivation is composable on public keys, the CLI, a web Host, or any external client can compute the same address the mobile wallet derives privately, without ever seeing the secret key. Your Product obtains this account through the [`signer`](/apps/product-sdk/signer/) package (`getProductAccount`) and signs with it; every approval routes to the user's phone. See [Sign and Submit Transactions](/apps/build/sign-and-submit/) for the working flow. Why per-app derivation If every Product saw the same account for a user, any two Products could compare accounts and correlate the user across them. Per-Product derivation makes that impossible by default: different Products see different, unlinkable addresses for the same person. Sharing an account across your own Products is possible, but it requires an explicit permission grant; it is never the default. The same reasoning governs the sandbox model in the [TrUAPI reference](/reference/apps/protocol/truapi/sandbox/). ## Proof of Personhood [Proof of Personhood](/reference/apps/infrastructure/pop/) is a separate signal that a user is a unique human. It always has a tier and a per-app alias, and it sometimes has an earned name: * **A tier**: The strength of the proof, from none, through an attested proof of a unique device, to full personhood, proven in the Polkadot App. The [Proof of Personhood reference](/reference/apps/infrastructure/pop/) names the tiers. * **A per-app alias**: A Ring-VRF-derived identifier that is deterministic for a given user and Product, and unlinkable across Products. * **An earned name**: The human-readable name the personhood gateway issues to a user who has proved a tier, such as `joseph.42`. An alias is never an account address, and — like the per-app account — it is scoped per Product so it cannot be used to correlate a user across Products. Cross-Product alias linking requires an explicit consent step. Use personhood to gate features on verified-human status (for example, one action per person) without learning who the user is. ### The Earned Name An earned name is the one part of a user's identity that is human-readable and stable across Products. The personhood gateway issues it rather than the public registration path, which gives it properties a name bought with a deposit does not have: it is soulbound, so it never transfers, and it is not free-form, because the gateway decides the shape it issues. Read it with `getUserId` from the [`signer`](/apps/product-sdk/signer/) package, which returns it as `primaryUsername`. A user with no personhood tier has no earned name, so treat it as optional and always have a fallback. For the call and its caveats, see [Show a Display Name](/apps/build/sign-and-submit/#show-a-display-name). One name, several labels These docs call this the **earned name**, the term the dotNS reference uses for a name the gateway grants. A name that identifies a person is a *personhood name* and one that identifies a proved device is a *device name*; the SDK returns either as `primaryUsername`. An earned name and a Product address can be coupled A user's identities and your Product's address are separate by design, but not always independent in practice: the gateway issues an earned name into dotNS naming, so the name is also a dotNS name of the same text. Do not assume the two can never be linked. ## Usernames in Your Product There is no built-in primitive for an in-app username, so most Products need to choose a display identity themselves. Until a primitive exists, the recommended pattern keeps you aligned with the platform's identity model rather than inventing a parallel one: * **Prefer the earned name where you have it.** When the user holds any personhood tier, read the username the platform already associates with them (through the [`signer`](/apps/product-sdk/signer/) package's `getUserId`) and use it as the display name. This reuses an identity the user already has instead of minting a new one. See [Show a Display Name](/apps/build/sign-and-submit/#show-a-display-name) for the call and its caveats. * **Otherwise, let the user set a per-Product display name** and store it in [local storage](/apps/product-sdk/local-storage/) (device-local) or [cloud storage](/apps/product-sdk/cloud-storage/) (shared), keyed to their per-app account. Keep it scoped to your Product so it does not become a cross-Product identifier. * **Do not treat a display name as identity.** Authorization and uniqueness come from the per-app account and Proof of Personhood; a display name is a label on top of them. Following this pattern means Products converge on the same approach instead of each reinventing usernames, which eases any future migration to a platform primitive. ## Your Product's `.dot` Address A [`.dot` name](/apps/register-dot-domain/) is registered with [dotNS](/reference/apps/infrastructure/dotns/) and resolves to a content record: the CID of a published Product bundle. Ownership of a name is held by a Polkadot Hub account, but the name is not an account and cannot sign. Transferability depends on how the name was acquired. A name anyone registered by paying the deposit can be transferred. A name earned through the personhood gateway, the route that grants device and personhood names, cannot move: it identifies the person or device that earned it, and it stays with them. Most names point at *content* rather than at a user, but a gateway name identifies an identity (a personhood name names a person, and a device name names a unique device its holder proved), so a client that needs to tell the kinds apart should read `isPopIssued(label)` on the PoP controller rather than inspect the string. See [PopRules and Pricing](/reference/apps/infrastructure/dotns/poprules-pricing/). A name is how users reach your Product; it is not how your Product identifies a user. The confusion is that both live in the same namespace: a name registered by paying the deposit points at content, while a name earned through the gateway points at a person or a device. ## How They Fit Together * Users **find** your Product by its `.dot` address, which identifies your Product rather than them. * Your Product **acts** as the user through the per-app account, signing on the user's phone. * Your Product optionally **gates** features on Proof of Personhood, reading a tier and a per-app alias rather than a real-world identity, and **displays** the user's earned name when there is one. None of these reveals the user's root key. The per-app account and the personhood alias stay scoped to your Product unless the user explicitly grants cross-Product linking. The earned name is the exception: it is stable across Products by design, which is why reading it goes through `getUserId` and a permission prompt. ## Where to Go Next * **Sign and Submit Transactions** *** Derive and sign with the per-app account in your Product. [→ Sign and Submit Transactions](/apps/build/sign-and-submit/) * **Proof of Personhood** *** The Ring-VRF mechanism, tiers, and per-app aliases in depth. [→ Reference](/reference/apps/infrastructure/pop/) * **The Sandbox Model** *** How the Host isolates each Product and derives its per-domain account. [→ Reference](/reference/apps/protocol/truapi/sandbox/) # Networks > The two TestNet environments a Polkadot Product can target — Paseo Next v2 and Products Devnet — how they relate and the differences that affect your app. ## Introduction Two TestNet environments are available while you build Polkadot Products, and they are separate networks, not two names for one. The [Product SDK](/apps/product-sdk/) exposes both as presets: * **`paseo` (Paseo Next v2)**: The environment Polkadot Desktop development builds default to. It is a preview network and the successor to Paseo Next v1. * **`devnet` (Products Devnet)**: A public Paseo TestNet operated by the [Polkadot Community Foundation](/apps/polkadot-app/) (PCF) using open-source technology developed by Parity. Parity does not operate it. Its chains, endpoints and faucet are listed in [Networks & endpoints](/apps/reference/networks/). Both expose the same core chains a Product uses — Asset Hub, the Bulletin Chain, and Individuality (the chain that carries identity, personhood, and the Statement Store, which the reference docs also call the People Chain) — so most Product code runs on either without changes. The production `polkadot` and `kusama` presets are not live yet; requesting them throws. Who operates each environment Polkadot Products can target environments run by two different operators. Each operator deploys, maintains, and supports its own environment, so report a problem to the operator of the environment where it occurs. See [Choose the Right Channel](/get-support/#choose-the-right-channel) for where to ask. * **Parity**: Runs Paseo Next v2 (the `paseo` preset, parachain 1500) and the services on it, including dotNS and the Playground directory, and maintains the `playground` CLI these docs use. Parity publishes development builds of Polkadot Desktop on the [`polkadot-desktop-community` releases page](https://github.com/paritytech/polkadot-desktop-community/releases) and nightly Android builds of the Polkadot App on the [`trinity-user-agents` releases page](https://github.com/paritytech/trinity-user-agents/releases/tag/nightly-android). Ask about Paseo Next v2 or Parity's tools through [Polkadot Developer Support](/get-support/#support-channels), or report bugs in the tool's own GitHub repository. * **Polkadot Community Foundation (PCF)**: Operates Products Devnet (the `devnet` preset) and everything on it, including its chains, registries, and deployments, using open-source technology developed by Parity. PCF also publishes its own builds of the Polkadot App, including the Google Play app, and of Polkadot Desktop, and the `pad` tooling that publishes to Browse. Parity does not operate these services; report issues with them in PCF's [`products-devnet-issues` repository](https://github.com/Polkadot-Community-Foundation/products-devnet-issues) or ask in `#devnet-discussion` on the [Polkadot Discord server](https://discord.com/invite/eD4jMYbC5U). ## What Differs The one behavioral difference documented today that can affect your app is transaction signing on Paseo Next v2: * **`AsPgas` signed extension (Paseo Next v2)**: Paseo Next v2 ships an `AsPgas` signed extension that legacy Polkadot.js-style signing does not understand, so that path fails with an error about the unsupported signed extension. Sign through the product account instead — get a signer from [`getProductAccount(...).getSigner()`](/apps/product-sdk/signer/), which routes through the Host's transaction path and preserves the extension. This is the path the SDK guides already use, so following them keeps you compatible. Beyond signing, the two networks are separate deployments with separate operators, so do not assume they offer the same capabilities. Endpoints and preset details are re-homed as the networks evolve, so resolve them from the SDK preset rather than hardcoding. ## Proof of Personhood Availability Whether the [Proof of Personhood](/apps/concepts/identity/) Full tier is active on a given network depends on operator-side configuration, so it can differ between environments and over time. Treat a `None` or `Lite` result as the safe default in your Product, and gate features so they still work when a higher tier is unavailable. Confirm current per-network capabilities Which personhood tiers, discovery directories, and services are live on each network is evolving and is not fully captured in these docs. Before depending on a specific capability being present on Products Devnet or Paseo Next v2, confirm its current status with that network's operator rather than assuming the two match. ## Where to Go Next * **Chain Client** *** How a Product connects to these networks through the Host, and how presets map to chains. [→ Chain Client](/apps/product-sdk/chain-client/) * **Get TestNet Tokens** *** Fund your account and grant service allowances on your target network. [→ Get TestNet Tokens](/apps/get-started/get-testnet-tokens/) # Deploy Your App > Deploy your Polkadot Product to the playground using the playground CLI — build, upload, and publish your app on-chain and register a dotNS name. ## Introduction This page covers how to take a finished Polkadot Product live with the `playground` CLI. By the end, your app bundle will be uploaded to the Bulletin Chain, registered under a dotNS name, and, if you choose, discoverable in the Polkadot Playground. TestNet names end in `.paseo`, not `.dot` dotNS top-level domains are per network. On Paseo Next v2, the TestNet the Apps tooling targets by default, names are minted under `.paseo`: publish `myproject57` and you get `myproject57.paseo`, served at `https://myproject57.paseo.li`. Whether you supply the bare label or the full name depends on the tool; see [Choose a Name](/apps/register-dot-domain/#choose-a-name). A deploy is really four stages, and `playground deploy` walks you through all of them in one flow: * **Build**: Compile your Product into a static bundle of files (HTML, JS, CSS, assets) with `playground build`. * **Register**: Reserve a dotNS name for your Product through the on-chain name service. This is the address people use to reach it. See [Register a `.dot` Domain](/apps/register-dot-domain/). * **Publish**: Optionally list your Product in the public Playground directory so others can discover it. Deploying without publishing keeps it reachable at its dotNS address but unlisted. See [List Your App](/apps/list-your-app/). * **Deploy**: Upload the bundle to the Bulletin Chain and bind it to your name, so any Host can fetch and verify it directly. If your Product includes a [smart contract](/apps/build/deploy-a-smart-contract/), the deploy flow can redeploy that too, covered in the contract prompt below. Products Devnet This page uses Paseo Next v2 (`paseo` preset). For the PCF Products Devnet (`devnet` preset), see [Build & publish an app](/apps/build/build-and-publish/). ## Prerequisites Before deploying, ensure you have: * Complete [Install Desktop and Pair](/apps/get-started/) and [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/); your account needs PAS funds and a Bulletin Chain authorization. If you have not obtained a Bulletin Chain authorization yet, request one from the [Bulletin Chain authorization page](https://paritytech.github.io/polkadot-bulletin-chain/authorizations) * A Polkadot Product project running locally. See [Set Up Your Project](/apps/build/#set-up-your-project) ## Build Your App Bundle Run `playground build` to compile your project into a deployable bundle. playground build The CLI auto-detects your project type and runs the appropriate build. The output is a set of static files (HTML, JS, CSS, assets) that will be uploaded in the next step. Tip If you have already built the project, you can skip this step. `playground deploy` will prompt you to reuse the existing build. ## Deploy Your App Run `playground deploy` to start the interactive deploy flow. The CLI walks you through a series of prompts, then shows a confirmation summary before uploading. playground deploy The CLI presents the following prompts in order: 1. **Review app detail page**: A reminder that your `README.md` becomes your app's detail page on the playground. Make sure it's up to date, then press `Enter` to continue (or `Esc` to exit and edit it first). 2. **Redeploy contracts if changed**: Smart contracts hold your app's on-chain logic and data, and deploy separately from your website. Choose **no** if you only changed the website. Choose **yes** if you changed contract code in this project. The CLI then redeploys and reinstalls the contracts and rebuilds the site to match. See [Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/) for the contract workflow in depth. ``` did you change your smart contracts? › no · I only changed the website yes · I changed contract code too ``` 3. **Choose to rebuild before deployment**: Compiles your latest code into the files that get uploaded. Choose **yes** to rebuild now, or **no** to redeploy the build that's already in your build folder. ``` build before deploy? › yes · rebuild with my latest code no · redeploy the existing build ``` 4. **Choose who signs the upload**: Publishing writes to the blockchain, which needs a signature. The **dev signer** uses a shared test account: instant, no phone needed. The **phone signer** signs with your own logged-in account, with a few taps on your phone. ``` who signs the upload? › dev signer · fast, no phone needed your phone signer · signs with your own account ``` Your phone will prompt — check it With the phone signer, each step waits for you to approve it in the Polkadot App, and there is no push notification announcing that a prompt is waiting. If the deploy appears to stall — including a deliberate pause while your name is registered — open the app and look for a pending approval. See the troubleshooting entries for [an unanswered phone prompt](/apps/troubleshooting/#the-app-seems-frozen-after-an-action) and [the registration pause](/apps/troubleshooting/#the-deploy-pauses-for-about-a-minute), and [Accounts and Signing](/apps/concepts/accounts/) for which account the phone signer uses. 5. **Choose a default build directory**: The folder holding your built site (the files that get uploaded). The default `dist` fits most projects. This example uses `.next` for a Next.js app. ``` build directory default: dist › .next█ ``` 6. **Choose a domain name**: Pick the address people will use to reach your app. Enter the bare label, such as `myproject57`; the CLI appends the environment's TLD, so on Paseo Next v2 that becomes `myproject57.paseo`. Which names you may register depends on the label's length, counted as written. Digits count like any other character: | Length | Requirement | | ---------------------- | ------------------------------------------------- | | 9 characters or longer | Open to everyone, with no personhood check | | 6 to 8 characters | Not sold on this path; earned in the Polkadot App | | 5 characters or fewer | Reserved for governance, not sold on this path | ``` domain › myproject57█ ``` The label also has to be 3 to 63 lowercase characters (`a-z`, `0-9`, `-`), with no leading or trailing dash. Digits are allowed anywhere and in any quantity. If registration is rejected, the name may already be [taken](/apps/troubleshooting/#the-name-is-already-registered) or [too short to buy](/apps/troubleshooting/#short-names-are-not-for-sale). See [Register a `.dot` Domain](/apps/register-dot-domain/#choose-a-name) for the full name rules. 7. **Publish to the playground**: Choose **yes** to list your app in the public Polkadot Playground so others can find and open it. Choose **no** to still deploy it to your dotNS address, but keep it unlisted. ``` publish to the playground? › yes · list it in the public playground no · deploy to my .paseo address only ``` 8. **Review confirmation summary**: The CLI shows a summary of your choices before uploading. Review it, then press `Enter` to deploy (or `Esc` to cancel). With the dev signer, no phone taps are needed and `phone approvals` reads `none`. ``` playground deploy · myproject57.paseo · paseo next v2 v0.47.0 ──────────────────────────────────────────────────────────────────────── deploying myproject57.paseo signer Dev signer (no phone taps for upload) build skip (use existing) build dir .next contracts skip publish dotNS only phone approvals none enter to deploy · esc to cancel ``` Press `Enter` to confirm. The CLI then runs the upload and on-chain registration steps. If you chose the **phone signer**, each step triggers an approval prompt in the Polkadot mobile app — open the app and approve when prompted. With the **dev signer** selected here, the upload and dotNS registration run automatically with no phone prompts, and the deploy finalizes: ``` playground deploy · myproject57.paseo · paseo next v2 v0.47.0 ──────────────────────────────────────────────────────────────────────── frontend · build skipped ✓ upload + dotns ✓ deploy complete url https://myproject57.paseo.li domain myproject57.paseo app cid bafybeihvru3e6ojhopxj7xxwtafrpyvsha6kylzklryon5k67u4clr26re ipfs cid bafybeigr2liqwftbmily4sdxvo7mq4atgboqsrpdadypmsbpkn7c25cwja ``` ## Open Your App Once the deploy completes, the CLI prints the URLs for your app. Regardless of whether you published it to the playground, your app is live at its dotNS address and reachable through the web gateway, which appends `.li` to the full name: ```text https://myproject57.paseo.li ``` You can also navigate directly by entering your name in the [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/) browser address bar: ```text myproject57.paseo ``` ![Successfully deployed app reachable at its dotNS URL](/images/apps/deploy-your-app/deploy-your-app-01.webp) Either way, the app loads directly from the Bulletin Chain — no central server involved. If you chose **yes** at the `publish to the playground?` prompt, your app is also listed in the public playground directory. Open `playground.dot` in Polkadot Desktop browser and your app appears under your name, so others can find and open it. If you chose **no** (`dotNS only`, as in this example), the app is still fully deployed and reachable at the URLs above, only unlisted in the directory. Tip If your app does not appear immediately, wait a few seconds and refresh. On-chain state propagation can take a short time after the deploy transaction finalizes, and the web gateway resolves your name through an in-browser light client. A `curl` or script against the gateway URL returns a generic gateway shell rather than your app — open it in a real browser. If it still does not resolve, see [Troubleshooting](/apps/troubleshooting/#the-app-does-not-appear-right-after-deploy). ## Keep Your App Available Data published to the Bulletin Chain, including your app bundle, is retained for about two weeks by default and must be renewed to persist beyond that. The exact retention window is still being finalized, so treat "about two weeks" as provisional. Renewal is a separate transaction that keeps the data available for another retention window without changing its CID. Renewal identifies each stored record by its content hash, which you can derive from the record's CID. Your app bundle is stored as several chunks, each in its own transaction, plus a manifest that lists them, so keeping the bundle available means renewing the manifest and every chunk. The CLI deploy does not renew your bundle `playground deploy` does not renew the data it uploads. The `app cid` it prints is the bundle's manifest, and its links are the chunk CIDs, so you can renew the whole bundle from that one CID without uploading it again. The [renewal example in Store Data on Chain](/apps/build/store-data-on-chain/#renew-long-lived-data) reads the manifest and renews the manifest and every chunk. See the [Bulletin Chain renewal reference](/reference/apps/infrastructure/bulletin-chain/renewal/) for the mechanics. ## If a Deploy Fails Deploy-time issues have named fixes in [Troubleshooting](/apps/troubleshooting/): * [The deploy pauses for about a minute](/apps/troubleshooting/#the-deploy-pauses-for-about-a-minute): the tooling waiting out the dotNS commit-reveal handshake, not a hang. * [The name is already registered](/apps/troubleshooting/#the-name-is-already-registered) or is [too short to buy](/apps/troubleshooting/#short-names-are-not-for-sale): choose a different or longer name. * [`no allowance set for account`](/apps/troubleshooting/#no-allowance-set-for-account) or [uploads are rejected](/apps/troubleshooting/#uploads-are-rejected-or-host-storage-unavailable): the signing account is missing PAS or a storage authorization. * [The app does not appear right after deploy](/apps/troubleshooting/#the-app-does-not-appear-right-after-deploy): on-chain propagation and gateway resolution take a moment. ## Where to Go Next * **Register a `.dot` Domain** *** The naming step in depth: availability rules, the commit-reveal flow, and managing your name. [→ Register a `.dot` Domain](/apps/register-dot-domain/) * **List Your App** *** Make your Product discoverable in the Playground and Browse directories. [→ List Your App](/apps/list-your-app/) * **Store Data on Chain** *** The store receipt, chunking, authorization, and renewal in full. [→ Store Data on Chain](/apps/build/store-data-on-chain/) # Install Polkadot Desktop and Pair > Install Polkadot Desktop, pair it with the Polkadot App on your phone with a QR scan, and set up the foundation for local Polkadot Product development. ## Introduction You should already have the [Polkadot App](/reference/apps/hosts/polkadot-app/) on your phone from the [Apps overview](/apps/); it holds your key and approves signing. This page covers installing [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/), where your Product runs, and pairing the two with a QR scan, then forwards you to TestNet funding. About 10 minutes. Two pieces of the Polkadot Triangle need to be talking to each other: Polkadot Desktop, where your Product runs, and the Polkadot App on your phone, where signing happens. ![Diagram: Polkadot Desktop displays a QR code that the Polkadot App scans; the App returns a session public key, and from then on every signing request routes from Desktop to the App for signature.](/images/apps/get-started/install-and-pair/pairing-flow.svg) Polkadot Desktop never holds your private key. Your identity lives on the Polkadot [People Chain](/reference/glossary/#people-chain), your private key lives in the Polkadot App, and Polkadot Desktop only ever holds a derived session public key — enough to identify you and construct per-Product accounts, but not enough to sign anything on its own. Products Devnet This page uses Paseo Next v2 (`paseo` preset). For the PCF Products Devnet (`devnet` preset), see [More resources](/apps/reference/resources/). ## Prerequisites Before getting started, ensure you have: * The [Polkadot App](/apps/#get-the-polkadot-app) installed on your phone with an account created (your developer identity and signing device for Polkadot Products) * A workstation running macOS, Windows, or Linux * A device (iOS or Android) with a working camera * Network connectivity on both devices On Android, the Polkadot App is installed from Parity's APK rather than Google Play, which requires allowing installs from unknown apps. See [Get the Polkadot App](/apps/#get-the-polkadot-app). Who operates each environment Polkadot Products can target environments run by two different operators. Each operator deploys, maintains, and supports its own environment, so report a problem to the operator of the environment where it occurs. See [Choose the Right Channel](/get-support/#choose-the-right-channel) for where to ask. * **Parity**: Runs Paseo Next v2 (the `paseo` preset, parachain 1500) and the services on it, including dotNS and the Playground directory, and maintains the `playground` CLI these docs use. Parity publishes development builds of Polkadot Desktop on the [`polkadot-desktop-community` releases page](https://github.com/paritytech/polkadot-desktop-community/releases) and nightly Android builds of the Polkadot App on the [`trinity-user-agents` releases page](https://github.com/paritytech/trinity-user-agents/releases/tag/nightly-android). Ask about Paseo Next v2 or Parity's tools through [Polkadot Developer Support](/get-support/#support-channels), or report bugs in the tool's own GitHub repository. * **Polkadot Community Foundation (PCF)**: Operates Products Devnet (the `devnet` preset) and everything on it, including its chains, registries, and deployments, using open-source technology developed by Parity. PCF also publishes its own builds of the Polkadot App, including the Google Play app, and of Polkadot Desktop, and the `pad` tooling that publishes to Browse. Parity does not operate these services; report issues with them in PCF's [`products-devnet-issues` repository](https://github.com/Polkadot-Community-Foundation/products-devnet-issues) or ask in `#devnet-discussion` on the [Polkadot Discord server](https://discord.com/invite/eD4jMYbC5U). ## Install Polkadot Desktop 1. Download the latest development build of Polkadot Desktop for your platform from the [`polkadot-desktop-community` releases page](https://github.com/paritytech/polkadot-desktop-community/releases). 2. Install the application using your platform's standard installer. 3. Launch Polkadot Desktop. On first launch, Desktop opens into the pairing flow with a QR code. ![Polkadot Desktop login screen showing the pairing QR code and the network selector at the top right with Paseo Next V2 selected.](/images/apps/get-started/install-and-pair/install-and-pair-02.webp) Skip for development The login screen also exposes a **Skip (Dev only)** button. Skipping the pairing drops you straight into Desktop without a paired signer, useful for inspecting Desktop or testing a local Product that does not require signing, but most development flows assume a paired Polkadot App. ## Pair Polkadot Desktop with the Polkadot App Pairing is a one-time cryptographic handshake. Desktop displays the QR code, the App scans it, and the App returns a session public key that Desktop stores. From that point forward, Desktop knows who you are and can construct per-Product sub-accounts, but every signing prompt still routes back to the App for approval. 1. Leave the QR code visible on the Polkadot Desktop login screen. 2. In the Polkadot App, open the camera-scanning view and scan the QR code shown on Desktop. A **Link a new device?** prompt appears with the Desktop version details. ![Polkadot App showing the "Link a new device?" prompt listing Polkadot Desktop with Cancel and Link buttons.](/images/apps/get-started/install-and-pair/install-and-pair-03.webp) 3. Tap **Link** to confirm. The App briefly shows a **Connecting device...** state while the handshake completes. ![Polkadot App showing the "Connecting device..." state with a loading spinner.](/images/apps/get-started/install-and-pair/install-and-pair-04.webp) 4. Desktop transitions from the QR code to a **Completing pairing...** state. ![Polkadot Desktop showing the "Completing pairing..." state with a loading spinner where the QR code was.](/images/apps/get-started/install-and-pair/install-and-pair-05.webp) 5. Once the handshake completes, Desktop opens the main dashboard. ![Polkadot Desktop showing the paired dashboard with the address bar and Browse section listing available Products.](/images/apps/get-started/install-and-pair/install-and-pair-06.webp) After pairing, your identity on the People Chain is bound to the Polkadot App for this Desktop session. Every subsequent signing request will route to the App, and you approve or reject each one on the signing device. ## Where to Go Next * **Get TestNet Tokens** *** Claim TestNet tokens from the Polkadot Faucet and unlock per-service allowances. [→ Continue](/apps/get-started/get-testnet-tokens/) # Get started as a developer On the Polkadot Products Devnet, an app is a static website with a `.dot` name. You build it, publish it to the Devnet, and people open it in the Polkadot app or in a browser. This page takes you from installing the tools to a live app. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Quick Start with the CLI](/apps/quick-start/) or [Quick Start with RevX](/apps/quick-start-revx/). ## What you are building These docs call a published app a Product. It is a static web app: HTML, CSS and JavaScript. There is no app store, no backend for you to run and no server between your users and your app. A Product runs inside a host: the Polkadot app (mobile or desktop) or the web gateway at [dev-dot.li](https://dev-dot.li). The host provides the wallet, the signing prompts, storage and chain access. Your app talks to the host over a protocol called TrUAPI, so the same code runs on mobile, desktop and the web, and your users never have to handle raw keys or RPC endpoints. To publish, you upload the bundle to the Devnet and point a `.dot` domain at it. The name then resolves to your bundle wherever someone opens it. ## How the pieces fit ``` flowchart TD subgraph U[Entry points] APP[Polkadot app
mobile + desktop] GW[Web gateway
dev-dot.li] end subgraph D[Your Product] BUNDLE[Static web bundle
.dot domain -> content] end subgraph S[Developer tooling] SDK[Product SDK
@parity/product-sdk] HOST[Host protocol: TrUAPI
@parity/truapi] CLIS[CLIs: pad / dotns] end subgraph P[Platform services on Paseo] NAME[DotNS naming
Asset Hub contracts] STORE[Bulletin content storage] ID[Identity + personhood
People chain] MONEY[CASH + assets
People chain / Asset Hub] CONTRACTS[PolkaVM contracts
pallet-revive] BROWSE[Browse directory
Publisher registry] end APP --> BUNDLE GW --> BUNDLE BUNDLE --> HOST BUNDLE --> SDK SDK --> HOST CLIS --> NAME CLIS --> STORE HOST --> ID HOST --> MONEY HOST --> CONTRACTS NAME --> STORE BROWSE --> NAME ``` The Polkadot app keeps keys on the device, runs each Product in a sandbox and speaks TrUAPI to it. You use the SDK in your app code, and the CLIs to name and publish your app. The services on the chains handle naming, storage, identity, money, contracts and discovery. When you get stuck, first work out which of these layers the problem is in. The [architecture overview](/apps/architecture/) explains each one, and follows a request from a `.dot` name to chain storage and back. ## Before you start You run every command below through the CLIs from [step 1](#1-install-the-tooling), and you sign with one account. If you don't have a key yet, [step 4](#4-set-up-an-account-and-register-a-dot-domain) shows how to create a throwaway one (no seed to import, no password). Before a command can touch the chain, that account must be: 1. Funded with native tokens on Asset Hub, to pay fees. Use the [faucet](/apps/reference/networks/#faucet). 2. Mapped to its EVM address. Do this once with `dotns account map --env devnet`. Every CLI here signs PolkaVM transactions on Asset Hub, and an unmapped account fails on the first one. 3. Authorized to write to Bulletin, so step 5 can upload your bundle. See [Get storage authorization](/apps/build/build-and-publish/#get-storage-authorization). The CLIs don't share a keystore. `dotns` keeps its own (step 4) and `pad` takes `--mnemonic` on the command line. Both can use the same account. ## 1. Install the tooling `pad` requires Node.js 22 or newer. On Node 20 it fails at startup with an unrelated-looking error (a module `SyntaxError`, or `Missing WebSocket class`), so check with `node --version` before installing. ```bash npm i -g @polkadot-community-foundation/dotns-cli@latest # dotns npm i -g @polkadot-community-foundation/polkadot-app-deploy@latest # pad, pad-bootstrap ``` Install only what you need: `pad` publishes (and can register the name for you), and `dotns` manages names in depth. Both are large. Expect a few minutes and roughly 1.5 GB across the global prefix and the npm cache, with no progress output while npm works. Always take the latest release. These CLIs carry the current contract addresses and network presets inside them, so an older copy can talk to a retired deployment and report success while nothing changes. To upgrade one you already have, re-run the same command. On some ARM64 platforms (for example Termux on Android), a transitive dependency, `node-datachannel`, ships no prebuilt binary, and its native build fails during `npm i -g`. It is only used for optional peer-to-peer CID verification, so skip the build with `--ignore-scripts`: ```bash npm i -g --ignore-scripts @polkadot-community-foundation/dotns-cli@latest ``` In this mode only the peer-to-peer verification path is unavailable. The CLI's gateway-based CID verification still works. Your app code also needs the SDK, at the version the hosts speak (see [Packages & tools](/apps/reference/packages/#install-the-sdk-version-the-hosts-speak)): ```bash npm i @parity/product-sdk@0.39.0 ``` ## 2. Choose a network preset Both CLIs take the network as a flag, and for this Devnet it is `--env devnet`. `pad` and `dotns` already default to `devnet`, but they also ship presets for other networks. Pass `--env devnet` anyway, so a command never lands on another chain by accident. ## 3. Build a web app with the Product SDK The Product SDK (`@parity/product-sdk`) gives your app typed access to the host: wallet, storage, chain calls, contracts and identity. ```ts import { createApp } from "@parity/product-sdk"; const app = await createApp({ cloudStorage: { environment: "devnet" }, // defaults to paseo }); const result = await app.cloudStorage!.upload("hello world"); if (result.ok) console.log(result.value); // the CID ``` This code only works inside a host. Outside the Polkadot app or the web gateway, `createApp()` itself throws `createApp requires a host product context`. Start from the [playground-app-template](https://github.com/Polkadot-Community-Foundation/playground-app-template), which is already on the SDK version the hosts speak. For automated tests, use the test host in `@parity/truapi-host`, described in [Use platform services from the SDK](/apps/build/platform-services-sdk/#test-without-the-real-host). Build your app to a static directory. The template uses `vite build`, which writes to `dist/`. ### Build with Claude Code The product-sdk repo is also a [Claude Code plugin marketplace](https://github.com/paritytech/product-sdk#claude-code-plugin). Its skills teach Claude Code the whole SDK: app scaffolding, chain connections, transactions, contracts, cloud storage, statement store, individuality, utilities, and migrating an existing codebase. Install it, then ask "build me a Polkadot app": ```plaintext /plugin marketplace add paritytech/product-sdk /plugin install product-sdk@paritytech /reload-plugins ``` Each skill is a plain Markdown file under [`product-sdk/skills/`](https://github.com/paritytech/product-sdk/tree/main/product-sdk/skills), so other agents and editors can read them as reference too. The skills follow the SDK's `main` branch, which is already past 0.39.0. Tell the agent to keep `@parity/product-sdk@0.39.0`, and check an API against that version when a skill and the installed package disagree. ## 4. Set up an account and register a `.dot` domain Your deploy account must own the `.dot` domain before you can publish to it. This is a CLI signing key, separate from any account in the Polkadot app. For a hackathon, you don't need to import a seed phrase or set a keystore password. Create a fresh account and pass its mnemonic to the CLIs through the environment: ```bash # One fresh BIP-39 mnemonic, generated with the crypto that ships inside the CLIs export MNEMONIC="$(NODE_PATH="$(npm root -g)/@polkadot-community-foundation/dotns-cli/node_modules" \ node -e 'const c=require("@polkadot/util-crypto");c.cryptoWaitReady().then(()=>console.log(c.mnemonicGenerate()))')" export DOTNS_MNEMONIC="$MNEMONIC" # dotns signs with this — no `dotns auth set`, no password dotns account address # the throwaway's address — fund THIS at the faucet ``` `pad` takes the same `$MNEMONIC` when it publishes (`--mnemonic "$MNEMONIC"`), so one account both owns the name and deploys to it. The phrase only lives in this shell session. Save it if you want to keep the name. If you discard it, the account really is throwaway. Set a key, or you sign as a shared account With neither `DOTNS_MNEMONIC`/`DOTNS_KEY_URI` set nor `dotns auth set` run, `dotns` falls back to a shared public dev account that anyone can control. A name registered to it is not yours, and anyone can transfer it away. `dotns` prints a warning on every command when this happens. To reuse an account across sessions, store a mnemonic or key-uri in the encrypted `dotns` keystore instead of the environment: ```bash dotns auth set # choose `mnemonic`, paste it, then set a password dotns account address # confirm the active account ``` Every later command then needs the keystore password. Export `DOTNS_KEYSTORE_PASSWORD` to avoid an interactive prompt. See [Register a `.dot` domain](/apps/build/register-a-dot-name/#set-up-an-account) for details. Fund, map and authorize the account as listed in [Before you start](#before-you-start). Then, with `$MNEMONIC` exported, register your name: ```bash dotns register domain --name my-cool-app --env devnet ``` Pick a label whose stem (the label without any trailing digits) is nine characters or longer. Shorter ones need proof of personhood or are reserved. Registration is a commit-reveal flow that takes a few minutes, so check that it landed before you move on: ```bash dotns lookup owner-of my-cool-app --env devnet ``` [Register a `.dot` domain](/apps/build/register-a-dot-name/) has the full rules. ## 5. Publish the bundle with `pad` `pad` uploads your static build and points the `.dot` domain at it. It does not read the dotns keystore, so give it the signer that owns the name: ```bash pad ./dist my-cool-app.dot --env devnet --mnemonic "$MNEMONIC" ``` That account must own the name and hold a Bulletin storage authorization. A successful run ends with `Verified on-chain:` and the published CID. Your app is now live as `my-cool-app.dot` in the Polkadot app and at `https://my-cool-app.dev-dot.li` on the gateway. To give it a name, description and icon in the directory, add a product config. See [Add card metadata](/apps/build/build-and-publish/#add-card-metadata). ## Next steps Each step above has a full guide under the **Guides** tab: * **[Build & publish an app](/apps/build/build-and-publish/)** *** Bundle, name, deploy and card metadata. * **[Register a `.dot` domain](/apps/build/register-a-dot-name/)** *** Account setup, name rules and the commit-reveal flow. * **[Use platform services from the SDK](/apps/build/platform-services-sdk/)** *** Chains, storage, contracts and identity from your app. To see finished Products, open [Calculator](https://calculator.dev-dot.li) or [Stopwatch](https://stopwatch.dev-dot.li). The full list of reference apps is in [More resources](/apps/reference/resources/). To try your own app as a user, install the Polkadot app and fund an account. See [Create an account & get funds](/apps/using-the-app/create-account/). # Get TestNet Tokens > Claim TestNet tokens from the Polkadot Faucet and unlock per-service allowances for Bulletin Chain, Statement Store, and dotNS. To build and test, your account needs two things on TestNet: a balance of [PAS](/reference/glossary/#pas) (the Paseo TestNet token, which pays transaction fees) and per-service *allowances* for the infrastructure your Product uses. Products Devnet This page uses Paseo Next v2 (`paseo` preset). For the PCF Products Devnet (`devnet` preset), see [Faucet](/apps/reference/networks/#faucet). ## Prerequisites Before getting started, ensure you have: * Completed the [Install Polkadot Desktop and Pair](/apps/get-started/) guide so [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/) is paired with your signer ## Get Tokens The Polkadot Faucet distributes free PAS tokens to developers. 1. Open the [Polkadot Faucet for parachain 1500](https://faucet.polkadot.io/?parachain=1500). Paseo Next v2's Polkadot Hub is parachain 1500, so use this link rather than picking a network by hand. ![Polkadot TestNet Faucet showing the Network and Chain dropdowns, the Paseo Address input, the reCAPTCHA check, and the Get some PASs button.](/images/apps/get-started/get-testnet-tokens/get-testnet-tokens-01.webp) 2. Paste the address of the account paired with Polkadot Desktop into the address field. 3. Click **Get Some PASs** to request tokens. They arrive in your account shortly after the request is processed. Pick parachain 1500, not the public Paseo Polkadot Hub The faucet's default selection drips to the public Paseo Polkadot Hub (parachain 1000), which is a different chain from the one Polkadot Desktop and the `playground` CLI target. Funding that chain leaves your Paseo Next v2 balance at zero, with no error to tell you why. The `?parachain=1500` link above is the same one the `playground` CLI uses. Parachain 1000 is the right choice only for the PCF Products Devnet (`devnet` preset); see its [Faucet](/apps/reference/networks/#faucet) instructions. Or top up from the CLI If you have paired the [`playground` CLI](/apps/quick-start/), `pg drip` funds your product account directly, no browser or captcha involved. It sends 1 PAS per run up to a 10 PAS cap, drawn from a shared dev funder rather than the public faucet. Run `pg status` afterward to confirm the balance landed on the account you expect. ## Service Allowances Some Polkadot infrastructure services use a separate allowance-based access model. These allowances are independent of your token balance; even with enough PAS to cover fees, a missing allowance will cause the service to reject your request. Allowances are granted per account, so a missing or misdirected one surfaces as [`no allowance set for account`](/apps/troubleshooting/#no-allowance-set-for-account) or [rejected uploads](/apps/troubleshooting/#uploads-are-rejected-or-host-storage-unavailable); see [Accounts and Signing](/apps/concepts/accounts/) for granting them to the account that actually signs. Service Allowances: Bulletin Chain Storage The [Bulletin Chain](/reference/apps/infrastructure/bulletin-chain/) has no token balance for storage. Every account needs an explicit authorization that grants a quota of transactions and bytes before it can store data on-chain. Without authorization, storage extrinsics are rejected. On TestNet, request your storage authorization directly from the [Bulletin Chain authorization page](https://paritytech.github.io/polkadot-bulletin-chain/authorizations). This is required before submitting any `store` extrinsic from your Product. After your authorization request is confirmed, you can verify the allocation on-chain by querying the `Authorizations` storage map of the `transaction-storage` pallet for your account. Service Allowances: Statement Store The [Statement Store](/reference/apps/infrastructure/statement-store/) lets accounts publish off-chain statements that are gossiped and persisted by the network. Access is controlled by an on-chain `StatementAllowance` record that specifies two limits per account: `max_count` (the maximum number of statements the account can publish) and `max_size` (the maximum total bytes across those statements). Provisional The process for obtaining a Statement Store allowance on TestNet is not yet documented. Check back for updates, or ask in the developer community for available access paths. Service Allowances: dotNS Names [dotNS](/reference/apps/infrastructure/dotns/) name registration charges the same refundable deposit for every name it admits on the public path, whatever its length. The deposit is paid in the network's native token, so on Paseo it is PAS, and names carry the environment's TLD rather than `.dot`. The public path sells only names of nine characters or more. Device and personhood names of six to eight characters are earned through the personhood gateway instead, and carry no deposit. See the [dotNS PopRules and Pricing reference](/reference/apps/infrastructure/dotns/poprules-pricing/) for the bands and the deposit. ## Where to Go Next * **Build Your Product** *** Set up a local project, load it in Polkadot Desktop via the `localhost` bypass, and add capabilities guide by guide. [→ Set Up Your Project](/apps/build/#set-up-your-project) # Set Up Your AI Agent > Point your AI coding agent at the right skills, repos, and docs so it produces idiomatic Polkadot Product code instead of generic boilerplate. ## Introduction Many developers build Polkadot Products with an AI coding agent. Out of the box, an agent does not know that Products run inside a Host, that chain access routes through the SDK rather than a direct RPC, or where the skills and repos live — so it falls back on generic patterns that do not work here. A few minutes of setup points the agent at the right context and tilts it toward correct, idiomatic code. This page gives you a paste-ready setup prompt, then the resources to wire in: the skills, the repos, and the machine-readable docs. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Build with Claude Code](/apps/get-started/developers/#build-with-claude-code). ## The Setup Prompt Paste this at the start of a session to orient your agent. It states the toolchain, the repos, the docs, and the rules that most often trip agents up: ```text You are helping me build a Polkadot Product: a sandboxed web app (HTML/JS/CSS) that runs inside a Polkadot Host (Polkadot Desktop, the Polkadot App, or Polkadot Web) and is addressed by a .dot name. Toolchain: - Build app code with @parity/product-sdk (TypeScript). Install its skills first. - Deploy with the playground CLI (`pg` / `playground`). - For smart contracts, use the Contract Dependency Manager (`cdm`); contracts compile to PolkaVM on pallet-revive (Asset Hub). Author them in Rust or Solidity (Solidity via resolc, Foundry, or Hardhat). Do not target mainnet-EVM/Ethereum tooling or legacy ink!/Wasm. Docs (read before answering; append `.md` to any page URL for raw markdown): - Guides: https://developers.polkadot.com/apps/ - Full corpus: https://developers.polkadot.com/ai/llms-full.jsonl - Index: https://developers.polkadot.com/llms.txt - SDK API reference: https://paritytech.github.io/product-sdk/ Repos: - https://github.com/paritytech/product-sdk (SDK packages + skills) - https://github.com/paritytech/playground-cli (the deploy CLI) - https://github.com/paritytech/contract-dependency-manager (contracts) Rules to follow: - All chain reads, signing, and storage route through the Host via @parity/product-sdk. Never open a direct WebSocket/RPC connection or dial a public IPFS gateway. - Sign with a product account: getProductAccount(...).getSigner(). Approvals happen on the user's phone. On Paseo Next v2, do not use Polkadot.js-style signing (the AsPgas signed extension breaks it) — use the product-account signer. - Most fallible SDK calls return a Result; check `.ok` before reading `.value`. Two exceptions: a contract read, `contract.method.query()`, returns `{ success, value }`, so check `.success`; and the `createApp` facade is not Result-typed except for `app.cloudStorage` — `app.wallet` and `app.chain` throw, and `app.localStorage` returns plain values. Prefer the individual packages (`signer`, `chain-client`, `local-storage`), which are Result-typed throughout. - From `@parity/product-sdk` v0.30.0, call `createApp()` with no `name`: the Host's product ID supplies the identity, and a `name` is ignored with a warning. If the Host declines to derive an account, `wallet.connect()` resolves with zero accounts rather than erroring, so always check `accounts.length`. - Storage: put files/blobs on the Bulletin Chain (content-addressed by CID, retained ~2 weeks, renewable). Keep bulk data OUT of contracts; store only small enforced state on-chain. Service allowances are granted per account. - Prefer the SDK packages and the installed skills over generic JavaScript. If you are unsure how a surface works, read the docs page or the package README rather than guessing. ``` Trim the sections your project does not need. If you scaffolded from a template, much of this is already encoded in the project's agent files (see below). ## Install the Skills The [Product SDK skills](/reference/apps/skills/) are modular instruction sets that teach an agent how to work across the Products stack (chain connections, storage, contracts, and more). They tilt the agent toward idiomatic answers instead of generic boilerplate. In Claude Code, add the Parity marketplace and install the plugin: ```text /plugin marketplace add paritytech/product-sdk /plugin install product-sdk@paritytech ``` For other agents (Cursor, Codex, Cline, Windsurf, or a custom harness), clone `paritytech/product-sdk` and register the skills under `product-sdk/skills/` with your agent's context mechanism. The [Skills reference](/reference/apps/skills/) covers the full list, how to register them, and how to keep them current. Keep skills current Product surfaces are in active development. A stale skill teaches stale API patterns, which is worse than no skill. Refresh after major releases. ## Start From a Template The official Playground starter template ships agent-instruction files, so an agent picks up the conventions automatically: * `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex and other `AGENTS.md`-aware tools. * `.clinerules`, `.windsurfrules`, and `.github/copilot-instructions.md` for Cline, Windsurf, and GitHub Copilot. Coverage varies by app: a moddable app you clone with `pg mod` may ship all of these, only `CLAUDE.md`, or none, so check the project. If it includes a `setup.sh`, `pg mod` runs it for you to install dependencies and fetch the latest skills; many apps do not ship one. ## Give Your Agent the Docs This documentation publishes machine-readable versions for AI tools: * **`/llms.txt`**: An index of the documentation, following the [llms.txt convention](https://llmstxt.org/). * **`/ai/llms-full.jsonl`**: Every page, pre-chunked by section, one JSON object per line. * **Per-page markdown**: Append `.md` to any page path (for example, `/apps/quick-start.md`) to get its raw markdown, or use the **Markdown for LLMs** button on any page to copy it or hand the URL to your agent. The [AI Resources](/ai-resources/) page collects these downloads. ## Where to Go Next * **Quick Start** *** With your agent set up, deploy your first Product from the terminal or the browser. [→ Quick Start](/apps/quick-start/) * **Build Guides** *** The capability recipes your agent will lean on, one per SDK package. [→ Open Build Guides](/apps/build/) * **Skills Reference** *** The full skills list, how to register them, and how to keep them current. [→ Skills](/reference/apps/skills/) # List Your App > List your published Polkadot Product in the Playground directory with the playground CLI, and understand how the Browse catalogue works. ## Introduction Deploying makes your Product reachable at its dotNS address. Listing makes it *discoverable*: it puts your Product in a directory that users browse inside their Host, so people who have never heard your `.dot` name can still find and open it. There are two discovery surfaces: * **The Playground directory** (`playground.dot`): The directory the [`playground` CLI](/apps/quick-start/) publishes to on the TestNet it targets. This is the path you use when you deploy with `playground deploy`. * **[Browse](/reference/glossary/#browse)**: Polkadot's native discovery catalogue, surfaced in the App and Desktop dashboards. It is the broader destination for a Product that is ready for end users. Both are catalogues of published Products surfaced inside the Hosts, and both store a minimal on-chain record while pulling display details from your name's [dotNS](/reference/apps/infrastructure/dotns/) metadata. They differ in the tooling that publishes to them, covered below. TestNet names end in `.paseo`, not `.dot` dotNS top-level domains are per network. On Paseo Next v2, the TestNet the Apps tooling targets by default, names are minted under `.paseo`: publish `myproject57` and you get `myproject57.paseo`, served at `https://myproject57.paseo.li`. Whether you supply the bare label or the full name depends on the tool; see [Choose a Name](/apps/register-dot-domain/#choose-a-name). Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [App discovery: Browse](/apps/architecture/discovery/). ## The Playground Directory The Playground directory lives at `playground.dot`, which you open in the Polkadot Desktop browser. It is scoped to the TestNet the `playground` CLI targets, so treat a listing there as a way to share work in progress rather than as a launch surface; [Browse](#browse) is where a Product goes when it is ready for end users. Listed Products appear under their dotNS name, and your Product's `README.md` becomes its detail page in the directory, so make sure it is up to date before you publish. ### List During Deploy Listing is a choice you make during `playground deploy`. At the `publish to the playground?` prompt, choose **yes**: ``` publish to the playground? › yes · list it in the public playground no · deploy to my .paseo address only ``` Choosing **no** still deploys your Product to its dotNS address; it stays unlisted. To skip the prompt, pass the `--playground` flag: ```bash playground deploy --domain my-product --playground ``` With the phone signer, publishing adds one more approval in the Polkadot App, for writing the listing to the Playground registry. ### Categorize the Listing Pass `--tag` to file your Product under a category, which drives the tag filter in the playground app. Omit the flag and the CLI prompts you: ```bash playground deploy --domain my-product --playground --tag gaming ``` An app carries at most one tag, and the accepted values are a fixed list: `site`, `social`, `chat`, `utility`, `gaming`, `marketplace`, and `irl`. There is no free-form tag, because a value outside this list still renders on your app's card but has no filter pill, making it effectively unfilterable. ### Keep a Listing Private Pass `--private` (alongside `--playground`) to publish with owner-only visibility. The listing exists but only you see it, which is useful for staging a Product in the directory before you announce it. Unlike the other listing choices, this one is never prompted for — you have to pass the flag: ```bash playground deploy --domain my-product --playground --private ``` ### Let Others Fork Your Product Pass `--moddable` (alongside `--playground`) to mark your Product as one others can clone, customize, and redeploy as their own. A moddable listing records your public repository as its source: ```bash playground deploy --domain my-product --playground --moddable ``` The CLI reads your existing `origin` remote and records its URL in the Bulletin metadata. It never creates a repo or pushes for you, so set that up first. The deploy fails with an actionable message if `origin` is unset, points at a private repo, or points anywhere other than GitHub, because `pg mod` fetches source only from `codeload.github.com`: ```bash git remote add origin https://github.com// git push -u origin main ``` Anyone can then clone a moddable Product with `pg mod`: ```bash pg mod my-product ``` `pg mod` copies a moddable Product from the Playground registry into a local project you can edit and redeploy under your own name. Omit the domain to open a picker showing every moddable Product. See the [Quick Start](/apps/quick-start/) for the full `pg mod` reference. ### Change or Remove a Listing The listing choice is made at deploy time through the `publish to the playground?` prompt (or `--playground`). Redeploying re-runs that choice, so deploy again with your preferred option to update the listing state. The `playground` CLI does not currently expose a separate unlist command. ## Browse [Browse](/reference/glossary/#browse) is Polkadot's native discovery catalogue: a curated directory surfaced inside the Host dashboards, and the destination for a Product once it is ready for end users. You saw its **Browse** section on the Polkadot Desktop dashboard after pairing. ### How a Browse Listing Works Browse enforces who can list, on chain, so the directory stays tied to real ownership and real people: * **Ownership**: You must own the dotNS name you are listing. * **Proof of Personhood**: The listing account needs [Proof of Personhood](/reference/apps/infrastructure/pop/), Lite or Full. Personhood is obtained in the Polkadot App on your device. * **Rate limits**: Listings are rate-limited per personhood tier over a rolling 24 hours — Lite accounts can publish one per day, Full accounts five per day. A listing itself stores only a minimal on-chain record: a hash of the label, the publisher's address, and a timestamp. The display name, description, and icon are not stored in the listing; they are read from your name's dotNS manifest when the directory renders, so keeping your manifest current keeps your Browse card current. ### Publishing to Browse Publishing into the on-chain Browse catalogue is separate from the `playground` CLI, which publishes to the Playground directory described above, not to Browse. Browse is run by the Polkadot Community Foundation (PCF), so report problems with it to PCF; see [Choose the Right Channel](/get-support/#choose-the-right-channel). PCF's `pad` deploy CLI no longer lists apps in Browse: its `--publish` and `--unpublish` flags were removed in October 2026. For the publish permission model, the personhood requirements, and the Browse contract details, see [App discovery: Browse](/apps/architecture/discovery/). Two toolchains, two directories These docs standardize on the `playground` CLI, whose listing path is the Playground directory. Browse is the Community Foundation's directory, with its own on-chain registry. The two are separate publish mechanisms that share the same idea: a discovery directory of published Products surfaced inside the Hosts. ## Where to Go Next * **Deploy Your App** *** The full deploy flow, where the `publish to the playground?` choice is made. [→ Deploy Your App](/apps/deploy-your-app/) * **Register a `.dot` Domain** *** A listing points at your `.dot` name, so register one first. [→ Register a `.dot` Domain](/apps/register-dot-domain/) * **Proof of Personhood** *** The personhood tiers a Browse listing checks, and how they gate names and features. [→ Reference](/reference/apps/infrastructure/pop/) # The Polkadot App > Documentation for the Polkadot Products Devnet, the Polkadot app, and the developer platform behind it. Documentation for the Polkadot app, the Polkadot Products Devnet it runs on, and the tools for building apps on it. ## Choose your path [Use the appInstall the Polkadot app, set up a devnet account and open your first app.](/apps/using-the-app/users/) [Build a ProductBuild a web app, give it a `.dot` domain and publish it on the Devnet.](/apps/get-started/developers/) ## Explore the platform [ArchitectureHow the app, DotNS, Bulletin, Asset Hub, People, CASH and messaging fit together.](/apps/architecture/) [GuidesStep by step: create an account, get CASH, register a `.dot` domain, publish an app.](/apps/using-the-app/) [ReferencePackages, network IDs, registries, addresses, source links and terms.](/apps/reference/) ## Popular guides * [Create an account & get funds](/apps/using-the-app/create-account/) * [Get & use CASH](/apps/using-the-app/get-and-use-cash/) * [Discover & open apps](/apps/using-the-app/discover-and-open-apps/) * [Build & publish an app](/apps/build/build-and-publish/) * [Register a `.dot` domain](/apps/build/register-a-dot-name/) * [Use platform services from the SDK](/apps/build/platform-services-sdk/) ## Devnet entry points [Web gatewaydev-dot.li](https://dev-dot.li) [Browse directorybrowse.dev-dot.li](https://browse.dev-dot.li) [Faucetfaucet.polkadot.io](https://faucet.polkadot.io) [On-chain docsdocs.dev-dot.li](https://docs.dev-dot.li) # Product SDK > Overview of the Product SDK, the TypeScript SDK for building Polkadot Products, including createApp, the package family, and links to the full API reference. ## Introduction The [Product SDK](https://github.com/paritytech/product-sdk) is the TypeScript SDK for building Polkadot Products. It gives your Product typed access to everything the platform provides: chain reads, transaction signing, decentralized storage, off-chain messaging, smart contracts, and identity, all routed through the Host your Product runs inside. The SDK never dials an RPC endpoint itself. Every sensitive operation (signing, chain access, storage) goes through the Host, which selects the network, holds the user's keys, and prompts for approval on the user's phone. Your Product calls a typed method; the Host mediates the rest. Fallible operations in the individual packages return a typed `Result` instead of throwing, so you check `.ok` before reading `.value`. That pattern runs through every capability package and is what each [Build guide](/apps/build/) teaches. The `createApp` facade below is thinner and does not follow it uniformly — see [What `createApp` Returns](#what-createapp-returns). Products Devnet Building on the PCF Products Devnet (`devnet` preset)? Its hosts need a pinned SDK version: see [Packages & tools](/apps/reference/packages/). ## Two Ways to Use the SDK The SDK ships as one umbrella package that re-exports most capabilities, plus individual per-capability packages you can install on their own: * **Umbrella package**: `npm install @parity/product-sdk`. One dependency that provides the `createApp` entry point and re-exports most capabilities through subpaths such as `@parity/product-sdk/cloud-storage`. Convenient when your Product uses several capabilities and bundle size is not a concern. A few packages, notably `statement-store`, are not re-exported and are always installed on their own. * **Individual packages**: `npm install @parity/product-sdk-chain-client @parity/product-sdk-signer` (and so on). Install only what you use to keep your bundle smaller and your dependencies explicit. The import specifiers differ between the two: the umbrella exposes subpaths like `@parity/product-sdk/cloud-storage`, while the standalone package is `@parity/product-sdk-cloud-storage`. Switching styles means updating your imports. The umbrella's subpaths are a fixed set: `address`, `chain`, `cloud-storage`, `contracts`, `core`, `crypto`, `host`, `identity`, `individuality`, `local-storage`, `react`, `renderer`, `testing`, and `wallet`. Two of those names do not match their leaf package — `@parity/product-sdk/chain` re-exports `chain-client`, and `@parity/product-sdk/wallet` re-exports `signer`, kept under the older name for compatibility. Note what is *not* there: `tx`, `keys`, `statement-store`, `terminal`, and `auth` have no umbrella subpath and are not re-exported from the root, so install those from their own packages even when you are otherwise on the umbrella. The root entry point does re-export the most common handful directly — `createApp`, `SignerManager`, `createChainClient`, `createLocalKvStore`, `CloudStorageClient`, `isInsideContainer`, and the `Result` trio (`ok`, `err`, `isErrorOf`). ## A Minimal Product `createApp` is the fastest way in. It wires the signer, local storage, chain client, and cloud storage behind one object — the signer is exposed as `app.wallet`, the facade's older name for it: ```typescript import { createApp } from '@parity/product-sdk'; async function start() { // Throws outside a host container; the Host supplies the Product's identity. const app = await createApp({ logLevel: 'info' }); // wallet.connect() throws rather than returning a Result. try { const { accounts } = await app.wallet.connect(); if (accounts.length === 0) { // Connected, but the Host did not derive an account for this Product. } else { console.log('Connected accounts:', accounts); } } catch (cause) { // The Host refused the connection. } // Per-Product storage, namespaced by the Host's product ID. No Result: a miss reads as null. await app.localStorage.set('lastVisit', new Date().toISOString()); const lastVisit = await app.localStorage.get('lastVisit'); // string | null console.log('Last visit:', lastVisit); return app; } ``` The Host supplies your Product's identity Since `@parity/product-sdk` v0.30.0, `createApp` takes no `name`. It reads the product ID the Host loaded your Product under, derives the user's account from that ID, and namespaces local storage under the ID minus its final domain suffix: `my-product.dot` becomes `my-product`, and local development IDs such as `localhost:3000` stay unchanged. A `name` you still pass is ignored and logged as a warning. Releases before v0.30.0 require `name` and use it for both the account and the storage namespace. `createApp` throws `HostUnavailableError` outside a host container. Inside one, if the Host declines to derive an account (for example, because the user is signed out), `wallet.connect()` resolves with *zero accounts* instead of failing, so the only symptom is an empty list. ### What `createApp` Returns An `App` exposing `wallet`, `localStorage`, `chain`, and `cloudStorage`, plus `getAppInfo`. The four do not share one error convention, so check which one you are calling before writing the guard: | Member | Convention | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `wallet` | **Throws.** `connect()` rethrows the signer's error as a plain `Error`, so the typed variant is lost — you cannot tell `HostUnavailableError` from a rejection. | | `localStorage` | **Neither.** `get` resolves to `string \| null`, `set` to `void`; a failed read is indistinguishable from a missing key. | | `chain` | **Throws.** `getClient` and `getRawClient` throw if the chain is not connected. | | `cloudStorage` | **Returns a `Result`.** `upload` and `fetch` resolve to `ok`/`err`, matching the rest of the SDK. Also `null` entirely when cloud storage is disabled via `cloudStorage: false`. | If you want the `Result` convention throughout, use the individual packages instead: [`signer`](/apps/product-sdk/signer/) in place of `app.wallet`, [`chain-client`](/apps/product-sdk/chain-client/) in place of `app.chain`, and [`local-storage`](/apps/product-sdk/local-storage/) in place of `app.localStorage`. That is the path every [Build guide](/apps/build/) takes. createApp requires a Host `createApp` must run inside a compatible Host ([Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/), the [Polkadot App](/reference/apps/hosts/polkadot-app/), or [Polkadot Web](/reference/apps/hosts/polkadot-web/)). Called outside one, it throws `HostUnavailableError`. For local development and tests, use the SDK's fake Host; see [Testing Without a Host](#testing-without-a-host). ## The Package Family Each capability is its own package. The umbrella re-exports most of them; a few (such as `statement-store`) are always installed on their own. Each capability package below has its own overview page in this section covering what it is, when to use it, its core concepts, and typical journeys. The API reference links point to the generated reference for the complete surface. | Package | What it does | API reference | | :-----------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------: | | [Chain Client](/apps/product-sdk/chain-client/) (`chain-client`) | Typed, host-routed client for reading on-chain storage, constants, and account state across chains | [API](https://paritytech.github.io/product-sdk/api/chain-client/) | | [Signer](/apps/product-sdk/signer/) (`signer`) | Derives product-scoped accounts and requests signatures, routing every approval to the phone | [API](https://paritytech.github.io/product-sdk/api/signer/) | | [Transactions](/apps/product-sdk/tx/) (`tx`) | Builds, submits, and follows transactions through to finality | [API](https://paritytech.github.io/product-sdk/api/tx/) | | [Cloud Storage](/apps/product-sdk/cloud-storage/) (`cloud-storage`) | Uploads and retrieves content-addressed data by CID, backed by the Bulletin Chain | [API](https://paritytech.github.io/product-sdk/api/cloud-storage/) | | [Statement Store](/apps/product-sdk/statement-store/) (`statement-store`) | Publish/subscribe client for signed, short-lived statements gossiped off-chain | [API](https://paritytech.github.io/product-sdk/api/statement-store/) | | [Local Storage](/apps/product-sdk/local-storage/) (`local-storage`) | Per-Product, per-device key-value store backed by the Host | [API](https://paritytech.github.io/product-sdk/api/local-storage/) | | [Contracts](/apps/product-sdk/contracts/) (`contracts`) | Typed calls to `pallet-revive` (PolkaVM) contracts on Asset Hub, resolved from a `cdm.json` | [API](https://paritytech.github.io/product-sdk/api/contracts/) | | [Keys](/apps/product-sdk/keys/) (`keys`) | Derives application and session keys from the user's accounts | [API](https://paritytech.github.io/product-sdk/api/keys/) | | [Individuality](/apps/product-sdk/individuality/) (`individuality`) | Reads personhood standing and usernames on the Individuality chain, and dispatches under a person origin | [Source](https://github.com/paritytech/product-sdk/tree/main/product-sdk/packages/individuality) | | [Host](/apps/product-sdk/host/) (`host`) | Detects the Host container and exposes its lower-level API surface directly | [API](https://paritytech.github.io/product-sdk/api/host/) | ### Command-Line Packages Two packages are for tools you run *next to* a Product — a deploy script, a migration job, a CI step — rather than inside one. A Product runs in a Host that already owns pairing and signing, so it uses [Signer](/apps/product-sdk/signer/) instead. Both require Node 21 or later. | Package | What it does | API reference | | :--------------------------------------------------: | :-------------------------------------------------------------------------: | :-----------------------------------------------------------: | | [Terminal](/apps/product-sdk/terminal/) (`terminal`) | QR-code pairing, session signing, and allowance signers for a Node CLI | [API](https://paritytech.github.io/product-sdk/api/terminal/) | | [Auth](/apps/product-sdk/auth/) (`auth`) | The runtime-agnostic login, logout, and allocation flow built on `terminal` | [API](https://paritytech.github.io/product-sdk/api/auth/) | ### Supporting Packages Lower-level primitives the capability packages build on. Each has its own generated API reference: * **[`address`](https://paritytech.github.io/product-sdk/api/address/)**: Encodes, decodes, and converts SS58 and H160 addresses. * **[`crypto`](https://paritytech.github.io/product-sdk/api/crypto/)**: Encryption, hashing, and encoding primitives. * **[`utils`](https://paritytech.github.io/product-sdk/api/utils/)**: Byte encoding, 32-byte hashes (`blake2b256`, `sha256`, `keccak256`), planck token formatting, and typed balance queries. * **[`logger`](https://paritytech.github.io/product-sdk/api/logger/)**: Structured, namespace-filtered logging. * **[`errors`](https://paritytech.github.io/product-sdk/api/errors/)** and **[`result`](https://paritytech.github.io/product-sdk/api/result/)**: The shared `SdkError` marker and the generic `Result` type the whole SDK returns. * **`descriptors`**: Typed chain metadata consumed by the chain client. Imported per chain (for example, `@parity/product-sdk-descriptors/paseo-asset-hub`). `result` breaks the package-name pattern Every other package installs as `@parity/product-sdk-`, but the result type ships as `@parity/result`, with no `product-sdk-` prefix. Most Products never install it directly, since the capability packages re-export `Result`, `ok`, and `err`; if you do need it standalone, use the unprefixed name. The full surface, every package, class, and method, is documented in the [Product SDK API reference](https://paritytech.github.io/product-sdk/). ## Capabilities That Live on the Host A few things the platform offers are reached through the [`host`](/apps/product-sdk/host/) package rather than a dedicated capability package, so there is no focused API to learn yet: * **Payments**: `getPaymentManager()` — request a payment, top up, and track status. * **Chat**: `getChatManager()` — rooms, bots, and interactive action buttons. * **Notifications**: `getNotificationManager()` — push notifications to the user's phone. * **Navigation**: `navigateTo()` — deep links between Products. These are Host getters that return `null` outside a container, and their surfaces are still settling. Treat them as lower-level than the rest of the SDK, and check the [`host` API reference](https://paritytech.github.io/product-sdk/api/host/) for the current shape before building on them. ## React Bindings The umbrella exposes a React entry point at `@parity/product-sdk/react`. Wrap your app in `ProductSDKProvider`, then reach the SDK from any component through hooks: * **`useProductSDK`**: The `App` instance and connection state. * **`useWallet`**: The connected account and signing helpers. * **`useLocalStorage`**: Reactive per-Product key-value storage. * **`useChain`**: The host-routed chain client. The [Shared Todo App tutorial](/apps/tutorials/shared-todo-app/) uses these bindings end to end. ## Testing Without a Host Because `createApp` and the host-only methods require a Host, the SDK ships fakes so *automated tests* can exercise Product logic in plain Node or a browser test runner. These are a test tool, not a development environment: to *develop* against a real Host, run your Product from `localhost` inside Polkadot Desktop, per [Set Up Your Project](/apps/build/#set-up-your-project). `@parity/product-sdk/testing` exports `createFakeApp`, which returns a fake `App` you can use directly in a logic test or hand to `ProductSDKContext.Provider` for a React component test: ```typescript import { createFakeApp } from '@parity/product-sdk/testing'; // Synchronous, unlike the real createApp, which returns a Promise. const app = createFakeApp({ wallet: { accounts: [alice, bob], selected: alice } }); await app.wallet.connect(); ``` It fakes `wallet`, `localStorage`, and `cloudStorage`. Each is overridable through the options, along with `name`. There is no chain fake, and `app.chain` throws `createFakeApp` leaves `chain` unconfigured, so `getClient` and `getRawClient` throw — deliberately, because the Host owns RPC selection and a fake would not exercise the real wiring. The SDK's own guidance is to put chain-reading logic behind an interface you control, unit-test against that, and cover the wiring in end-to-end tests. Pass a `chain` override to `createFakeApp` if you would rather supply your own double. This matters most for [Read On-Chain Data](/apps/build/read-chain-state/), the first Build recipe, which is entirely chain reads. The subpath also re-exports the per-package fakes for [`signer`](/apps/product-sdk/signer/), [`local-storage`](/apps/product-sdk/local-storage/), [`contracts`](/apps/product-sdk/contracts/), and [`host`](/apps/product-sdk/host/) — `createFakeSignerProvider`, `createFakeHostLocalStorage`, and the rest — so one import covers them. Statement store fakes are imported separately They are deliberately not re-exported here, for the same reason `statement-store` has no umbrella subpath: adding it would pull in a dependency the umbrella does not otherwise have, and could pin a different version than the one your Product installs. Import them from `@parity/product-sdk-statement-store/testing` instead. Individual packages also expose a dev path where it makes sense; for example, `SignerManager.connect('dev')` loads the standard Substrate dev accounts. See [Sign and Submit Transactions](/apps/build/sign-and-submit/#test-without-a-host). ## Requirements * **Node.js**: version 20 or later — **except [`terminal`](/apps/product-sdk/terminal/) and [`auth`](/apps/product-sdk/auth/), which need 21 or later.** Those two open a WebSocket through the global `WebSocket` that Node 21 was the first to expose; on Node 18 or 20 they fail at connect time with `WebSocket is not defined`, not at install time. * **Module format**: ESM only. The SDK does not ship CommonJS builds. * **TypeScript**: version 5.0 or later, if you consume the types. * **Runtime Host**: The umbrella package and host-only methods require a compatible Host at runtime. Use the SDK's testing fakes in automated tests. ## Where to Go Next * **Build Guides** *** Task-focused recipes, one per capability, that take you from an empty project to working Product code. [→ Open Build Guides](/apps/build/) * **Product SDK API Reference** *** The complete SDK surface: installation, quickstart, testing, and per-package API docs for every class and method. [→ Visit Site](https://paritytech.github.io/product-sdk/) * **App Development Reference** *** How the Product, SDK, Host, and on-chain infrastructure fit together. [→ Reference](/reference/apps/) # Auth > Overview of the Product SDK auth package — the runtime-agnostic sign-in, session-signing, and resource-allocation flow behind a Polkadot product CLI. ## Introduction [`@parity/product-sdk-auth`](https://paritytech.github.io/product-sdk/api/auth/) is the sign-in flow for a Polkadot product CLI, with no interface attached. It wraps QR pairing, session discovery, session signing, resource allocation, and sign-out behind one object, `AuthClient`, and leaves every rendering decision to you. It sits one level above [Terminal](/apps/product-sdk/terminal/): where that package gives you an adapter and the primitives, this one composes them into the login, logout, and allowance steps a CLI actually performs, parameterized by an `AuthConfig` so the same code serves any product. Terminal-rendering helpers live behind a separate `./ui` entry point, so a headless consumer never pulls them in. Not for Products Like [Terminal](/apps/product-sdk/terminal/), this is CLI infrastructure. A Product runs inside a Host that already owns pairing and signing, so it uses [Signer](/apps/product-sdk/signer/) instead. ## When to Use It * To build the login and logout flows of a command-line tool that signs as the user's Polkadot App account. * To resolve a signer from mixed sources — a paired phone session, a dev `--suri`, or a named dev account — behind one call (`resolveSigner`). * To request the resource allowances a fresh session needs before it can sign anything (`requestResourceAllocation`). * When you want the flow without the terminal rendering: import from the package root and supply your own interface. * Not inside a Product, and not when [Terminal](/apps/product-sdk/terminal/)'s lower-level primitives are all you need. ## Core Concepts * **`createAuthClient(config)`**: Builds a client bound to one product's `AuthConfig`. Every adapter, derivation, and storage path reads from that config, which is what makes the package product-agnostic. * **`AuthConfig`**: Four fields. `dappId` scopes the on-disk session namespace (`~/.polkadot-apps/{dappId}_*`) and the pairing, so each product gets an independently revocable session; `productId` and `derivationIndex` derive the product account; `peopleEndpoints` are the RPC endpoints the adapter connects to. * **`connect()` returns one of two shapes**: `{ kind: 'existing' }` when a session is already on disk, or `{ kind: 'qr', qrCode, login }` when the user has to scan. Print the QR *before* mounting any interface, then await `waitForLogin(handle, onStatus)`. * **Three addresses, one key**: `SessionAddresses` carries `rootAddress` (the wallet root, the right input for `lookupUsername` in [Individuality](/apps/product-sdk/individuality/)), `productAddress` (the product account that actually signs), and `productH160` (the same product key as an EVM address). The last two are the same public key in two encodings. * **`SessionHandle.destroy()` is mandatory**: The signer depends on a long-lived adapter whose WebSocket keeps the Node event loop alive. Not calling `destroy()` means your CLI hangs on exit. * **Allocation before signing**: A freshly paired session cannot sign until the user grants resource allowances. `requestAllocation` requests `DEFAULT_RESOURCES` through the client's own `productId`, and `summarizeOutcomes` sorts the results into `granted`, `rejected`, and `unavailable` buckets by pairing each outcome with the resource at the same index. ## Log In and Sign Build the client, branch on whether a session already exists, then get a signer: ```typescript import { createAuthClient } from '@parity/product-sdk-auth'; const auth = createAuthClient({ dappId: 'my-cli', productId: 'my-cli.dot', derivationIndex: 0, peopleEndpoints: ['wss://paseo-people-next-system-rpc.polkadot.io'], }); const connection = await auth.connect(); if (connection.kind === 'qr') { console.log(connection.qrCode); // print before any interface mounts await auth.waitForLogin(connection.login, (status) => { if (status.step === 'pending') console.log(status.stage); }); } const session = await auth.getSessionSigner(); if (session) { try { console.log('signing as', session.addresses.productAddress); // Use session.signer with submitAndWatch, a contract .tx(), or any PAPI call. } finally { session.destroy(); // required — releases the WebSocket } } ``` ## Request Allowances A fresh session needs allowances before its first signature. Request them once and report what the user actually granted: ```typescript import { summarizeOutcomes, DEFAULT_RESOURCES } from '@parity/product-sdk-auth'; // The client binds `productId` from your AuthConfig, so it is not passed here. const outcomes = await auth.requestAllocation(session.userSession, DEFAULT_RESOURCES); const { granted, rejected, unavailable } = summarizeOutcomes(outcomes, DEFAULT_RESOURCES); if (rejected.length || unavailable.length) { console.warn( 'not granted:', [...rejected, ...unavailable].map((resource) => resource.tag).join(', '), ); } ``` `DEFAULT_RESOURCES` covers what a CLI product account normally needs: `BulletInAllowance`, `StatementStoreAllowance`, and `SmartContractAllowance` for derivation index `0`. `summarizeOutcomes` buckets the results into `granted`, `rejected`, and `unavailable` — it is order-sensitive, so pass the same resource array you requested. Treat anything other than granted as a capability being unavailable rather than a fatal error, so a declined grant degrades gracefully. See [Allowances and Permissions](/apps/concepts/allowances/) for what each resource authorizes. These outcomes are tagged objects, not strings An allocation outcome here is `{ tag: 'Allocated' | 'Rejected' | 'NotAvailable', ... }`, so compare `outcome.tag`, not `outcome`. The same concept in [`host`](/apps/product-sdk/host/) is a bare string union, and a comparison written for one silently never matches on the other. The standalone `requestResourceAllocation(session, productId, resources?, onExisting?)` is there when you are not holding an `AuthClient`. It throws on transport failures; per-resource refusals come back as outcomes rather than exceptions. ## Resolve a Signer From Mixed Sources A CLI usually accepts several ways to sign: the paired phone in normal use, a dev key in CI. `resolveSigner` collapses that into one call: ```typescript import { resolveSigner, SignerNotAvailableError } from '@parity/product-sdk-auth'; let resolved; try { // A `--suri` wins; otherwise the paired session is used. resolved = await resolveSigner(auth, { suri: process.env.DEPLOY_SURI }); } catch (error) { if (error instanceof SignerNotAvailableError) { console.error('No signer: pass --suri or log in first.'); } throw error; } try { console.log(`signing as ${resolved.address} (${resolved.source})`); // Pass resolved.signer to submitAndWatch, a contract .tx(), or any PAPI call. } finally { resolved.destroy(); // tears down the session adapter; a no-op for dev signers } ``` `resolveSigner` takes the client first, then the options, and returns a `ResolvedSigner`: the `signer` itself plus `address`, `source` (`'dev'` or `'session'`), and a `destroy()` to call in a `finally` block. For a mobile session it also carries `userSession` and the `addresses` triple; both are absent for a dev signer. `parseDevAccountName` turns a name such as `//Alice` into the corresponding well-known dev account, for the CI path. ## Limitations * Node only, like [Terminal](/apps/product-sdk/terminal/), and subject to the same Node 21 requirement through it. * Failures are thrown, not returned on a `Result` channel. `resolveSigner` raises `SignerNotAvailableError`; other steps surface their own errors. * `SessionHandle.destroy()` must be called or the process will not exit. * `AuthConfig` has no defaults — `dappId`, `productId`, `derivationIndex`, and `peopleEndpoints` are all required, because the values are per product and per network. * Sessions are keyed by `dappId` on disk, so two products never share a session and signing out of one leaves the other paired. ## Where to Go Next * **Terminal** *** The layer below: the adapter, QR rendering, and allowance signers this package composes. [→ Terminal](/apps/product-sdk/terminal/) * **Allowances and Permissions** *** What each resource allowance authorizes, its scope and lifetime, and how re-approval works. [→ Allowances](/apps/concepts/allowances/) * **API Reference** *** The complete `auth` surface: `AuthClient`, session signers, allocation helpers, and the `/ui` subpath. [→ Visit Site](https://paritytech.github.io/product-sdk/api/auth/) # Chain Client > Overview of the Product SDK chain-client package — a typed, host-routed Polkadot API client for reading chain state and building extrinsics. ## Introduction [`@parity/product-sdk-chain-client`](https://paritytech.github.io/product-sdk/api/chain-client/) is the connection layer of the Product SDK. It gives your Product a typed [PAPI](https://papi.how) client for reading state and building extrinsics across the Polkadot ecosystem chains a Product uses (Asset Hub, the Bulletin Chain, and Individuality), and it routes every connection through the Host rather than opening a WebSocket itself. Because the Host owns the connection, your Product never picks an RPC endpoint or manages reconnection. You ask for a chain by name or by descriptor, and the client hands back a fully typed API. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Connect to the chains](/apps/build/platform-services-sdk/#connect-to-the-chains). ## When to Use It * Whenever your Product needs to read on-chain storage, constants, or account state, or to build a transaction to submit later. * Use `getChainAPI` for the zero-config path: pass an environment name and get the preset chains back with no descriptor imports. * Use `createChainClient` when you want to bring your own descriptors: a custom chain, a pre-release runtime, or only a subset of chains. * Do not reach for it to submit or sign; pair it with [Signer](/apps/product-sdk/signer/) and [Transactions](/apps/product-sdk/tx/) for that. There is no direct-WebSocket fallback, so it requires a Host. ## Core Concepts * **`getChainAPI(env)`**: The zero-config factory. Pass `'paseo'` (or `'devnet'` for Products Devnet, operated by the Polkadot Community Foundation) and it lazy-loads the descriptors and returns a client with fixed `assetHub`, `bulletin`, and `individuality` keys. * **`createChainClient(config)`**: The bring-your-own-descriptors factory. You pass a `chains` map of names to descriptors, and each becomes a typed API on the returned client. * **`ChainClient`**: The returned object. Each configured key is a typed PAPI `TypedApi`; `.raw` exposes the underlying `PolkadotClient` per chain for advanced use; and `.destroy()` tears down the connections. * **Connection caching**: Clients are cached by a genesis-hash fingerprint of their chain set. Two calls with the same descriptors share one instance, so you do not accumulate duplicate connections. * **Graceful degradation**: A chain the Host cannot serve does not break the whole client. The supported chains stay usable, and any access to the unsupported one throws a `ChainNotSupportedError` instead of hanging. ## Read Chain State With a Preset The fastest path is `getChainAPI`. Connect to Paseo and read an account and a constant, then release the connection: ```typescript import { getChainAPI } from '@parity/product-sdk-chain-client'; const client = await getChainAPI('paseo'); const account = await client.assetHub.query.System.Account.getValue(address); const byteFee = await client.bulletin.query.TransactionStorage.ByteFee.getValue(); client.destroy(); ``` ## Bring Your Own Descriptor When you need a specific chain or a smaller client, pass descriptors directly. `isConnected` is a synchronous, side-effect-free check: ```typescript import { createChainClient, isConnected, } from '@parity/product-sdk-chain-client'; import { paseo_asset_hub } from '@parity/product-sdk-descriptors/paseo-asset-hub'; const client = await createChainClient({ chains: { assetHub: paseo_asset_hub } }); const blockNumber = await client.assetHub.query.System.Number.getValue(); console.log(isConnected(paseo_asset_hub)); // true client.destroy(); ``` ## Limitations * The client is Host-only; it throws if no Host provider is available and there is no standalone fallback. * The `polkadot` and `kusama` environments are not live yet and throw when requested; use `paseo` or `devnet`. * Descriptors are per-environment. A `paseo` descriptor and a `devnet` descriptor have different genesis hashes and are not interchangeable. * Call `.destroy()` (or `destroyAll()`) to release cached connections when a client is no longer needed. ## Where to Go Next * **Read On-Chain Data** *** The task-focused recipe: set up the client and read balances and storage step by step. [→ Read On-Chain Data](/apps/build/read-chain-state/) * **Signer** *** Get an account and a signer to pair with the client when you need to submit, not just read. [→ Signer](/apps/product-sdk/signer/) * **API Reference** *** The complete `chain-client` surface: `getChainAPI`, `createChainClient`, and every type. [→ Visit Site](https://paritytech.github.io/product-sdk/api/chain-client/) # Cloud Storage > Overview of the Product SDK cloud-storage package — upload and retrieve content-addressed data by CID on the Polkadot Bulletin Chain. ## Introduction [`@parity/product-sdk-cloud-storage`](https://paritytech.github.io/product-sdk/api/cloud-storage/) stores content-addressed data on the [Bulletin Chain](/reference/apps/infrastructure/bulletin-chain/). You upload bytes and get back a CID; you fetch by CID from anywhere inside a Host. It handles chunking, DAG-PB manifests, and CID calculation for you, and adds network presets, container-only read helpers, and an authorization pre-flight. Reach for it when your Product needs content that outlives a session and is addressable by anyone who has the CID: profile photos, published posts, file uploads, or full snapshots of app state. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Storage & data](/apps/architecture/storage/). ## When to Use It * To store bytes or files on chain and receive a CID plus a block receipt (`store(data).send()`). * To fetch content by CID inside a Host, with automatic reassembly of chunked uploads (`fetchBytes`, `fetchJson`). * To check an account's storage quota before uploading, so a missing allowance becomes an actionable error rather than a bare on-chain rejection (`checkAuthorization`). * Reads are Host-only; there is no public gateway fallback. To confirm a CID landed on chain without fetching the bytes, use `verifyStored`. ## Core Concepts * **`CloudStorageClient`**: The main class. Create it with `CloudStorageClient.create({ environment, signer })`, then call `store`, `fetchBytes`, and `fetchJson`. * **Content addressing**: Uploads are identified by a CID (CIDv1) derived from their content, not by a path or key. The same bytes always produce the same CID. * **`store(data)` builder**: A fluent builder ending in `.send()`, which resolves with a `StoreResult`. Only `size` is always present; `cid`, `blockNumber`, and `extrinsicIndex` are optional. Large payloads are chunked automatically. * **Read helpers return a `Result`**: `fetchBytes` and `fetchJson` return a `Result` (check `.ok`); DAG-PB chunked content is reassembled for you unless you opt out. * **Authorization pre-flight**: `checkAuthorization` returns a `Result` wrapping an `AuthorizationStatus` with the remaining transactions, bytes, and expiration, and never throws. Uploading requires an [authorization](/apps/get-started/get-testnet-tokens/) on the account. * **`createLazySigner(getSigner)`**: A signer wrapper that resolves the underlying signer on each call, so you can build the client before an account is selected. ## Store and Fetch by CID Create a client with a lazy signer, upload bytes, and fetch them back by CID: ```typescript import { CloudStorageClient, createLazySigner, } from '@parity/product-sdk-cloud-storage'; const client = await CloudStorageClient.create({ environment: 'paseo', signer: createLazySigner(() => manager.getSigner()), }); const stored = await client.store(bytes).send(); if (!stored.cid) throw new Error('The store returned no CID.'); const cid = stored.cid.toString(); console.log(cid, stored.blockNumber, stored.size); const fetched = await client.fetchBytes(cid); if (fetched.ok) { console.log(new TextDecoder().decode(fetched.value)); } ``` ## Check the Quota Before Uploading Confirm the account is authorized and has room before you submit an upload: ```typescript import { checkAuthorization } from '@parity/product-sdk-cloud-storage'; const status = await checkAuthorization(api, address); if (!status.ok) { console.error(status.error.message); } else if (!status.value.authorized) { // The account has no storage authorization yet. } else if (status.value.remainingBytes < BigInt(bytes.length)) { // The upload exceeds the remaining quota. } ``` ## Limitations * Reads run inside a Host only; outside a container, `fetchBytes` returns a `CloudStorageHostUnavailableError`. * Uploading requires a signer and an on-chain storage authorization for the account. * `authorizeAccount` is additive and is deliberately not retried; verify the result with `checkAuthorization` before retrying yourself. * `verifyStored` needs a known block; it does not scan the whole chain. * A chunked upload (large files) returns no `blockNumber` or `extrinsicIndex`, so it cannot be renewed by position. [Renew it by content hash](/apps/build/store-data-on-chain/#renew-long-lived-data) instead: the manifest CID and every chunk CID, which you can read from `StoreResult.chunks.chunkCids` or from the manifest's links. ## Where to Go Next * **Store Data on Chain** *** The task-focused recipe: upload to the Bulletin Chain and fetch by CID, with chunking and authorization. [→ Store Data on Chain](/apps/build/store-data-on-chain/) * **Statement Store** *** Pair durable storage with real-time signaling: announce a fresh CID to other users as it changes. [→ Statement Store](/apps/product-sdk/statement-store/) * **API Reference** *** The complete `cloud-storage` surface: `CloudStorageClient`, CID helpers, and authorization. [→ Visit Site](https://paritytech.github.io/product-sdk/api/cloud-storage/) # Contracts > Overview of the Product SDK contracts package — typed query, transaction, and batch calls to pallet-revive contracts on Asset Hub via a cdm.json manifest. ## Introduction [`@parity/product-sdk-contracts`](https://paritytech.github.io/product-sdk/api/contracts/) gives your Product typed access to smart contracts deployed on Asset Hub. It calls `pallet-revive` (PolkaVM) contracts through the typed chain API, resolves each contract's address and ABI from a `cdm.json` manifest, and exposes reads, signed writes, and atomic batches on a typed handle. It is the frontend counterpart to deploying a contract: once a contract is deployed and registered, this package turns its manifest entry into a typed object you call by name. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Smart contracts](/apps/architecture/contracts/) or [Call smart contracts](/apps/build/platform-services-sdk/#call-smart-contracts). ## When to Use It * To call a contract deployed on Asset Hub: reads with `query`, signed writes with `tx`, or atomic multi-call batches with `prepare`. * When you have a `cdm.json` manifest (address and ABI per installed contract), which is the primary path via `ContractManager.fromClient`. * Not for deploying contracts; deployment is handled by the `cdm` toolchain, covered in [Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/). The target chain must expose the `Revive` pallet. ## Core Concepts * **`ContractManager`**: Resolves contracts from a `cdm.json` manifest. `fromClient(...)` is synchronous and uses the addresses snapshotted in the manifest; `getContract(name)` returns a typed handle and throws `ContractNotFoundError` if the name is not in the manifest. * **Contract handle**: Each ABI method exposes `query`, `tx`, and `prepare`. * **`query` returns a discriminated result**: A read is a dry run that returns `{ success, value, gasRequired }`. It does not throw on a revert, so branch on `.success` rather than using `try`/`catch`. * **`tx` returns a `Result`**: A signed write returns a `Result` (check `.ok`). Before signing, it dry-runs the call to size gas and fail fast on a revert. * **Account mapping**: `pallet-revive` requires each signing account to be mapped to its H160 address once. Call `ensureContractAccountMapped` at startup, or every `tx` on a fresh account fails with `AccountNotMapped`. * **Product-account signing**: Writes are signed by your Product-scoped account, so contract calls route to the user's phone for approval like any other transaction. ## Call a Contract Build a manager from the manifest and the chain client, map the account once, then read and write: ```typescript import { ContractManager, ensureContractAccountMapped, } from '@parity/product-sdk-contracts'; import { paseo_asset_hub } from '@parity/product-sdk-descriptors/paseo-asset-hub'; import cdmJson from './cdm.json'; const manager = ContractManager.fromClient( cdmJson, chain.raw.assetHub, paseo_asset_hub, { signerManager }, ); await ensureContractAccountMapped(manager.getRuntime(), account.address, signer); const counter = manager.getContract('@my-app/counter'); // Read: a dry run. Check .success, not .ok. const count = await counter.getCount.query(); if (count.success) console.log(count.value); // Write: signs through the Host. Check .ok. const result = await counter.increment.tx({ signer }); if (!result.ok) console.error(result.error.message); ``` ## Limitations * `query` never throws on a chain-side failure; it returns `{ success: false, value: }`, so branch on `.success`. * A fresh signing account fails every `tx` with `AccountNotMapped` until `ensureContractAccountMapped` runs once. * Passing both `gasLimit` and `storageDepositLimit` skips the dry-run, including the revert pre-check, so a reverting transaction is still submitted and its gas paid. * The `/codegen` and `/pvm` subpaths pull in Node-only modules; keep them out of browser bundles. ## Where to Go Next * **Add a Smart Contract to Your Product** *** The task-focused recipe: scaffold, deploy, and register a contract, then wire it into your frontend. [→ Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/) * **Transactions** *** The submission layer this package builds on for its signed writes and batches. [→ Transactions](/apps/product-sdk/tx/) * **API Reference** *** The complete `contracts` surface: `ContractManager`, contract handles, and the `pvm` subpath. [→ Visit Site](https://paritytech.github.io/product-sdk/api/contracts/) # Host > Overview of the Product SDK host package — detect the Polkadot Host container and reach its lower-level API for accounts, storage, payments, chat, and more. ## Introduction [`@parity/product-sdk-host`](https://paritytech.github.io/product-sdk/api/host/) detects the Polkadot Host container and exposes its full surface directly: accounts and signing, storage, permissions, payments, chat, notifications, navigation, entropy, the statement store, and chain providers. It is the foundation the other SDK packages build on, wrapping the Host protocol so higher-level packages can offer focused APIs. Most Products reach these capabilities through the higher-level packages rather than calling the Host directly. Use this package when you need a surface those packages do not wrap yet, or when you need to detect whether your Product is running inside a Host at all. ## When to Use It * To detect whether your Product is running inside a Host container (`isInsideContainer`, `isInsideContainerSync`) and branch behavior accordingly. * To reach a Host capability directly: accounts and signers, payments, chat, push notifications, deep-link navigation, or feature and chain probes. * To get a PAPI-compatible provider that routes chain traffic through the Host (`getHostProvider`), or the native statement store transport (`getStatementStore`). * Prefer the higher-level packages where they exist: [Signer](/apps/product-sdk/signer/) for signing, [Local Storage](/apps/product-sdk/local-storage/) for key-value storage, and [Chain Client](/apps/product-sdk/chain-client/) for connections. Outside a container, every getter resolves to `null`. ## Core Concepts * **Container detection**: `isInsideContainer()` is the async check; `isInsideContainerSync()` is a fast heuristic. Every Host getter returns `null` when not inside a container. * **Feature-detection getters**: `getAccountsProvider`, `getHostLocalStorage`, `getPaymentManager`, `getChatManager`, `getNotificationManager`, and more each return an adapter, or `null` if the Host is absent. * **Two error conventions**: Flat operations such as `requestPermission` and `navigateTo` return a `Result` (check `.ok`). Adapter methods keep throwing, because they implement external interfaces such as PAPI's provider that cannot carry a `Result`. * **Accounts surface**: `getAccountsProvider()` exposes product accounts (app-scoped keypairs the Host derives per Product) and legacy accounts (the user's existing wallet keys), plus signer factories for each. * **Chain support probes**: `getHostProvider(genesisHash)` throws a `ChainNotSupportedError` when the Host cannot serve a chain, rather than returning a provider that hangs. ## Detect the Container and Read Host Storage Check for a Host, then use its storage surface directly: ```typescript import { isInsideContainer, getHostLocalStorage, } from '@parity/product-sdk-host'; if (await isInsideContainer()) { const storage = await getHostLocalStorage(); if (storage) { await storage.writeString('theme', 'dark'); const theme = await storage.readString('theme'); // "" if missing } } ``` ## Get a Product Account and Signer Reach an app-scoped product account and build a signer for it: ```typescript import { getAccountsProvider } from '@parity/product-sdk-host'; const accounts = await getAccountsProvider(); if (accounts) { const account = await accounts .getProductAccount('my-product.dot', 0) .match((a) => a, () => null); if (account) { const signer = accounts.getProductAccountSigner(account); } } ``` ## Limitations * Every getter returns `null` outside a Host container; this package has no standalone fallback. * The package mixes two error conventions: flat operations return a `Result`, while adapter methods throw. Handle both. * `getHostProvider` throws `ChainNotSupportedError` when the Host cannot serve a chain, rather than returning a working provider. * Host storage returns an empty string for a missing key; normalize it yourself, or use the [Local Storage](/apps/product-sdk/local-storage/) package, which does. ## Where to Go Next * **App Development Reference** *** How the Host mediates between your Product and Polkadot's infrastructure. [→ Reference](/reference/apps/) * **Signer** *** The higher-level way to discover accounts and sign, built on this package. [→ Signer](/apps/product-sdk/signer/) * **API Reference** *** The complete `host` surface: container detection and every Host capability getter. [→ Visit Site](https://paritytech.github.io/product-sdk/api/host/) # Individuality > Overview of the Product SDK individuality package — read a person's personhood standing and usernames on the Individuality chain, and act under a person origin. ## Introduction [`@parity/product-sdk-individuality`](https://github.com/paritytech/product-sdk/tree/main/product-sdk/packages/individuality) reads a person's standing on the Individuality chain and lets your Product act as that person on it. It is the typed way to answer "is this a verified human, and how far along are they?" without learning who they are. The package has two halves. The *read* half works in both directions: given a `.dot` username or an account, what is that person's [Proof of Personhood](/reference/apps/infrastructure/pop/) state; and given an account, which usernames does it hold. The *write* half is a single function, `withAsPerson`, which wraps a signer so a transaction dispatches under a *person* origin instead of an account origin. Reads return a typed `Result`, so you check `.ok` before reading `.value`. A username nobody owns is not a failure: it arrives on the success channel as a `UsernameUnowned` result. Not an authorization oracle This is a client-side read in a client-side library. A backend that trusts "the SDK said `Member`" is trivially spoofed. Use it to shape your interface — show progress, gate a button, pick a label — but anything that gates real value must verify on chain itself. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Identity & personhood](/apps/architecture/identity/). ## When to Use It * To read a person's personhood state and progress metrics for display, from either a username or an account (`readPersonhoodState`). * To resolve which usernames an account holds, and which one to show (`lookupUsername`, `displayUsername`). * To dispatch a call under a person origin rather than an account origin (`withAsPerson`), for extrinsics the Individuality chain gates on personhood. * To read the periodic game and its prize draws, and to build the sign-up and claim calls around them. * Not to authorize anything server-side, and not to gate access to funds. See the warning above. ## Core Concepts * **Everything is pinned to one block**: A read batches several storage lookups and reports the `FinalizedSnapshot` (`blockHash`, `blockNumber`) they all came from. The personhood threshold and the absence-grace ratio update on a session cadence, so an unpinned read could mix eras and derive a state that never existed. * **`PersonhoodResult` versus `PersonhoodState`**: The outer result is `UsernameUnowned` or `Resolved`. Only `Resolved` carries an account, an optional contextual `alias`, the `state`, and `metrics`. * **Seven states, discriminated by `tag`**: `NotEnrolled`, `Lite`, `Candidate` (accruing score, carries `score` and `personhoodThreshold`), `MembershipReady`, `Member` (carries `activeWeeks`), `Caution` (the next absence would breach the grace policy), and `Suspended`. * **`metrics` is always present on a resolved read**: The same numbers the state was derived from, in every state, so a progress interface renders without branching on the tag first. * **`Caution.misses` is a projection**: It is what the absence window *would* hold after one more absence, not a count of past absences. A `window` of `0` means no grace at all and lands in `Caution` regardless. * **Lite and full usernames**: An account always has a lite username (`example.07`); a full one appears only once the person claims a bare name. `displayUsername` picks the right one, `usernameBase` extracts the letters a claim would offer, and `canClaimFullUsername` is the chain's own precondition, not an approximation. * **The derivation is exported separately**: `derivePersonhoodState` is pure. Feed it a snapshot you already hold and it needs no chain client and no Host. ## Read a Person's Standing Pass either a `username` or an `account`. Branch on `.ok`, then on the result `tag`: ```typescript import { getChainAPI } from '@parity/product-sdk-chain-client'; import { readPersonhoodState } from '@parity/product-sdk-individuality'; const chain = await getChainAPI('paseo'); const result = await readPersonhoodState(chain, { username: 'alice.dot' }); if (!result.ok) { console.error(result.error.message); // ProductIndividualityError } else if (result.value.tag === 'UsernameUnowned') { // Nobody owns this name — a success value, not an error. } else { const { state, metrics, at } = result.value; console.log(state.tag, 'as of block', at.blockNumber); if (state.tag === 'Candidate') { console.log(`${state.score} of ${state.personhoodThreshold}`); } else if (state.tag === 'Member') { console.log(`${state.activeWeeks} consecutive games`); } } ``` ## Resolve an Account's Username The other direction, from an account to the names it holds: ```typescript import { getChainAPI } from '@parity/product-sdk-chain-client'; import { canClaimFullUsername, displayUsername, lookupUsername, usernameBase, } from '@parity/product-sdk-individuality'; const chain = await getChainAPI('paseo'); const usernames = await lookupUsername(chain, { account: rootAddress }); if (usernames.ok && usernames.value !== null) { const record = usernames.value; console.log(displayUsername(record)); // full name if claimed, else the lite one if (canClaimFullUsername(record)) { console.log('could claim:', usernameBase(record.liteUsername)); } } ``` A `null` value means the account has no record at all, which is an answer rather than a failure. ## Act Under a Person Origin `withAsPerson` wraps a `PolkadotSigner` so the call dispatches as a person. It returns a signer, so submission stays with [Transactions](/apps/product-sdk/tx/): ```typescript import { submitAndWatch } from '@parity/product-sdk-tx'; import { withAsPerson } from '@parity/product-sdk-individuality'; const personSigner = withAsPerson(accounts.getProductAccountSigner(account), { tag: 'AliasWithAccount', }); const result = await submitAndWatch(someGatedCall, personSigner); ``` The `AsPersonInfo` variants are `AliasWithAccount` (the signing account is already bound to the alias, no proof needed), `AliasWithProof` (authorized by a ring-VRF proof alone), and `AliasWithAccountRevised` (signs and moves the stored alias to the current ring revision, which is the fix when the chain answers `BadSigner`). AsPerson errors are thrown, not returned Unlike the rest of the package, `withAsPerson` raises `AsPersonError` rather than returning a `Result`. It has to: the failure happens inside `PolkadotSigner.signTx`, where there is no error channel to return on. Wrap the submission in `try`/`catch` as well as checking the `Result`. ## The Game and Prize Draws The Individuality chain runs a periodic game, and the package covers it end to end: `readCurrentGame` for the current game and its phase, `readGameAirdropEventIds` and `readAirdropDraw` for its prize draws, `readPrizeStatus` for one identity's outcome across every draw at a single pinned block, `signUpWithAccountTx` to enter, and `readClaimEligibility` plus `claimPrizeTx` and `confirmClaim` to collect a prize. Two details shape how you use it: `claim_airdrop` has six gates and only two concern personhood, so eligibility is exported as a predicate (`deriveClaimEligibility`) separately from the read that feeds it; and `confirmClaim` re-reads whether a claim landed, which is how a claim flow survives a page reload, since a successful claim removes the `Winners` row. Only the account sign-up path is buildable today Of the two sign-up variants, only `Account` can be constructed. The `Alias` variant needs a ring-VRF proof at a context the chain chooses, and every context a Host will sign under is derived from the product id. The package's `signup-types.ts` records the current blockers. ## Limitations * Client-side only, and not a source of authorization. Verify on chain for anything that gates value. * Reads return a `Result` carrying `ProductIndividualityError`; `withAsPerson` throws `AsPersonError` instead. * `readPersonhoodState` pins one finalized block. Treat the state as a snapshot with an `at`, not a live value, and re-read rather than caching across sessions. * The `AliasWithProof` variant is rejected on the Individuality runtime Paseo runs today, however correct the bytes are. It becomes reachable after the network upgrades, with no change needed here. * A personhood tier is obtained in the [Polkadot App](/reference/apps/hosts/polkadot-app/); nothing in this package grants or raises one. ## Where to Go Next * **Identity** *** How a user's per-app account and Proof of Personhood stay separate, and why. [→ Identity](/apps/concepts/identity/) * **Proof of Personhood** *** The Ring-VRF mechanism, the tiers this package reads, and per-app aliases in depth. [→ Reference](/reference/apps/infrastructure/pop/) * **Package Source** *** The complete `individuality` surface: the state machine, the game and airdrop reads, and `withAsPerson`. [→ Visit Repo](https://github.com/paritytech/product-sdk/tree/main/product-sdk/packages/individuality) # Keys > Overview of the Product SDK keys package — derive app-scoped keys, session signers, and product-account addresses without touching the seed phrase. ## Introduction [`@parity/product-sdk-keys`](https://paritytech.github.io/product-sdk/api/keys/) derives application-scoped keys and accounts without ever touching the user's seed phrase. From a one-time user signature it can derive symmetric keys and keypairs your Product owns; it can generate and persist a session signer; and it can compute the address of a Host-derived product account from a public key alone. Reach for it when your Product needs its own keys — for encrypting local data, deriving an app-scoped account, or maintaining a burner signer that survives reloads — rather than the user's primary wallet accounts. ## When to Use It * To derive app-private encryption or signing keys deterministically from a one-time user signature (`KeyManager.fromSignature`), so the app scopes its own keys without asking for a mnemonic. * To keep a persistent session or burner signer that survives reloads by storing its mnemonic in a local store (`SessionKeyManager`). * To compute the public address of a Host-derived product account off-device, from a parent public key (`deriveProductAccountPublicKey`). * Not for signing real transactions with the user's wallet accounts; use the [Signer](/apps/product-sdk/signer/) package for that. This package manages app-derived and session keys. ## Core Concepts * **`KeyManager`**: Holds a master key in memory and derives child keys with HKDF. Create it with `KeyManager.fromSignature(signature, signerAddress)` or `KeyManager.fromRawKey(masterKey)`. It persists nothing; persistence is the consumer's responsibility. * **Derivation methods**: `deriveSymmetricKey(context)` returns a 32-byte key; `deriveAccount(context)` returns an sr25519 account; `deriveKeypairs()` returns encryption and signing keypairs. The same context always yields the same key, and different contexts are uncorrelated. * **`SessionKeyManager`**: Storage-backed. It generates a mnemonic, persists it in a `LocalKvStore`, and derives an account. `create`, `get`, `getOrCreate`, and `clear` manage its lifecycle. * **`DerivedAccount`**: The account shape returned throughout: `publicKey`, `ss58Address`, `h160Address`, and a ready-to-use `signer`. * **`deriveProductAccountPublicKey`**: Computes a product account's public key from a parent public key and a Product identifier, matching the derivation the Host performs privately, so an external client derives the same address. ## Keep a Persistent Session Key Back a session signer with the local store so it survives reloads: ```typescript import { SessionKeyManager } from '@parity/product-sdk-keys'; import { createLocalKvStore } from '@parity/product-sdk-local-storage'; const store = await createLocalKvStore(); const sessionKeys = new SessionKeyManager({ store }); const session = await sessionKeys.getOrCreate(); console.log(session.account.ss58Address); ``` ## Derive App-Scoped Keys From a Signature Turn a one-time user signature into keys the app owns, scoped by context: ```typescript import { KeyManager } from '@parity/product-sdk-keys'; const keys = KeyManager.fromSignature(signatureBytes, signerAddress); const docKey = keys.deriveSymmetricKey('doc:123'); // 32-byte symmetric key const docAccount = keys.deriveAccount('doc-account:123'); // sr25519 account const { encryption, signing } = keys.deriveKeypairs(); ``` ## Limitations * `KeyManager` holds the master key in memory and persists nothing; use `exportKey` and `fromRawKey` to manage persistence yourself. * `fromSignature` requires at least 32 bytes of signature material, and `fromRawKey` requires exactly 32 bytes; both throw otherwise. * A session key's mnemonic is stored in plaintext in the key-value store; it is the only thing persisted. * Invalid mnemonics throw; validate input before deriving. ## Where to Go Next * **Signer** *** For signing with the user's wallet accounts and deriving Host product accounts. [→ Signer](/apps/product-sdk/signer/) * **Local Storage** *** The store the session-key manager persists its mnemonic to. [→ Local Storage](/apps/product-sdk/local-storage/) * **API Reference** *** The complete `keys` surface: `KeyManager`, `SessionKeyManager`, and derivation helpers. [→ Visit Site](https://paritytech.github.io/product-sdk/api/keys/) # Local Storage > Overview of the Product SDK local-storage package — a per-Product, per-device key-value store backed by the Host, with namespacing and JSON helpers. ## Introduction [`@parity/product-sdk-local-storage`](https://paritytech.github.io/product-sdk/api/local-storage/) is an async key-value store backed by the Host container's storage. It gives your Product a small, per-device place to keep state — settings, drafts, cached identifiers — with optional key namespacing and typed JSON helpers, without touching raw browser `localStorage`. The store is scoped per Product, so keys never collide with other Products, and reads are error-tolerant: a missing or failed read resolves to `null` rather than throwing. ## When to Use It * To persist small app state inside a Host: preferences, drafts, cached values, or a session identifier. * To namespace keys per Product with a `prefix`, so `theme` becomes `my-product:theme` and stays isolated. * To hand a store to higher-level SDK pieces; for example, the session-key manager in [Keys](/apps/product-sdk/keys/) takes a store to persist its mnemonic. * Not a general-purpose browser shim: the store requires a Host and has no standalone browser fallback. For raw Host storage without the key-value convenience layer, use the [Host](/apps/product-sdk/host/) package directly. ## Core Concepts * **`createLocalKvStore(options)`**: The single factory. It is async because it detects the Host storage backend, and it returns a `LocalKvStore`. * **`LocalKvStore`**: The returned store. It exposes `get`, `set`, and `remove` for strings, plus `getJSON` and `setJSON` for typed JSON values. * **Namespacing**: Pass a `prefix` to isolate this Product's keys from everything else in the Host's storage. * **Error-tolerant reads**: `get` and `getJSON` return `null` for a missing key or a failed read; writes and removes log failures rather than throwing. Only the factory throws, when no Host is present. ## Persist and Read App State Create a namespaced store, then read and write both strings and JSON: ```typescript import { createLocalKvStore } from '@parity/product-sdk-local-storage'; const store = await createLocalKvStore({ prefix: 'my-product' }); await store.set('theme', 'dark'); const theme = await store.get('theme'); // string | null await store.setJSON('draft', { title: 'Untitled', body: '' }); const draft = await store.getJSON<{ title: string; body: string }>('draft'); await store.remove('draft'); ``` ## Limitations * `createLocalKvStore` throws if no Host storage is detected; the store is Host-only. * Write and remove failures are logged, not thrown, so a failed `set` looks like success to the caller. * Reads never throw: both errors and missing keys surface as `null`. ## Where to Go Next * **Persist Data Locally** *** The task-focused recipe: JSON helpers, prefixes, and React usage, step by step. [→ Persist Data Locally](/apps/build/persist-data-locally/) * **Keys** *** A common consumer of this store: the session-key manager persists its mnemonic here. [→ Keys](/apps/product-sdk/keys/) * **API Reference** *** The complete `local-storage` surface: `createLocalKvStore` and `LocalKvStore`. [→ Visit Site](https://paritytech.github.io/product-sdk/api/local-storage/) # Signer > Overview of the Product SDK signer package — discover accounts, select one, and obtain a signer, with every approval routed to the user's Polkadot App. ## Introduction [`@parity/product-sdk-signer`](https://paritytech.github.io/product-sdk/api/signer/) handles account discovery, selection, and signing, decoupled from where the keys actually live. Your Product talks to one class, `SignerManager`, and the same call sites work whether signing routes to the user's [Polkadot App](/reference/apps/hosts/polkadot-app/) in production or to local dev accounts in a test. Every fallible method returns a typed `Result`, so you check `.ok` before reading `.value` rather than wrapping calls in `try`/`catch`. Products Devnet Building on the PCF Products Devnet (`devnet` preset)? See [Sign transactions](/apps/build/platform-services-sdk/#sign-transactions). ## When to Use It * Whenever your Product needs to discover accounts, select one, and obtain a `PolkadotSigner` to sign transactions or raw bytes. * To manage the connection lifecycle: connect, disconnect, subscribe to state changes, and run once-per-session setup through the `onConnect` hook (for example, requesting permissions). * Use the host provider for real signing on [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/) and the Polkadot App; use the dev provider for tests with well-known accounts such as Alice and Bob. * The product-account and Ring-VRF methods are Host-only; they return `HostUnavailableError` under the dev provider. ## Core Concepts * **`SignerManager`**: The central class. It wraps one or more providers behind a `Result`-typed API and holds a `SignerState` that it pushes to subscribers. * **`Result`, `ok`, `err`**: The return idiom across the package. Branch on `res.ok`, then read `res.value` or `res.error`; only unexpected internal failures throw. * **`SignerAccount`**: A signing-capable account. It exposes the SS58 `address`, the EVM-derived `h160Address` (for `pallet-revive`), the `publicKey`, an optional `name`, and `getSigner()`. * **Host vs dev providers**: `connect()` defaults to the Host; `connect('dev')` loads well-known dev accounts locally, so no Host is needed for tests. * **`onConnect` and `subscribe`**: `subscribe` fires on every state change; `onConnect` fires exactly once per transition into the connected state (and again after an auto-reconnect), which is where you request resources up front. * **Product accounts**: `getProductAccount(dotNsIdentifier, derivationIndex)` returns a per-Product account the Host derives, so different Products get different addresses for the same user. This is a Host-only API. ## Connect and Sign Raw Bytes Construct the manager once, connect, select an account, and sign. Each step returns a `Result`: ```typescript import { SignerManager } from '@parity/product-sdk-signer'; async function signHello() { const manager = new SignerManager({ ss58Prefix: 0, dappName: 'my-product' }); const connectResult = await manager.connect(); if (!connectResult.ok) return; // HostUnavailableError outside a Host const [account] = connectResult.value; if (!account) return; // connected, but the Host returned no accounts manager.selectAccount(account.address); const signature = await manager.signRaw(new TextEncoder().encode('hello')); if (signature.ok) { console.log(signature.value); // Uint8Array } } ``` A successful connect can still yield zero accounts `connect()` resolves with `ok([])` — not an error — when `dappName` is unset or the Host rejects the derivation, typically because the `.dot` identifier is not registered for that user. Destructure and check before indexing, or `value[0].address` throws on a path the SDK documents as normal. A Product in that state can still drive the explicit signing paths, such as `getLegacyAccountSigner`. ## Request Permissions Once Per Session Use the `onConnect` hook to request resource allocations as soon as the connection is established, before any signing call. Unlike the rest of the package, `requestResourceAllocation` throws rather than returning a `Result`, so guard it: ```typescript import { SignerManager } from '@parity/product-sdk-signer'; const manager = new SignerManager({ ss58Prefix: 0, dappName: 'my-product', onConnect: async (_account, { requestResourceAllocation, signal }) => { try { const outcomes = await requestResourceAllocation([ { tag: 'BulletinAllowance', value: undefined }, ]); if (signal.aborted) return; // user disconnected mid-request if (outcomes.some((outcome) => outcome !== 'Allocated')) { // Degrade gracefully: treat the capability as unavailable, not fatal. } } catch (cause) { // Typed host error — the connection itself is unaffected. } }, }); ``` Three things that example is doing deliberately: * **`try`/`catch`**: `requestResourceAllocation` adapts the Host's `Result`-returning call into a throwing one, so an unguarded `await` can throw inside `onConnect`. Errors thrown here are logged and do not break the connected state, but you lose the chance to react. * **`signal.aborted`**: The `AbortSignal` fires if the user disconnects or the manager is destroyed while the request is still in flight. Check it before acting on the outcomes. * **Checking the outcomes**: Each is `'Allocated'`, `'Rejected'`, or `'NotAvailable'` — bare strings here, unlike the tagged objects the [`auth`](/apps/product-sdk/auth/) package returns. See [Allowances and Permissions](/apps/concepts/allowances/) for what each resource authorizes. Why not `AutoSigning` in this example `AutoSigning` is the most interesting resource to request and the one you cannot rely on: it returns `NotAvailable` on both the Android and iOS wallets today. Request it if you want, but treat per-transaction signing as the real path and do not build a flow that depends on the grant landing. ## Limitations * Most methods return a `Result`; branch on `.ok`. Only terminal conditions such as calling a destroyed manager surface as thrown errors. * `destroy()` is terminal: later calls return `DestroyedError`. Use `disconnect()` for a reversible reset. * `subscribe` does not prime with the current state; call `getState()` for the initial read, and use `onConnect` for once-per-connect logic. * `getProductAccount`, `getProductAccountAlias`, `createRingVRFProof`, and `getUserId` are Host-only. ## Where to Go Next * **Sign and Submit Transactions** *** The task-focused recipe: derive a product account, sign, and submit a transaction end to end. [→ Sign and Submit Transactions](/apps/build/sign-and-submit/) * **Transactions** *** Take the signer this package produces and submit and track a transaction to finality. [→ Transactions](/apps/product-sdk/tx/) * **API Reference** *** The complete `signer` surface: `SignerManager`, `SignerAccount`, providers, and the error hierarchy. [→ Visit Site](https://paritytech.github.io/product-sdk/api/signer/) # Statement Store > Overview of the Product SDK statement-store package — publish and subscribe to signed, short-lived statements gossiped off-chain for real-time state. ## Introduction [`@parity/product-sdk-statement-store`](https://paritytech.github.io/product-sdk/api/statement-store/) is a publish/subscribe client over the [Statement Store](/reference/apps/infrastructure/statement-store/): signed, short-lived messages gossiped between instances of your Product, off-chain and with no fee per message. On top of raw pub/sub it adds an optional last-write-wins channel abstraction for per-key shared state. Reach for it when your Product needs real-time state between users: presence, typing indicators, multiplayer cursors, or announcing where the latest snapshot of shared content lives. ## When to Use It * For ephemeral, signed, topic-routed messaging between app instances: presence, signaling, and transient state (`publish` / `subscribe`). * For last-write-wins per-key state where the newest value for a key wins (`ChannelStore`). * For tests without a Host or network, using the in-memory transport from the `/testing` subpath. * Not for durable storage or large payloads: statements expire (default 30 seconds) and are capped at 512 bytes. Pair it with [Cloud Storage](/apps/product-sdk/cloud-storage/) when you need to keep the content. ## Core Concepts * **`StatementStoreClient`**: The main class. Construct it with an `appName` (which becomes the primary topic), then `connect`, `publish`, and `subscribe`. * **`publish` returns a `Result`, `subscribe` returns a handle**: Check `.ok` on the `publish` result; `subscribe` returns an `Unsubscribable` you call to stop listening. * **Topics and channels**: A topic routes messages between instances of the same Product; a channel is a named key whose latest value wins. Both are hashed identifiers derived from the names you choose. * **`ChannelStore`**: A last-write-wins map over the client. `write(name, value)` publishes a value, `read` and `readAll` return the current values, and `onChange` notifies you of updates. * **Size and TTL limits**: Statements are capped at 512 bytes and carry a default 30-second TTL. `encodeData` throws if a payload exceeds the cap, so keep statements small and treat them as signaling, not storage. * **Connection modes**: `host` mode signs through the Host's sponsored path; `local` mode signs locally with a supplied key, mainly for tests. ## Publish and Subscribe Connect in host mode, subscribe to incoming statements, and publish one to a room topic: ```typescript import { StatementStoreClient } from '@parity/product-sdk-statement-store'; const client = new StatementStoreClient({ appName: 'my-product' }); await client.connect({ mode: 'host' }); const subscription = client.subscribe((statement) => { console.log(statement.data); }); const result = await client.publish( { type: 'presence', text: 'gm', timestamp: Date.now() }, { topic2: 'lobby' }, ); if (!result.ok) console.error(result.error.message); ``` ## Share Last-Write-Wins State `ChannelStore` keeps one live value per channel and reconciles updates by timestamp, so every participant converges on the newest value: ```typescript import { StatementStoreClient, ChannelStore, } from '@parity/product-sdk-statement-store'; const client = new StatementStoreClient({ appName: 'my-product' }); await client.connect({ mode: 'host' }); const channels = new ChannelStore(client); channels.onChange((name, value) => { console.log(name, value); }); await channels.write('presence', { status: 'online', timestamp: Date.now() }); ``` ## Limitations * Statements are hard-capped at 512 bytes; `encodeData` throws before submitting if you exceed it. * The default TTL is 30 seconds. Data is ephemeral, so late joiners see nothing until the next message. * The client is Host-only by default; `local` mode needs a signing key, or inject a custom transport for tests. * `publish` and `ChannelStore.write` return a `Result`, but `subscribe` and `onChange` return handles; malformed received statements are dropped silently. ## Where to Go Next * **Publish and Subscribe to Off-Chain Data** *** The task-focused recipe: topics, channels, TTLs, and allowances, step by step. [→ Publish and Subscribe to Off-Chain Data](/apps/build/pub-sub-off-chain-data/) * **Build a Shared Todo App** *** A full tutorial that composes the statement store with cloud storage and local persistence. [→ Build a Shared Todo App](/apps/tutorials/shared-todo-app/) * **API Reference** *** The complete `statement-store` surface: `StatementStoreClient`, `ChannelStore`, and topics. [→ Visit Site](https://paritytech.github.io/product-sdk/api/statement-store/) # Terminal > Overview of the Product SDK terminal package — QR-code login, allowance signers, and transaction signing for command-line tools paired with the Polkadot App. ## Introduction [`@parity/product-sdk-terminal`](https://paritytech.github.io/product-sdk/api/terminal/) brings the Polkadot App pairing flow to command-line tools. It prints a QR code, waits for the user to scan it with their phone, and hands back a `PolkadotSigner` that routes every signature to that phone, exactly as a Host does for a Product in a browser. This is the package the [`playground` CLI](/apps/quick-start/) is built on. `pg login` is `createTerminalAdapter` plus a QR render plus `authenticate()`; `pg deploy`'s Bulletin uploads are signed by `getBulletinSigner`. Not for Products A Polkadot Product runs inside a Host, which already owns the pairing and the signing route, so a Product uses [Signer](/apps/product-sdk/signer/) instead. Reach for this package when you are writing a Node CLI *alongside* your Product — a deploy script, a migration tool, a CI job that has to sign as you. ## When to Use It * To pair a Node CLI with the Polkadot App over a QR code and sign transactions as the paired account (`createTerminalAdapter`, `createSessionSigner`). * To write to the Bulletin Chain or publish to the Statement Store from a CLI, through an allowance slot the phone grants once (`getBulletinSigner`, `getStatementStoreProver`). * To check whether an allowance is already cached, so a health check or readiness probe never makes the user's phone buzz (`hasBulletinAllowance`, `hasStatementStoreAllowance`). * Not inside a Product, and not in a browser: this package assumes Node, a filesystem for its session store, and a terminal to draw in. ## Core Concepts * **`createTerminalAdapter(options)`**: The entry point. `appId` is the storage namespace and the product identity; `endpoints` defaults to Paseo, and `storageDir` overrides the on-disk session directory (`~/.polkadot-apps/` by default). `await destroy()` when finished — it returns a promise, and the WebSocket keeps the Node event loop alive until it settles. * **Pairing is a subscription, not a return value**: Subscribe to `adapter.sso.pairingStatus` and render the QR when a `pairing` status arrives, *then* await `adapter.sso.authenticate()`. Printing before any interface mounts is what keeps the code scannable. * **Sessions load asynchronously**: They are read from disk after the adapter starts, so `waitForSessions(adapter, timeoutMs)` bridges the gap rather than an immediate read that would see an empty list. * **Two signer entry points**: `createSessionSigner(session, adapter)` signs as the session's default account (`derivationIndex: 0`) under the adapter's `appId`, which is what nearly every CLI wants. `createSessionSignerForAccount(session, ref)` is the escape hatch for a non-default sub-account or a different `productId`. * **Allowance signers are the canonical write path**: For Bulletin and Statement Store writes, ask the wallet for an allowance slot once and sign locally afterward. The first call prompts the phone; later calls return the cached slot key with no round trip. * **Cache-only probes never prompt**: `hasBulletinAllowance` reads the on-disk allowance file directly. Use it to decide whether to warn the user that a prompt is coming. ## Pair a CLI and Sign Create the adapter, render the QR as pairing starts, authenticate, then build a signer: ```typescript import { createTerminalAdapter, createSessionSigner, renderQrCode, waitForSessions, } from '@parity/product-sdk-terminal'; const adapter = createTerminalAdapter({ appId: 'my-cli' }); try { adapter.sso.pairingStatus.subscribe(async (status) => { if (status.step === 'pairing') { console.log(await renderQrCode(status.payload)); console.log('Scan with the Polkadot App…'); } }); const result = await adapter.sso.authenticate(); result.match( (session) => console.log('Logged in:', session?.id), (error) => console.error('Failed:', error.message), ); const [session] = await waitForSessions(adapter, 2000); if (session) { const signer = createSessionSigner(session, adapter); // Pass `signer` to submitAndWatch, a contract .tx(), or any PAPI call. } } finally { await adapter.destroy(); // async, and required — otherwise the CLI never exits } ``` ## Get an Allowance Signer For Bulletin or Statement Store writes, request a slot and sign with what comes back. Probe the cache first if you want to warn the user before their phone lights up: ```typescript import { getBulletinSigner, hasBulletinAllowance, AllowanceError, } from '@parity/product-sdk-terminal'; if (!(await hasBulletinAllowance(adapter, 'my-cli.dot'))) { console.log('Approve the allowance request on your phone…'); } try { const signer = await getBulletinSigner(adapter, 'my-cli.dot'); // Sign Bulletin extrinsics with `signer`. } catch (error) { if (error instanceof AllowanceError && error.reason === 'Rejected') { console.error('The allowance request was declined on the phone.'); } else { throw error; } } ``` Both helpers default `sessionId` to the only paired session. With zero or more than one paired session and no explicit id, they throw `AllowanceError` with `reason: 'NoSession'`. ## Limitations * **Requires Node 21 or later.** The package relies on the global `WebSocket` that Node 21 was the first to expose. On Node 18 or 20 it installs fine and then fails at connect time with `WebSocket is not defined`. * Node only. There is no browser build, and sessions are stored on disk. * Allowance helpers throw rather than returning a `Result`, because they unwrap the underlying library's own result type. Catch `AllowanceError` and branch on `reason`. * `adapter.destroy()` is not optional: without it the WebSocket keeps the process alive and your CLI never exits. It is async, so `await` it, and call it from a `finally` block so a failed pairing still tears down. * `destroy()` suppresses one benign teardown line (`Client destroyed`) that the upstream statement-store logs to `console.error`, and exports the predicate it uses, `isBenignTeardownError`, for consumers filtering their own output. It does not cover an auth subscription left open at teardown, which still raises `Error: Not connected`. * The cache-only probes mirror an upstream codec that has no public probe API yet. The public surface will not change when the upstream one ships. * If you are on a release before 0.3, drop any `--import @parity/product-sdk-terminal/register` flag from your `node` or `tsx` invocation — that WASM loader hook has been removed and is no longer needed. ## Where to Go Next * **Auth** *** The runtime-agnostic core beneath this package, if you want the sign-in flow without the terminal rendering. [→ Auth](/apps/product-sdk/auth/) * **Signer** *** The equivalent for a Product running inside a Host, where pairing is already handled for you. [→ Signer](/apps/product-sdk/signer/) * **API Reference** *** The complete `terminal` surface: the adapter, session signers, allowance helpers, and the `/host` subpath. [→ Visit Site](https://paritytech.github.io/product-sdk/api/terminal/) # Transactions > Overview of the Product SDK tx package — submit transactions, follow them to finality, batch calls atomically, and handle a typed error hierarchy. ## Introduction [`@parity/product-sdk-tx`](https://paritytech.github.io/product-sdk/api/tx/) is the submission layer. It signs and broadcasts an extrinsic, follows it through its lifecycle to block inclusion or finality, and reports every status transition. It also covers the machinery around a submission: atomic batching, dry-run extraction, weight buffering, Asset Hub account mapping, retries, and readable error formatting. It closes the loop that [Signer](/apps/product-sdk/signer/) and [Chain Client](/apps/product-sdk/chain-client/) open: the signer gives you a `PolkadotSigner`, the chain client gives you the typed API to build a transaction, and this package submits it and tells you what happened. ## When to Use It * To sign, broadcast, and track a single extrinsic with per-status callbacks (`submitAndWatch`). * To submit several calls as one atomic batch through the Utility pallet (`batchSubmitAndWatch`). * For the surrounding steps: dry-run extraction and weight buffering, Asset Hub account mapping for `pallet-revive`, retries with backoff, and dev signers for tests. * Do not use it to build the transaction object or open connections; that is the typed API from the chain client. To submit a contract call, prefer the higher-level [Contracts](/apps/product-sdk/contracts/) package, which wraps this one. ## Core Concepts * **`submitAndWatch(tx, signer, options)`**: Signs, broadcasts, and watches through `signing`, `broadcasting`, `in-block`, and `finalized`. It returns a `Result`, resolving expected failures on the error channel rather than throwing. * **`TxResult` and `TxStatus`**: `TxResult` carries the `txHash`, the `block`, and the emitted `events`. `TxStatus` drives the `onStatus` callback for progress UI. * **One `Result` to check**: `result.ok` means the transaction was included and its dispatch succeeded. A dispatch that fails on chain is reported on `result.error` as a `TxDispatchError`, not as a successful result — so you branch on `result.ok`, not on a flag inside the value. * **Typed error hierarchy**: `TxError` is the base, with `TxTimeoutError`, `TxDispatchError` (dispatch failed on chain), `TxValidityError` (rejected before inclusion), `TxSigningRejectedError` (the user declined), `TxBatchError`, and `TxDryRunError`. * **`batchSubmitAndWatch(calls, api, signer, options)`**: Wraps calls in `Utility.batch_all` by default (or `batch` / `force_batch`) and submits them as one transaction. All calls must target the same chain as the passed API. ## Submit and Track a Transaction Build a transaction from the typed API, then submit it with a status callback: ```typescript import { submitAndWatch } from '@parity/product-sdk-tx'; import { Binary } from 'polkadot-api'; const tx = chain.assetHub.tx.System.remark({ remark: Binary.fromText('hello') }); const result = await submitAndWatch(tx, signer, { onStatus: (status) => console.log(status.type), }); if (result.ok) { console.log(`Landed in block #${result.value.block.number}`); } else { console.error(result.error.message); // TxError } ``` ## Batch Calls Atomically Group several calls into one atomic transaction with `batchSubmitAndWatch`. With `batch_all`, either every call succeeds or the whole batch rolls back: ```typescript import { batchSubmitAndWatch } from '@parity/product-sdk-tx'; import { Binary } from 'polkadot-api'; const calls = [1, 2, 3].map((i) => chain.assetHub.tx.System.remark({ remark: Binary.fromText(`batch-${i}`) }), ); const result = await batchSubmitAndWatch(calls, chain.assetHub, signer, { mode: 'batch_all', }); ``` ## Limitations * Expected failures (dispatch error, timeout, signing rejection, validity error) arrive on the `Result` error channel, not as thrown exceptions. * A dispatch that fails on chain comes back on `result.error` as `TxDispatchError`; a `result.ok` transaction has both landed in a block and dispatched successfully. * The default `waitFor` is `'best-block'`; the default timeout is 300 seconds. * Every call in a batch must target the same chain as the passed API; an empty call list returns a `TxBatchError`. ## Where to Go Next * **Sign and Submit Transactions** *** The task-focused recipe: derive an account, sign, and submit end to end. [→ Sign and Submit Transactions](/apps/build/sign-and-submit/) * **Signer** *** Where the `PolkadotSigner` this package consumes comes from. [→ Signer](/apps/product-sdk/signer/) * **API Reference** *** The complete `tx` surface: `submitAndWatch`, `batchSubmitAndWatch`, and the error hierarchy. [→ Visit Site](https://paritytech.github.io/product-sdk/api/tx/) # Quick Start with the CLI > Install playground-cli, pair it with the Polkadot App, build your Product, and deploy it to a live dotNS name from the terminal. Deploy a Polkadot Product from your terminal with playground-cli. The `pg` command pairs with your [Polkadot App](/reference/apps/hosts/polkadot-app/), builds your Product, uploads the bundle, and publishes it to a dotNS name. No local host setup is required to reach a live deployment. The CLI is the command-line counterpart to [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/): Desktop runs published Products by their dotNS names; `pg` takes a project on disk and turns it into one. By the end of this guide, you will have a Product live at its own name, reachable in any browser through the dotNS web gateway. TestNet names end in `.paseo`, not `.dot` dotNS top-level domains are per network. On Paseo Next v2, the TestNet the Apps tooling targets by default, names are minted under `.paseo`: publish `myproject57` and you get `myproject57.paseo`, served at `https://myproject57.paseo.li`. Whether you supply the bare label or the full name depends on the tool; see [Choose a Name](/apps/register-dot-domain/#choose-a-name). Building with an AI agent? Point your coding agent at the right skills, repos, and docs first, so it writes idiomatic Product code instead of generic boilerplate. See [Set Up Your AI Agent](/apps/get-started/set-up-your-ai-agent/) for a paste-ready setup prompt. Products Devnet This page uses Paseo Next v2 (`paseo` preset). For the PCF Products Devnet (`devnet` preset), see [Get started as a developer](/apps/get-started/developers/). ## Before You Start Get these in order before your first deploy. The last two are easy to skip and fail silently later, so do not leave them out: 1. **Install the [Polkadot App](/apps/)** on your phone and create an account. It pairs with `pg` and signs your deploy. 2. **Have a terminal** with `curl` available and permission to install CLI tools in your user shell. 3. **Have a Product project** on disk with a package-manager build command. 4. **Fund your account with PAS** from the [faucet](/apps/get-started/get-testnet-tokens/). PAS pays transaction fees and the name deposit. 5. **Get a Bulletin Chain storage authorization** for the account that will sign. Without it, uploads are rejected at deploy time even when your balance is fine — a prerequisite that surfaces only as a failed publish. See [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/). Fund the account that actually signs The PAS balance and the storage authorization are both per account, and the account that signs your deploy may not be the one you expect. If a deploy fails with `no allowance set for account`, see [Accounts and Signing](/apps/concepts/accounts/) and the [troubleshooting entry](/apps/troubleshooting/#no-allowance-set-for-account). Account mapping to an EVM address is handled for you for the product account you deploy with; a smart contract needs its signing account mapped explicitly, covered in [Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/). What a first deploy costs In one test run, taking an app live cost about 10.4 PAS: roughly 10 PAS for the name and about 0.4 PAS for a 2.6 KB upload, with each on-chain step taking around a minute. Name cost depends on length and tier, so treat these as a ballpark. On TestNet, funding is rarely the constraint. CLI version The CLI is in active development, and breaking changes between versions are expected. If a command below no longer matches, check this page's last update against the latest [playground-cli release](https://github.com/paritytech/playground-cli/releases). ## Install the CLI The installer supports Linux and macOS. On Windows, work inside [WSL](https://learn.microsoft.com/windows/wsl/install) and follow the Debian/Ubuntu steps there. 1. Install the base prerequisites. macOS needs no preparation: `curl` ships with the OS, and the Xcode Command Line Tools cover the rest. On a fresh Debian or Ubuntu system: ```bash sudo apt update && sudo apt install -y build-essential curl ``` 2. Run the installer: ```bash curl -fsSL https://raw.githubusercontent.com/paritytech/playground-cli/main/install.sh | bash ``` The binary lands in `~/.polkadot/bin/`, with both commands symlinked into `~/.local/bin/` and that path appended to your shell RC file. 3. Open a new shell, or `source` your RC file, and verify the install: ```bash pg --version ``` Command aliases The installer registers two interchangeable commands: `playground` (canonical) and `pg` (short alias). This guide uses `pg` throughout. Pinning a version Pass `VERSION` to install a specific release, for example `curl -fsSL … | VERSION=v0.47.0 bash`. Later, `pg update` moves you to the newest release. ## Log In `pg login` is the first-run setup: it pairs the CLI with your signer, installs the toolchain, and requests your service allowances. It is safe to re-run; existing installs and sessions are detected and skipped. Do not reach for `pg init` here — that scaffolds a project from the starter template and pairs nothing. ```bash pg login ``` pg login ✔ logged in 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY ✔ account in use playground.dot/0 — 0x90b5ab205c6974c9ea841be688864633dc9ca8a3 · 5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty Three things happen, and the first two run concurrently: 1. **Login**: A QR code is printed to the terminal. Scan it with the Polkadot App to pair. Skipped if you already have a session under `~/.polkadot-apps/`. 2. **Toolchain install**: `git`, `curl`, a C linker, `rustup` with nightly and `rust-src`, `cargo-pvm-contract`, `wget`, and the `ipfs` CLI (Kubo). Existing installs are detected and skipped. 3. **Account setup**: Once a session exists, your phone shows a single approval dialog requesting the `BulletInAllowance` (Bulletin uploads at deploy time) and `SmartContractAllowance` (which mints PGAS to your `playground.dot/0` product account and account-maps it on chain). `pg deploy` needs the `ipfs` CLI, and `pg login` is what installs it Do not skip this step. `pg deploy` requires the Kubo `ipfs` binary on your `PATH`; if you never log in, install it yourself with `brew install ipfs` or from [docs.ipfs.tech/install](https://docs.ipfs.tech/install/). This is a temporary requirement while the pure-JS merkleizer is being fixed. Signer modes Signer choice is made at deploy time, not at login, through `pg deploy --signer`: * **Mobile signer** (`--signer phone`): Signs with the account you paired here, approving each on-chain step on your phone. Recommended for any deploy you intend to keep. * **Dev-only signer** (`--signer dev`): No phone needed; uses shared development keys (pair it with `--suri //Alice` to pin a known keypair). The deployed Product will be owned by the shared dev account, not by you. Funding is opt-in `pg login` never sends tokens. If your product account needs a testnet balance, run `pg drip` to top it up (1 PAS per run, up to 10 PAS, from a shared dev funder), or use the [faucet](/apps/get-started/get-testnet-tokens/). Run `pg status` at any time to see your product account address, its balances, and your allowance state. ## Build `pg build` auto-detects and runs your project build. ```bash pg build ``` pg build ✔ Build succeeded → dist/ ## Deploy `pg deploy` runs the full pipeline: build the frontend, upload artifacts to the Polkadot Bulletin Chain, and register a dotNS domain under the environment's TLD (`.paseo` on Paseo Next v2). Before building, it always runs your package manager's install step to keep dependencies in sync. ```bash # Interactive - pg prompts for signer, domain, and build directory pg deploy # Dev signer - no phone needed (the deployed Product is owned by the shared dev account) pg deploy --signer dev --suri //Alice --domain my-product ``` Pass the bare label to `--domain`. The CLI appends the environment's TLD, so `my-product` becomes `my-product.paseo` on Paseo Next v2. Name availability depends on the label's length, counted as written; see [Choose a Name](/apps/register-dot-domain/#choose-a-name) for the rules the prompt enforces. pg deploy --signer dev --suri //Alice --domain my-product ✔ my-product.paseo is available ✔ Deploy complete URL https\://my-product.paseo.li Domain my-product.paseo App CID bafybeihvru3e6ojhopxj7xxwtafrpyvsha6kylzklryon5k67u4clr26re Your phone will prompt — check it With the phone signer, each on-chain step waits for you to approve it in the Polkadot App, and no push notification announces the prompt. If the deploy seems to pause (including a deliberate \~60-second wait while your name is registered), open the app and approve the pending request. See [Troubleshooting](/apps/troubleshooting/#the-app-seems-frozen-after-an-action). Note `pg deploy` includes a memory watchdog that aborts the deploy if the process exceeds 4 GB RSS. If you hit this limit, set `DOT_MEMORY_TRACE=1` alongside `DOT_DEPLOY_VERBOSE=1` to capture per-second RSS and heap samples. For the full interactive deploy walkthrough, including the domain-name rules, contract redeploys, and the confirmation summary, see [Deploy Your App](/apps/deploy-your-app/). More CLI commands **Account and session** * **`pg status`**: Prints your signed-in product account in both encodings (SS58 and H160), its PAS and PGAS balances, and the state of your Bulletin and smart-contract allowances. Read-only: it signs nothing and submits nothing, so it is safe to run at any time. With no session paired it prints a "log in first" notice and exits cleanly. ```bash pg status ``` * **`pg drip`**: Tops up your product account with a little TestNet PAS: 1 PAS per run, up to a 10 PAS cap, from a shared dev funder rather than the public faucet. It only ever funds the caller's own account, resolved from the active session, so there is no address flag. Login never calls it for you. ```bash pg drip ``` * **`pg logout`**: Signs out of the paired account, tells the paired phone to drop its side of the connection, and clears session files under `~/.polkadot-apps/`. A no-op if you are not signed in. ```bash pg logout ``` **Projects and deploys** * **`pg init`**: Scaffolds a new project from the playground starter template. A shorthand for `pg mod playground-template`. ```bash pg init ``` * **`pg mod`**: Clones a moddable app from the Playground registry so you can customize and redeploy it as your own Product. Only apps that opted into `--moddable` at deploy time are listed. Pass a domain label, such as `my-product` or `my-product.paseo`, to clone directly, or omit it to open an interactive picker showing every moddable app. Source is fetched as a tarball over HTTPS, so neither `git` nor `gh` is required. ```bash pg mod [domain] ``` * **`pg decentralize`**: Takes a static site you already have — a live URL to mirror, or a local build directory — uploads it to the Bulletin Chain, and registers a dotNS name pointing at it. The counterpart to `pg deploy`, which builds your project first. ```bash pg decentralize --site https://example.com pg decentralize --path ./dist ``` * **`pg deploy-all`**: Deploys several apps listed in a JSON manifest in one invocation. Builds run in parallel, while all on-chain work is serialized per signing account so concurrent deploys never collide on a nonce. Non-interactive by design. ```bash pg deploy-all --manifest apps.json --signer dev --playground ``` * **`pg contract`**: The playground-native path to contracts, backed by `cdm`. `pg contract deploy` builds, deploys, and registers your contracts signed by your logged-in account; `pg contract install` writes `cdm.json` and the generated type outputs. See [Add a Smart Contract to Your Product](/apps/build/deploy-a-smart-contract/) for the workflow, including when to call `cdm` directly instead. ```bash pg contract deploy pg contract install [libraries...] ``` * **`pg update`**: Updates `pg` to the latest version from the GitHub releases page. ```bash pg update ``` Scripting a deploy, or handing one to an agent `pg deploy -y` runs non-interactively using defaults, skipping every prompt. It requires `--domain`, and `--signer` defaults to `dev`. For full control in CI, pass `--signer`, `--domain`, `--buildDir`, and `--playground` explicitly; add `--suri //Alice` with `--signer dev` so the dev signer uses a known keypair. See [Set Up Your AI Agent](/apps/get-started/set-up-your-ai-agent/) for orienting a coding agent around this toolchain. You have deployed a Polkadot Product. To keep building it with your own editor and toolchain, head to the Build guides; they open with [project setup](/apps/build/#set-up-your-project) so Polkadot Desktop can load your Product from `localhost` while you iterate with live reload. ## Where to Go Next * **Product SDK** *** Understand the SDK that powers your Product: what each package does and how the pieces fit together. [→ Product SDK](/apps/product-sdk/) * **Build Guides** *** Set up the local dev loop, then add capabilities to your Product: signing, on-chain reads, decentralized storage, off-chain pub/sub, local persistence, and smart contracts. [→ Open Build Guides](/apps/build/) * **Deploy Your App** *** The full deploy flow in depth: build the bundle, register a dotNS name, publish to the playground, and go live on the Bulletin Chain. [→ Deploy Your App](/apps/deploy-your-app/) # Quick Start with RevX > Generate and publish a Polkadot Product from the browser with RevX App Builder, then sign the final .dot deployment with the Polkadot App. Generate and publish a Polkadot Product in the browser with RevX App Builder. RevX gives you a browser-based IDE, scaffolds a Product from a natural-language prompt, and publishes it to a `.dot` name after you sign the final step with the Polkadot App. This route does not require a local development environment. By the end, you will have configured an AI provider in App Builder, generated a Polkadot Product from a prompt, inspected the generated code, and published it to `.dot`. TestNet names end in `.paseo`, not `.dot` dotNS top-level domains are per network. On Paseo Next v2, the TestNet the Apps tooling targets by default, names are minted under `.paseo`: publish `myproject57` and you get `myproject57.paseo`, served at `https://myproject57.paseo.li`. Whether you supply the bare label or the full name depends on the tool; see [Choose a Name](/apps/register-dot-domain/#choose-a-name). Products Devnet This page uses Paseo Next v2 (`paseo` preset). For the PCF Products Devnet (`devnet` preset), see [Get started as a developer](/apps/get-started/developers/). ## Prerequisites Before starting, make sure you have: * The [Polkadot App](/apps/) installed on your phone with an account created; it signs the final publish step. * An API key for an AI provider supported by App Builder, such as OpenAI or Anthropic. ## Open RevX Open [RevX](https://revx.dev/) in your browser. RevX is a browser-based IDE; you will use the App Builder track to scaffold a Polkadot Product end to end. ![RevX IDE landing view showing the main workspace](/images/apps/quick-start/revx/revx-01.webp) ## Open App Builder From the sidebar, select **App Builder**. App Builder is RevX's track for generating Polkadot Products using AI-assisted workflows. ![RevX sidebar with the App Builder option highlighted](/images/apps/quick-start/revx/revx-02.webp) ## Create a New App Click **Create App** to start a new project. RevX automatically installs the required dependencies and initializes the project environment so you can move straight into configuration and prompting. ![RevX App Builder showing the Create App action and the initialized project environment](/images/apps/quick-start/revx/revx-03.webp) After clicking **Create App**, you will see a loading screen while the IDE initializes the project environment. ![RevX App Builder showing the loading screen while the IDE initializes the project environment](/images/apps/quick-start/revx/revx-04.webp) Note Initial setup may take a moment while dependencies install. Wait for the environment to finish initializing before configuring the builder. Once the environment is initialized, you will see a minimal app scaffolded in the editor and running in the terminal. ![RevX App Builder showing the minimal app scaffolded in the editor and running in the terminal](/images/apps/quick-start/revx/revx-05.webp) ## Configure the Builder From the App Builder view, click the **Settings** icon to open the AI configuration panel. ![RevX App Builder settings icon](/images/apps/quick-start/revx/revx-06.webp) Configure the following: * **AI provider**: The backend service that powers code generation. * **API key**: The credential for your AI provider. * **Model**: The specific model to use from the selected provider. ![RevX App Builder configuration panel showing API key, AI provider, and model fields](/images/apps/quick-start/revx/revx-07.webp) These settings let the IDE generate applications using the selected AI backend. You can change them at any time if you want to switch providers or models. ## Generate an App Use the chat interface to describe the app you want to build. RevX generates the application structure and code automatically based on your prompt. Example prompt Build a Product that shows the balance of Alice (a standard Substrate dev account) After you submit the prompt, the IDE produces the project files and scaffolds the app for you to review. ![RevX chat interface with a prompt entered and the generated app structure on the right](/images/apps/quick-start/revx/revx-08.webp) Tip Keep prompts concrete and scoped. Short, specific prompts tend to produce app structures that are easier to review and iterate on. ## Inspect the Generated Code Once generation completes, open the generated files in the editor to review what was produced. You can continue iterating on the application from within RevX: refine the prompt, edit code directly, or layer additional changes through the chat interface. ![RevX editor showing the generated app source files open for inspection](/images/apps/quick-start/revx/revx-09.webp) ## Publish to `.dot` When your app is ready, click **Publish to .dot** to deploy the application to the Polkadot ecosystem. The publish action takes the app you generated in RevX and makes it available under a `.dot` name. ![RevX App Builder showing the Publish to .dot action](/images/apps/quick-start/revx/revx-10.webp) After clicking **Start Deploy**, you will be asked to sign the transaction with your Polkadot App. ![RevX App Builder showing the transaction signing prompt](/images/apps/quick-start/revx/revx-11.webp) After signing the transaction, you will see the deployment progress in the terminal. The action is labeled **Publish to .dot**, but the name you receive carries the network's TLD, so on Paseo Next v2 your Product is live under its `.paseo` name. Open it in Polkadot Desktop, or on Polkadot Web at `https://.paseo.li` in any browser. ## Where to Go Next * **Build Guides** *** Set up the local dev loop, then add capabilities to your Product: signing, on-chain reads, decentralized storage, off-chain pub/sub, and local persistence. [→ Open Build Guides](/apps/build/) # Reference Exact values, package names, endpoints and definitions, with links to where each one comes from. * [Networks & endpoints](/apps/reference/networks/): the Devnet chains, the `devnet` preset, and the current RPC and gateway values. * [Packages & tools](/apps/reference/packages/): the SDKs and CLIs you install to build Products. * [Addresses & registries](/apps/reference/addresses/): on-chain registries, asset IDs and contract addresses. * [Glossary](/apps/reference/glossary/): short definitions of the terms used across the docs. * [More resources](/apps/reference/resources/): app installs, reference Products and source repositories. # Addresses & registries Public identifiers for the Polkadot Products Devnet: chain IDs, asset IDs, registry addresses and contract addresses. Each section says where to read the current value before you build anything around it. Every address here is a snapshot Addresses are network-specific and change when a network is redeployed. Before you hard-code one, read it back from the `devnet` preset in the tooling address book, or resolve it on chain. Only public identifiers appear here. Account keys, mnemonics and seeds are never published: the platform signs on the device, and operator secrets live outside every source repository. Paseo Next v2 The dotNS contracts on Paseo are listed separately, with different addresses: see [TestNet Contracts](/reference/apps/infrastructure/dotns/testnet-contracts/). ## Key chains and identifiers The Devnet runs on the community-operated Paseo network: a relay chain plus a set of system parachains. Product developers usually start with Asset Hub (para 1000) for contracts and assets, People (para 1004) for identity, and Bulletin (para 1010) for app bundle storage. | Chain | Para ID | Role | | --------- | ------- | -------------------------------------------------- | | Asset Hub | `1000` | Contracts (`pallet-revive`), assets, DotNS gateway | | People | `1004` | Identity and proof-of-personhood | | Bulletin | `1010` | Web-app bundle storage | | Field | Value | | ---------------------------------------- | -------------------------------- | | EVM chain id (Asset Hub `pallet-revive`) | `420420417` | | Native token | PAS, 10 decimals | | SS58 prefix (Devnet) | `42` | | Web gateway | [dev-dot.li](https://dev-dot.li) | ## Native token and stablecoins CASH, the balance users see in the app, is a Devnet digital-dollar asset. On Asset Hub its asset ID is `50000413`. The same logical asset can be represented on the People chain for app-facing CASH flows. | Asset | Asset Hub u32 id | Decimals | Notes | | ------------------------------ | ---------------- | -------- | -------------------------------------- | | pUSD (Digital Dollar / "CASH") | `50000413` | 6 | The main CASH asset used by the Devnet | | USDt (Tether USD) | `1984` | 6 | | The native token is PAS, with 10 decimals. Devnet tokens carry no value. You can get Devnet funds from the [Polkadot faucet](https://faucet.polkadot.io). ## On-chain registries Two registries make the platform's names and apps discoverable. Each network has its own deployment, so always resolve the address for the network you are targeting. ### DotNS (the `.dot` naming system) DotNS records who owns a `.dot` domain and which app bundle it points to. The gateway reads that record to load the app. Devnet runs DotNS v1.1.0 (`protocolVersion()` on `DotnsProtocolRegistry`). | Contract | Devnet address | | ------------------------ | -------------------------------------------- | | DotnsProtocolRegistry | `0xdDF3D3838Ff056F15602fC5a65927f185679C36F` | | DotnsRegistrar (ERC-721) | `0xc609e0c2DAB4433d55a32FB098Db8788C1956302` | | DotnsRegistrarController | `0x59dcF8BfFFa7239243785C3fC336D8Bb22312e8c` | | DotnsRegistry | `0xb052E5EfC5ADEff1f21d48DEfb5169Cb394A1a73` | | DotnsResolver | `0xFcB74C073a2d14dc65B178Bb873f4dE51318DDC2` | | DotnsReverseResolver | `0x736e067290AE71f841399575ABfc8b2BAA5Eed7E` | | DotnsContentResolver | `0x7e75491ecfb04900EB05ee63CABA2B33900aABB5` | | DotnsPopController | `0xC3a3EdAb753F91488fD84E6134b5b0325dc22452` | | DotnsPopResolver | `0x398912c9bb03180Ff049f0E034FE2E0024fb8406` | | PopRules | `0xD5Ee34610F06f7FF4668aB4fabE2393B65a43AE7` | | DotnsNameEscrow | `0xb50269322010DeeF2afb162c009Caf897971952C` | | StoreFactory | `0x5Df012daA06cA2602DA153309C2E3A83284Cb879` | | Multicall3 | `0x92640655c5c7ee7E42F0B5aD68D205a8A767b81C` | Some supporting DotNS contracts vary by network and are not listed here. Read them from `DotnsProtocolRegistry` (`get(key)`) or from the `dotns-sdk` address book for the `devnet` preset when you need them. See [Naming (DotNS)](/apps/architecture/naming/) for how these contracts fit together. ### Browse `Publisher` Browse is the app-discovery directory. `Publisher` records which `.dot` apps are discoverable; display metadata lives in DotNS records. | Contract | Devnet address | | --------- | -------------------------------------------- | | Publisher | `0x8d3CE7Bb2ED68C06306b4C1d5EEe79435AAE0A10` | Browse also reads attestation-resolver contracts for compliance badges. Those addresses are network-specific, so read them from the Browse address book for the network you target. See [App discovery (Browse)](/apps/architecture/discovery/). ### Polkadot app `AccountDataStore` `AccountDataStore` is the contract the Polkadot app uses to back up coinage installations. Each install stores a small, client-encrypted record under the account's own address, so restoring the same recovery phrase on a new device can find coins held by earlier installs. The contract has no owner or admin, and only the device holding the key can read a record's contents. | Contract | Devnet address | | ---------------- | -------------------------------------------- | | AccountDataStore | `0x58c9963308c7735cf72ab633e8a9d892f5ab9e05` | ### Attestation protocol An EAS-style attestation suite (`SchemaRegistry` + `AttestationService`) provides general, permissionless attestations, used by Browse compliance badges and others. Both contracts run on Asset Hub via `pallet-revive`. The `SchemaRegistry` and `AttestationService` addresses are network-specific and are not listed here. Read them from the [`attestation-protocol`](https://github.com/paritytech/attestation-protocol) deployment records for the network you target. ## Runtime precompiles Some capabilities are available to contracts at fixed precompile addresses, not as deployed contracts: | Precompile | Address | Purpose | | ---------- | -------------------------------------------- | ------------------------------------------------------------------- | | Personhood | `0x000000000000000000000000000000000a010000` | `personhoodStatus(address, bytes32 context)` → tier + per-app alias | [Identity & personhood](/apps/architecture/identity/) explains how Products use it. ## How addresses are resolved by tooling You rarely paste these addresses by hand. The CLIs select the `devnet` network preset (`--env devnet`), and that preset carries the RPC endpoints and the full address book. Apps and frontends resolve names to addresses at runtime through the registries above. When you need a value directly, read it from the preset instead of assuming it. ## Sources * [paseo-network/runtimes](https://github.com/paseo-network/runtimes): parachains, assets, precompiles * Contract source: [dotns](https://github.com/paritytech/dotns) · [browse](https://github.com/paritytech/browse) · [attestation-protocol](https://github.com/paritytech/attestation-protocol) · [AccountDataStore](https://github.com/paritytech/polkadot-mobile-datastore-contract-community) # Glossary Short definitions of the terms used in these docs, with a link to the page that covers each one in depth. ## Platform and entry points ### Product An app published to the Devnet under a `.dot` domain and opened inside the Polkadot app or the web gateway. These docs say "Product" when they mean the published, named app, and not a web app in general. See [App delivery](/apps/architecture/app-delivery/). ### Polkadot Products Devnet The public developer preview these docs describe. It runs on the community-operated Paseo network. Product developers mainly use Asset Hub for contracts and assets, People for identity, and Bulletin for app bundle storage. ### Polkadot app The app people use to reach the platform, on mobile and desktop. Products run inside it, and it handles signing, storage, chain access and identity for the user. Download links are in [More resources](/apps/reference/resources/). ### dev-dot.li The web gateway that serves `.dot` apps in an ordinary browser, reachable at . It resolves a `.dot` domain, fetches the app bundle, and renders it in a sandboxed iframe. ## Naming and discovery ### `.dot` domain A readable name, such as `calculator.dot`, that points to a deployed app bundle. For users it works like an app name. For developers it is the name you register, update and publish with the DotNS tools. ### DotNS The `.dot` naming system. You use it to register an app name, point that name at content, or look up where an app is published. See the [naming architecture](/apps/architecture/naming/). ### Browse / Publisher Browse is the app-discovery directory for the Devnet (). Use it to find published Products, or to check that your own app appears after you list it. Publishing requires ownership of the `.dot` domain and may require personhood checks. ## Contracts ### PolkaVM / revive PolkaVM is the contract execution layer on Asset Hub, available through `pallet-revive`. If your Product needs custom on-chain logic, this is most likely where your contracts run. See the [contracts architecture](/apps/architecture/contracts/). ## Storage and delivery ### Bulletin The Bulletin chain stores published web-app bundles and contract metadata. Stored content is addressed by CID. Uploads need a storage authorization: a deploy account must hold a live one before it can upload, and authorizations expire and must be refreshed. ### CID The content identifier of a stored bundle or file. A `.dot` domain resolves to a CID, and the CID is what the client fetches. See [App delivery](/apps/architecture/app-delivery/). ### Statement store A People-chain store of short signed statements. The app uses it as the transport for encrypted chat messages and call signalling. See [Messaging & calls](/apps/architecture/messaging/). ## Developer SDKs ### Product SDK `@parity/product-sdk` is the main TypeScript SDK for building Products. It gives your app the wallet, chain, storage, contract and identity services that the host provides. It runs inside the Polkadot app or the web gateway, and is not a standalone wallet. See [Packages & tools](/apps/reference/packages/). ### TrUAPI (host protocol) TrUAPI is the protocol between a Product and its host (the Polkadot app or the web gateway). It covers accounts, signing, permissions, storage, chat, payments and chain access. `@parity/truapi` is the Product-side client, and `@parity/product-sdk-host` speaks it for you. It replaced the earlier Host API (`@novasamatech/host-api`). See [Packages & tools](/apps/reference/packages/#host-protocol-truapi). ### Deploy CLI (`pad`) `@polkadot-community-foundation/polkadot-app-deploy` (bin: `pad`) is the CLI that publishes a built static bundle and points a `.dot` domain at it. On this Devnet, use the `devnet` preset: `pad` and `dotns` take it with `--env devnet`. ## Identity and personhood ### Proof of personhood How an account is recognized as a distinct human without revealing who that human is. It has two tiers, and either can unlock product flows such as app listing, naming, rewards or rate limits. * Lite: an attested username. Most users hold this tier. * Full: a stronger guarantee of one account per human, reached by redeeming an invitation. See [Username & proof of personhood](/apps/using-the-app/username-and-personhood/). ### Alias A per-application pseudonym derived for your account, so an app can recognize a returning person without learning who they are or linking them across apps. See [Identity & personhood](/apps/architecture/identity/). ### People / Asset Hub Two of the system parachains Products use. Asset Hub hosts contracts, assets and DotNS. People hosts identity and personhood. ## Accounts and addresses ### SS58 The Substrate address format an account is shown in (Devnet prefix `42`). Faucets and chain tools take the SS58 address. Contract tooling uses the mapped EVM `0x…` address instead. See [Addresses & registries](/apps/reference/addresses/). ## Money ### CASH The name users see for a Devnet digital-dollar asset. Users get CASH inside the Polkadot app, through in-app flows or rewards, depending on the current build. See [Get & use CASH](/apps/using-the-app/get-and-use-cash/). ### PAS The native token of the underlying Paseo network, used to pay transaction fees and keep an account alive. It is not CASH. It comes from the faucet: see [Create an account & get funds](/apps/using-the-app/create-account/). ### Pocket The wallet surface in the Polkadot app: the screen holding your balances, including the CASH card and its top-up button. ### Coinage The privacy-preserving payment system on the People chain that CASH is spent through. See [Money (CASH & funding)](/apps/architecture/money/). ## Learn more * [Packages & tools](/apps/reference/packages/): what to install * [Networks & endpoints](/apps/reference/networks/): chains, the `devnet` preset and endpoints * [More resources](/apps/reference/resources/): apps, downloads and source # Networks & endpoints Which chain does what on the Polkadot Products Devnet, and the public endpoints and gateways you are likely to need. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Networks](/apps/concepts/networks/). ## The Devnet at a glance The Devnet runs on the community-operated Paseo network. [The network](/apps/architecture/network/) explains what each chain is responsible for. | Parameter | Value | | ------------------ | -------------------------------------------- | | Contract execution | `pallet-revive` on Asset Hub (PolkaVM / EVM) | | EVM chain id | `420420417` | | Native token | PAS, 10 decimals | | Web gateway | `dev-dot.li` | ## How tools pick a network Both CLIs take a network preset with `--env`: ```bash pad ./dist my-app.dot --env devnet # @polkadot-community-foundation/polkadot-app-deploy dotns ... --env devnet # @polkadot-community-foundation/dotns-cli ``` For this Devnet the preset is `devnet`. A preset bundles the endpoints and registry addresses a tool needs, so a wrong preset points the tool at the wrong endpoints or contract addresses. Don't guess the name. ## Parachains and para IDs Product development targets Asset Hub (1000), People (1004) and Bulletin (1010). Other system parachains share the relay but are not part of the Product surface. ## Public endpoints and gateways ### Web gateway The web gateway is a client-side resolver that serves `.dot` apps over HTTPS: * Gateway: * Any deployed app resolves at `https://.dev-dot.li` (for example `https://calculator.dev-dot.li`). ### Reference apps and app installs The deployed reference Products and the Polkadot app download links are in [More resources](/apps/reference/resources/). ### Faucet Devnet funds come from the [Polkadot faucet](https://faucet.polkadot.io). It serves several networks, so you have to pick two things: Paseo, and the right parachain. These links pre-select both: | You need fees for | Use | | ----------------------------------- | ------------------------------------------------------------------------- | | Contracts, `.dot` names, publishing | [Paseo Asset Hub (1000)](https://faucet.polkadot.io/paseo?parachain=1000) | | Sending CASH, usernames, personhood | [Paseo People (1004)](https://faucet.polkadot.io/paseo?parachain=1004) | Paste your SS58 address (the one the app shows on its receive screen, or `dotns account address` for CLI work), not an EVM `0x…` address. The faucet pays the native token, PAS. Do not pick an *Asset Hub Next* or *People Next* chain The faucet also lists Asset Hub Next (1500) and People Next (1502). Those belong to Paseo Next v2 (`paseo` preset), a different network. Funds sent there will not appear on this Devnet, and the balance you are waiting for will never arrive. ### Storage authorization Publishing an app writes to the Bulletin Chain, which works by authorization, not by fees. This is separate from the token faucet above: a deploy account needs an authorization grant (a byte and transaction quota) before it can upload. Grant one from the Faucet tab of the [Bulletin Chain Console](https://paritytech.github.io/polkadot-bulletin-chain/) after selecting the **Products Devnet** network. See [Get storage authorization](/apps/build/build-and-publish/#get-storage-authorization). ### Node RPC endpoints The `devnet` preset already has an endpoint for each chain, so the CLIs connect without any setup. Use the lists below when you need to point a tool or a browser-based explorer at a chain directly, or when the endpoint a preset picked is down. Paseo is community-operated. Each chain is served by several independent providers, and any single endpoint can go offline or move. If one fails, try another from the same list. The `devnet` preset tracks a working set, so prefer it over pasting a URL by hand. The CLIs reconnect on their own. A run that prints several `Unable to connect` lines normally still completes, so only switch endpoints if the command fails. **Relay** * `wss://paseo-rpc.n.dwellir.com` * `wss://paseo-v2.rpc.turboflakes.io` * `wss://rpc-paseo.stakeworld.io` * `wss://rpc.interweb-it.com/paseo` **Asset Hub (1000)** * `wss://asset-hub-paseo-rpc.n.dwellir.com` * `wss://sys.turboflakes.io/asset-hub-paseo` **People (1004)** * `wss://people-paseo.rotko.net` * `wss://people-paseo.gatotech.network` * `wss://rpc.interweb-it.com/people-paseo` **Bulletin (1010)** * `wss://bulletin-paseo.tservices.es:8443` * `wss://bullet.sik.rocks` * `wss://bullet.tunastaking.eu` #### Ethereum JSON-RPC Contract tooling that speaks Ethereum JSON-RPC (Hardhat, `cast`, viem) needs the ETH-RPC endpoint for Asset Hub, not a Substrate WebSocket endpoint: * `https://eth-rpc-testnet.polkadot.io` #### Bulletin IPFS gateways An app bundle stored on Bulletin is addressed by CID. Serving it over HTTP takes an IPFS gateway peered to a Bulletin node. The Bulletin RPC endpoints above do not serve `/ipfs/` themselves. * `https://devnet-ipfs.api.polkadotcommunity.foundation`: operated by the Polkadot Community Foundation, and the gateway the deploy tooling uses by default Tools append `/ipfs/` to this bare origin. Contract and registry addresses are in [Addresses & registries](/apps/reference/addresses/). ## Source of the runtimes The Paseo relay and system parachain runtimes live in [`paseo-network/runtimes`](https://github.com/paseo-network/runtimes). Go there to check chain-level details such as para IDs, pallets, precompiles or runtime constants. ## Learn more * [The network](/apps/architecture/network/): what each chain is responsible for * [Addresses & registries](/apps/reference/addresses/): contract addresses # Packages & tools Which packages to install for a Product project. Your app code needs the Product SDK, pinned to the version the hosts speak. The CLIs register names and publish bundles. Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Product SDK](/apps/product-sdk/). ## Developer packages Most projects only need a few direct dependencies: | Package | Install | Purpose | Bin | | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | [`@parity/product-sdk`](https://www.npmjs.com/package/@parity/product-sdk) | `npm i @parity/product-sdk@0.39.0` | TypeScript SDK for building apps: multi-chain access, transactions, signing, contract calls, cloud storage, and identity. Pinned: see [Install the SDK version the hosts speak](#install-the-sdk-version-the-hosts-speak). | — | | [`@polkadot-community-foundation/dotns-cli`](https://www.npmjs.com/package/@polkadot-community-foundation/dotns-cli) | `npm i -g @polkadot-community-foundation/dotns-cli@latest` | CLI for the `.dot` naming system: register names, set content/address records, manage reverse names and stores. | `dotns` | | [`@polkadot-community-foundation/polkadot-app-deploy`](https://www.npmjs.com/package/@polkadot-community-foundation/polkadot-app-deploy) | `npm i -g @polkadot-community-foundation/polkadot-app-deploy@latest` | Deploy CLI: uploads a built static bundle to Bulletin, and binds it to a `.dot` domain. `pad-bootstrap` (same package) authorizes the Bulletin storage pool. | `pad`, `pad-bootstrap` | `pad` requires Node 22+. On Node 20 it fails at startup with an unrelated-looking error, so check `node --version` first. Install the CLIs at their latest release, and re-run the same command to upgrade. They carry network presets and contract addresses, and a stale copy is the usual cause of a command that succeeds while nothing changes on chain. The Product SDK is the one package to pin, as described below. Both CLIs select a network preset with `--env`, and for this Devnet it is `--env devnet`. ## Product SDK family `@parity/product-sdk` is the main dependency for Product app code. It gives an app access to wallet, storage, chain, contract and identity services through the host: the Polkadot app or the web gateway. This is deliberate. Your app should not manage private keys or build its own wallet layer. | Package | Purpose | | ----------------------------------- | -------------------------------------------------------- | | `@parity/product-sdk` | Main SDK entry point for Product apps. | | `@parity/product-sdk-chain-client` | Typed access to the Devnet chains. | | `@parity/product-sdk-descriptors` | Chain descriptors used by the SDK. | | `@parity/product-sdk-signer` | Host-backed signing, plus development signers for tests. | | `@parity/product-sdk-contracts` | Contract calls and ABI handling for PolkaVM contracts. | | `@parity/product-sdk-cloud-storage` | Bulletin-backed content storage helpers. | | `@parity/product-sdk-host` | Host detection and host-provided services. | These packages live in the [Product SDK monorepo](https://github.com/paritytech/product-sdk) and are versioned separately. `@parity/product-sdk` pins a matching version of each, so install them through it, not one by one. ### Install the SDK version the hosts speak Apps talk to their host over TrUAPI. The Devnet hosts speak the TrUAPI version that Product SDK 0.39.0 speaks, so install exactly that version: ```bash npm i @parity/product-sdk@0.39.0 ``` Newer SDK releases speak a newer TrUAPI that these hosts do not. If you add SDK packages one by one, use the versions `@parity/product-sdk@0.39.0` depends on. ### Current Devnet chain metadata The Devnet chains run newer runtimes than the metadata in `@parity/product-sdk-descriptors`. For typed access to the current pallets, swap in the Polkadot Community Foundation's build of the same package. Add it as a dependency and as an override, with the same value in both: * npm ```json { "dependencies": { "@parity/product-sdk-descriptors": "npm:@polkadot-community-foundation/product-sdk-descriptors@0.14.0-pcf.1" }, "overrides": { "@parity/product-sdk-descriptors": "npm:@polkadot-community-foundation/product-sdk-descriptors@0.14.0-pcf.1" } } ``` * pnpm ```json { "dependencies": { "@parity/product-sdk-descriptors": "npm:@polkadot-community-foundation/product-sdk-descriptors@0.14.0-pcf.1" }, "pnpm": { "overrides": { "@parity/product-sdk-descriptors": "npm:@polkadot-community-foundation/product-sdk-descriptors@0.14.0-pcf.1" } } } ``` Your imports stay the same (`@parity/product-sdk-descriptors/...`), and every SDK package uses the same copy. ## Host protocol (TrUAPI) `@parity/product-sdk-host` speaks TrUAPI to the host for you, so apps rarely import it directly. For end-to-end tests, use the test host in [`@parity/truapi-host`](https://www.npmjs.com/package/@parity/truapi-host); see [Test without the real host](/apps/build/platform-services-sdk/#test-without-the-real-host). TrUAPI lives in [trinity-user-agents](https://github.com/paritytech/trinity-user-agents). `@novasamatech/host-api`, `@novasamatech/host-api-wrapper` and `@parity/host-api-test-sdk` do not speak the Devnet hosts' current protocol. ## Command-line tools | CLI | Package | Bin | What it does | | ----------------- | ---------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- | | Deploy | `@polkadot-community-foundation/polkadot-app-deploy` | `pad` | Publishes a built static bundle, stores it on Bulletin, and points a `.dot` domain at it. | | Storage bootstrap | `@polkadot-community-foundation/polkadot-app-deploy` | `pad-bootstrap` | Authorizes the Bulletin storage pool `pad` uploads with, using an authorizer key. Ships in the same package as `pad`. | | DotNS | `@polkadot-community-foundation/dotns-cli` | `dotns` | Registers and manages `.dot` domains: `register`, `lookup`, `content`, `primary`, `transfer`, `store`, `pop`, and more. | A typical deploy binds a built bundle to a name on a chosen network: ```bash pad ./dist my-app.dot --env devnet ``` The account `pad` deploys with must hold a live Bulletin storage authorization, because `pad` never authorizes itself. See [Get storage authorization](/apps/build/build-and-publish/#get-storage-authorization). ## Where your app runs Your Product runs inside the Polkadot app or the web gateway. Download links, the deployed reference Products and source repositories are in [More resources](/apps/reference/resources/). ## Learn more * Source: [product-sdk](https://github.com/paritytech/product-sdk) · [trinity-user-agents](https://github.com/paritytech/trinity-user-agents) (TrUAPI) · [polkadot-app-deploy](https://github.com/Polkadot-Community-Foundation/polkadot-app-deploy) · [dotns-sdk](https://github.com/Polkadot-Community-Foundation/dotns-sdk) * [Networks & endpoints](/apps/reference/networks/): which network these tools target # More resources App downloads, the reference Products and source repositories. For what to `npm install` and why, see [Packages & tools](/apps/reference/packages/). For chains, endpoints and the network preset, see [Networks & endpoints](/apps/reference/networks/). Paseo Next v2 This page covers the PCF Products Devnet (`devnet` preset). For Paseo Next v2 (`paseo` preset), see [Get the Polkadot App](/apps/#get-the-polkadot-app) or [Install Polkadot Desktop and Pair](/apps/get-started/). ## Get the app The Polkadot app is where people use Products, on mobile and desktop. The web gateway works in any browser if you only want to look around. These are devnet builds. The Polkadot releases on Google Play and the App Store connect to a different network and do not work with these docs. | Platform | Where to get it | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Android (recommended) | [join the tester group](https://appdistribution.firebase.dev/i/f3b79521380b40b9) to get each new build automatically | | Android (manual APK) | the [latest Android release](https://github.com/Polkadot-Community-Foundation/polkadot-android-community/releases/latest) | | iOS (TestFlight) | [join the TestFlight beta](https://testflight.apple.com/join/HnBX59vz) | | Desktop (macOS / Windows / Linux) | the [latest desktop release](https://github.com/Polkadot-Community-Foundation/polkadot-desktop-community/releases/latest) | | Web gateway (no install) | | On Android, the tester group is the easiest route. Accept the invitation with a Google account and you are notified of each new build. To install by hand instead, take `app-polkadot-devnet.apk` (\~200 MB) from the latest release and allow installs from unknown sources. The same APK runs with or without Google Play services. iOS builds are only distributed through TestFlight. The first build of each version reaches the group once Beta App Review approves it. If an account cannot submit a transaction, it probably needs devnet funds. Get them from the [faucet](https://faucet.polkadot.io). ## Reference Products to open These apps run on the Devnet. They are developer-preview examples, not audited production applications. | App | Open | `.dot` name | What it does | | --------------- | ------------------------------------ | --------------------- | ------------------------------------------------------ | | Calculator | | `calculator.dot` | A basic calculator | | Stopwatch | | `stopwatch.dot` | A stopwatch | | Countdown Timer | | `countdown-timer.dot` | Counts down from a time you set | | Alarm Clock | | `alarm-clock.dot` | Rings at the time you set | | Chess Clock | | `chess-clock.dot` | Two clocks for a two-player game; tap to pass the turn | | Unit Converter | | `unit-converter.dot` | Converts units, such as metres to feet | ## Source repositories For detail these docs do not cover, go to the source. **Platform and tooling** * [product-sdk](https://github.com/paritytech/product-sdk): the Product SDK, also a [Claude Code plugin](https://github.com/paritytech/product-sdk#claude-code-plugin) with [agent skills](https://github.com/paritytech/product-sdk/tree/main/product-sdk/skills) * [trinity-user-agents](https://github.com/paritytech/trinity-user-agents): TrUAPI, the host protocol client and the host runtime * [polkadot-app-deploy](https://github.com/Polkadot-Community-Foundation/polkadot-app-deploy): the `pad` deploy CLI * [dotns](https://github.com/paritytech/dotns) · [dotns-sdk](https://github.com/Polkadot-Community-Foundation/dotns-sdk): naming contracts, CLI and UI * [browse](https://github.com/paritytech/browse): the discovery directory * [dotli-community](https://github.com/paritytech/dotli-community): the web gateway * [paseo-network/runtimes](https://github.com/paseo-network/runtimes): chain runtimes **Polkadot app clients** * [Android](https://github.com/Polkadot-Community-Foundation/polkadot-android-community) · [iOS](https://github.com/Polkadot-Community-Foundation/polkadot-ios-community) · [Desktop](https://github.com/Polkadot-Community-Foundation/polkadot-desktop-community) **Reference Products** * [Calculator, Stopwatch, Countdown Timer, Alarm Clock, Chess Clock and Unit Converter](https://github.com/paritytech/browse/tree/main/apps/registry/tests/fixture-projects): the reference apps above * [playground-app-template](https://github.com/Polkadot-Community-Foundation/playground-app-template): a starter app on the Product SDK ## Protocol background For the underlying Polkadot protocol, tooling and network concepts, see the official [Polkadot developer documentation](/). # Register a .dot Domain > Register a .dot domain with dotNS, covering name rules, the commit-reveal flow, the three CLIs that can register a name, and managing your name. ## Introduction Every published Polkadot Product is reached by a dotNS name, such as `awesome.dot`. That name is registered with [dotNS](/reference/apps/infrastructure/dotns/), Polkadot's decentralized, on-chain name service. dotNS turns a human-readable name into the Product bundle it points at, and it is the lookup every Host runs when a user navigates to it. TestNet names end in `.paseo`, not `.dot` dotNS top-level domains are per network. On Paseo Next v2, the TestNet the Apps tooling targets by default, names are minted under `.paseo`: publish `myproject57` and you get `myproject57.paseo`, served at `https://myproject57.paseo.li`. Whether you supply the bare label or the full name depends on the tool; see [Choose a Name](/apps/register-dot-domain/#choose-a-name). The registry (names, owners, and the content record each name points at) lives as contract state on Polkadot Hub. Resolution runs `name → namehash → contenthash → CID`: the name hashes to a deterministic key, the record's `contenthash` points at your bundle's CID, and the Host fetches and content-verifies the bundle before loading it. Registration happens on chain, so the name rules below hold whichever tool you use. Three CLIs can register a name: the [`playground` CLI](/apps/quick-start/) folds it into a deploy, `pad` publishes a built bundle and registers its name in one command, and the [dotNS CLI](/reference/apps/infrastructure/dotns/cli/) drives the registry directly. This guide explains how to choose a name your account is allowed to register, which path to take, and how to manage the name afterward. Products Devnet This page uses Paseo Next v2 (`paseo` preset). For the PCF Products Devnet (`devnet` preset), see [Register a .dot domain](/apps/build/register-a-dot-name/). ## Prerequisites Before registering, ensure you have: * Completed [Install Desktop and Pair](/apps/get-started/) and [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/); your account needs PAS to pay fees and any name deposit. * One of the CLIs in [Ways to Register](#ways-to-register) installed. On the `playground` path that means `pg login` has paired it with your signer. * A Product project ready to deploy, if you are registering as part of a deploy with `playground` or `pad`. Registering with the dotNS CLI needs no bundle. See [Deploy Your App](/apps/deploy-your-app/). ## Choose a Name A name is a bare label plus the network's TLD, as in `johnsmith57.paseo`. How you supply it depends on the tool: `playground` and the dotNS CLI take the bare label (`johnsmith57`) and append the TLD for you, rejecting a label that already carries a different one, while `pad` takes the full name. ### Label Rules A label must satisfy all of these, or registration is rejected before anything is submitted on chain: * **Length**: 3 to 63 characters. * **Character set**: lowercase letters, digits, and dashes (`a-z`, `0-9`, `-`) only. * **Dashes**: cannot start or end with a dash. * **Digits**: allowed anywhere, in any quantity. A trailing run of digits no longer carries any special meaning. Out-of-date tooling is stricter Releases built against the previous label rules cap a trailing run of digits at two and reject a longer one, which the chain no longer does. `@parity/dotns-cli` lifted the cap in `0.9.0`. If a label with three or more trailing digits is refused before anything is submitted on chain, update your tooling rather than changing the name. ### Length Bands Which band a name falls into depends on its length, counted as written. Digits count like any other character: | Length | Requirement | | ---------------------- | ------------------------------------------------- | | 9 characters or longer | Open to everyone, with no personhood check | | 6 to 8 characters | Not sold on this path; earned in the Polkadot App | | 5 characters or fewer | Reserved for governance, not sold on this path | So `johnsmith57` is open to anyone because it is 11 characters, and so is `johnsmith` at exactly nine. `johnny` and `johnny01`, at six and eight characters, cannot be registered on this path whatever personhood status the account holds, and neither can `john` at four. `johnny` can still be earned as a personhood name in the Polkadot App. `johnny01` cannot be earned there either, because a gateway name never carries digits without a separator. Adding digits no longer lowers the tier a name demands: it only makes the name longer, which can move it into the open band. The six-to-eight band is closed on this path by a governance switch in `PopRules`, which is off by default. While it is off, registering a name of that length fails with `Short names are not for sale`. Every name this path admits pays the same refundable deposit, whatever its length. See the [PopRules and Pricing reference](/reference/apps/infrastructure/dotns/poprules-pricing/) for the bands and the deposit. Personhood and the network Proof of Personhood is obtained in the Polkadot App on your device; there is no CLI path to a tier. On this path, pick a name of nine characters or more, which registers with no personhood check. A name of six to eight characters is available only as a device or personhood name, such as `johnny.42` or `johnny`, which is earned through the personhood gateway rather than registered here. See [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/) for how names, deposits, and personhood interact on TestNet. ## Ways to Register All three CLIs write to the same registry, so the name rules above apply identically to each. They differ in how much of the deploy they own: | Tool | Best for | What it does | | :--------------------------------------------------: | :-----------------------------------------: | :--------------------------------------------------------------------------------------------: | | [`playground`](/apps/quick-start/) | A first Product, and hackathons | Registers the name as one step of an interactive `playground deploy` | | `pad` | Scripted or CI deploys of a built bundle | Uploads the bundle, registers the name if needed, and writes the content record in one command | | [`dotns`](/reference/apps/infrastructure/dotns/cli/) | Managing names on their own, with no deploy | Registration, lookups, content records, transfers, subnames, and escrow | The choice is not permanent. A name registered by any of them is an ordinary name owned by your account, and the others operate on it afterward. ## Register with the `playground` CLI When you run `playground deploy` and reach the `domain` prompt, enter the name you want: ``` domain › johnsmith57█ ``` From there, the CLI registers the name on chain. If you deploy with the phone signer, each on-chain step is a separate approval in the Polkadot App, in this order: 1. **Reserve domain**: Submits a dotNS commitment for the name without revealing it in the clear. 2. **Finalize domain**: Claims the name for your account. 3. **Link content**: Points the name's `contenthash` at your uploaded bundle's CID, so the name now resolves to your Product. The \~60-second pause is expected Between reserve and finalize, the deploy pauses for about 60 seconds. Most of that is the tooling waiting for the commitment to settle: the contract requires only that the commitment be six seconds old before the name is claimed. The two-step handshake is what stops a watcher seeing your desired name and racing to register it ahead of you. The deploy is not stuck. An abandoned commitment expires after a day A commitment is valid for one day. If a deploy fails between reserve and finalize and you come back later than that, the commitment is no longer claimable and the handshake starts over from the beginning. Names are first come, first served. If the CLI reports that a name is [already registered](/apps/troubleshooting/#the-name-is-already-registered), choose another; if it reports that [short names are not for sale](/apps/troubleshooting/#short-names-are-not-for-sale), pick a name of nine characters or more. With the dev signer, these steps run without phone prompts; the deployed name is owned by the shared dev account rather than by you. ## Register with `pad` [`polkadot-app-deploy`](https://github.com/paritytech/polkadot-app-deploy) publishes a built bundle and registers its name in a single command, which suits a scripted or CI deploy: ```bash npm i -g @parity/polkadot-app-deploy pad ./dist johnsmith57.paseo --mnemonic "$MNEMONIC" ``` `pad` uploads the bundle to the Bulletin Chain, skipping unchanged blocks on repeat deploys, registers the name if you do not already own it, and writes the content record on Polkadot Hub. It also has a `login` mode: on TestNet a local worker registers the name and then transfers it to the signed-in account, so the deploy runs without phone taps unless you pass `--no-transfer-to-signedin-user`. `pad` does not read the dotNS keystore, so supply the key explicitly when you are not using `login`. Keep the mnemonic out of your shell history Pass the phrase through an environment variable, never as a literal on the command line, and never commit it. A deploy key that registers names controls them. Node 22 or newer `pad` requires Node 22+ and fails at startup on older versions with an unrelated-looking error. It also describes itself as a prototype reference implementation, so check `pad --help` against the version you installed before scripting around it. ## Register with the dotNS CLI The [dotNS CLI](/reference/apps/infrastructure/dotns/cli/) registers a name on its own, with no bundle and no deploy involved. Reach for it when you want to hold a name before the Product is ready, script a batch of names, or debug a registration that failed. From `1.0.0`, the CLI targets Polkadot by default, where a registration spends DOT. To register on the TestNet this guide uses, set `DOTNS_ENV=paseo-v2` or pass `--env paseo-v2` on each command: ```bash npm i -g @parity/dotns-cli export DOTNS_ENV=paseo-v2 dotns register domain --help ``` Registration runs the same commit-reveal handshake described above, so expect a comparable pause whichever tool drives it. The CLI can also preview `PopRules` eligibility for a proposed name and account, showing the band and the deposit before you submit. Check the flags against your version The dotNS CLI's per-command flags are still being confirmed against the published package, which is why the [CLI reference](/reference/apps/infrastructure/dotns/cli/) lists command families rather than a flag table. Run `--help` on the version you installed rather than copying flags from elsewhere; the PCF publishes its own build of this tool under a different scope, and the two are not interchangeable. ## Update the Bundle a Name Points At Registration binds the name to your account once. Publishing a new version of your Product does not re-register the name; it updates the name's `contenthash` to the new CID. Every path handles this the same way, and re-running against a name you already own skips the reservation steps, so later deploys need fewer approvals: * **`playground`**: Re-run `playground deploy` against the same name. * **`pad`**: Re-run the same command; it uploads only the changed blocks and rewrites the content record. * **`dotns`**: Set the record directly with the CLI's `content set` command once you have the new CID, targeting the same network you registered the name on. Because a name's content record is mutable and the owner can transfer or repoint it, treat a name as a pointer rather than a permanent identity. Code that consumes another Product should verify the `contenthash` it resolves at use time, not assume a name maps to the same bundle forever. ## Manage Your Name Everything past registration is the [dotNS CLI](/reference/apps/infrastructure/dotns/cli/)'s job. A deploy tool repoints the one name it just published; `dotns` operates on any name your account owns: * **Transfer**: A name registered on this path is owned by a Polkadot Hub account and can be transferred to another account. A transfer changes only the owner; the name and its current content record are unchanged, so users keep seeing the same bundle until the new owner updates it. Proof of Personhood status and reservations do not transfer with the name. A device or personhood name cannot be transferred at all, and some moves carry a fee. See the [transfer reference](/reference/apps/infrastructure/dotns/transfer/). * **Subnames**: The dotNS CLI can register subnames under a name you own. * **Content records**: The dotNS CLI can view and set a name's content record outside a deploy. These CLIs are still moving `@parity/dotns-cli` is in active development with breaking changes expected between versions, and `pad` describes itself as a prototype reference implementation. Both work today; treat the commands here as a snapshot and confirm them with `--help` before depending on them in a pipeline. ## Where to Go Next * **Deploy Your App** *** The full deploy flow that registers your name and uploads your bundle in one pass. [→ Deploy Your App](/apps/deploy-your-app/) * **List Your App** *** Once your name resolves, list your Product so others can discover it. [→ List Your App](/apps/list-your-app/) * **dotNS Reference** *** The name mechanism, PopRules pricing, contract architecture, and transfer model in depth. [→ Reference](/reference/apps/infrastructure/dotns/) # Troubleshooting > Named fixes for the errors developers hit building and deploying Polkadot Products — allowances, unannounced phone prompts, deploy pauses, and more. Named entries for the failures developers hit most while building and deploying Polkadot Products. Each one states the cause and the resolution. Who operates each environment Polkadot Products can target environments run by two different operators. Each operator deploys, maintains, and supports its own environment, so report a problem to the operator of the environment where it occurs. See [Choose the Right Channel](/get-support/#choose-the-right-channel) for where to ask. * **Parity**: Runs Paseo Next v2 (the `paseo` preset, parachain 1500) and the services on it, including dotNS and the Playground directory, and maintains the `playground` CLI these docs use. Parity publishes development builds of Polkadot Desktop on the [`polkadot-desktop-community` releases page](https://github.com/paritytech/polkadot-desktop-community/releases) and nightly Android builds of the Polkadot App on the [`trinity-user-agents` releases page](https://github.com/paritytech/trinity-user-agents/releases/tag/nightly-android). Ask about Paseo Next v2 or Parity's tools through [Polkadot Developer Support](/get-support/#support-channels), or report bugs in the tool's own GitHub repository. * **Polkadot Community Foundation (PCF)**: Operates Products Devnet (the `devnet` preset) and everything on it, including its chains, registries, and deployments, using open-source technology developed by Parity. PCF also publishes its own builds of the Polkadot App, including the Google Play app, and of Polkadot Desktop, and the `pad` tooling that publishes to Browse. Parity does not operate these services; report issues with them in PCF's [`products-devnet-issues` repository](https://github.com/Polkadot-Community-Foundation/products-devnet-issues) or ask in `#devnet-discussion` on the [Polkadot Discord server](https://discord.com/invite/eD4jMYbC5U). ## `no allowance set for account` **Cause**: [Allowances](/apps/concepts/allowances/) are granted per account. This error means the account that actually signed the request has no allowance — almost always because the allowance was granted to a *different* account than the one signing. Common ways this happens: you funded a dev key but signed with your phone account (or the reverse), or your Product derived its [per-app account](/apps/concepts/accounts/) under a different `productId` than the one you granted the allowance under (for example, running from `localhost`, which derives under `playground.dot`, versus a `.dot.li` URL, which derives under `.dot`). **Resolution**: 1. Determine which account actually signs. A Product running inside a Host can read its product account address (SS58 and H160) through the [`signer`](/apps/product-sdk/signer/) package; surface it in your dev UI. See [Accounts and Signing](/apps/concepts/accounts/#see-the-signing-address). 2. Grant the allowance (or storage authorization) to *that* account. See [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/). 3. Keep the `productId` consistent between where you request the allowance and where you sign, so the same account is used throughout. ## The App Seems Frozen After an Action **Cause**: Signing happens on your phone, and there is no push notification telling you the phone is waiting. After you trigger a signable action, the interface can look stuck while an approval prompt sits unopened in the Polkadot App. **Resolution**: Open the Polkadot App and check for a pending approval. Approve or reject it there, and the flow continues. When building, show a non-blocking "check your phone" state after any signable action rather than a spinner that looks frozen. See [Sign and Submit Transactions](/apps/build/sign-and-submit/) for designing around cross-device signing latency. ## The Deploy Pauses for About a Minute **Cause**: During `playground deploy`, there is a deliberate pause of about 60 seconds between reserving and finalizing your dotNS name. Most of that is the tooling waiting for the commitment to settle; the [dotNS](/apps/register-dot-domain/) contract itself requires only that the commitment be six seconds old. The two-step handshake prevents someone from front-running your name. **Resolution**: Wait. The deploy is not stuck. The next approval appears in the Polkadot App once the window elapses. ## Short Names Are Not for Sale **Cause**: Registering a name of eight characters or fewer fails with `Short names are not for sale`. The public registration path that `playground`, `pad`, and the dotNS CLI use sells only names of nine characters or more. The six-to-eight band is closed by a governance switch in `PopRules`, which is off by default, so [Proof of Personhood](/apps/concepts/identity/) does not open it. A name of five characters or fewer stays closed on this path even when the switch is on, because it is reserved for governance. Length is counted as written, so digits do not change which band a name falls in. **Resolution**: Choose a name of nine characters or more. A name of six to eight characters is available as a personhood or device name, earned in the Polkadot App. See [Register a `.dot` Domain](/apps/register-dot-domain/#choose-a-name). ## The Name Is Already Registered **Cause**: dotNS names are first come, first served. **Resolution**: Choose a different name. Re-deploying a name you already own is fine and does not conflict. ## Uploads Are Rejected or `Host storage unavailable` **Cause**: Two different problems share this symptom. Storing on the Bulletin Chain requires an explicit storage authorization on the signing account — without it, the store is rejected regardless of your token balance. Separately, `Host storage unavailable` means code that needs a Host is running outside one. **Resolution**: Request a storage authorization for the signing account (see [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/)), and confirm you granted it to the account that actually signs (see the allowance entry above). For `Host storage unavailable`, run your Product inside [Polkadot Desktop](/reference/apps/hosts/polkadot-desktop/), or use the SDK's dev and testing paths for out-of-Host development. ## The App Does Not Appear Right After Deploy **Cause**: On-chain state takes a short time to propagate after the deploy transaction finalizes, and the web gateway resolves your name through an in-browser light client. **Resolution**: Wait a few seconds and refresh. A `curl` or script against the gateway URL returns a generic gateway shell, not your app — open it in a real browser to see the resolved Product. If it still does not resolve after a minute, confirm the deploy finalized and check network status with the developer community. ## Connecting to a Chain Throws Outside a Host **Cause**: The [`chain-client`](/apps/product-sdk/chain-client/) routes every connection through the Host and has no direct-WebSocket fallback, so it throws when no Host provider is present. **Resolution**: Run your Product inside a Host. For out-of-Host development and tests, use the SDK's testing fakes rather than a live connection. See [Read On-Chain Data](/apps/build/read-chain-state/). # Build a Shared Todo App > Build a complete Polkadot Product end to end with a shared todo board that combines signing, local persistence, real-time pub/sub, and on-chain storage. ## Introduction Each [Build guide](/apps/build/) takes one `product-sdk` capability from zero to working code. This tutorial is the capstone: it combines four of them into one product, a Shared Todo Board where every participant sees changes live and the board survives durably on chain. What you will build, and which package carries each part: | Capability | Package | Role in the app | | :------------------: | :----------------------------------------: | :---------------------------------------------------------------------------------------------------------------------: | | Identity and signing | `signer` (via the umbrella's `wallet` API) | Connect to the Host and get the account that authors and signs everything | | Local persistence | `local-storage` | The board renders instantly from the device's last known state | | Real-time sharing | `statement-store` | Every mutation gossips to other participants as a signed statement | | Durable storage | `cloud-storage` | Snapshots of the board live on the [Bulletin Chain](/reference/apps/infrastructure/bulletin-chain/), addressable by CID | ![The Shared Todo Board running inside Polkadot Desktop, with the connected account in the header, a synced todo list, and the latest snapshot CID in the footer](/images/apps/tutorials/shared-todo-app/shared-todo-app-01.webp) The guides cover the individual calls. This tutorial focuses on how the layers compose. Statements are capped at 512 bytes and expire after 30 seconds, so they carry individual mutations, not the whole board. The Bulletin Chain holds full snapshots, and a last-write-wins channel announces the latest snapshot's CID. This is the same split [Polkadot App](/reference/apps/hosts/polkadot-app/)'s Chat uses: gossip for signaling, Bulletin for content. The code here targets `@parity/product-sdk` v0.30.0. It was written against `@parity/product-sdk-statement-store` v0.6.7 and `@parity/product-sdk-cloud-storage` v0.11.1, and every symbol it imports from them is still exported in v0.6.12 and v0.12.2. It needs at least `product-sdk` v0.30.0, the release that takes the Product's identity from the Host, and `statement-store` v0.5.0, which introduced the sponsored host-signing path. Upgrading from an SDK before 0.18.0 Version 0.18.0 moved several calls this app uses from throwing (or returning a bare value) to returning a typed `Result`: `app.cloudStorage.upload` and `.fetch`, `checkAuthorization`, and `StatementStoreClient.publish` and `ChannelStore.write` (previously `Promise`). Code written against an earlier release keeps compiling in places but stops working, because a `Result` object is always truthy, so `if (!accepted)` on a publish never fires, and `if (!status.authorized)` always does. The snippets below check `.ok` throughout. If you are porting older code, audit every call site rather than trusting it to fail loudly. ## Prerequisites Before starting, ensure you have: * Node.js 20 or later. * Polkadot Desktop installed and paired. See [Install Desktop and Pair](/apps/get-started/). * A statement allowance and a Bulletin Chain storage authorization for your wallet account. See [Get TestNet Tokens](/apps/get-started/get-testnet-tokens/) and the [Bulletin Chain authorizations](https://paritytech.github.io/polkadot-bulletin-chain/authorizations) reference. Without the storage authorization, snapshot uploads are rejected. * The individual [Build guides](/apps/build/) are optional but helpful because they cover each capability in more depth. ## Scaffold the Project Create a Next.js app and install the SDK: ```bash npx create-next-app@latest shared-todo-board --typescript --tailwind --eslint --app --no-src-dir cd shared-todo-board npm install @parity/product-sdk @parity/product-sdk-statement-store @parity/product-sdk-cloud-storage ``` Three dependencies, for three reasons: * **`@parity/product-sdk`**: The umbrella package. It re-exports the wallet, local-storage, and cloud-storage capabilities this app uses, plus the React provider. See [Umbrella or Individual Packages](/apps/build/#umbrella-or-individual-packages) if you would rather install per-capability packages. * **`@parity/product-sdk-statement-store`**: The pub/sub client. It is not re-exported by the umbrella, so it is always its own dependency. * **`@parity/product-sdk-cloud-storage`**: Installed explicitly because the app imports `CloudStorageClient` and `getBulletinAllowanceStatus` directly for its allowance pre-flight; relying on the umbrella's transitive copy would depend on npm hoisting. If the build fails on `@polkadot-api/json-rpc-provider` Earlier SDK releases had transitive dependencies pinning `@polkadot-api/json-rpc-provider@0.0.1`, which npm hoisted to the top of `node_modules` and broke the build. The current dependency tree resolves `0.2.0` throughout, so no workaround should be needed. If you do hit it, declare `@polkadot-api/json-rpc-provider@^0.2.0` as a direct dependency to force the resolution — no `overrides` or patching required. Wrap the app in `ProductSDKProvider` so every component can reach the SDK through `useProductSDK()`: ```tsx 'use client'; import { ProductSDKProvider } from '@parity/product-sdk/react'; import type { ReactNode } from 'react'; export function Providers({ children }: { children: ReactNode }) { return ( Initializing SDK…} > {children} ); } ``` Then mount it in the root layout. The inline script is a Polkadot Desktop workaround: it sets the host webview mark synchronously, so the SDK's container detection returns true before its bundle evaluates. It forces host mode unconditionally, which is acceptable here because every capability in this app needs the Host anyway. Drop the line if you want honest container detection — for a Product that renders a useful "open me in a Host" state instead of failing, say — but note that nothing in this app functions outside one: ```tsx import type { Metadata } from 'next'; import { Geist, Geist_Mono } from 'next/font/google'; import { Providers } from './providers'; import './globals.css'; const geistSans = Geist({ variable: '--font-geist-sans', subsets: ['latin'], }); const geistMono = Geist_Mono({ variable: '--font-geist-mono', subsets: ['latin'], }); export const metadata: Metadata = { title: 'Shared Todo Board', description: 'Build a Full Product tutorial companion app', }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( {/* Sets the mark synchronously so isWebview() returns true before the SDK bundle evaluates */}