// Use when writing tutorial documentation or create-leo-app examples for the Provable SDK (@provablehq/sdk). Covers how to structure runnable templates, write tutorial-style docs, and handle Node.js vs web runtime differences.
| name | provable-sdk-tutorial-docs |
| description | Use when writing tutorial documentation or create-leo-app examples for the Provable SDK (@provablehq/sdk). Covers how to structure runnable templates, write tutorial-style docs, and handle Node.js vs web runtime differences. |
This skill guides writing two interconnected artifacts for each SDK feature set:
The template and tutorial are the same content expressed two ways — step numbers, section names, and code structure must correspond exactly.
Require the developer to specify:
| Input | Description |
|---|---|
| Feature bucket | Explicit list of SDK features to demonstrate (e.g. "key caching, offline execution, deployment") |
| Target runtimes | node, web, or both |
| Highlight areas | What concepts readers should leave understanding — not just what the code does, but WHY |
| Complexity level | beginner / intermediate / advanced — determines how much Aleo/ZK background to assume |
Tutorials must open with context about why someone would use the SDK in this environment. Use the framing below as a guide.
The SDK runs natively in Node — no WASM worker setup needed. Common use cases:
In browser contexts, the SDK is most commonly used to supplement features that wallet adapters don't yet provide. The aleo-wallet-adapter handles account management and basic transaction signing — developers reach for the SDK directly when they need:
Web tutorials must recommend using aleo-wallet-adapter alongside the SDK for account/signing concerns, transaction execution and should show how the two integrate where relevant. Do not suggest the SDK replaces the wallet adapter on the web.
WASM runs in a Web Worker in browsers, this is optional but highly recommend. Every web template should at least suggestion the worker pattern.
template-node-*-ts)src/index.ts # Main entry point
src/** # Any other files that make sense to box different required functionality.
package.json # yarn start runs src/index.ts
.env.example # Any required secrets or endpoints
Use top-level await, initialize thread pool at the top: await initThreadPool();
Organize into named async functions, one per feature.
Use section headers matching tutorial step numbers:
// --- STEP 1: Initialize key provider and cache keys. --- //
yarn start must run successfully without modification (offline features) or with only .env filled in (network features)
template-react-*-ts)The wallet adapter has this API here:
and for web examples, this should be used to do the following.
executeTransaction method)createAccount method)transactionStatus method)decrypt method). Note this does not do arbitrary encryption and decryption schemes, only decryption of transition inputs and outputs.requestRecords method)executeDeployment method)React environments should look here for context on how to invoke wallets via react: https://github.com/ProvableHQ/aleo-dev-toolkit/blob/master/packages/aleo-wallet-adaptor/react/src/WalletProvider.tsx
For most create leo app examples (for now) there should be the ability to execute any of the above functions optionally via the wallet AND via native SDK methods (where the wallet is preferred).
src/
App.tsx # UI — calls worker, manages state
** # Any other files that make sense to organize functionality and features.
workers/AleoWorker.ts # All SDK calls go here, exposed via Comlink
vite.config.ts
.env.example
@provablehq/sdk imports and calls live in AleoWorker.ts — never in App.tsxApp.tsx or any other file calls them like async functionsinitThreadPool() runs inside the worker, not in the main threadaleo-wallet-adapter for account connection; the SDK worker handles the supplemental operations@provablehq/sdk/testnet.js or /mainnet.js — never the bare package} catch (e) {
throw new KeySynthesisError(`Failed to synthesize keys: ${e}`);
}
For each feature in the bucket:
yarn start print? What does the UI show?Every tutorial follows this shape:
What the reader will build. Which features from the bucket are covered. Link to the template.
Why a developer would use the SDK in this runtime for this use case. Reference the framing from the Runtime Context section above. For web tutorials, mention aleo-wallet-adapter and its relationship to the SDK.
.env values and where to get themaleo-wallet-adapter is needed for account connectionPlain-English explanation of each feature before showing code. This is where Highlight Areas from the developer's inputs go. Assume only the complexity level specified — don't assume ZK/cryptography knowledge for beginner tutorials.
One section per step, numbered to match the template's section headers. For each step:
Exact commands. Expected output copied from an actual run.
Links to related templates, the wallet adapter docs (web only), and relevant SDK API docs.
Third person replacing "you" with appropriate 3rd party nouns, tutorial style: "callers should notice...", "this tells the SDK to...", "here the keys are cached because...". Not API reference style. Not first person.
initThreadPool() — why it exists, what happens without itkeyProvider.cacheKeys(...) — why caching matters (proving key synthesis is slow)OfflineQuery — what it replaces and when to use itbuildDeploymentTransaction vs deploy — the distinction between building and submittingBefore the tutorial is done:
yarn start without modification (or only .env needed).env.example provided for any secrets or endpointsaleo-wallet-adapter and its role