Colibri documentation · SDK source · Published packages
Runnable, commented lessons for Colibri and Stellar. Each script shows the actual SDK calls, account roles, and transaction steps. Start with one file and its README. Variants are separate commands, not branches in a large demo runner.
The React web examples runs 29 focused Testnet lessons covering Colibri's 33 React hooks, with Wallets Kit, live controls and step-by-step explanations and feature documentation links. Requires Deno 2.9.6+. Run it from its own directory:
cd examples/web
deno task install
deno task devOptional deno task setup prepares Testnet fixtures. The dev command starts the
local authentication fixture too; deno task auth runs it separately when
needed. The web app uses its own dependency scope and lockfile; the CLI lessons
below keep their existing versions.
Install Deno 2.7.11 or newer, clone this repository, then:
deno install
cd getting-started/native-payment
deno task paymentTransaction and authentication lessons use Testnet, disposable generated keys, and Friendbot test XLM where funding is needed. The existing event-streamer lessons only READ public Mainnet data and never sign or submit transactions. Do not insert production keys or replace Testnet with Mainnet. Public endpoints and Testnet state may change or reset.
Contract lessons include Wasm artifacts, so normal runs need no Rust or Stellar CLI. Rebuild commands are optional and require Rust, the wasm32v1-none target, and a compatible Stellar CLI. Docker is needed only for the local-ledger and build-verification lessons, not for delegated signers or SEP-45.
Dependencies are declared by the Deno workspace and locked in deno.lock. Each lesson records its required Colibri versions; generated bindings use Core 1.1. The examples use Stellar JS SDK 17. Keep native SDK objects such as Operation, Asset, Memo, Spec, and XDR values visible at the integration boundary.
| Lesson | What you learn |
|---|---|
| Native payment | Native operations, a callable pipeline, configuration, confirmed outcomes |
| Generic contract | Wasm versus instances, spec loading, simulated reads, committed writes, raw XDR, named contract errors |
| Generated contract bindings | Generate and inspect a package, then use typed calls, custom values, errors and events |
| SAC transfer | Transfer XLM through its Stellar Asset Contract |
| SAC asset issuance | Native trustline setup plus contract-backed minting |
| Handling errors | Identify a Colibri error and inspect diagnostic metadata |
| Lesson | Independent commands / concepts |
|---|---|
| StellarAsset | Mint/transfer/burn; issuer authorization; clawback |
| SEP-41 token | Approve an allowance, then transfer as the spender |
| SDEX | Sell and buy offer lifecycles; explicit price units and exact ratios |
| Liquidity pool | Share trustline, labelled deposit, position, bounded withdrawal |
| Claimable balances | Recipient claim before expiry; sender refund afterward |
Market lessons use a freshly issued asset and explicit limits. They do not discover prices, index an order book, or choose financial policies for users.
| Lesson | What you learn |
|---|---|
| Fees | Per-operation base, exact inclusion, Soroban total cap; bid versus actual charge |
| Soroban resources | Absolute overrides, amount/percentage padding, and an explicit network-priced calculator |
| Fee bump | Separate payment authority from the outer fee payer |
| Channel accounts | Independent sequence numbers; a separate advanced fee-bump/muxed composition |
| Reserve sponsorship | Explicit native begin/end sponsorship and trustline ownership |
| SEP-29 memo guard | Native Memo plus opt-in pre-submission memo-presence checks |
Pipelines are callable:
const sendPayment = createClassicTransactionPipeline(...), then
await sendPayment(...). Attach plugins with sendPayment.use(...) and
continue using the original callable.
| Lesson | What you learn |
|---|---|
| Delegated signers | Direct, recursive, deeply nested, and branching Soroban authorization |
| Hash-X | Require a preimage in addition to normal transaction authorization |
| Signed payload | D reveals the signature needed for a separately finalized C |
| Preauthorized transaction | Install one exact transaction hash and verify one-shot removal through RPC |
| WebAuth | SEP-10 account login; SEP-45 custom contract-account login |
| Message signing | Offline SEP-53 signature verification |
These demonstrate protocol primitives, not complete custody, multisig, exchange, or production authentication policies.
| Lesson | What you learn |
|---|---|
| Test recorder | Real Testnet tests with silent recording, console summaries, JSON, and standalone HTML |
| Local test ledger | Direct Docker-backed test setup, plus optional reusable-ledger/logging tasks |
| Build verification | GitHub out-of-band rebuild, strict SEP-58 Testnet target, JSR CLI summary/evidence |
| Contract metadata | Declared SEP claims versus independent structural interface matching |
| Event streamer | Live and archived Soroban event ingestion |
| Transaction streamer | Finite transaction and successful native-payment slices |
| Identicon | Offline deterministic SVG/PNG rendering |
deno task check
deno task lint
deno task fmt:checkThe check task first generates the ignored package for the bindings lesson, then type-checks the examples. These commands do not submit transactions. To exercise behavior, run the individual lessons. The local-test-ledger and test-recorder subprojects contain tests because those lessons explicitly teach testing. The recorder lesson requires Deno 2.9.6+ and uses real public Testnet endpoints.
Start each README with what the lesson teaches and the Stellar concept behind it. Explain setup, give each independent path its own command, link the source, and tell the reader what output to expect. Keep optional rebuilds separate from the normal walkthrough and link to the SDK docs for wider API details.
Keep one learning objective per file. Declare ordinary configuration and signer values in the lesson, call Colibri directly, and comment on both what happens and why Stellar requires it. A small deployment helper is acceptable; a shared wrapper that hides the feature being taught is not. Keep genuine validation and cleanup guards, separate independent variants, and document expected results and limitations. Never commit private keys or generated JWTs.
Write for someone learning both Stellar and Colibri:
- Place explanations before the line or block they describe. Use an end-of-line comment only for a short annotation. Do not put explanatory comments after the action.
- Leave one blank line between conceptual steps, including inside callbacks. Keep related fields and declarations together so spacing reflects the lesson, not every individual line of syntax.
- Name intermediate values when they explain a distinction: an offer effect versus an offer entry, raw balance units versus display text, or an authorization preimage versus its signature. Keep the native SDK types.
- Prefer a linear flow and short guards to nested conditionals. Use try/catch for the error being taught and try/finally for required cleanup; do not hide the workflow in helpers or promise chains just to make the entrypoint shorter.