| name | product-sdk-app-builder |
| description | End-to-end scaffolding and implementation of Polkadot applications using @parity/product-sdk packages. Use when: creating a new Polkadot project, building a dApp, scaffolding chain interactions, choosing which @parity/product-sdk packages to install, or when a user says "build me a Polkadot app". Handles both developer-guided and fully autonomous (non-developer) workflows.
|
Product SDK App Builder
Orchestrator skill for building applications with the @parity/product-sdk package ecosystem.
Quick Start
Preset Path (zero-config for known environments)
import { getChainAPI } from "@parity/product-sdk-chain-client";
const client = await getChainAPI("paseo");
const balance = await client.assetHub.query.System.Account.getValue("5GrwvaEF...");
client.destroy();
BYOD Path (Bring Your Own Descriptors)
import { createChainClient } 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 balance = await client.assetHub.query.System.Account.getValue("5GrwvaEF...");
client.destroy();
Workflow
1. Understand Requirements
Determine what the app needs:
- Read chain state (balances, storage, block info)
- Submit transactions (transfers, remarks, contract calls)
- Store data in Cloud Storage
- Real-time messaging via Statement Store
- Address utilities (SS58, H160 conversion)
- Encryption (AES, ChaCha20, NaCl)
- Key management (derivation, session keys)
2. Select Packages
Use the decision tree in references/package-selector.md.
Every app needs:
@parity/product-sdk-chain-client # Connect to chains
@parity/product-sdk-descriptors # Chain type definitions (peer dep of chain-client)
polkadot-api # Core runtime (peer dep of descriptors)
Add based on features:
| Feature | Package | Skill |
|---|
| Smart contracts (PolkaVM/Solidity) | @parity/product-sdk-contracts | product-sdk-contracts |
| Submit transactions | @parity/product-sdk-tx | product-sdk-transactions |
| Wallet connection (Talisman, Polkadot.js, Host API) | @parity/product-sdk-signer | product-sdk-transactions |
| Key derivation | @parity/product-sdk-keys | product-sdk-transactions |
| CLI sign-in (QR/mobile) + session signers | @parity/product-sdk-auth | product-sdk-transactions |
| Decentralized storage | @parity/product-sdk-cloud-storage | product-sdk-cloud-storage |
| Pub/sub messaging | @parity/product-sdk-statement-store | product-sdk-statement-store |
| Address encoding | @parity/product-sdk-address | product-sdk-utilities |
| Encryption | @parity/product-sdk-crypto | product-sdk-utilities |
| KV storage | @parity/product-sdk-local-storage | product-sdk-utilities |
| Logging | @parity/product-sdk-logger | product-sdk-utilities |
3. Scaffold Project
Use templates in references/project-templates.md.
mkdir my-polkadot-app && cd my-polkadot-app
npm init -y
package.json essentials:
{
"type": "module",
"dependencies": {
"@parity/product-sdk-chain-client": "latest",
"polkadot-api": "^2.0.2"
}
}
tsconfig.json essentials:
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"resolveJsonModule": true,
"isolatedModules": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"]
}
Install:
npm install
4. Implement
Invoke the relevant domain skill(s) based on the selected packages:
- product-sdk-chain-connection — for connecting and querying chains
- product-sdk-contracts — for smart contracts (ContractManager, createContract, ContractRuntime, codegen)
- product-sdk-transactions — for submitting transactions, signing, keys
- product-sdk-cloud-storage — for Cloud Storage
- product-sdk-statement-store — for pub/sub messaging
- product-sdk-utilities — for address, crypto, storage, logger
5. Build and Verify
npx tsc
node dist/index.js
Chain Client: BYOD vs Preset
@parity/product-sdk-chain-client offers two paths for connecting to chains:
| getChainAPI (Preset) | createChainClient (BYOD) |
|---|
| When | Known environments (paseo, polkadot, kusama) | Custom chains or a subset of chains |
| Descriptors | Built-in, lazy-loaded | You import and provide them |
| Chains | Always assetHub + bulletin + individuality | Any combination you choose |
| Bundle size | Slightly larger (all 3 chains loaded) | Minimal (only what you import) |
Use getChainAPI when you want zero-config connection to a standard environment.
Use createChainClient when you need:
- Only one chain (e.g., just Asset Hub for contracts)
- Chains not in the preset list
- Minimal bundle size
Both return the same ChainClient type with .raw access for advanced use (e.g., createContractRuntime).
Environments and Chains
See references/chains.md for full details.
WARNING: Only the "paseo" environment is currently available. Using "polkadot" or "kusama" will throw an error.
| Environment | Asset Hub | Bulletin | Individuality |
|---|
| paseo (testnet) | Yes | Yes | Yes |
| polkadot (mainnet) | Planned | Planned | Planned |
| kusama (canary) | Planned | Planned | Planned |
Common Mistakes
- Missing
polkadot-api — It's a peer dependency of @parity/product-sdk-descriptors. Always install it.
- Barrel import of descriptors — Use
@parity/product-sdk-descriptors/paseo-bulletin, NOT @parity/product-sdk-descriptors.
- Using unavailable environments — Only
"paseo" works. "polkadot" and "kusama" throw.
- Forgetting
await — getChainAPI() and createChainClient() return a Promise. Always await it.
- Not cleaning up — Call
client.destroy() or destroyAll() when done to close WebSocket connections.
- Using
api.contracts — There is no .contracts property on chain clients. Create ContractRuntime yourself: createContractRuntime(client.raw.assetHub, { atBest: true }), or use ContractManager.fromClient() for convenience.
- Dev signers in production —
createDevSigner("Alice") is testnet-only. Use SignerManager for production.
- Wrong signer type —
PolkadotSigner (tx), StatementSignerWithKey (statement-store), and SignerManager (wallet UI) are distinct.
Non-Developer Tier
When building autonomously for a non-technical user:
- Ask what the app should do (in plain language)
- Map requirements to packages using the selector
- Scaffold the project with all dependencies
- Implement all features using domain skills
- Build and test before presenting the result
- Include clear instructions for running the app
Developer Tier
When assisting a developer:
- Present the package selection rationale
- Show the project scaffold and let them review
- Implement features incrementally, explaining each step
- Reference the domain skill docs for API details
- Let the developer customize and extend
Resources
