An educational project on Stellar (classic assets), built to teach developers the full spectrum of issuer control — from a bare, ungoverned promise to a regulated stablecoin the issuer can freeze and claw back, to an asset whose price is controlled by no account at all (a liquidity pool) — by issuing one asset and walking it across the whole spectrum.
The asset is cBRL, a fictional, testnet-only BRL-pegged community stablecoin issued by a "casa da
moeda comunitária". You issue it, gate it, freeze and claw it back, lock the issuer for a fixed supply,
then make it liquid against a mock US-dollar asset in Stellar's native AMM.
Audience: developers. No Rust or smart contracts required — this is the base protocol. Format: a project explored across 3 classes, built incrementally. Network: Stellar testnet (a hard guard refuses to run against public).
Most "what is a token" explainers stop at fungible vs. non-fungible, or jump straight to smart contracts. This project teaches the control spectrum because every classic-asset mechanism lands on a different point of it:
| Point on the spectrum | Position | What it teaches |
|---|---|---|
| Trustline | Holder sovereignty | Nothing reaches you without your consent (changeTrust). |
| Basic issued asset | The bare promise | Identity is CODE:ISSUER; supply is unbounded; backing is trust. |
| Auth flags / freeze | Issuer authority | The issuer gates (AUTH_REQUIRED) and freezes (AUTH_REVOCABLE). |
| Clawback | Issuer authority (max) | The issuer seizes a balance — but not retroactively. |
| Locked issuer | Renunciation | masterWeight: 0 → fixed supply, irreversibly. |
| AMM / pool | Control ceded to code | Price is a formula x·y=k, not an account's decision. |
This table is the spine of the whole course. See docs/control-spectrum.md.
The through-line question, on every deck: "Quem controla este ativo, e onde essa autoridade está codificada?"
| Document | What's inside |
|---|---|
docs/control-spectrum.md |
The conceptual spine: the axis and where each mechanism sits. |
docs/architecture.md |
The three accounts, the asset, the flag/authority map, and the op modules. |
docs/decisions.md |
Decision log — what was decided and why (ADR-style, D1…D15). |
docs/issuance-and-supply.md |
Supply, the peg, backing, and the numbers behind asset.config.ts. |
docs/bootstrap-and-issue.md |
Account setup, the issue order (flags → trustlines → distribute → pool). |
docs/frontend-and-testnet.md |
Frontend stack, wallet, and testnet notes. |
docs/glossary.md |
Shared vocabulary (issuer, trustline, authorize, freeze, clawback, AMM…). |
docs/implementation-plan.md |
Phased build plan, class branches/tags, and live status. |
Class 1 changeTrust · payment (issue + consent + distribute)
Class 2 setOptions(setFlags) · setTrustLineFlags · clawback · setOptions(masterWeight:0)
Class 3 changeTrust(pool share) · liquidityPoolDeposit · pathPaymentStrictSend · liquidityPoolWithdraw
Each is a thin builder in src/operations/ returning an unsigned operation; the
scripts and (later) the frontend inject signing. See docs/architecture.md.
npm install
cp .env.example .env # defaults already target testnet
npm run bootstrap # create + friendbot-fund issuer/distributor/user (writes .keystore.json)
npm run issue # issue + distribute cBRL from asset.config.ts (flags before distribution)Then run any class's acceptance check against testnet:
npm run reproduce:class-1 # issue + trustline + payment; forces & asserts op_no_trust
npm run reproduce:class-2 # authorize / freeze / clawback / lock; asserts each
npm run reproduce:class-3 # pool deposit + strict-send swap + withdraw; asserts price movedThe holder-facing dApp:
cd frontend && npm install && npm run dev✅ Complete — all 3 classes built and verified on testnet. Each reproduce:class-N runs green
end-to-end (issue + op_no_trust; authorize/freeze/clawback + the non-retroactive-clawback bug + the
irreversible lock; pool deposit + strict-send swap + withdraw). Cumulative branches
(class-1-emissao-trustlines … class-3-liquidez-amm; tags v0.1-consentimento … v0.3-mercado) mark
each checkpoint; main integrates everything, including the holder-facing frontend. See
docs/implementation-plan.md; open questions are at the bottom of
docs/decisions.md.
cBRLandUSDxare fictional, testnet-only assets used for teaching. They are not financial products.