From ef347fdf419a2a86bf6682ebacd606c3b370a35b Mon Sep 17 00:00:00 2001 From: Kaan Kacar Date: Tue, 11 Aug 2026 03:19:10 +0300 Subject: [PATCH 1/5] Split standards: SEP/CAP router + ecosystem.md + resources.md SKILL.md keeps the SEP/CAP routing map (129 lines) with a task-to-file table; Part 2 moves verbatim to ecosystem.md, Part 3 to resources.md. Cross-part references now link the companion files. --- skills/standards/SKILL.md | 739 +--------------------------------- skills/standards/ecosystem.md | 462 +++++++++++++++++++++ skills/standards/resources.md | 265 ++++++++++++ 3 files changed, 736 insertions(+), 730 deletions(-) create mode 100644 skills/standards/ecosystem.md create mode 100644 skills/standards/resources.md diff --git a/skills/standards/SKILL.md b/skills/standards/SKILL.md index b148f1f..9cae054 100644 --- a/skills/standards/SKILL.md +++ b/skills/standards/SKILL.md @@ -9,6 +9,14 @@ argument-hint: "[standards or ecosystem lookup]" Three things bundled because they're all reference material you reach for in the same moment: "which standard handles X?", "is there an existing project doing Y?", and "where's the canonical doc for Z?". +This file carries the SEP/CAP standards routing map. The other two live alongside it — **read the file that matches the task**: + +| Task | File | +|------|------| +| Pick the right SEP/CAP, check standard status, map a use case to standards docs | this file | +| Find DeFi protocols, wallets, dev tools, indexers, oracles, bridges, builder teams, funding programs | [ecosystem.md](ecosystem.md) | +| Locate official docs, SDKs, CLI tools, testing guides, RPC providers, learning resources, community links | [resources.md](resources.md) | + ## When to use this skill - Picking the right SEP for an integration (anchors, deposits, federation, deep links, KYC, paths) - Checking CAP status for a protocol feature you want to rely on @@ -23,7 +31,7 @@ Three things bundled because they're all reference material you reach for in the --- -# Part 1: SEP / CAP Standards Reference +# SEP / CAP Standards Reference ## When to use this guide @@ -119,732 +127,3 @@ Use the CAP preamble status fields as the source of truth for implementation rea - Advanced architecture guidance: [`../smart-contracts/development.md`](../smart-contracts/development.md) - RPC and data access: [`../data/SKILL.md`](../data/SKILL.md) - Security considerations: [`../smart-contracts/security.md`](../smart-contracts/security.md) - ---- - -# Part 2: Stellar Ecosystem - - -This guide catalogs the major projects, protocols, and tools in the Stellar ecosystem. Use this as a reference when building on Stellar to find relevant integrations, examples, and community projects. - -> **Canonical directories** — For the most up-to-date project lists, check: -> - [Stellar Ecosystem](https://stellar.org/ecosystem) — Official directory (searchable by country, asset, category) -> - [SCF Projects](https://communityfund.stellar.org/projects) — Funded projects with status tracking -> - [Stellar on DefiLlama](https://defillama.com/chain/stellar) — Live DeFi TVL data -> -> Treat project metrics/status as volatile. Validate latest activity and production readiness before taking dependencies. - -## DeFi Protocols - -### Lending & Borrowing - -#### Blend Protocol -Universal liquidity protocol enabling permissionless lending pools. -- **Use Case**: Lending, borrowing, yield generation -- **GitHub**: https://github.com/blend-capital/blend-contracts -- **GitHub (v2)**: https://github.com/blend-capital/blend-contracts-v2 -- **Integrations**: Meru, Airtm, Lobstr, DeFindex, Beans - -#### K2 -Money market on Soroban with a modular router architecture (Aave V3-inspired). Live on mainnet. -- **Use Case**: Supply to earn variable interest, borrow against collateral, collateral swaps, flash loans -- **Website**: https://k2lend.com -- **Docs**: https://docs.k2lend.com — agent-friendly: every page has a `.md` twin, plus [llms.txt](https://docs.k2lend.com/llms.txt) and a full corpus export at [llms-full.txt](https://docs.k2lend.com/llms-full.txt) -- **Position model**: per reserve, an **aToken** (interest-bearing supply receipt) and a **debt ledger** token; balances are `scaled balance x current index`, so they accrue without user action. Separate liquidity index (linear approximation per interval) and borrow index (full compound). The index updates on the first interaction with a reserve in a ledger. -- **Rates**: variable only, two-slope curve with a kink at optimal utilization (typically 80%). `Supply Rate = Borrow Rate x Utilization x (1 - Reserve Factor)`. Up to 64 reserves. -- **Risk**: liquidation threshold 65–85% by asset (85% stables, 65% volatile); health factor < 1.0 is liquidatable with no grace period; partial liquidation by default, 100% when HF < 0.5 or the debt/collateral leg is under $2,000. Liquidation bonus 10% for XLM/SolvBTC/wBTC. -- **Fees**: reserve factor typically 10–20%; flash loan premium 9 bps default; liquidation protocol fee 0.3% default. No deposit/withdraw/repay fees. -- **Oracle**: RedStone primary, Reflector fallback. Staleness rejection (1h default, per-asset override), 20% circuit breaker that keeps the last good price, zero-price rejection, and a global oracle pause. -- **Flash loans**: enabled per reserve plus a global kill switch; repay principal + premium in the same transaction or the whole thing reverts. -- **DEX integration**: Soroswap and Aquarius adapters power collateral swaps and flash liquidations. **Direct pairs only — no multi-hop routing**, so a swap fails if no direct pair exists. -- **Liquidation access**: whitelisted liquidators during the launch period, opening to permissionless over time — check current state before building a liquidation bot. -- **Audits**: Halborn, WatchPug, and a Code4rena contest; Hypernative for runtime monitoring. - -**Mainnet contracts.** `kinetic_router` is the entry point you call; the rest are the modules it routes to. - -| Contract | Address | -|----------|---------| -| `kinetic_router` | `CCTUJZLYFAW7ZNQD2SXMUZIHBUUJJICYRKWLZJ6SK6TGNAWNXOJIV6J7` | -| `configurator` | `CAYS7DTBBBG6TDT326KYTE72L6Q7NSEI2U2CA7TKCQIWPXB2GNJWU7M4` | -| `price_oracle` | `CCHRZE2K5TCERZLDO5IXDUWUKLRPVE72DI3TDF2RP6EQKEW6BNOMQRMU` | -| `interest_rate` | `CATBSCEN73MFGD4LCCC6SFJHGNEHC2QLSSXFZXFCW3NK45BBPGEYDXOC` | -| `treasury` | `CCQ4J5VLQHM2ORP4K7GBVAJJPK5SGG23DH4RD7QEHAZDHTN7JNESNXKZ` | -| `incentives` | `CAAMA46SQXQKHZDWAS2CNZVAX67TOMGBVH3DVSZSMDKKVP25VGTDQIRX` | -| `flash_liquidation` | `CACGHPQB2QOKNAPH3PVGKXXSULNGMNZYWVZQVPTHMWHFRXAGASSRNQ7H` | -| `reward_token` | `CA4V5C3KWDXBJEPIIKZT2PQWQZB4SY3G3G3S4PYPD5XXGXF5RKQUBE2N` | -| `soroswap_swap_adapter` | `CDL35ZAOYVDBMSTIKOF4HJKXA7MWHF5ZJNZKES6EAZAOOHLXURSGSYAJ` | -| `aquarius_swap_adapter` | `CBJBQMSBXYBOSRK6WLBAEVGF2GXQVPTYVVMVDGZF7ZBJHHFT2IGJNDMN` | -| `aquarius_multihop_swap_handler` | `CB3EHO42TDWT5EG6X62QTMPQPWIETVFLM7Q7DT62Z6MT5J4HP33XKXWE` | -| `solvbtc_composite_oracle` | `CABOR5KOCMIC226J5B63W5MV75VH5ZPAFEXZFET2JDD2H6IGJY5UPWP4` | - -**Reserve tokens.** Read a user's supply balance from the aToken and their debt from the debt ledger. The `underlying` column is the asset's SAC, not a K2 contract. - -| Market | Underlying (SAC) | aToken | Debt ledger | -|--------|------------------|--------|-------------| -| USDC | `CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75` | `CDHRPTO3NLGQ2CV75LFV6NF6ZMXIPGPID5GTAZTEICBYLMLKJICOMFZK` | `CBN4GDHRJN7AIARTSTUD3OK7IOCU5V6HTSOTVARFUA5KVE7XSNBZUQG6` | -| XLM | `CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA` | `CDTHJR27QWKAPCFTZWKP7GTX3RZO7HACVAC2KLCW2RENCMOCI35ORU5K` | `CC3OKG4VDLGFBS7V6UTSJVP3YL3A4OLV63EMTNUU3MQ2AOAU4M65H7QG` | -| PYUSD | `CCCRWH6Q3FNP3I2I57BDLM5AFAT7O6OF6GKQOC6SSJNDAVRZ57SPHGU2` | `CA7ELGRS4FNCYJPRZSNLF7NDD6VVOFZKFKMY56VVSG3RMNYTFQNNFUTD` | `CAVFE34MWBIXT4AOFXPTI7U7JTLPHKG4YWDDMRXVJOIZKG6HFJW3IHXV` | -| SolvBTC | `CBIJBDNZNF4X35BJ4FFZWCDBSCKOP5NB4PLG4SNENRMLAPYG4P5FM6VN` | `CDDTJ7OZU2WZAEZNTUZWIRAE4EMP5CF63M3INFQWTLX4ENMYUFK6RCTX` | `CADGKVZKBNLPKFIWDWTRSQAPBWH77H2OPJIF3WGVL7VADVLCXDZ5CSNH` | - -wBTC appears in K2's risk-parameter and liquidation tables as a supported asset but has no published reserve token set — treat only the four markets above as live. - -**External contracts K2 reads or routes through** (not K2-owned): Reflector Stellar mainnet DEX oracle `CALI2BYU2JE6WVRUFYTS6MSBNEHGJ35P4AVCZYF3B6QOE3QKOB2PLE6M`, Reflector external CEX/DEX oracle `CAFJZQWSED6YAWZU3GWRTOCNPPCGBN32L7QV43XX5LZLFTK6JLN34DLN`, RedStone batch adapter `CA526Y2NQWGWVVQ7RFFPGAZMU66PSYJ3UC2MTVAV4ZU7OM5BOPHDXUSG`. - -> Every address above was resolved on pubnet (2026-07-31). Legacy manual reserve tokens and published-but-uninstantiated WASM hashes are omitted; [docs.k2lend.com/contracts](https://docs.k2lend.com/contracts) is the source of truth — re-check it before hard-coding, since reserves and adapters can be added or rotated. - -#### Slender -First non-custodial lending protocol on Stellar with flash loan support. -- **Use Case**: Lending, borrowing, flash loans -- **Features**: Pool-based strategy, sTokens, dTokens, utilization caps -- **Oracle**: SEP-40 compatible (Reflector) - -### DEXs & AMMs - -#### Soroswap -First DEX and aggregator on Stellar. -- **Use Case**: Token swaps, liquidity provision, aggregation -- **Website**: https://soroswap.finance -- **GitHub (Core)**: https://github.com/soroswap/core -- **GitHub (Frontend)**: https://github.com/soroswap/frontend -- **GitHub (Aggregator)**: https://github.com/soroswap/aggregator -- **Docs**: https://docs.soroswap.finance -- **Features**: AMM + DEX aggregator across Aqua, Phoenix, Stellar Classic DEX - -#### Aquarius / AQUA Network -Governance-driven liquidity layer with AMM functionality. -- **Use Case**: Liquidity incentives, AMM, governance -- **Website**: https://aqua.network -- **GitHub**: https://github.com/AquaToken/soroban-amm -- **GitHub (Org)**: https://github.com/AquaToken -- **Token**: AQUA (governance + rewards) -- **Docs**: https://docs.aqua.network - -#### Phoenix Protocol -AMM protocol on Stellar. -- **GitHub**: https://github.com/Phoenix-Protocol-Group -- **Use Case**: Token swaps, liquidity pools - -### Yield & Vaults - -#### DeFindex -Yield aggregation and vault infrastructure by PaltaLabs. -- **Use Case**: Tokenized vaults, yield strategies, DeFi abstraction -- **Docs**: https://docs.defindex.io -- **Features**: Automated rebalancing, vault management, Blend integration - -### Stablecoins & CDPs - -#### Orbit CDP Protocol -Collateralized stablecoin issuance (USD, EUR, MXN). -- **Use Case**: Mint stablecoins against XLM/bond collateral -- **Docs**: https://docs.orbitcdp.finance -- **Features**: Multi-currency stablecoins, Pegkeeper automation, Blend integration - -## Wallets - -### Browser Extensions - -#### Freighter -SDF's flagship non-custodial browser wallet. -- **Website**: https://freighter.app -- **Docs**: https://docs.freighter.app -- **GitHub**: https://github.com/stellar/freighter -- **GitHub (Mobile)**: https://github.com/stellar/freighter-mobile -- **API**: https://github.com/stellar/freighter/tree/master/library/freighter-api -- **Features**: Smart contract support, mobile apps (iOS/Android), Discover browser - -#### xBull -Feature-rich browser wallet with advanced capabilities. -- **Website**: https://xbull.app -- **Features**: Multi-account, hardware wallet support - -#### Albedo -Lightweight web-based wallet and signing provider. -- **Website**: https://albedo.link -- **Use Case**: Web authentication, transaction signing - -#### Rabet -Browser extension wallet for Stellar. -- **Website**: https://rabet.io - -#### Hana Wallet -Modern Stellar wallet with DeFi features. -- **Website**: https://hana.network - -### Mobile Wallets - -#### LOBSTR -Most popular Stellar mobile wallet. -- **Website**: https://lobstr.co -- **Platforms**: iOS, Android, Web -- **Features**: DEX trading, multisig, 2FA, asset discovery - -#### Beans -Payments platform with yield features. -- **Use Case**: Payments, earning (via DeFindex/Blend) -- **Features**: Non-custodial yield generation - -### Multi-Wallet Integration - -#### Stellar Wallets Kit -SDK for integrating multiple Stellar wallets. -- **GitHub**: https://github.com/Creit-Tech/Stellar-Wallets-Kit -- **Supports**: Freighter, LOBSTR, xBull, Albedo, Rabet, Hana, Ledger, Trezor, WalletConnect - -## Developer Tools - -### Smart Account & Authentication - -#### Smart Account Kit (Recommended) -Comprehensive TypeScript SDK for OpenZeppelin Smart Accounts on Stellar. -- **GitHub**: https://github.com/kalepail/smart-account-kit -- **Use Case**: Production smart wallets with passkeys -- **Built On**: [OpenZeppelin stellar-contracts](https://github.com/OpenZeppelin/stellar-contracts) -- **Features**: - - Context rules with fine-grained authorization scopes - - Policy support (threshold multisig, spending limits, custom policies) - - Session management with automatic credential persistence - - External wallet adapter support (Freighter, LOBSTR, etc.) - - Built-in indexer for contract discovery - - Multiple signer types (passkeys, Ed25519, policies) - -#### Passkey Kit (Legacy) -Original TypeScript SDK for passkey-based smart wallets. -- **GitHub**: https://github.com/kalepail/passkey-kit -- **Status**: Legacy - use Smart Account Kit for new projects -- **Use Case**: Simple passkey wallet integration -- **Integration**: OpenZeppelin Relayer (gasless tx), Mercury (indexing) -- **Demo**: [passkey-kit-demo.pages.dev](https://passkey-kit-demo.pages.dev) -- **Example**: [Super Peach](https://github.com/kalepail/superpeach) - -#### OpenZeppelin Relayer -Service for fee-sponsored transaction submission. -- **Docs**: https://docs.openzeppelin.com/relayer -- **Use Case**: Gasless transactions, fee sponsoring - -### Data Indexing - -For a full directory of indexing options, see [Stellar Indexer Docs](https://developers.stellar.org/docs/data/indexers). - -#### Mercury -Stellar-native data indexing platform with Retroshades technology. -- **Website**: https://mercurydata.app -- **Docs**: https://docs.mercurydata.app -- **Use Case**: Event indexing, data queries, automation -- **Features**: Zephyr VM (serverless Rust execution at ledger close), GraphQL API - -#### SubQuery -Multi-chain indexer supporting Stellar. -- **Website**: https://subquery.network -- **Quick Start**: https://subquery.network/doc/indexer/quickstart/quickstart_chains/stellar.html -- **Features**: Block/transaction/operation/event handlers, multi-threading, 300+ chains - -#### Goldsky -Real-time data replication and subgraph platform. -- **Website**: https://goldsky.com -- **Docs**: https://docs.goldsky.com/chains/stellar -- **Features**: Mirror (real-time pipelines), subgraphs, on-chain + off-chain data - -#### Zephyr VM -Cloud execution environment for blockchain data processing. -- **GitHub**: https://github.com/xycloo/zephyr-vm -- **Use Case**: Indexing, monitoring, automation -- **Features**: Self-hostable, ledger-close execution - -### Contract Libraries - -#### OpenZeppelin Stellar Contracts -Audited smart contract library for Stellar (track latest release tags before pinning versions). -- **GitHub**: https://github.com/OpenZeppelin/stellar-contracts -- **Docs**: https://developers.stellar.org/docs/tools/openzeppelin-contracts -- **Contract Wizard**: https://wizard.openzeppelin.com/stellar -- **Includes**: Tokens (fungible/NFT), governance (timelock), vaults (SEP-56), access control, fee forwarder -- **Crates**: `stellar-tokens`, `stellar-access`, `stellar-contract-utils` - -### Security Tools - -Usage details, detector lists, and workflow guidance live in [the smart contract security guide](../smart-contracts/security.md#tooling). Catalog: - -- [Scout Soroban](https://github.com/CoinFabrik/scout-soroban) (CoinFabrik) - static analysis, 20+ detectors, VSCode extension, SARIF output ([examples](https://github.com/CoinFabrik/scout-soroban-examples)) -- [Security Detectors SDK](https://github.com/OpenZeppelin/soroban-security-detectors-sdk) (OpenZeppelin) - pre-built detectors plus a framework for custom ones -- [Certora Sunbeam Prover](https://docs.certora.com/en/latest/docs/sunbeam/index.html) - formal verification at WASM level, CVLR spec language ([Blend V1 report](https://www.certora.com/reports/blend-smart-contract-verification-report)) -- [Komet](https://docs.runtimeverification.com/komet) (Runtime Verification) - property testing and formal verification via KWasm semantics ([reports](https://github.com/runtimeverification/publications)) -- [Soroban Security Portal](https://sorobansecurity.com) (Inferara) - searchable audit reports and vulnerability database - -### CLI & SDKs - -#### Stellar CLI -Official command-line interface for Stellar. -- **Docs**: https://developers.stellar.org/docs/tools/stellar-cli -- **Features**: Contract build, deploy, invoke, bindings generation - -#### Stellar SDK (JavaScript) -Official JavaScript/TypeScript SDK. -- **GitHub**: https://github.com/stellar/js-stellar-sdk -- **npm**: `@stellar/stellar-sdk` - -#### Soroban Rust SDK -Rust SDK for smart contract development. -- **GitHub**: https://github.com/stellar/rs-soroban-sdk -- **Crate**: `soroban-sdk` - -### AI & MCP Tools - -#### Raven -Remote Model Context Protocol (MCP) server for AI agents. Searches Stellar docs and live ecosystem data, cross-referenced into single answers. Its catalog also serves these skills. -- **Server**: https://raven.stellar.buzz (MCP endpoint: https://raven.stellar.buzz/mcp) -- **Playground**: https://raven.stellar.buzz/playground (hosted chat UI for humans; sign-in required) -- **GitHub**: https://github.com/kalepail/stellar-raven -- **Connect (Claude Code)**: `claude mcp add --transport http stellar-raven "https://raven.stellar.buzz/mcp"` -- **Tools**: `search`, `execute` - -## Oracles - -#### Reflector Network -Community-powered price oracle for Stellar. -- **Website**: https://reflector.network -- **Docs**: https://developers.stellar.org/docs/data/oracles/oracle-providers -- **Features**: SEP-40 compatible, on-chain/off-chain prices, webhooks -- **Integrations**: Blend, OrbitCDP, DeFindex, EquitX, Slender - -#### DIA Oracle -Cross-chain oracle with 20,000+ asset support. -- **Website**: https://diadata.org -- **Blog**: https://www.diadata.org/blog/post/soroban-stellar-oracle-dia/ -- **Features**: VWAPIR methodology, custom feeds - -#### Band Protocol -Cross-chain data oracle on BandChain. -- **Website**: https://bandprotocol.com -- **Architecture**: Cosmos SDK-based, cross-chain - -## Gaming & NFTs - -#### Litemint -NFT marketplace and gaming platform. -- **GitHub**: https://github.com/litemint/litemint-soroban-contracts -- **Contracts**: Timed auctions, royalty payments -- **Features**: Open/sealed bids, ascending/descending price, buy-now - -## Infrastructure - -### Anchors & On/Off Ramps - -#### Stellar Ramps -Suite of open standards for fiat-crypto bridges. -- **Docs**: https://stellar.org/use-cases/ramps -- **SEPs**: SEP-6, SEP-24, SEP-31 (deposits/withdrawals/cross-border) - -#### Anchor Platform -SDF-maintained platform for building SEP-compliant anchors. -- **Docs**: https://developers.stellar.org/docs/learn/fundamentals/anchors -- **GitHub**: https://github.com/stellar/java-stellar-anchor-sdk - -### Block Explorers - -#### StellarExpert -Comprehensive network explorer with analytics. -- **Website**: https://stellar.expert -- **Features**: Transactions, accounts, assets, contracts - -#### Stellar Lab -Developer tools and transaction builder. -- **Website**: https://lab.stellar.org - -#### StellarChain -Alternative explorer with contract support. -- **Website**: https://stellarchain.io - -### Disbursements - -#### Stellar Disbursement Platform (SDP) -Bulk payment infrastructure for enterprises. -- **Docs**: https://developers.stellar.org/docs/category/use-the-stellar-disbursement-platform -- **GitHub**: https://github.com/stellar/stellar-disbursement-platform -- **Use Case**: Mass payments, aid distribution, payroll - -## Example Repositories - -### Official Examples - -#### Soroban Examples -Official educational smart contract examples. -- **GitHub**: https://github.com/stellar/soroban-examples -- **Includes**: Tokens, atomic swaps, auth, events, liquidity pools, timelock, deployer, merkle distribution - -#### Soroban Example dApp -Crowdfunding dApp with Next.js frontend. -- **GitHub**: https://github.com/stellar/soroban-example-dapp -- **Learning**: Full-stack contract development, Freighter integration - -### Community Examples - -#### Soroban Guide (Xycloo) -Learning resources and example contracts. -- **GitHub**: https://github.com/xycloo/soroban-guide -- **Includes**: Events, rock-paper-scissors, vaults, Dutch auctions - -#### Soroban Contracts (icolomina) -Governance and investment contract examples. -- **GitHub**: https://github.com/icolomina/soroban-contracts -- **Includes**: Ballot voting, investment contracts, multisig - -#### Oracle Example -Publisher-subscriber oracle pattern. -- **GitHub**: https://github.com/FredericRezeau/soroban-oracle-example -- **Uses**: soroban-kit oracle module - -#### OZ Stellar NFT -Simple NFT using OpenZeppelin. -- **GitHub**: https://github.com/jamesbachini/OZ-Stellar-NFT - -## Cross-Chain - -#### Axelar -Cross-chain gateway and Interchain Token Service for Stellar. -- **GitHub**: https://github.com/axelarnetwork/axelar-amplifier-stellar -- **Use Case**: Cross-chain messaging, token bridging, interoperability -- **Status**: Active development (verify latest activity before integrating) - -#### Allbridge Core -Cross-chain stable swap bridge (Stellar is 10th supported chain). -- **Use Case**: Cross-chain stablecoin transfers (USDC between Stellar, Base, Arbitrum, etc.) -- **Features**: Automatic Stellar account activation, liquidity pools - -#### LayerZero -Omnichain interoperability protocol with Stellar support. -- **Use Case**: Cross-chain messaging, token bridging (OFT/ONFT), dApp interoperability -- **Features**: OApp standard, Omni-Chain Fungible Tokens, native issuer minting/burning control - -## Builder Teams & Companies - -Notable teams shipping production-level code on Stellar. For a broader directory, see [Stellar Ecosystem](https://stellar.org/ecosystem). - -| Team | Website | GitHub | X/Twitter | Notable Projects | -|------|---------|--------|-----------|-----------------| -| **Lightsail Network** | [lightsail.network](https://lightsail.network) | [lightsail-network](https://github.com/lightsail-network) | [@overcat_me](https://x.com/overcat_me) | Quasar RPC, Java/Python SDKs, Ledger app, validators | -| **PaltaLabs** | [paltalabs.io](https://paltalabs.io) | [paltalabs](https://github.com/paltalabs) | [@PaltaLabs](https://x.com/PaltaLabs) | Soroswap, DeFindex | -| **Aha Labs** | [ahalabs.dev](https://ahalabs.dev) | [AhaLabs](https://github.com/AhaLabs) | [@AhaLabsDev](https://x.com/AhaLabsDev) | Scaffold Stellar, Soroban CLI contributions | -| **OpenZeppelin** | [openzeppelin.com](https://www.openzeppelin.com/networks/stellar) | [OpenZeppelin](https://github.com/OpenZeppelin/stellar-contracts) | [@OpenZeppelin](https://x.com/OpenZeppelin) | Contracts library, Relayer, Monitor, Security Detectors SDK | -| **Cheesecake Labs** | [cheesecakelabs.com](https://cheesecakelabs.com) | [CheesecakeLabs](https://github.com/CheesecakeLabs) | [@CheesecakeLabs](https://x.com/CheesecakeLabs) | Stellar Plus library | -| **Script3 / Blend Capital** | [script3.io](https://script3.io) | [script3](https://github.com/script3), [blend-capital](https://github.com/blend-capital) | [@script3official](https://x.com/script3official) | Blend Protocol | -| **Xycloo Labs** | [xycloo.com](https://xycloo.com) | [Xycloo](https://github.com/Xycloo) | [@heytdep](https://x.com/heytdep) | Mercury indexer, Zephyr VM | -| **CoinFabrik** | [coinfabrik.com](https://www.coinfabrik.com) | [CoinFabrik](https://github.com/CoinFabrik) | [@coinfabrik](https://x.com/coinfabrik) | Scout Soroban (static analysis) | -| **Creit Tech** | [creit.tech](https://creit.tech) | [Creit-Tech](https://github.com/Creit-Tech) | [@CreitTech_](https://x.com/CreitTech_) | Stellar Wallets Kit, xBull, SorobanHub | -| **Ultra Stellar** | [ultrastellar.com](https://ultrastellar.com) | [lobstrco](https://github.com/lobstrco) | [@Lobstrco](https://x.com/Lobstrco) | LOBSTR wallet, StellarExpert | - -## Project Directories - -### Official Directories - -#### Stellar Ecosystem Directory -The canonical, up-to-date project directory maintained by SDF. -- **Website**: https://stellar.org/ecosystem -- **Features**: Search by country, asset, category -- **Includes**: DeFi, wallets, anchors, on/off ramps, exchanges, infrastructure - -#### SCF Project Tracker -All Stellar Community Fund–funded projects with status and milestones. -- **Website**: https://communityfund.stellar.org/projects - -### Funding Programs - -#### Stellar Community Fund (SCF) -Grants up to $150K per funding round. -- **Website**: https://communityfund.stellar.org -- **Funded**: 100+ projects across DeFi, NFT, GameFi, Web3 - -#### Soroban Audit Bank -Security audit funding for SCF projects. -- **Website**: https://stellar.org/grants-and-funding/soroban-audit-bank -- **Features**: Pre-negotiated audit rates, readiness checklist - -## Real-World Assets - -### Major Issuers on Stellar -- **Franklin Templeton**: Regulated fund tokens -- **Ondo**: Tokenized real estate -- **RedSwan**: $100M commercial real estate -- **Centrifuge**: Yield-generating tokens -- **WisdomTree**: Asset-backed tokens - -### Stablecoins -- **USDC** (Circle): Primary USD stablecoin -- **EURC** (Circle): EUR stablecoin -- **PYUSD** (PayPal): Verify current issuance and distribution details before launch planning - -## Enterprise Integrations - -Major companies building on Stellar: -- **PayPal**: PYUSD stablecoin -- **Visa**: Settlement infrastructure -- **Mastercard**: Payment rails -- **Wirex**: USDC/EURC settlement -- **U.S. Bank**: Custom stablecoin testing -- **PwC**: Stablecoin exploration - ---- - -# Part 3: Curated Resources - - -## Official Documentation - -### Stellar Developer Docs -- [Stellar Documentation](https://developers.stellar.org/docs) - Primary documentation -- [Build Smart Contracts](https://developers.stellar.org/docs/build/smart-contracts) - smart contract guides -- [Build Apps](https://developers.stellar.org/docs/build/apps) - Client application guides -- [Tools & SDKs](https://developers.stellar.org/docs/tools) - Available tooling -- [Networks](https://developers.stellar.org/docs/networks) - Network configuration -- [Learn Fundamentals](https://developers.stellar.org/docs/learn/fundamentals) - Core concepts -- [Security Best Practices](https://developers.stellar.org/docs/build/security-docs) - -### API References -- [Stellar RPC Methods](https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods) - RPC API -- [Horizon API](https://developers.stellar.org/docs/data/apis/horizon/api-reference) - REST API (legacy-focused) -- [Oracle Providers](https://developers.stellar.org/docs/data/oracles/oracle-providers) - -## SDKs - -### Client SDKs (Application Development) -- [JavaScript SDK](https://github.com/stellar/js-stellar-sdk) - `@stellar/stellar-sdk` -- [Python SDK](https://github.com/StellarCN/py-stellar-base) - `stellar-sdk` -- [Java SDK](https://github.com/lightsail-network/java-stellar-sdk) - `network.lightsail:stellar-sdk` (Lightsail Network) -- [Go SDK](https://github.com/stellar/go-stellar-sdk) - `txnbuild`, Horizon & RPC clients -- [Rust SDK (RPC Client)](https://github.com/stellar/rs-stellar-rpc-client) -- [SDK Documentation](https://developers.stellar.org/docs/tools/sdks/client-sdks) - -### Contract SDK (Rust) -- [Soroban Rust SDK](https://github.com/stellar/rs-soroban-sdk) - `soroban-sdk` -- [Soroban SDK Docs](https://docs.rs/soroban-sdk/latest/soroban_sdk/) - Rust docs - -## CLI Tools - -### Stellar CLI -- [Stellar CLI Repository](https://github.com/stellar/stellar-cli) -- [CLI Installation](https://developers.stellar.org/docs/tools/stellar-cli) -- [CLI Commands Reference](https://developers.stellar.org/docs/tools/stellar-cli/stellar-cli-commands) - -### Scaffold Stellar -- [Scaffold Stellar](https://scaffoldstellar.org) - Full-stack dApp scaffolding (contracts + React/Vite/TS frontend) -- [Scaffold Docs](https://developers.stellar.org/docs/tools/scaffold-stellar) - Official documentation -- [GitHub](https://github.com/theahaco/scaffold-stellar) - Open source (Apache 2.0) - -### Quickstart (Local Development) -- [Quickstart Docker](https://github.com/stellar/quickstart) -- [Quickstart Guide](https://developers.stellar.org/docs/tools/quickstart) - -## Contract Libraries & Tools - -### OpenZeppelin Stellar Contracts -- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/stellar-contracts) -- [Documentation](https://developers.stellar.org/docs/tools/openzeppelin-contracts) -- [Contract Wizard](https://wizard.openzeppelin.com/stellar) - Generate contracts - -### Smart Account SDKs -- [Smart Account Kit](https://github.com/kalepail/smart-account-kit) - Production smart wallet SDK (recommended) -- [Passkey Kit](https://github.com/kalepail/passkey-kit) - Legacy passkey wallet SDK -- [Super Peach](https://github.com/kalepail/superpeach) - Smart wallet implementation example - -### Developer Tools -- [Stellar Wallets Kit](https://github.com/Creit-Tech/Stellar-Wallets-Kit) - Multi-wallet integration -- [OpenZeppelin Relayer](https://docs.openzeppelin.com/relayer) - Fee-sponsored transactions - -## Example Repositories - -Official and community example repos are cataloged in Part 2: Example Repositories above. See also [Stellar Repositories](https://github.com/orgs/stellar/repositories) for everything under the stellar org. - -## Ecosystem Projects - -For DeFi protocols, wallets, oracles, gaming/NFTs, cross-chain bridges, and builder teams, see Part 2: Stellar Ecosystem above. - -## Security - -Vulnerability patterns, checklists, tooling (static analysis, formal verification, monitoring), the Audit Bank, and the Immunefi bounty programs are covered in [the smart contract security guide](../smart-contracts/security.md). The Security Tools catalog in Part 2 above lists the tool links. - -Additional resources not covered there: -- [HackerOne VDP](https://stellar.org/grants-and-funding/bug-bounty) - Web application vulnerabilities -- [Audited Projects List](https://stellar.org/audit-bank/projects) - Public audit registry -- [Veridise Security Checklist](https://veridise.com/blog/audit-insights/building-on-stellar-soroban-grab-this-security-checklist-to-avoid-vulnerabilities/) - smart-contract security checklist -- [CoinFabrik Audit Reports](https://www.coinfabrik.com/smart-contract-audit-reports/) -- [Certora Security Reports](https://github.com/Certora/SecurityReports) - Includes Stellar verifications - -## Zero-Knowledge Proofs (Status-Sensitive) - -For comprehensive ZK development guidance, see the [zk-proofs skill](../zk-proofs/SKILL.md). - -Always verify CAP status and network support before treating any ZK primitive as production-available. - -### Protocol & Specifications -- [Protocol upgrades](https://stellar.org/protocol-upgrades) - Upgrade timeline and network context -- [CAP-0074](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0074.md) - BN254 host functions (G1 add/mul, pairing check) — Final, Protocol 25+ -- [CAP-0075](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0075.md) - Poseidon/Poseidon2 permutation primitives — Final, Protocol 25+ -- [CAP-0080](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0080.md) - BN254 G1 MSM, Fr arithmetic, on-curve checks — Implemented, Protocol 26+ - -### SDK Documentation -- [Soroban SDK BN254 module](https://docs.rs/soroban-sdk/latest/soroban_sdk/crypto/bn254/) - Verify availability in your pinned SDK version -- [Soroban SDK Crypto](https://docs.rs/soroban-sdk/latest/soroban_sdk/crypto/) - Full crypto module reference - -### Proving Systems & Tooling -- [Noir Documentation](https://noir-lang.org/docs/) - Aztec's ZK domain-specific language -- [RISC Zero](https://dev.risczero.com/) - General-purpose zkVM for Rust programs - -### Example Contracts -- [Soroban Examples](https://github.com/stellar/soroban-examples) - Official examples (includes `groth16_verifier`, `privacy-pools`, `import_ark_bn254`) - -## Testing - -### Testing Guides -- [Definitive Guide to Testing Smart Contracts](https://stellar.org/blog/developers/the-definitive-guide-to-testing-smart-contracts-on-stellar) - Comprehensive overview -- [Fuzzing Guide](https://developers.stellar.org/docs/build/guides/testing/fuzzing) - cargo-fuzz + SorobanArbitrary -- [Fuzzing Example Contract](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/fuzzing) -- [Differential Testing](https://developers.stellar.org/docs/build/guides/testing/differential-tests-with-test-snapshots) - Automatic test snapshots -- [Fork Testing](https://developers.stellar.org/docs/build/guides/testing/fork-testing) - Test against production state -- [Mutation Testing](https://developers.stellar.org/docs/build/guides/testing/mutation-testing) - cargo-mutants - -### Local Development -- [Stellar Quickstart](https://github.com/stellar/quickstart) -- [Docker Setup](https://developers.stellar.org/docs/tools/quickstart) - -### Test Networks -- [Testnet Info](https://developers.stellar.org/docs/networks/testnet) -- [Friendbot](https://friendbot.stellar.org) - Testnet faucet - -## Data & Analytics - -### Data Documentation Hub -- [Stellar Data Overview](https://developers.stellar.org/docs/data) - Choose the right tool (APIs, indexers, analytics, oracles) -- [Indexer Directory](https://developers.stellar.org/docs/data/indexers) - All supported indexers -- [RPC Provider Directory](https://developers.stellar.org/docs/data/apis/rpc/providers) - All RPC infrastructure providers - -### Block Explorers -- [StellarExpert](https://stellar.expert) - Network explorer & analytics -- [StellarExpert API](https://stellar.expert/openapi.html) - Free REST API (no auth, CORS-enabled) -- [Stellar Lab](https://lab.stellar.org) - Developer tools -- [StellarChain](https://stellarchain.io) - Alternative explorer - -### Data Indexers - -Mercury, SubQuery, Goldsky, and Zephyr VM are cataloged with docs links in Part 2: Data Indexing above. Full directory: [Indexer Directory](https://developers.stellar.org/docs/data/indexers). - -### Historical Data & Analytics -- [Hubble](https://developers.stellar.org/docs/data/analytics/hubble) - BigQuery dataset (updated every 30 min) -- [Galexie](https://developers.stellar.org/docs/data/indexers/build-your-own/galexie) - Data pipeline for building data lakes -- [Data Lake](https://developers.stellar.org/docs/data/apis/rpc/admin-guide/data-lake-integration) - Powers RPC Infinite Scroll (public via AWS Open Data) - -## Infrastructure - -Anchors, on/off ramps, and the Stellar Disbursement Platform are cataloged in Part 2: Infrastructure above. See also the [Anchor Platform docs](https://developers.stellar.org/docs/category/anchor-platform). - -### RPC Providers -- [RPC Provider Directory](https://developers.stellar.org/docs/data/apis/rpc/providers) - Full list of providers -- [Quasar (Lightsail Network)](https://quasar.lightsail.network) - Stellar-native RPC, Archive RPC, hosted Galexie Data Lake -- [Blockdaemon](https://www.blockdaemon.com/soroban) - Enterprise RPC -- [Validation Cloud](https://www.validationcloud.io) - Testnet & Mainnet -- [QuickNode](https://www.quicknode.com) - Testnet, Mainnet & Dedicated -- [Ankr](https://www.ankr.com) - Testnet & Mainnet -- [NOWNodes](https://nownodes.io) - All networks incl. Futurenet -- [GetBlock](https://getblock.io) - Testnet & Mainnet - -## Protocol & Governance - -### Stellar Protocol -- [Stellar Protocol Repo](https://github.com/stellar/stellar-protocol) -- [CAPs](https://github.com/stellar/stellar-protocol/tree/master/core) - Core Advancement Proposals -- [SEPs](https://github.com/stellar/stellar-protocol/tree/master/ecosystem) - Stellar Ecosystem Proposals - -### Key SEP Standards -- [SEP-0001](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md) - stellar.toml -- [SEP-0010](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md) - Web Authentication -- [SEP-0024](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md) - Hosted Deposit/Withdrawal -- [SEP-0030](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md) - Account Recovery -- [SEP-0031](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0031.md) - Cross-Border Payments -- [SEP-0041](https://developers.stellar.org/docs/tokens/token-interface) - Token Interface -- [SEP-0045](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0045.md) - Web Auth for Contract Accounts (Draft) -- [SEP-0046](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0046.md) - Contract Meta (Active) -- [SEP-0048](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0048.md) - Contract Interface Specification (Active) -- [SEP-0050](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0050.md) - Non-Fungible Tokens (Draft) -- [SEP-0056](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0056.md) - Tokenized Vault Standard (Draft, ERC-4626 equivalent) - -### Network Upgrades -- [Protocol Upgrades](https://stellar.org/protocol-upgrades) -- [SDF Blog](https://stellar.org/blog) - -## Project Directories & Funding - -Directories (Stellar Ecosystem, SCF Project Tracker) and funding programs (SCF, Audit Bank) are cataloged in Part 2: Project Directories above. See also the [$100M Soroban Adoption Fund](https://stellar.org/soroban). - -## Learning Resources - -### Official Tutorials -- [Getting Started](https://developers.stellar.org/docs/build/smart-contracts/getting-started) -- [Hello World Contract](https://developers.stellar.org/docs/build/smart-contracts/getting-started/hello-world) -- [Deploy to Testnet](https://developers.stellar.org/docs/build/smart-contracts/getting-started/deploy-to-testnet) -- [TypeScript Bindings](https://developers.stellar.org/docs/build/apps/guestbook/bindings) -- [Passkey Prerequisites](https://developers.stellar.org/docs/build/apps/guestbook/passkeys-prerequisites) - -### Video Content -- [Stellar YouTube](https://www.youtube.com/@StellarDevelopmentFoundation) -- [Learn Rust for Smart Contracts (DAO Series)](https://www.youtube.com/watch?v=VeQM5N-0DrI) -- [Call Option Contract Walkthrough](https://www.youtube.com/watch?v=Z8FHVllP_D0) -- [Blend Protocol Tutorial](https://www.youtube.com/watch?v=58j0QkXKiDU) - -### Developer Tools -- [Stella AI Bot](https://developers.stellar.org/docs/tools/developer-tools) - AI assistant for Stellar developer questions -- [Soroban Playground](https://soropg.com) - Browser-based smart contract IDE ([GitHub](https://github.com/jamesbachini/Soroban-Playground)) - -### Blog Posts & Guides -- [Composability on Stellar](https://stellar.org/blog/developers/composability-on-stellar-from-concept-to-reality) -- [Testing Smart Contracts Guide](https://stellar.org/blog/developers/the-definitive-guide-to-testing-smart-contracts-on-stellar) -- [Sorobounty Spectacular Tutorials](https://stellar.org/blog/developers/sorobounty-spectacular-dapp-tutorials) -- [Learn Soroban 1-2-3 (Community Tools)](https://stellar.org/blog/developers/learn-soroban-as-easy-as-1-2-3-with-community-made-tooling) -- [SCF Infrastructure Recap](https://stellar.org/blog/ecosystem/stellar-community-fund-recap-soroban-infrastructure) -- [Native vs Soroban Tokens](https://cheesecakelabs.com/blog/native-tokens-vs-soroban-tokens/) -- [57Blocks Integration Testing](https://57blocks.com/blog/soroban-integration-testing-best-practices) - -## Stablecoins on Stellar - -### Major Stablecoins -- [USDC on Stellar](https://www.circle.com/usdc/stellar) - Circle -- [EURC on Stellar](https://www.circle.com/en/eurc) - Circle -- PYUSD (PayPal) - Verify current issuer/distribution details before integration - -### Asset Discovery -- [StellarExpert Asset Directory](https://stellar.expert/explorer/public/asset) - -## Community - -### Developer Resources -- [Stellar Developers Discord](https://discord.gg/stellar) -- [Stellar Stack Exchange](https://stellar.stackexchange.com) -- [GitHub Discussions](https://github.com/stellar/stellar-protocol/discussions) - -### Key People to Follow - -Builders and contributors actively shaping the Stellar ecosystem: - -| Name | GitHub | X/Twitter | Focus | -|------|--------|-----------|-------| -| Tyler van der Hoeven | [kalepail](https://github.com/kalepail) | [@kalepail](https://x.com/kalepail) | SDF DevRel, Smart Account Kit, Passkey Kit, Launchtube | -| Leigh McCulloch | [leighmcculloch](https://github.com/leighmcculloch) | [@___leigh___](https://x.com/___leigh___) | SDF core engineer, Stellar CLI, Soroban SDK | -| James Bachini | [jamesbachini](https://github.com/jamesbachini) | [@james_bachini](https://x.com/james_bachini) | SDF Dev in Residence, Soroban Playground, tutorials | -| Elliot Voris | [ElliotFriend](https://github.com/ElliotFriend) | [@ElliotFriend](https://x.com/ElliotFriend) | SDF DevRel, community education | -| Carsten Jacobsen | [carstenjacobsen](https://github.com/carstenjacobsen) | — | SDF, weekly dev meetings, Soroban examples | -| Esteban Iglesias | [esteblock](https://github.com/esteblock) | [@esteblock_dev](https://x.com/esteblock_dev) | PaltaLabs, Soroswap, DeFindex | -| Markus Paulson-Luna | [markuspluna](https://github.com/markuspluna) | [@script3official](https://x.com/script3official) | Script3, Blend Protocol | -| Alexander Mootz | [mootz12](https://github.com/mootz12) | — | Script3, Blend contracts | -| Tommaso | [heytdep](https://github.com/heytdep) | [@heytdep](https://x.com/heytdep) | Xycloo Labs, Mercury indexer, ZephyrVM | -| OrbitLens | [orbitlens](https://github.com/orbitlens) | [@orbitlens](https://x.com/orbitlens) | Reflector oracle, StellarExpert, Albedo | -| Frederic Rezeau | [FredericRezeau](https://github.com/FredericRezeau) | [@FredericRezeau](https://x.com/FredericRezeau) | Litemint, soroban-kit, gaming | -| Jun Luo (Overcat) | [overcat](https://github.com/overcat) | [@overcat_me](https://x.com/overcat_me) | Lightsail Network, Quasar RPC, Java/Python SDKs, Ledger app | -| Jay Geng | [jayz22](https://github.com/jayz22) | — | SDF, Soroban SDK, confidential tokens | -| Chad Ostrowski | [chadoh](https://github.com/chadoh) | [@chadoh](https://x.com/chadoh) | Aha Labs CEO, Scaffold Stellar, Soroban CLI | -| Willem Wyndham | [willemneal](https://github.com/willemneal) | [@willemneal](https://x.com/willemneal) | Aha Labs co-founder, Scaffold Stellar, JS contract client | - -### Builder Teams & Companies -See Part 2: Stellar Ecosystem above for a table of teams shipping production code on Stellar, with GitHub orgs, websites, and Twitter handles. - -### Foundation -- [Stellar Development Foundation](https://stellar.org/foundation) -- [Foundation Roadmap](https://stellar.org/foundation/roadmap) -- [Ecosystem Blog](https://stellar.org/blog/ecosystem) diff --git a/skills/standards/ecosystem.md b/skills/standards/ecosystem.md new file mode 100644 index 0000000..38ec3e2 --- /dev/null +++ b/skills/standards/ecosystem.md @@ -0,0 +1,462 @@ +# Stellar Ecosystem + + +This guide catalogs the major projects, protocols, and tools in the Stellar ecosystem. Use this as a reference when building on Stellar to find relevant integrations, examples, and community projects. + +Companion to [SKILL.md](SKILL.md) (SEP/CAP standards routing); curated docs/SDK/learning links live in [resources.md](resources.md). + +> **Canonical directories** — For the most up-to-date project lists, check: +> - [Stellar Ecosystem](https://stellar.org/ecosystem) — Official directory (searchable by country, asset, category) +> - [SCF Projects](https://communityfund.stellar.org/projects) — Funded projects with status tracking +> - [Stellar on DefiLlama](https://defillama.com/chain/stellar) — Live DeFi TVL data +> +> Treat project metrics/status as volatile. Validate latest activity and production readiness before taking dependencies. + +## DeFi Protocols + +### Lending & Borrowing + +#### Blend Protocol +Universal liquidity protocol enabling permissionless lending pools. +- **Use Case**: Lending, borrowing, yield generation +- **GitHub**: https://github.com/blend-capital/blend-contracts +- **GitHub (v2)**: https://github.com/blend-capital/blend-contracts-v2 +- **Integrations**: Meru, Airtm, Lobstr, DeFindex, Beans + +#### K2 +Money market on Soroban with a modular router architecture (Aave V3-inspired). Live on mainnet. +- **Use Case**: Supply to earn variable interest, borrow against collateral, collateral swaps, flash loans +- **Website**: https://k2lend.com +- **Docs**: https://docs.k2lend.com — agent-friendly: every page has a `.md` twin, plus [llms.txt](https://docs.k2lend.com/llms.txt) and a full corpus export at [llms-full.txt](https://docs.k2lend.com/llms-full.txt) +- **Position model**: per reserve, an **aToken** (interest-bearing supply receipt) and a **debt ledger** token; balances are `scaled balance x current index`, so they accrue without user action. Separate liquidity index (linear approximation per interval) and borrow index (full compound). The index updates on the first interaction with a reserve in a ledger. +- **Rates**: variable only, two-slope curve with a kink at optimal utilization (typically 80%). `Supply Rate = Borrow Rate x Utilization x (1 - Reserve Factor)`. Up to 64 reserves. +- **Risk**: liquidation threshold 65–85% by asset (85% stables, 65% volatile); health factor < 1.0 is liquidatable with no grace period; partial liquidation by default, 100% when HF < 0.5 or the debt/collateral leg is under $2,000. Liquidation bonus 10% for XLM/SolvBTC/wBTC. +- **Fees**: reserve factor typically 10–20%; flash loan premium 9 bps default; liquidation protocol fee 0.3% default. No deposit/withdraw/repay fees. +- **Oracle**: RedStone primary, Reflector fallback. Staleness rejection (1h default, per-asset override), 20% circuit breaker that keeps the last good price, zero-price rejection, and a global oracle pause. +- **Flash loans**: enabled per reserve plus a global kill switch; repay principal + premium in the same transaction or the whole thing reverts. +- **DEX integration**: Soroswap and Aquarius adapters power collateral swaps and flash liquidations. **Direct pairs only — no multi-hop routing**, so a swap fails if no direct pair exists. +- **Liquidation access**: whitelisted liquidators during the launch period, opening to permissionless over time — check current state before building a liquidation bot. +- **Audits**: Halborn, WatchPug, and a Code4rena contest; Hypernative for runtime monitoring. + +**Mainnet contracts.** `kinetic_router` is the entry point you call; the rest are the modules it routes to. + +| Contract | Address | +|----------|---------| +| `kinetic_router` | `CCTUJZLYFAW7ZNQD2SXMUZIHBUUJJICYRKWLZJ6SK6TGNAWNXOJIV6J7` | +| `configurator` | `CAYS7DTBBBG6TDT326KYTE72L6Q7NSEI2U2CA7TKCQIWPXB2GNJWU7M4` | +| `price_oracle` | `CCHRZE2K5TCERZLDO5IXDUWUKLRPVE72DI3TDF2RP6EQKEW6BNOMQRMU` | +| `interest_rate` | `CATBSCEN73MFGD4LCCC6SFJHGNEHC2QLSSXFZXFCW3NK45BBPGEYDXOC` | +| `treasury` | `CCQ4J5VLQHM2ORP4K7GBVAJJPK5SGG23DH4RD7QEHAZDHTN7JNESNXKZ` | +| `incentives` | `CAAMA46SQXQKHZDWAS2CNZVAX67TOMGBVH3DVSZSMDKKVP25VGTDQIRX` | +| `flash_liquidation` | `CACGHPQB2QOKNAPH3PVGKXXSULNGMNZYWVZQVPTHMWHFRXAGASSRNQ7H` | +| `reward_token` | `CA4V5C3KWDXBJEPIIKZT2PQWQZB4SY3G3G3S4PYPD5XXGXF5RKQUBE2N` | +| `soroswap_swap_adapter` | `CDL35ZAOYVDBMSTIKOF4HJKXA7MWHF5ZJNZKES6EAZAOOHLXURSGSYAJ` | +| `aquarius_swap_adapter` | `CBJBQMSBXYBOSRK6WLBAEVGF2GXQVPTYVVMVDGZF7ZBJHHFT2IGJNDMN` | +| `aquarius_multihop_swap_handler` | `CB3EHO42TDWT5EG6X62QTMPQPWIETVFLM7Q7DT62Z6MT5J4HP33XKXWE` | +| `solvbtc_composite_oracle` | `CABOR5KOCMIC226J5B63W5MV75VH5ZPAFEXZFET2JDD2H6IGJY5UPWP4` | + +**Reserve tokens.** Read a user's supply balance from the aToken and their debt from the debt ledger. The `underlying` column is the asset's SAC, not a K2 contract. + +| Market | Underlying (SAC) | aToken | Debt ledger | +|--------|------------------|--------|-------------| +| USDC | `CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75` | `CDHRPTO3NLGQ2CV75LFV6NF6ZMXIPGPID5GTAZTEICBYLMLKJICOMFZK` | `CBN4GDHRJN7AIARTSTUD3OK7IOCU5V6HTSOTVARFUA5KVE7XSNBZUQG6` | +| XLM | `CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA` | `CDTHJR27QWKAPCFTZWKP7GTX3RZO7HACVAC2KLCW2RENCMOCI35ORU5K` | `CC3OKG4VDLGFBS7V6UTSJVP3YL3A4OLV63EMTNUU3MQ2AOAU4M65H7QG` | +| PYUSD | `CCCRWH6Q3FNP3I2I57BDLM5AFAT7O6OF6GKQOC6SSJNDAVRZ57SPHGU2` | `CA7ELGRS4FNCYJPRZSNLF7NDD6VVOFZKFKMY56VVSG3RMNYTFQNNFUTD` | `CAVFE34MWBIXT4AOFXPTI7U7JTLPHKG4YWDDMRXVJOIZKG6HFJW3IHXV` | +| SolvBTC | `CBIJBDNZNF4X35BJ4FFZWCDBSCKOP5NB4PLG4SNENRMLAPYG4P5FM6VN` | `CDDTJ7OZU2WZAEZNTUZWIRAE4EMP5CF63M3INFQWTLX4ENMYUFK6RCTX` | `CADGKVZKBNLPKFIWDWTRSQAPBWH77H2OPJIF3WGVL7VADVLCXDZ5CSNH` | + +wBTC appears in K2's risk-parameter and liquidation tables as a supported asset but has no published reserve token set — treat only the four markets above as live. + +**External contracts K2 reads or routes through** (not K2-owned): Reflector Stellar mainnet DEX oracle `CALI2BYU2JE6WVRUFYTS6MSBNEHGJ35P4AVCZYF3B6QOE3QKOB2PLE6M`, Reflector external CEX/DEX oracle `CAFJZQWSED6YAWZU3GWRTOCNPPCGBN32L7QV43XX5LZLFTK6JLN34DLN`, RedStone batch adapter `CA526Y2NQWGWVVQ7RFFPGAZMU66PSYJ3UC2MTVAV4ZU7OM5BOPHDXUSG`. + +> Every address above was resolved on pubnet (2026-07-31). Legacy manual reserve tokens and published-but-uninstantiated WASM hashes are omitted; [docs.k2lend.com/contracts](https://docs.k2lend.com/contracts) is the source of truth — re-check it before hard-coding, since reserves and adapters can be added or rotated. + +#### Slender +First non-custodial lending protocol on Stellar with flash loan support. +- **Use Case**: Lending, borrowing, flash loans +- **Features**: Pool-based strategy, sTokens, dTokens, utilization caps +- **Oracle**: SEP-40 compatible (Reflector) + +### DEXs & AMMs + +#### Soroswap +First DEX and aggregator on Stellar. +- **Use Case**: Token swaps, liquidity provision, aggregation +- **Website**: https://soroswap.finance +- **GitHub (Core)**: https://github.com/soroswap/core +- **GitHub (Frontend)**: https://github.com/soroswap/frontend +- **GitHub (Aggregator)**: https://github.com/soroswap/aggregator +- **Docs**: https://docs.soroswap.finance +- **Features**: AMM + DEX aggregator across Aqua, Phoenix, Stellar Classic DEX + +#### Aquarius / AQUA Network +Governance-driven liquidity layer with AMM functionality. +- **Use Case**: Liquidity incentives, AMM, governance +- **Website**: https://aqua.network +- **GitHub**: https://github.com/AquaToken/soroban-amm +- **GitHub (Org)**: https://github.com/AquaToken +- **Token**: AQUA (governance + rewards) +- **Docs**: https://docs.aqua.network + +#### Phoenix Protocol +AMM protocol on Stellar. +- **GitHub**: https://github.com/Phoenix-Protocol-Group +- **Use Case**: Token swaps, liquidity pools + +### Yield & Vaults + +#### DeFindex +Yield aggregation and vault infrastructure by PaltaLabs. +- **Use Case**: Tokenized vaults, yield strategies, DeFi abstraction +- **Docs**: https://docs.defindex.io +- **Features**: Automated rebalancing, vault management, Blend integration + +### Stablecoins & CDPs + +#### Orbit CDP Protocol +Collateralized stablecoin issuance (USD, EUR, MXN). +- **Use Case**: Mint stablecoins against XLM/bond collateral +- **Docs**: https://docs.orbitcdp.finance +- **Features**: Multi-currency stablecoins, Pegkeeper automation, Blend integration + +## Wallets + +### Browser Extensions + +#### Freighter +SDF's flagship non-custodial browser wallet. +- **Website**: https://freighter.app +- **Docs**: https://docs.freighter.app +- **GitHub**: https://github.com/stellar/freighter +- **GitHub (Mobile)**: https://github.com/stellar/freighter-mobile +- **API**: https://github.com/stellar/freighter/tree/master/library/freighter-api +- **Features**: Smart contract support, mobile apps (iOS/Android), Discover browser + +#### xBull +Feature-rich browser wallet with advanced capabilities. +- **Website**: https://xbull.app +- **Features**: Multi-account, hardware wallet support + +#### Albedo +Lightweight web-based wallet and signing provider. +- **Website**: https://albedo.link +- **Use Case**: Web authentication, transaction signing + +#### Rabet +Browser extension wallet for Stellar. +- **Website**: https://rabet.io + +#### Hana Wallet +Modern Stellar wallet with DeFi features. +- **Website**: https://hana.network + +### Mobile Wallets + +#### LOBSTR +Most popular Stellar mobile wallet. +- **Website**: https://lobstr.co +- **Platforms**: iOS, Android, Web +- **Features**: DEX trading, multisig, 2FA, asset discovery + +#### Beans +Payments platform with yield features. +- **Use Case**: Payments, earning (via DeFindex/Blend) +- **Features**: Non-custodial yield generation + +### Multi-Wallet Integration + +#### Stellar Wallets Kit +SDK for integrating multiple Stellar wallets. +- **GitHub**: https://github.com/Creit-Tech/Stellar-Wallets-Kit +- **Supports**: Freighter, LOBSTR, xBull, Albedo, Rabet, Hana, Ledger, Trezor, WalletConnect + +## Developer Tools + +### Smart Account & Authentication + +#### Smart Account Kit (Recommended) +Comprehensive TypeScript SDK for OpenZeppelin Smart Accounts on Stellar. +- **GitHub**: https://github.com/kalepail/smart-account-kit +- **Use Case**: Production smart wallets with passkeys +- **Built On**: [OpenZeppelin stellar-contracts](https://github.com/OpenZeppelin/stellar-contracts) +- **Features**: + - Context rules with fine-grained authorization scopes + - Policy support (threshold multisig, spending limits, custom policies) + - Session management with automatic credential persistence + - External wallet adapter support (Freighter, LOBSTR, etc.) + - Built-in indexer for contract discovery + - Multiple signer types (passkeys, Ed25519, policies) + +#### Passkey Kit (Legacy) +Original TypeScript SDK for passkey-based smart wallets. +- **GitHub**: https://github.com/kalepail/passkey-kit +- **Status**: Legacy - use Smart Account Kit for new projects +- **Use Case**: Simple passkey wallet integration +- **Integration**: OpenZeppelin Relayer (gasless tx), Mercury (indexing) +- **Demo**: [passkey-kit-demo.pages.dev](https://passkey-kit-demo.pages.dev) +- **Example**: [Super Peach](https://github.com/kalepail/superpeach) + +#### OpenZeppelin Relayer +Service for fee-sponsored transaction submission. +- **Docs**: https://docs.openzeppelin.com/relayer +- **Use Case**: Gasless transactions, fee sponsoring + +### Data Indexing + +For a full directory of indexing options, see [Stellar Indexer Docs](https://developers.stellar.org/docs/data/indexers). + +#### Mercury +Stellar-native data indexing platform with Retroshades technology. +- **Website**: https://mercurydata.app +- **Docs**: https://docs.mercurydata.app +- **Use Case**: Event indexing, data queries, automation +- **Features**: Zephyr VM (serverless Rust execution at ledger close), GraphQL API + +#### SubQuery +Multi-chain indexer supporting Stellar. +- **Website**: https://subquery.network +- **Quick Start**: https://subquery.network/doc/indexer/quickstart/quickstart_chains/stellar.html +- **Features**: Block/transaction/operation/event handlers, multi-threading, 300+ chains + +#### Goldsky +Real-time data replication and subgraph platform. +- **Website**: https://goldsky.com +- **Docs**: https://docs.goldsky.com/chains/stellar +- **Features**: Mirror (real-time pipelines), subgraphs, on-chain + off-chain data + +#### Zephyr VM +Cloud execution environment for blockchain data processing. +- **GitHub**: https://github.com/xycloo/zephyr-vm +- **Use Case**: Indexing, monitoring, automation +- **Features**: Self-hostable, ledger-close execution + +### Contract Libraries + +#### OpenZeppelin Stellar Contracts +Audited smart contract library for Stellar (track latest release tags before pinning versions). +- **GitHub**: https://github.com/OpenZeppelin/stellar-contracts +- **Docs**: https://developers.stellar.org/docs/tools/openzeppelin-contracts +- **Contract Wizard**: https://wizard.openzeppelin.com/stellar +- **Includes**: Tokens (fungible/NFT), governance (timelock), vaults (SEP-56), access control, fee forwarder +- **Crates**: `stellar-tokens`, `stellar-access`, `stellar-contract-utils` + +### Security Tools + +Usage details, detector lists, and workflow guidance live in [the smart contract security guide](../smart-contracts/security.md#tooling). Catalog: + +- [Scout Soroban](https://github.com/CoinFabrik/scout-soroban) (CoinFabrik) - static analysis, 20+ detectors, VSCode extension, SARIF output ([examples](https://github.com/CoinFabrik/scout-soroban-examples)) +- [Security Detectors SDK](https://github.com/OpenZeppelin/soroban-security-detectors-sdk) (OpenZeppelin) - pre-built detectors plus a framework for custom ones +- [Certora Sunbeam Prover](https://docs.certora.com/en/latest/docs/sunbeam/index.html) - formal verification at WASM level, CVLR spec language ([Blend V1 report](https://www.certora.com/reports/blend-smart-contract-verification-report)) +- [Komet](https://docs.runtimeverification.com/komet) (Runtime Verification) - property testing and formal verification via KWasm semantics ([reports](https://github.com/runtimeverification/publications)) +- [Soroban Security Portal](https://sorobansecurity.com) (Inferara) - searchable audit reports and vulnerability database + +### CLI & SDKs + +#### Stellar CLI +Official command-line interface for Stellar. +- **Docs**: https://developers.stellar.org/docs/tools/stellar-cli +- **Features**: Contract build, deploy, invoke, bindings generation + +#### Stellar SDK (JavaScript) +Official JavaScript/TypeScript SDK. +- **GitHub**: https://github.com/stellar/js-stellar-sdk +- **npm**: `@stellar/stellar-sdk` + +#### Soroban Rust SDK +Rust SDK for smart contract development. +- **GitHub**: https://github.com/stellar/rs-soroban-sdk +- **Crate**: `soroban-sdk` + +### AI & MCP Tools + +#### Raven +Remote Model Context Protocol (MCP) server for AI agents. Searches Stellar docs and live ecosystem data, cross-referenced into single answers. Its catalog also serves these skills. +- **Server**: https://raven.stellar.buzz (MCP endpoint: https://raven.stellar.buzz/mcp) +- **Playground**: https://raven.stellar.buzz/playground (hosted chat UI for humans; sign-in required) +- **GitHub**: https://github.com/kalepail/stellar-raven +- **Connect (Claude Code)**: `claude mcp add --transport http stellar-raven "https://raven.stellar.buzz/mcp"` +- **Tools**: `search`, `execute` + +## Oracles + +#### Reflector Network +Community-powered price oracle for Stellar. +- **Website**: https://reflector.network +- **Docs**: https://developers.stellar.org/docs/data/oracles/oracle-providers +- **Features**: SEP-40 compatible, on-chain/off-chain prices, webhooks +- **Integrations**: Blend, OrbitCDP, DeFindex, EquitX, Slender + +#### DIA Oracle +Cross-chain oracle with 20,000+ asset support. +- **Website**: https://diadata.org +- **Blog**: https://www.diadata.org/blog/post/soroban-stellar-oracle-dia/ +- **Features**: VWAPIR methodology, custom feeds + +#### Band Protocol +Cross-chain data oracle on BandChain. +- **Website**: https://bandprotocol.com +- **Architecture**: Cosmos SDK-based, cross-chain + +## Gaming & NFTs + +#### Litemint +NFT marketplace and gaming platform. +- **GitHub**: https://github.com/litemint/litemint-soroban-contracts +- **Contracts**: Timed auctions, royalty payments +- **Features**: Open/sealed bids, ascending/descending price, buy-now + +## Infrastructure + +### Anchors & On/Off Ramps + +#### Stellar Ramps +Suite of open standards for fiat-crypto bridges. +- **Docs**: https://stellar.org/use-cases/ramps +- **SEPs**: SEP-6, SEP-24, SEP-31 (deposits/withdrawals/cross-border) + +#### Anchor Platform +SDF-maintained platform for building SEP-compliant anchors. +- **Docs**: https://developers.stellar.org/docs/learn/fundamentals/anchors +- **GitHub**: https://github.com/stellar/java-stellar-anchor-sdk + +### Block Explorers + +#### StellarExpert +Comprehensive network explorer with analytics. +- **Website**: https://stellar.expert +- **Features**: Transactions, accounts, assets, contracts + +#### Stellar Lab +Developer tools and transaction builder. +- **Website**: https://lab.stellar.org + +#### StellarChain +Alternative explorer with contract support. +- **Website**: https://stellarchain.io + +### Disbursements + +#### Stellar Disbursement Platform (SDP) +Bulk payment infrastructure for enterprises. +- **Docs**: https://developers.stellar.org/docs/category/use-the-stellar-disbursement-platform +- **GitHub**: https://github.com/stellar/stellar-disbursement-platform +- **Use Case**: Mass payments, aid distribution, payroll + +## Example Repositories + +### Official Examples + +#### Soroban Examples +Official educational smart contract examples. +- **GitHub**: https://github.com/stellar/soroban-examples +- **Includes**: Tokens, atomic swaps, auth, events, liquidity pools, timelock, deployer, merkle distribution + +#### Soroban Example dApp +Crowdfunding dApp with Next.js frontend. +- **GitHub**: https://github.com/stellar/soroban-example-dapp +- **Learning**: Full-stack contract development, Freighter integration + +### Community Examples + +#### Soroban Guide (Xycloo) +Learning resources and example contracts. +- **GitHub**: https://github.com/xycloo/soroban-guide +- **Includes**: Events, rock-paper-scissors, vaults, Dutch auctions + +#### Soroban Contracts (icolomina) +Governance and investment contract examples. +- **GitHub**: https://github.com/icolomina/soroban-contracts +- **Includes**: Ballot voting, investment contracts, multisig + +#### Oracle Example +Publisher-subscriber oracle pattern. +- **GitHub**: https://github.com/FredericRezeau/soroban-oracle-example +- **Uses**: soroban-kit oracle module + +#### OZ Stellar NFT +Simple NFT using OpenZeppelin. +- **GitHub**: https://github.com/jamesbachini/OZ-Stellar-NFT + +## Cross-Chain + +#### Axelar +Cross-chain gateway and Interchain Token Service for Stellar. +- **GitHub**: https://github.com/axelarnetwork/axelar-amplifier-stellar +- **Use Case**: Cross-chain messaging, token bridging, interoperability +- **Status**: Active development (verify latest activity before integrating) + +#### Allbridge Core +Cross-chain stable swap bridge (Stellar is 10th supported chain). +- **Use Case**: Cross-chain stablecoin transfers (USDC between Stellar, Base, Arbitrum, etc.) +- **Features**: Automatic Stellar account activation, liquidity pools + +#### LayerZero +Omnichain interoperability protocol with Stellar support. +- **Use Case**: Cross-chain messaging, token bridging (OFT/ONFT), dApp interoperability +- **Features**: OApp standard, Omni-Chain Fungible Tokens, native issuer minting/burning control + +## Builder Teams & Companies + +Notable teams shipping production-level code on Stellar. For a broader directory, see [Stellar Ecosystem](https://stellar.org/ecosystem). + +| Team | Website | GitHub | X/Twitter | Notable Projects | +|------|---------|--------|-----------|-----------------| +| **Lightsail Network** | [lightsail.network](https://lightsail.network) | [lightsail-network](https://github.com/lightsail-network) | [@overcat_me](https://x.com/overcat_me) | Quasar RPC, Java/Python SDKs, Ledger app, validators | +| **PaltaLabs** | [paltalabs.io](https://paltalabs.io) | [paltalabs](https://github.com/paltalabs) | [@PaltaLabs](https://x.com/PaltaLabs) | Soroswap, DeFindex | +| **Aha Labs** | [ahalabs.dev](https://ahalabs.dev) | [AhaLabs](https://github.com/AhaLabs) | [@AhaLabsDev](https://x.com/AhaLabsDev) | Scaffold Stellar, Soroban CLI contributions | +| **OpenZeppelin** | [openzeppelin.com](https://www.openzeppelin.com/networks/stellar) | [OpenZeppelin](https://github.com/OpenZeppelin/stellar-contracts) | [@OpenZeppelin](https://x.com/OpenZeppelin) | Contracts library, Relayer, Monitor, Security Detectors SDK | +| **Cheesecake Labs** | [cheesecakelabs.com](https://cheesecakelabs.com) | [CheesecakeLabs](https://github.com/CheesecakeLabs) | [@CheesecakeLabs](https://x.com/CheesecakeLabs) | Stellar Plus library | +| **Script3 / Blend Capital** | [script3.io](https://script3.io) | [script3](https://github.com/script3), [blend-capital](https://github.com/blend-capital) | [@script3official](https://x.com/script3official) | Blend Protocol | +| **Xycloo Labs** | [xycloo.com](https://xycloo.com) | [Xycloo](https://github.com/Xycloo) | [@heytdep](https://x.com/heytdep) | Mercury indexer, Zephyr VM | +| **CoinFabrik** | [coinfabrik.com](https://www.coinfabrik.com) | [CoinFabrik](https://github.com/CoinFabrik) | [@coinfabrik](https://x.com/coinfabrik) | Scout Soroban (static analysis) | +| **Creit Tech** | [creit.tech](https://creit.tech) | [Creit-Tech](https://github.com/Creit-Tech) | [@CreitTech_](https://x.com/CreitTech_) | Stellar Wallets Kit, xBull, SorobanHub | +| **Ultra Stellar** | [ultrastellar.com](https://ultrastellar.com) | [lobstrco](https://github.com/lobstrco) | [@Lobstrco](https://x.com/Lobstrco) | LOBSTR wallet, StellarExpert | + +## Project Directories + +### Official Directories + +#### Stellar Ecosystem Directory +The canonical, up-to-date project directory maintained by SDF. +- **Website**: https://stellar.org/ecosystem +- **Features**: Search by country, asset, category +- **Includes**: DeFi, wallets, anchors, on/off ramps, exchanges, infrastructure + +#### SCF Project Tracker +All Stellar Community Fund–funded projects with status and milestones. +- **Website**: https://communityfund.stellar.org/projects + +### Funding Programs + +#### Stellar Community Fund (SCF) +Grants up to $150K per funding round. +- **Website**: https://communityfund.stellar.org +- **Funded**: 100+ projects across DeFi, NFT, GameFi, Web3 + +#### Soroban Audit Bank +Security audit funding for SCF projects. +- **Website**: https://stellar.org/grants-and-funding/soroban-audit-bank +- **Features**: Pre-negotiated audit rates, readiness checklist + +## Real-World Assets + +### Major Issuers on Stellar +- **Franklin Templeton**: Regulated fund tokens +- **Ondo**: Tokenized real estate +- **RedSwan**: $100M commercial real estate +- **Centrifuge**: Yield-generating tokens +- **WisdomTree**: Asset-backed tokens + +### Stablecoins +- **USDC** (Circle): Primary USD stablecoin +- **EURC** (Circle): EUR stablecoin +- **PYUSD** (PayPal): Verify current issuance and distribution details before launch planning + +## Enterprise Integrations + +Major companies building on Stellar: +- **PayPal**: PYUSD stablecoin +- **Visa**: Settlement infrastructure +- **Mastercard**: Payment rails +- **Wirex**: USDC/EURC settlement +- **U.S. Bank**: Custom stablecoin testing +- **PwC**: Stablecoin exploration diff --git a/skills/standards/resources.md b/skills/standards/resources.md new file mode 100644 index 0000000..0c33341 --- /dev/null +++ b/skills/standards/resources.md @@ -0,0 +1,265 @@ +# Curated Resources + +Curated documentation, SDK, tooling, and learning links. Companion to [SKILL.md](SKILL.md) (SEP/CAP standards routing); project/protocol catalog lives in [ecosystem.md](ecosystem.md). + + +## Official Documentation + +### Stellar Developer Docs +- [Stellar Documentation](https://developers.stellar.org/docs) - Primary documentation +- [Build Smart Contracts](https://developers.stellar.org/docs/build/smart-contracts) - smart contract guides +- [Build Apps](https://developers.stellar.org/docs/build/apps) - Client application guides +- [Tools & SDKs](https://developers.stellar.org/docs/tools) - Available tooling +- [Networks](https://developers.stellar.org/docs/networks) - Network configuration +- [Learn Fundamentals](https://developers.stellar.org/docs/learn/fundamentals) - Core concepts +- [Security Best Practices](https://developers.stellar.org/docs/build/security-docs) + +### API References +- [Stellar RPC Methods](https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods) - RPC API +- [Horizon API](https://developers.stellar.org/docs/data/apis/horizon/api-reference) - REST API (legacy-focused) +- [Oracle Providers](https://developers.stellar.org/docs/data/oracles/oracle-providers) + +## SDKs + +### Client SDKs (Application Development) +- [JavaScript SDK](https://github.com/stellar/js-stellar-sdk) - `@stellar/stellar-sdk` +- [Python SDK](https://github.com/StellarCN/py-stellar-base) - `stellar-sdk` +- [Java SDK](https://github.com/lightsail-network/java-stellar-sdk) - `network.lightsail:stellar-sdk` (Lightsail Network) +- [Go SDK](https://github.com/stellar/go-stellar-sdk) - `txnbuild`, Horizon & RPC clients +- [Rust SDK (RPC Client)](https://github.com/stellar/rs-stellar-rpc-client) +- [SDK Documentation](https://developers.stellar.org/docs/tools/sdks/client-sdks) + +### Contract SDK (Rust) +- [Soroban Rust SDK](https://github.com/stellar/rs-soroban-sdk) - `soroban-sdk` +- [Soroban SDK Docs](https://docs.rs/soroban-sdk/latest/soroban_sdk/) - Rust docs + +## CLI Tools + +### Stellar CLI +- [Stellar CLI Repository](https://github.com/stellar/stellar-cli) +- [CLI Installation](https://developers.stellar.org/docs/tools/stellar-cli) +- [CLI Commands Reference](https://developers.stellar.org/docs/tools/stellar-cli/stellar-cli-commands) + +### Scaffold Stellar +- [Scaffold Stellar](https://scaffoldstellar.org) - Full-stack dApp scaffolding (contracts + React/Vite/TS frontend) +- [Scaffold Docs](https://developers.stellar.org/docs/tools/scaffold-stellar) - Official documentation +- [GitHub](https://github.com/theahaco/scaffold-stellar) - Open source (Apache 2.0) + +### Quickstart (Local Development) +- [Quickstart Docker](https://github.com/stellar/quickstart) +- [Quickstart Guide](https://developers.stellar.org/docs/tools/quickstart) + +## Contract Libraries & Tools + +### OpenZeppelin Stellar Contracts +- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/stellar-contracts) +- [Documentation](https://developers.stellar.org/docs/tools/openzeppelin-contracts) +- [Contract Wizard](https://wizard.openzeppelin.com/stellar) - Generate contracts + +### Smart Account SDKs +- [Smart Account Kit](https://github.com/kalepail/smart-account-kit) - Production smart wallet SDK (recommended) +- [Passkey Kit](https://github.com/kalepail/passkey-kit) - Legacy passkey wallet SDK +- [Super Peach](https://github.com/kalepail/superpeach) - Smart wallet implementation example + +### Developer Tools +- [Stellar Wallets Kit](https://github.com/Creit-Tech/Stellar-Wallets-Kit) - Multi-wallet integration +- [OpenZeppelin Relayer](https://docs.openzeppelin.com/relayer) - Fee-sponsored transactions + +## Example Repositories + +Official and community example repos are cataloged in [ecosystem.md](ecosystem.md#example-repositories). See also [Stellar Repositories](https://github.com/orgs/stellar/repositories) for everything under the stellar org. + +## Ecosystem Projects + +For DeFi protocols, wallets, oracles, gaming/NFTs, cross-chain bridges, and builder teams, see [ecosystem.md](ecosystem.md). + +## Security + +Vulnerability patterns, checklists, tooling (static analysis, formal verification, monitoring), the Audit Bank, and the Immunefi bounty programs are covered in [the smart contract security guide](../smart-contracts/security.md). The [Security Tools catalog in ecosystem.md](ecosystem.md#security-tools) lists the tool links. + +Additional resources not covered there: +- [HackerOne VDP](https://stellar.org/grants-and-funding/bug-bounty) - Web application vulnerabilities +- [Audited Projects List](https://stellar.org/audit-bank/projects) - Public audit registry +- [Veridise Security Checklist](https://veridise.com/blog/audit-insights/building-on-stellar-soroban-grab-this-security-checklist-to-avoid-vulnerabilities/) - smart-contract security checklist +- [CoinFabrik Audit Reports](https://www.coinfabrik.com/smart-contract-audit-reports/) +- [Certora Security Reports](https://github.com/Certora/SecurityReports) - Includes Stellar verifications + +## Zero-Knowledge Proofs (Status-Sensitive) + +For comprehensive ZK development guidance, see the [zk-proofs skill](../zk-proofs/SKILL.md). + +Always verify CAP status and network support before treating any ZK primitive as production-available. + +### Protocol & Specifications +- [Protocol upgrades](https://stellar.org/protocol-upgrades) - Upgrade timeline and network context +- [CAP-0074](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0074.md) - BN254 host functions (G1 add/mul, pairing check) — Final, Protocol 25+ +- [CAP-0075](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0075.md) - Poseidon/Poseidon2 permutation primitives — Final, Protocol 25+ +- [CAP-0080](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0080.md) - BN254 G1 MSM, Fr arithmetic, on-curve checks — Implemented, Protocol 26+ + +### SDK Documentation +- [Soroban SDK BN254 module](https://docs.rs/soroban-sdk/latest/soroban_sdk/crypto/bn254/) - Verify availability in your pinned SDK version +- [Soroban SDK Crypto](https://docs.rs/soroban-sdk/latest/soroban_sdk/crypto/) - Full crypto module reference + +### Proving Systems & Tooling +- [Noir Documentation](https://noir-lang.org/docs/) - Aztec's ZK domain-specific language +- [RISC Zero](https://dev.risczero.com/) - General-purpose zkVM for Rust programs + +### Example Contracts +- [Soroban Examples](https://github.com/stellar/soroban-examples) - Official examples (includes `groth16_verifier`, `privacy-pools`, `import_ark_bn254`) + +## Testing + +### Testing Guides +- [Definitive Guide to Testing Smart Contracts](https://stellar.org/blog/developers/the-definitive-guide-to-testing-smart-contracts-on-stellar) - Comprehensive overview +- [Fuzzing Guide](https://developers.stellar.org/docs/build/guides/testing/fuzzing) - cargo-fuzz + SorobanArbitrary +- [Fuzzing Example Contract](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/fuzzing) +- [Differential Testing](https://developers.stellar.org/docs/build/guides/testing/differential-tests-with-test-snapshots) - Automatic test snapshots +- [Fork Testing](https://developers.stellar.org/docs/build/guides/testing/fork-testing) - Test against production state +- [Mutation Testing](https://developers.stellar.org/docs/build/guides/testing/mutation-testing) - cargo-mutants + +### Local Development +- [Stellar Quickstart](https://github.com/stellar/quickstart) +- [Docker Setup](https://developers.stellar.org/docs/tools/quickstart) + +### Test Networks +- [Testnet Info](https://developers.stellar.org/docs/networks/testnet) +- [Friendbot](https://friendbot.stellar.org) - Testnet faucet + +## Data & Analytics + +### Data Documentation Hub +- [Stellar Data Overview](https://developers.stellar.org/docs/data) - Choose the right tool (APIs, indexers, analytics, oracles) +- [Indexer Directory](https://developers.stellar.org/docs/data/indexers) - All supported indexers +- [RPC Provider Directory](https://developers.stellar.org/docs/data/apis/rpc/providers) - All RPC infrastructure providers + +### Block Explorers +- [StellarExpert](https://stellar.expert) - Network explorer & analytics +- [StellarExpert API](https://stellar.expert/openapi.html) - Free REST API (no auth, CORS-enabled) +- [Stellar Lab](https://lab.stellar.org) - Developer tools +- [StellarChain](https://stellarchain.io) - Alternative explorer + +### Data Indexers + +Mercury, SubQuery, Goldsky, and Zephyr VM are cataloged with docs links in [ecosystem.md](ecosystem.md#data-indexing). Full directory: [Indexer Directory](https://developers.stellar.org/docs/data/indexers). + +### Historical Data & Analytics +- [Hubble](https://developers.stellar.org/docs/data/analytics/hubble) - BigQuery dataset (updated every 30 min) +- [Galexie](https://developers.stellar.org/docs/data/indexers/build-your-own/galexie) - Data pipeline for building data lakes +- [Data Lake](https://developers.stellar.org/docs/data/apis/rpc/admin-guide/data-lake-integration) - Powers RPC Infinite Scroll (public via AWS Open Data) + +## Infrastructure + +Anchors, on/off ramps, and the Stellar Disbursement Platform are cataloged in [ecosystem.md](ecosystem.md#infrastructure). See also the [Anchor Platform docs](https://developers.stellar.org/docs/category/anchor-platform). + +### RPC Providers +- [RPC Provider Directory](https://developers.stellar.org/docs/data/apis/rpc/providers) - Full list of providers +- [Quasar (Lightsail Network)](https://quasar.lightsail.network) - Stellar-native RPC, Archive RPC, hosted Galexie Data Lake +- [Blockdaemon](https://www.blockdaemon.com/soroban) - Enterprise RPC +- [Validation Cloud](https://www.validationcloud.io) - Testnet & Mainnet +- [QuickNode](https://www.quicknode.com) - Testnet, Mainnet & Dedicated +- [Ankr](https://www.ankr.com) - Testnet & Mainnet +- [NOWNodes](https://nownodes.io) - All networks incl. Futurenet +- [GetBlock](https://getblock.io) - Testnet & Mainnet + +## Protocol & Governance + +### Stellar Protocol +- [Stellar Protocol Repo](https://github.com/stellar/stellar-protocol) +- [CAPs](https://github.com/stellar/stellar-protocol/tree/master/core) - Core Advancement Proposals +- [SEPs](https://github.com/stellar/stellar-protocol/tree/master/ecosystem) - Stellar Ecosystem Proposals + +### Key SEP Standards +- [SEP-0001](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md) - stellar.toml +- [SEP-0010](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md) - Web Authentication +- [SEP-0024](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md) - Hosted Deposit/Withdrawal +- [SEP-0030](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md) - Account Recovery +- [SEP-0031](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0031.md) - Cross-Border Payments +- [SEP-0041](https://developers.stellar.org/docs/tokens/token-interface) - Token Interface +- [SEP-0045](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0045.md) - Web Auth for Contract Accounts (Draft) +- [SEP-0046](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0046.md) - Contract Meta (Active) +- [SEP-0048](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0048.md) - Contract Interface Specification (Active) +- [SEP-0050](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0050.md) - Non-Fungible Tokens (Draft) +- [SEP-0056](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0056.md) - Tokenized Vault Standard (Draft, ERC-4626 equivalent) + +### Network Upgrades +- [Protocol Upgrades](https://stellar.org/protocol-upgrades) +- [SDF Blog](https://stellar.org/blog) + +## Project Directories & Funding + +Directories (Stellar Ecosystem, SCF Project Tracker) and funding programs (SCF, Audit Bank) are cataloged in [ecosystem.md](ecosystem.md#project-directories). See also the [$100M Soroban Adoption Fund](https://stellar.org/soroban). + +## Learning Resources + +### Official Tutorials +- [Getting Started](https://developers.stellar.org/docs/build/smart-contracts/getting-started) +- [Hello World Contract](https://developers.stellar.org/docs/build/smart-contracts/getting-started/hello-world) +- [Deploy to Testnet](https://developers.stellar.org/docs/build/smart-contracts/getting-started/deploy-to-testnet) +- [TypeScript Bindings](https://developers.stellar.org/docs/build/apps/guestbook/bindings) +- [Passkey Prerequisites](https://developers.stellar.org/docs/build/apps/guestbook/passkeys-prerequisites) + +### Video Content +- [Stellar YouTube](https://www.youtube.com/@StellarDevelopmentFoundation) +- [Learn Rust for Smart Contracts (DAO Series)](https://www.youtube.com/watch?v=VeQM5N-0DrI) +- [Call Option Contract Walkthrough](https://www.youtube.com/watch?v=Z8FHVllP_D0) +- [Blend Protocol Tutorial](https://www.youtube.com/watch?v=58j0QkXKiDU) + +### Developer Tools +- [Stella AI Bot](https://developers.stellar.org/docs/tools/developer-tools) - AI assistant for Stellar developer questions +- [Soroban Playground](https://soropg.com) - Browser-based smart contract IDE ([GitHub](https://github.com/jamesbachini/Soroban-Playground)) + +### Blog Posts & Guides +- [Composability on Stellar](https://stellar.org/blog/developers/composability-on-stellar-from-concept-to-reality) +- [Testing Smart Contracts Guide](https://stellar.org/blog/developers/the-definitive-guide-to-testing-smart-contracts-on-stellar) +- [Sorobounty Spectacular Tutorials](https://stellar.org/blog/developers/sorobounty-spectacular-dapp-tutorials) +- [Learn Soroban 1-2-3 (Community Tools)](https://stellar.org/blog/developers/learn-soroban-as-easy-as-1-2-3-with-community-made-tooling) +- [SCF Infrastructure Recap](https://stellar.org/blog/ecosystem/stellar-community-fund-recap-soroban-infrastructure) +- [Native vs Soroban Tokens](https://cheesecakelabs.com/blog/native-tokens-vs-soroban-tokens/) +- [57Blocks Integration Testing](https://57blocks.com/blog/soroban-integration-testing-best-practices) + +## Stablecoins on Stellar + +### Major Stablecoins +- [USDC on Stellar](https://www.circle.com/usdc/stellar) - Circle +- [EURC on Stellar](https://www.circle.com/en/eurc) - Circle +- PYUSD (PayPal) - Verify current issuer/distribution details before integration + +### Asset Discovery +- [StellarExpert Asset Directory](https://stellar.expert/explorer/public/asset) + +## Community + +### Developer Resources +- [Stellar Developers Discord](https://discord.gg/stellar) +- [Stellar Stack Exchange](https://stellar.stackexchange.com) +- [GitHub Discussions](https://github.com/stellar/stellar-protocol/discussions) + +### Key People to Follow + +Builders and contributors actively shaping the Stellar ecosystem: + +| Name | GitHub | X/Twitter | Focus | +|------|--------|-----------|-------| +| Tyler van der Hoeven | [kalepail](https://github.com/kalepail) | [@kalepail](https://x.com/kalepail) | SDF DevRel, Smart Account Kit, Passkey Kit, Launchtube | +| Leigh McCulloch | [leighmcculloch](https://github.com/leighmcculloch) | [@___leigh___](https://x.com/___leigh___) | SDF core engineer, Stellar CLI, Soroban SDK | +| James Bachini | [jamesbachini](https://github.com/jamesbachini) | [@james_bachini](https://x.com/james_bachini) | SDF Dev in Residence, Soroban Playground, tutorials | +| Elliot Voris | [ElliotFriend](https://github.com/ElliotFriend) | [@ElliotFriend](https://x.com/ElliotFriend) | SDF DevRel, community education | +| Carsten Jacobsen | [carstenjacobsen](https://github.com/carstenjacobsen) | — | SDF, weekly dev meetings, Soroban examples | +| Esteban Iglesias | [esteblock](https://github.com/esteblock) | [@esteblock_dev](https://x.com/esteblock_dev) | PaltaLabs, Soroswap, DeFindex | +| Markus Paulson-Luna | [markuspluna](https://github.com/markuspluna) | [@script3official](https://x.com/script3official) | Script3, Blend Protocol | +| Alexander Mootz | [mootz12](https://github.com/mootz12) | — | Script3, Blend contracts | +| Tommaso | [heytdep](https://github.com/heytdep) | [@heytdep](https://x.com/heytdep) | Xycloo Labs, Mercury indexer, ZephyrVM | +| OrbitLens | [orbitlens](https://github.com/orbitlens) | [@orbitlens](https://x.com/orbitlens) | Reflector oracle, StellarExpert, Albedo | +| Frederic Rezeau | [FredericRezeau](https://github.com/FredericRezeau) | [@FredericRezeau](https://x.com/FredericRezeau) | Litemint, soroban-kit, gaming | +| Jun Luo (Overcat) | [overcat](https://github.com/overcat) | [@overcat_me](https://x.com/overcat_me) | Lightsail Network, Quasar RPC, Java/Python SDKs, Ledger app | +| Jay Geng | [jayz22](https://github.com/jayz22) | — | SDF, Soroban SDK, confidential tokens | +| Chad Ostrowski | [chadoh](https://github.com/chadoh) | [@chadoh](https://x.com/chadoh) | Aha Labs CEO, Scaffold Stellar, Soroban CLI | +| Willem Wyndham | [willemneal](https://github.com/willemneal) | [@willemneal](https://x.com/willemneal) | Aha Labs co-founder, Scaffold Stellar, JS contract client | + +### Builder Teams & Companies +See the [Builder Teams table in ecosystem.md](ecosystem.md#builder-teams--companies) for teams shipping production code on Stellar, with GitHub orgs, websites, and Twitter handles. + +### Foundation +- [Stellar Development Foundation](https://stellar.org/foundation) +- [Foundation Roadmap](https://stellar.org/foundation/roadmap) +- [Ecosystem Blog](https://stellar.org/blog/ecosystem) From 599381b45400297b25775e433d7b8b323ac38b23 Mon Sep 17 00:00:00 2001 From: Kaan Kacar Date: Tue, 11 Aug 2026 03:19:10 +0300 Subject: [PATCH 2/5] Split dapp: router + react/data-fetching/smart-accounts companions SKILL.md keeps SDK setup, wallet connection, and tx build/submit (467 lines). React + Next.js patterns, client-side reads, and passkeys/fee sponsorship move to companion files; Quick Navigation becomes the task-to-file routing table. --- skills/dapp/SKILL.md | 326 ++-------------------------------- skills/dapp/data-fetching.md | 85 +++++++++ skills/dapp/react.md | 147 +++++++++++++++ skills/dapp/smart-accounts.md | 83 +++++++++ 4 files changed, 328 insertions(+), 313 deletions(-) create mode 100644 skills/dapp/data-fetching.md create mode 100644 skills/dapp/react.md create mode 100644 skills/dapp/smart-accounts.md diff --git a/skills/dapp/SKILL.md b/skills/dapp/SKILL.md index 59f35ec..560d222 100644 --- a/skills/dapp/SKILL.md +++ b/skills/dapp/SKILL.md @@ -32,13 +32,19 @@ Client-side development with `@stellar/stellar-sdk`, wallet connection, signing, - Clean separation of client/server in Next.js - Transaction sending with proper confirmation handling -## Quick Navigation -- SDK setup and env config: [SDK Initialization](#sdk-initialization) -- Wallet integrations: [Wallet Integration](#wallet-integration) -- Tx build/send patterns: [Transaction Building](#transaction-building), [Transaction Submission](#transaction-submission) -- React + Next.js patterns: [React Components](#react-components), [Next.js App Router Setup](#nextjs-app-router-setup) -- Smart wallets/passkeys: [Smart Accounts (Passkey Wallets)](#smart-accounts-passkey-wallets) -- Production UX checklist: [Transaction UX Checklist](#transaction-ux-checklist) +## Read the file that matches the task + +This file covers SDK setup, wallet connection, and transaction build/sign/submit. The deep dives live alongside it: + +| Task | File | +|------|------| +| SDK setup and env config | [SDK Initialization](#sdk-initialization) (below) | +| Wallet integrations (Freighter, Wallets Kit) | [Wallet Integration](#wallet-integration) (below) | +| Tx build/send patterns | [Transaction Building](#transaction-building), [Transaction Submission](#transaction-submission) (below) | +| Connect-wallet button, payment form, Next.js App Router wiring | [react.md](react.md) | +| Account balances, contract reads (`queryContract`), raw ledger entries | [data-fetching.md](data-fetching.md) | +| Passkey smart wallets (Smart Account Kit), gasless tx via OpenZeppelin Relayer | [smart-accounts.md](smart-accounts.md) | +| Production UX checklist | [Transaction UX Checklist](#transaction-ux-checklist) (below) | ## Recommended Dependencies @@ -445,312 +451,6 @@ async function submitClassicTransaction(signedXdr: string) { } ``` -## React Components - -### Connect Wallet Button -```tsx -// components/ConnectButton.tsx -"use client"; - -import { useFreighter } from "@/hooks/useFreighter"; - -export function ConnectButton() { - const { connected, address, connect, disconnect } = useFreighter(); - - if (connected && address) { - return ( -
- - {address.slice(0, 4)}...{address.slice(-4)} - - -
- ); - } - - return ( - - ); -} -``` - -### Send Payment Form -```tsx -// components/SendPayment.tsx -"use client"; - -import { useState } from "react"; -import { useFreighter } from "@/hooks/useFreighter"; -import { buildPaymentTx, submitTransaction } from "@/lib/transactions"; -import { config } from "@/lib/stellar"; - -export function SendPayment() { - const { address, sign } = useFreighter(); - const [destination, setDestination] = useState(""); - const [amount, setAmount] = useState(""); - const [status, setStatus] = useState(null); - const [loading, setLoading] = useState(false); - - const handleSubmit = async (e: React.FormEvent) => { - e.preventDefault(); - if (!address) return; - - setLoading(true); - setStatus("Building transaction..."); - - try { - const xdr = await buildPaymentTx(address, destination, amount); - - setStatus("Please sign in your wallet..."); - const signedXdr = await sign(xdr, config.networkPassphrase); - - setStatus("Submitting transaction..."); - const result = await submitTransaction(signedXdr); - - setStatus(`Success! Hash: ${result.hash}`); - } catch (error) { - setStatus(`Error: ${error.message}`); - } finally { - setLoading(false); - } - }; - - return ( -
- setDestination(e.target.value)} - className="w-full p-2 border rounded" - /> - setAmount(e.target.value)} - className="w-full p-2 border rounded" - /> - - {status &&

{status}

} -
- ); -} -``` - -## Next.js App Router Setup - -### Provider Component -```tsx -// app/providers.tsx -"use client"; - -import { ReactNode } from "react"; - -// Add any context providers here -export function Providers({ children }: { children: ReactNode }) { - return <>{children}; -} -``` - -### Layout -```tsx -// app/layout.tsx -import { Providers } from "./providers"; - -export default function RootLayout({ - children, -}: { - children: React.ReactNode; -}) { - return ( - - - {children} - - - ); -} -``` - -## Data Fetching - -### Account Balance -```typescript -import { NotFoundError } from "@stellar/stellar-sdk"; -import { horizon } from "@/lib/stellar"; - -export async function getBalance(address: string) { - try { - const account = await horizon.loadAccount(address); - const nativeBalance = account.balances.find( - (b) => b.asset_type === "native" - ); - return nativeBalance?.balance || "0"; - } catch (error) { - // loadAccount rejects with the typed NotFoundError for an unfunded account. - if (error instanceof NotFoundError) { - return "0"; // Account not funded yet - } - throw error; - } -} -``` - -> For submission failures, Horizon returns result codes under `error.response?.data?.extras?.result_codes` (`transaction` + per-`operation`). See [Handle Errors](https://stellar.github.io/js-stellar-sdk/guides/05-handle-errors). - -### Contract State - -For a read-only contract call, `rpc.Server` has one-line shortcuts that build the contract interface for you (including the built-in spec for Stellar Asset Contracts), so no client setup or manual ScVal work is needed: - -```typescript -import { rpc } from "@/lib/stellar"; - -// Run a read-only method and get the decoded result directly. -const { result: balance, isReadCall } = await rpc.queryContract( - tokenId, - "balance", - { id: "G..." } // named args, keyed by parameter name; omit for no-arg methods -); - -// Discover a contract's callable methods from just its ID. -const methods = await rpc.getContractMethods(tokenId); -// [{ name: "balance", inputs: [{ name: "id", type: "Address" }], outputs: ["I128"] }, ...] -``` - -`isReadCall` is per-call: `false` means the `result` is only a simulation preview of a call that would change state (apply it by signing a transaction via `contract.Client`). - -
-Advanced: read a raw ledger entry - -Reach for `getLedgerEntries` only when you need a specific storage key that isn't exposed as a contract method. - -```typescript -import * as StellarSdk from "@stellar/stellar-sdk"; -import { rpc } from "@/lib/stellar"; - -export async function getContractData( - contractId: string, - key: StellarSdk.xdr.ScVal -) { - const ledgerKey = StellarSdk.xdr.LedgerKey.contractData( - new StellarSdk.xdr.LedgerKeyContractData({ - contract: new StellarSdk.Address(contractId).toScAddress(), - key: key, - durability: StellarSdk.xdr.ContractDataDurability.persistent(), - }) - ); - - const entries = await rpc.getLedgerEntries(ledgerKey); - - if (entries.entries.length === 0) { - return null; - } - - return StellarSdk.scValToNative( - entries.entries[0].val.contractData().val() - ); -} -``` - -
- -## Smart Accounts (Passkey Wallets) - -For passwordless authentication using WebAuthn passkeys, use Smart Account Kit. - -### Installation -```bash -npm install smart-account-kit -``` - -### Quick Start -```typescript -import { SmartAccountKit, IndexedDBStorage } from 'smart-account-kit'; - -const kit = new SmartAccountKit({ - rpcUrl: 'https://soroban-testnet.stellar.org', - networkPassphrase: 'Test SDF Network ; September 2015', - accountWasmHash: 'YOUR_ACCOUNT_WASM_HASH', - webauthnVerifierAddress: 'CWEBAUTHN_VERIFIER_ADDRESS', - storage: new IndexedDBStorage(), -}); - -// On page load - silent restore from stored session -const result = await kit.connectWallet(); -if (!result) { - showConnectButton(); // No stored session -} - -// Create new wallet with passkey -const { contractId, credentialId } = await kit.createWallet( - 'My App', - 'user@example.com', - { autoSubmit: true } -); - -// Connect to existing wallet (prompts for passkey) -await kit.connectWallet({ prompt: true }); - -// Sign and submit transactions -const result = await kit.signAndSubmit(transaction); - -// Transfer tokens -await kit.transfer(tokenContract, recipient, amount); -``` - -### Key Features -- **Session Management**: Automatic credential persistence and silent reconnection -- **Multiple Signer Types**: Passkeys (secp256r1), Ed25519 keys, policies -- **Context Rules**: Fine-grained authorization for different operations -- **Policy Support**: Threshold multisig, spending limits, custom policies -- **External Wallet Support**: Connect Freighter, LOBSTR via adapters -- **Gasless Transactions**: Optional relayer integration for fee sponsoring - -### Fee Sponsorship with OpenZeppelin Relayer - -The [OpenZeppelin Relayer](https://docs.openzeppelin.com/relayer/stellar) (also called Stellar Channels Service) handles gasless transaction submission. It replaces the deprecated Launchtube service and uses Stellar's native fee bump mechanism so users don't need XLM for fees. - -```typescript -import * as RPChannels from "@openzeppelin/relayer-plugin-channels"; - -const client = new RPChannels.ChannelsClient({ - baseUrl: "https://channels.openzeppelin.com/testnet", - apiKey: "your-api-key", -}); - -// Submit a smart contract call with fee sponsorship -const response = await client.submitSorobanTransaction({ - func: contractFunc, - auth: contractAuth, -}); -``` - -- **Testnet hosted instance**: `https://channels.openzeppelin.com/testnet` (API keys at `/gen`) -- **Production**: Self-host via Docker ([GitHub](https://github.com/OpenZeppelin/openzeppelin-relayer)) -- **Stellar docs**: https://developers.stellar.org/docs/tools/openzeppelin-relayer - -### Resources -- **GitHub**: https://github.com/kalepail/smart-account-kit -- **OpenZeppelin Contracts**: https://github.com/OpenZeppelin/stellar-contracts -- **Legacy SDK**: https://github.com/kalepail/passkey-kit (for simpler use cases) - ## Transaction UX Checklist - [ ] Show loading state during wallet signing diff --git a/skills/dapp/data-fetching.md b/skills/dapp/data-fetching.md new file mode 100644 index 0000000..4966ca8 --- /dev/null +++ b/skills/dapp/data-fetching.md @@ -0,0 +1,85 @@ +# Client-Side Data Fetching + +Reading balances and contract state from the client. Companion to [SKILL.md](SKILL.md); UI patterns live in [react.md](react.md). + +## Data Fetching + +### Account Balance +```typescript +import { NotFoundError } from "@stellar/stellar-sdk"; +import { horizon } from "@/lib/stellar"; + +export async function getBalance(address: string) { + try { + const account = await horizon.loadAccount(address); + const nativeBalance = account.balances.find( + (b) => b.asset_type === "native" + ); + return nativeBalance?.balance || "0"; + } catch (error) { + // loadAccount rejects with the typed NotFoundError for an unfunded account. + if (error instanceof NotFoundError) { + return "0"; // Account not funded yet + } + throw error; + } +} +``` + +> For submission failures, Horizon returns result codes under `error.response?.data?.extras?.result_codes` (`transaction` + per-`operation`). See [Handle Errors](https://stellar.github.io/js-stellar-sdk/guides/05-handle-errors). + +### Contract State + +For a read-only contract call, `rpc.Server` has one-line shortcuts that build the contract interface for you (including the built-in spec for Stellar Asset Contracts), so no client setup or manual ScVal work is needed: + +```typescript +import { rpc } from "@/lib/stellar"; + +// Run a read-only method and get the decoded result directly. +const { result: balance, isReadCall } = await rpc.queryContract( + tokenId, + "balance", + { id: "G..." } // named args, keyed by parameter name; omit for no-arg methods +); + +// Discover a contract's callable methods from just its ID. +const methods = await rpc.getContractMethods(tokenId); +// [{ name: "balance", inputs: [{ name: "id", type: "Address" }], outputs: ["I128"] }, ...] +``` + +`isReadCall` is per-call: `false` means the `result` is only a simulation preview of a call that would change state (apply it by signing a transaction via `contract.Client`). + +
+Advanced: read a raw ledger entry + +Reach for `getLedgerEntries` only when you need a specific storage key that isn't exposed as a contract method. + +```typescript +import * as StellarSdk from "@stellar/stellar-sdk"; +import { rpc } from "@/lib/stellar"; + +export async function getContractData( + contractId: string, + key: StellarSdk.xdr.ScVal +) { + const ledgerKey = StellarSdk.xdr.LedgerKey.contractData( + new StellarSdk.xdr.LedgerKeyContractData({ + contract: new StellarSdk.Address(contractId).toScAddress(), + key: key, + durability: StellarSdk.xdr.ContractDataDurability.persistent(), + }) + ); + + const entries = await rpc.getLedgerEntries(ledgerKey); + + if (entries.entries.length === 0) { + return null; + } + + return StellarSdk.scValToNative( + entries.entries[0].val.contractData().val() + ); +} +``` + +
diff --git a/skills/dapp/react.md b/skills/dapp/react.md new file mode 100644 index 0000000..a34c39c --- /dev/null +++ b/skills/dapp/react.md @@ -0,0 +1,147 @@ +# React & Next.js Patterns + +React components and Next.js App Router wiring for a Stellar dapp. Companion to [SKILL.md](SKILL.md) (SDK setup, wallets, transactions); client-side reads live in [data-fetching.md](data-fetching.md), passkey wallets in [smart-accounts.md](smart-accounts.md). + +## React Components + +### Connect Wallet Button +```tsx +// components/ConnectButton.tsx +"use client"; + +import { useFreighter } from "@/hooks/useFreighter"; + +export function ConnectButton() { + const { connected, address, connect, disconnect } = useFreighter(); + + if (connected && address) { + return ( +
+ + {address.slice(0, 4)}...{address.slice(-4)} + + +
+ ); + } + + return ( + + ); +} +``` + +### Send Payment Form +```tsx +// components/SendPayment.tsx +"use client"; + +import { useState } from "react"; +import { useFreighter } from "@/hooks/useFreighter"; +import { buildPaymentTx, submitTransaction } from "@/lib/transactions"; +import { config } from "@/lib/stellar"; + +export function SendPayment() { + const { address, sign } = useFreighter(); + const [destination, setDestination] = useState(""); + const [amount, setAmount] = useState(""); + const [status, setStatus] = useState(null); + const [loading, setLoading] = useState(false); + + const handleSubmit = async (e: React.FormEvent) => { + e.preventDefault(); + if (!address) return; + + setLoading(true); + setStatus("Building transaction..."); + + try { + const xdr = await buildPaymentTx(address, destination, amount); + + setStatus("Please sign in your wallet..."); + const signedXdr = await sign(xdr, config.networkPassphrase); + + setStatus("Submitting transaction..."); + const result = await submitTransaction(signedXdr); + + setStatus(`Success! Hash: ${result.hash}`); + } catch (error) { + setStatus(`Error: ${error.message}`); + } finally { + setLoading(false); + } + }; + + return ( +
+ setDestination(e.target.value)} + className="w-full p-2 border rounded" + /> + setAmount(e.target.value)} + className="w-full p-2 border rounded" + /> + + {status &&

{status}

} +
+ ); +} +``` + +## Next.js App Router Setup + +### Provider Component +```tsx +// app/providers.tsx +"use client"; + +import { ReactNode } from "react"; + +// Add any context providers here +export function Providers({ children }: { children: ReactNode }) { + return <>{children}; +} +``` + +### Layout +```tsx +// app/layout.tsx +import { Providers } from "./providers"; + +export default function RootLayout({ + children, +}: { + children: React.ReactNode; +}) { + return ( + + + {children} + + + ); +} +``` diff --git a/skills/dapp/smart-accounts.md b/skills/dapp/smart-accounts.md new file mode 100644 index 0000000..79d99e0 --- /dev/null +++ b/skills/dapp/smart-accounts.md @@ -0,0 +1,83 @@ +# Smart Accounts (Passkeys) & Fee Sponsorship + +Passkey smart wallets with Smart Account Kit and gasless transactions via the OpenZeppelin Relayer. Companion to [SKILL.md](SKILL.md). + +## Smart Accounts (Passkey Wallets) + +For passwordless authentication using WebAuthn passkeys, use Smart Account Kit. + +### Installation +```bash +npm install smart-account-kit +``` + +### Quick Start +```typescript +import { SmartAccountKit, IndexedDBStorage } from 'smart-account-kit'; + +const kit = new SmartAccountKit({ + rpcUrl: 'https://soroban-testnet.stellar.org', + networkPassphrase: 'Test SDF Network ; September 2015', + accountWasmHash: 'YOUR_ACCOUNT_WASM_HASH', + webauthnVerifierAddress: 'CWEBAUTHN_VERIFIER_ADDRESS', + storage: new IndexedDBStorage(), +}); + +// On page load - silent restore from stored session +const result = await kit.connectWallet(); +if (!result) { + showConnectButton(); // No stored session +} + +// Create new wallet with passkey +const { contractId, credentialId } = await kit.createWallet( + 'My App', + 'user@example.com', + { autoSubmit: true } +); + +// Connect to existing wallet (prompts for passkey) +await kit.connectWallet({ prompt: true }); + +// Sign and submit transactions +const result = await kit.signAndSubmit(transaction); + +// Transfer tokens +await kit.transfer(tokenContract, recipient, amount); +``` + +### Key Features +- **Session Management**: Automatic credential persistence and silent reconnection +- **Multiple Signer Types**: Passkeys (secp256r1), Ed25519 keys, policies +- **Context Rules**: Fine-grained authorization for different operations +- **Policy Support**: Threshold multisig, spending limits, custom policies +- **External Wallet Support**: Connect Freighter, LOBSTR via adapters +- **Gasless Transactions**: Optional relayer integration for fee sponsoring + +### Fee Sponsorship with OpenZeppelin Relayer + +The [OpenZeppelin Relayer](https://docs.openzeppelin.com/relayer/stellar) (also called Stellar Channels Service) handles gasless transaction submission. It replaces the deprecated Launchtube service and uses Stellar's native fee bump mechanism so users don't need XLM for fees. + +```typescript +import * as RPChannels from "@openzeppelin/relayer-plugin-channels"; + +const client = new RPChannels.ChannelsClient({ + baseUrl: "https://channels.openzeppelin.com/testnet", + apiKey: "your-api-key", +}); + +// Submit a smart contract call with fee sponsorship +const response = await client.submitSorobanTransaction({ + func: contractFunc, + auth: contractAuth, +}); +``` + +- **Testnet hosted instance**: `https://channels.openzeppelin.com/testnet` (API keys at `/gen`) +- **Production**: Self-host via Docker ([GitHub](https://github.com/OpenZeppelin/openzeppelin-relayer)) +- **Stellar docs**: https://developers.stellar.org/docs/tools/openzeppelin-relayer + +### Resources +- **GitHub**: https://github.com/kalepail/smart-account-kit +- **OpenZeppelin Contracts**: https://github.com/OpenZeppelin/stellar-contracts +- **Legacy SDK**: https://github.com/kalepail/passkey-kit (for simpler use cases) From c5cc806ed1e2b1c8847b84019e6bb9e757759c8c Mon Sep 17 00:00:00 2001 From: Kaan Kacar Date: Tue, 11 Aug 2026 03:19:10 +0300 Subject: [PATCH 3/5] Split agentic-payments: shared-setup router + x402.md + mpp.md SKILL.md keeps the decision table, the shared testnet account setup (keypairs, funding, trustlines, Circle faucet), and the two-USDC-address reference (116 lines). Part 1 becomes x402.md with the OZ-specific runbook steps renumbered; Part 2 becomes mpp.md. --- skills/agentic-payments/SKILL.md | 574 +------------------------------ skills/agentic-payments/mpp.md | 282 +++++++++++++++ skills/agentic-payments/x402.md | 266 ++++++++++++++ 3 files changed, 567 insertions(+), 555 deletions(-) create mode 100644 skills/agentic-payments/mpp.md create mode 100644 skills/agentic-payments/x402.md diff --git a/skills/agentic-payments/SKILL.md b/skills/agentic-payments/SKILL.md index 72f908f..d689a4f 100644 --- a/skills/agentic-payments/SKILL.md +++ b/skills/agentic-payments/SKILL.md @@ -19,14 +19,25 @@ Two complementary protocols for AI-agent and machine-to-machine payments on Stel | Setup complexity | Low | Low | Medium (deploy contract first) | | Best for | Quickest setup, fee-free clients | No third-party dep | High-frequency agents | -- Selling an API, want zero-XLM clients → see **x402 Seller** below -- Calling an x402 API from an agent → see **x402 Buyer** below -- Selling an API, no facilitator dependency → see **MPP Charge** below -- Agent making many requests per session → see **MPP Session** below +- Selling an API, want zero-XLM clients → **x402 Seller** in [x402.md](x402.md) +- Calling an x402 API from an agent → **x402 Buyer** in [x402.md](x402.md) +- Selling an API, no facilitator dependency → **Charge mode** in [mpp.md](mpp.md) +- Agent making many requests per session → **Session mode** in [mpp.md](mpp.md) - Unsure → x402 (lowest friction to get started) All protocols use USDC (SEP-41 SAC) by default; `stellar:testnet` / `stellar:pubnet` CAIP-2 network IDs. +## Read the file that matches the task + +This file carries the decision table, the shared testnet account setup, and the USDC address reference. The protocol playbooks live alongside it: + +| Task | File | +|------|------| +| Sell a paid API via a facilitator (zero-XLM clients), build an x402 buyer agent | [x402.md](x402.md) | +| Facilitator-free per-request payments (Charge) or channel-backed sessions (Session) | [mpp.md](mpp.md) | +| Create/fund testnet accounts, add USDC trustlines, get testnet USDC | [Testnet setup](#testnet-setup-shared) (below) | +| Which USDC address goes where (classic issuer vs SAC) | [Two USDC addresses](#two-usdc-addresses-dont-confuse-them) (below) | + ## Related skills - The SACs the protocols call → `../smart-contracts/SKILL.md` - USDC and other classic assets → `../assets/SKILL.md` @@ -34,151 +45,12 @@ All protocols use USDC (SEP-41 SAC) by default; `stellar:testnet` / `stellar:pub - RPC simulation / submission patterns → `../data/SKILL.md` - SEP-41 (token interface) and related standards → `../standards/SKILL.md` ---- - -# Part 1: x402 — Paid APIs + Agent Buyer Clients - - -## When to use x402 -x402 is the right choice when: -- You want the fastest path to a paid API — minimal code, no contract deployment -- You want clients (including AI agents) to pay with **zero XLM** — the OZ Channels facilitator sponsors all network fees -- You're building on top of an existing x402 ecosystem (Coinbase, other chains) - -Trade-off: you depend on OZ Channels (or a self-hosted relayer) for verification and settlement. If you need zero third-party dependency, use MPP Charge (Part 2 below) instead. - -## How x402 works on Stellar - -``` -Client → GET /resource → Server -Client ← 402 Payment Required (payment requirements) ← Server -Client builds SAC USDC transfer -Client signs auth entries only (not the full tx envelope) -Client → GET /resource + X-PAYMENT header → Server -Server → OZ Channels /verify + /settle → Stellar (~5s) -Client ← 200 OK + resource -``` - -The key Stellar difference: clients sign **auth entries**, not full transaction envelopes. The facilitator assembles the transaction, pays fees, and submits. Clients need zero XLM. - -## Seller: monetize an Express API - -```bash -npm install @x402/express @x402/core @x402/stellar express dotenv -npm pkg set type=module -``` - -```js -// server.js -import "dotenv/config"; -import express from "express"; -import { paymentMiddleware, x402ResourceServer } from "@x402/express"; -import { HTTPFacilitatorClient } from "@x402/core/server"; -import { ExactStellarScheme } from "@x402/stellar/exact/server"; - -// Drive the CAIP-2 network ID from one place. Switching to mainnet means -// flipping STELLAR_NETWORK and FACILITATOR_URL in .env, nothing in code. -const NETWORK = process.env.STELLAR_NETWORK || "stellar:testnet"; - -if (!process.env.OZ_API_KEY) { - throw new Error( - "OZ_API_KEY is required. Generate one at https://channels.openzeppelin.com/testnet/gen (testnet) or https://channels.openzeppelin.com/gen (mainnet)." - ); -} - -const facilitator = new HTTPFacilitatorClient({ - url: process.env.FACILITATOR_URL ?? "https://channels.openzeppelin.com/x402/testnet", - // OZ Channels requires Bearer auth on both testnet and mainnet - createAuthHeaders: async () => { - const h = { Authorization: `Bearer ${process.env.OZ_API_KEY}` }; - return { verify: h, settle: h, supported: h }; - }, -}); - -const resourceServer = new x402ResourceServer(facilitator) - .register(NETWORK, new ExactStellarScheme()); - -const app = express(); - -app.use( - paymentMiddleware( - { - "GET /weather": { - accepts: { - scheme: "exact", - price: "$0.001", // human-readable, auto-converts to 7-decimal USDC units - network: NETWORK, - payTo: process.env.STELLAR_RECIPIENT, // recipient G... account - }, - description: "Current weather data", - }, - }, - resourceServer - ) -); - -app.get("/weather", (_req, res) => { - res.json({ city: "San Francisco", temp: 18, conditions: "Foggy" }); -}); - -app.listen(3001, () => console.log(`x402 server on http://localhost:3001 (${NETWORK})`)); -``` - -**Env vars:** -- `STELLAR_NETWORK` — CAIP-2 network ID; defaults to `stellar:testnet`. Set to `stellar:pubnet` for mainnet. -- `STELLAR_RECIPIENT` — your G... address (receives USDC, needs a USDC trustline) -- `OZ_API_KEY` — OZ Channels API key (**required on both testnet and mainnet**; generate at the link in the runbook below) -- `FACILITATOR_URL` — defaults to testnet URL above; set to `https://channels.openzeppelin.com/x402` for mainnet - -**Price format options:** -- `"$0.001"` — human-readable, auto-converts to 7-decimal USDC units -- `{ amount: "1000", asset: "ASSET_SAC_CONTRACT_ID" }` — explicit base units for non-USDC assets - -**`payTo` is the recipient's classic Stellar account (`G...`), not the USDC SAC contract address.** Sending USDC lands in the classic balance of the `payTo` account, which is why that account also needs a USDC trustline. The SAC contract address is what the protocol invokes `transfer` on; see "Two USDC addresses" below. - -## Buyer: agent client - -```bash -npm install @x402/fetch @x402/stellar dotenv -npm pkg set type=module -``` - -```js -// client.js -import "dotenv/config"; -import { wrapFetchWithPaymentFromConfig } from "@x402/fetch"; -import { createEd25519Signer } from "@x402/stellar"; -import { ExactStellarScheme } from "@x402/stellar/exact/client"; - -const NETWORK = process.env.STELLAR_NETWORK || "stellar:testnet"; - -// createEd25519Signer takes the raw S... secret string and the CAIP-2 network ID. -// Do NOT pre-wrap with Keypair.fromSecret or call getNetworkPassphrase yourself — -// the signer does both internally. -const signer = createEd25519Signer(process.env.STELLAR_SECRET_KEY, NETWORK); - -// wrapFetchWithPaymentFromConfig returns a fetch that handles 402 negotiation -// and auth-entry signing transparently. -const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, { - schemes: [{ network: NETWORK, client: new ExactStellarScheme(signer) }], -}); - -const res = await fetchWithPayment("http://localhost:3001/weather"); -console.log(await res.json()); -// Paid automatically: 402 negotiation + auth-entry signing under the hood -``` -**Env vars:** -- `STELLAR_NETWORK` — CAIP-2 network ID; defaults to `stellar:testnet`. Must match the server's network. -- `STELLAR_SECRET_KEY` — your S... secret key (needs USDC trustline + balance) +## Testnet setup (shared) -**Browser frontends:** this client uses Node `fetch` and `createEd25519Signer`, both of which run in Node. A vanilla browser cannot sign contract auth entries through a typical wallet extension without additional glue. For a browser payer, run the x402 client server-side and expose a thin proxy endpoint to the page, or wire up Wallets-Kit / Freighter with custom auth-entry signing. +Both protocols need the same base setup: a **client/payer** account (signs and pays from a USDC balance) and a **server/recipient** account. Both need a USDC trustline. -## Testnet runbook - -You need two Stellar testnet accounts: a **client/payer** (signs and pays from a USDC balance) and a **server/recipient** (the `payTo` in your route config). Both need a USDC trustline. - -Two steps are web-only (Captcha or auth form) and cannot be scripted: the Circle USDC faucet and the OZ Channels key generator. Everything else can be automated. A complete `setup.js` sketch lives at the end of this section. +One step is web-only (Captcha) and cannot be scripted: the Circle USDC faucet. Everything else can be automated — [x402.md](x402.md) ships a `setup.js` that does steps 1–3 and writes a starter `.env`. (x402 additionally needs the web-only OZ Channels key generator; MPP needs no third-party key.) 1. **Generate two keypairs** ```bash @@ -224,63 +96,6 @@ Two steps are web-only (Captcha or auth form) and cannot be scripted: the Circle 4. **Fund the PAYER with testnet USDC** — open the [Circle testnet faucet](https://faucet.circle.com/), select **Stellar testnet**, paste the payer's `G...`. Web Captcha; no API. -5. **Generate an OZ Channels testnet API key** ([channels.openzeppelin.com/testnet/gen](https://channels.openzeppelin.com/testnet/gen)). **Required, not optional.** Without it the server crashes at startup with `Failed to initialize: no supported payment kinds loaded from any facilitator`. - -6. **Fill in `.env`** - ``` - STELLAR_NETWORK=stellar:testnet - STELLAR_RECIPIENT=G... (recipient public key) - STELLAR_SECRET_KEY=S... (payer secret key) - OZ_API_KEY=... - ``` - -7. **Run it** - ```bash - node server.js - # in another terminal - node client.js - ``` - -### Optional: setup.js to automate steps 1–3 - -Drop this in your project and run once. It generates keys, friendbots, and adds USDC trustlines, then writes a starter `.env` so you only need to do the two manual web steps afterward. - -```js -// setup.js -import fs from "fs/promises"; -import { - Keypair, Horizon, Networks, TransactionBuilder, Operation, Asset, BASE_FEE, -} from "@stellar/stellar-sdk"; - -const USDC_ISSUER = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"; -const horizon = new Horizon.Server("https://horizon-testnet.stellar.org"); - -const friendbot = (addr) => fetch(`https://friendbot.stellar.org?addr=${addr}`); - -async function addTrustline(kp) { - const acc = await horizon.loadAccount(kp.publicKey()); - const tx = new TransactionBuilder(acc, { fee: BASE_FEE, networkPassphrase: Networks.TESTNET }) - .addOperation(Operation.changeTrust({ asset: new Asset("USDC", USDC_ISSUER) })) - .setTimeout(60).build(); - tx.sign(kp); - return horizon.submitTransaction(tx); -} - -const recipient = Keypair.random(); -const payer = Keypair.random(); -await Promise.all([friendbot(recipient.publicKey()), friendbot(payer.publicKey())]); -await new Promise(r => setTimeout(r, 2000)); -await Promise.all([addTrustline(recipient), addTrustline(payer)]); - -await fs.writeFile(".env", `STELLAR_RECIPIENT=${recipient.publicKey()} -STELLAR_SECRET_KEY=${payer.secret()} -OZ_API_KEY= -`); - -console.log(`Fund payer with USDC: https://faucet.circle.com → ${payer.publicKey()}`); -console.log(`Get OZ key: https://channels.openzeppelin.com/testnet/gen → paste into OZ_API_KEY`); -``` - ## Two USDC addresses (don't confuse them) USDC on Stellar has two addresses, used in different places. Mixing them up is a common stumble. @@ -298,355 +113,4 @@ import { USDC_TESTNET_ADDRESS, USDC_PUBNET_ADDRESS } from "@x402/stellar"; // USDC_PUBNET_ADDRESS = "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75" ``` -`payTo` in your route config is always a classic recipient account (`G...`). The SAC address only appears if you set a custom `asset` in the price config for a non-USDC token. - -## Mainnet checklist - -| Config | Value | -|--------|-------| -| Network ID | `stellar:pubnet` | -| RPC URL | Provider-specific endpoint (see [Stellar RPC providers directory](https://developers.stellar.org/docs/data/apis/rpc/providers)) | -| Facilitator URL | `https://channels.openzeppelin.com/x402` | -| USDC SAC | `USDC_PUBNET_ADDRESS` from `@x402/stellar` (currently `CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75`) | -| OZ Channels API key | Required ([channels.openzeppelin.com/gen](https://channels.openzeppelin.com/gen)) | -| Funding | Real USDC on mainnet (CEX, DEX, or bridge) | - -Always test on testnet first. To switch a working setup to mainnet, change only the `.env` (`STELLAR_NETWORK=stellar:pubnet`, `FACILITATOR_URL=https://channels.openzeppelin.com/x402`, mainnet `OZ_API_KEY`, and a mainnet `STELLAR_RECIPIENT`); the samples derive their network from `STELLAR_NETWORK`, so no code changes are needed. Both networks require an OZ Channels API key in the `Authorization: Bearer` header. - -## Key concepts - -**Auth entry signing** — On Stellar, x402 clients sign contract authorization entries, not full transaction envelopes. The facilitator assembles the complete transaction. This is lighter than EVM/Solana signing, and means clients never need to manage sequence numbers or pay fees. - -**Fee sponsorship** — OZ Channels pays all Stellar network fees (~$0.00001/tx). Clients need a funded wallet with USDC but zero XLM. - -**`exact-v2` scheme** — The Stellar x402 scheme version. Server advertises `scheme: "exact"` + `x402Version: 2`. Don't mix v1 and v2 packages. - -**SAC (Stellar Asset Contract)** — USDC on Stellar is a classic asset wrapped in a smart contract. x402 payments invoke `transfer` on the SAC. Any SEP-41 token works; USDC is the default. - -**Ledger expiration** — Auth entries include a `max_ledger` bound. Use `latestLedger + 12` (~1 minute at 5s/ledger). Expired entries fail at settlement. - -**CAIP-2 network IDs** — `stellar:testnet` and `stellar:pubnet`. These are the exact strings the protocol expects. - -## Common pitfalls - -**Auth entry expired on settle** -- Symptom: facilitator returns `isValid: false`, error mentions ledger expiration -- Fix: ensure client uses `latestLedger + 12` (or higher) as expiration; don't cache auth entries across requests - -**Wrong USDC decimal precision** -- Symptom: payment amount off by 10x or 100x -- Fix: Stellar USDC uses **7 decimal places** (not 6 like EVM USDC). `$0.001` = `10000` in base units. - -**V1/V2 package mismatch** -- Symptom: TypeScript errors or silent payment failures -- Fix: use all `@x402/*` packages at the same major version. V2 is multi-chain; don't import V1 `@x402/core` alongside V2 `@x402/stellar`. - -**Missing USDC trustline** -- Symptom: `op_no_trust` error during settlement -- Fix: add a USDC `changeTrust` operation before attempting any x402 payment (see testnet runbook above) - -**OZ Channels 401 on testnet or mainnet** -- Symptom: facilitator rejects with 401, server logs `Failed to initialize: no supported payment kinds loaded from any facilitator` -- Fix: an API key is required on **both** networks. Generate one at [channels.openzeppelin.com/testnet/gen](https://channels.openzeppelin.com/testnet/gen) (testnet) or [channels.openzeppelin.com/gen](https://channels.openzeppelin.com/gen) (mainnet), then set `OZ_API_KEY` and pass it via `createAuthHeaders` (see the Seller example). - -**Trustline missing on the recipient** -- Symptom: `op_no_trust` during settlement, even though the client has USDC -- Fix: the `payTo` account needs a USDC trustline too. The SAC `transfer` settles the underlying classic asset, which the recipient cannot hold without a trustline. Add `changeTrust` to both accounts during setup. - -**Trying to sign auth entries from a browser** -- Symptom: bundling errors, or a browser wallet that has no API to sign contract auth entries -- Fix: run the x402 client server-side (e.g. an Express route the browser calls), or use Wallets-Kit / Freighter with custom auth-entry signing. `@x402/fetch` + `createEd25519Signer` target Node and assume a raw secret key. - -**Passing a `Keypair` (or a network passphrase) to `createEd25519Signer`** -- Symptom: `TypeError: encoded argument must be of type String`, or `Error: Unknown Stellar network: Test SDF Network ; September 2015` -- Fix: the signer takes the raw `S...` secret string and a CAIP-2 network ID. Do **not** wrap with `Keypair.fromSecret` first, and do **not** pre-convert with `getNetworkPassphrase` — both are done internally. - ```js - // wrong - const signer = createEd25519Signer(Keypair.fromSecret(s), getNetworkPassphrase("stellar:testnet")); - // right - const signer = createEd25519Signer(s, "stellar:testnet"); - ``` - ---- - -# Part 2: MPP — Machine Payments Protocol (Charge + Session) - - -## When to use MPP -MPP is the right choice when: -- You want **no facilitator dependency** — payments settle directly on Stellar via SAC transfers -- Your AI agent makes **many requests per session** — use Session mode (a payment channel under the hood) to pay off-chain and settle once -- You're building a Stellar-native payment stack without relying on third-party infrastructure - -Two modes: - -| Mode | On-chain txs | Best for | -|------|-------------|----------| -| **Charge** | One per request | Per-request payments, no pre-funding required | -| **Session** | One deposit + one close | High-frequency agents (100s of requests/session) | - -If you need zero-XLM clients or the simplest possible setup, use x402 (Part 1 above) instead. - -## Charge mode: per-request payments - -Each request triggers a SAC token transfer settled on-chain. No facilitator. Server can optionally sponsor fees so clients don't need XLM. - -```bash -npm install express@^5 @stellar/mpp mppx @stellar/stellar-sdk@^15 dotenv -npm pkg set type=module -``` - -> **Version alignment matters:** `@stellar/mpp@0.7.x` pins `@stellar/stellar-sdk@^15.1.0` (installing alongside SDK 13/14 fails with `ERESOLVE`), and `mppx` expects `express@>=5`. - -**Server:** - -```js -// charge-server.js -import express from "express"; -import { Mppx } from "mppx/express"; -import { Store } from "mppx/server"; -import * as stellar from "@stellar/mpp/charge/server"; -import * as StellarSdk from "@stellar/stellar-sdk"; - -const USDC_SAC_TESTNET = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA"; -const RECIPIENT = process.env.STELLAR_RECIPIENT; // G... address - -const mppx = Mppx.create({ - secretKey: process.env.MPP_SECRET_KEY, // shared secret for credential verification - methods: [ - stellar.charge({ - recipient: RECIPIENT, - currency: USDC_SAC_TESTNET, - network: "stellar:testnet", - store: Store.memory(), // required in charge mode; dev only — use a persistent store in production - // optional: server pays network fees so clients don't need XLM - feePayer: process.env.FEE_PAYER_SECRET - ? { envelopeSigner: StellarSdk.Keypair.fromSecret(process.env.FEE_PAYER_SECRET) } - : undefined, - }), - ], -}); - -const app = express(); -app.use(express.json()); - -// Mppx.create returns per-intent Express handlers — mount one per paid route. -// The price is set here, per route, not in the method config. -app.get( - "/data", - mppx.charge({ amount: "0.001", description: "paid API call" }), - (req, res) => { - res.json({ result: "paid content", price: "$0.001 USDC" }); - }, -); - -app.listen(3002, () => console.log("MPP charge server on http://localhost:3002")); -``` - -**Client:** - -```js -// charge-client.js -import { Mppx } from "@stellar/mpp/charge/client"; // re-exports the client Mppx from mppx/client -import * as stellar from "@stellar/mpp/charge/client"; -import * as StellarSdk from "@stellar/stellar-sdk"; - -const keypair = StellarSdk.Keypair.fromSecret(process.env.STELLAR_SECRET_KEY); - -const mppx = Mppx.create({ - methods: [ - stellar.charge({ - keypair, - mode: "pull", // server assembles and broadcasts the transaction - onProgress(event) { - // event.type: "challenge" | "signing" | "signed" | "paying" | "confirming" | "paid" - if (event.type === "paid") console.log("Paid:", event.hash); - }, - }), - ], -}); - -// mppx wraps fetch — 402 handling is transparent -const res = await mppx.fetch("http://localhost:3002/data"); -console.log(await res.json()); -``` - -**Env vars (server):** `STELLAR_RECIPIENT`, `MPP_SECRET_KEY`, `FEE_PAYER_SECRET` (optional) -**Env vars (client):** `STELLAR_SECRET_KEY` - -**`mode: "pull"` vs `"push"`:** -- `"pull"` — client signs auth entries, server assembles + broadcasts (default; use with `feePayer`) -- `"push"` — client builds and broadcasts the transaction directly (client must have XLM for fees) - -## Session mode: high-frequency off-chain payments - -> **Naming:** current MPP material calls the payment intent a **Session**; it settles over a **one-way payment channel**. Older docs (including earlier versions of this skill) said "Channel mode" — treat that as a synonym. "Channel" below always refers to the settlement mechanism, not the mode. - -The client deploys a one-way payment channel contract, deposits USDC once, then signs **cumulative commitments** off-chain for each request. No transaction per request — only two on-chain txs total (deposit + close). Ideal for AI agents making hundreds of calls in a session. - -### Session lifecycle - -``` -1. Deploy channel contract (one-time) → C... contract address -2. Client deposits USDC into channel → on-chain tx -3. Per request: client signs commitment → off-chain (just a signature) - Amount is cumulative: each sig covers all previous payments + this one -4. Server closes channel when done → on-chain tx, settles total -``` - -### Prerequisites - -- Deploy a one-way-channel smart contract to get a `C...` contract address -- Generate an ed25519 keypair for commitment signing (see [stellar-mpp SDK](https://github.com/stellar/stellar-mpp-sdk)) -- Fund the channel with USDC before making requests - -### Server: - -```js -// channel-server.js -import express from "express"; -import { Mppx } from "mppx/express"; -import { Store } from "mppx/server"; -import * as stellar from "@stellar/mpp/channel/server"; - -const mppx = Mppx.create({ - secretKey: process.env.MPP_SECRET_KEY, - methods: [ - stellar.channel({ - channel: process.env.CHANNEL_CONTRACT, // C... contract address - commitmentKey: process.env.COMMITMENT_PUBKEY, // 64-char hex ed25519 public key - store: Store.memory(), // dev only — use persistent store in production - network: "stellar:testnet", - }), - ], -}); - -const app = express(); -app.use(express.json()); - -// Per-route handler, same adapter model as charge mode; price per route. -app.get( - "/data", - mppx.channel({ amount: "0.001", description: "paid API call" }), - (req, res) => { - res.json({ result: "paid content" }); - }, -); - -app.listen(3003); -``` - -### Client: - -```js -// channel-client.js -import { Mppx } from "mppx/client"; -import * as stellar from "@stellar/mpp/channel/client"; -import * as StellarSdk from "@stellar/stellar-sdk"; - -// commitment key must be a raw ed25519 seed — NOT a standard Stellar secret key -const commitmentKey = StellarSdk.Keypair.fromRawEd25519Seed( - Buffer.from(process.env.COMMITMENT_SECRET, "hex") // 64-char hex secret -); - -const mppx = Mppx.create({ - methods: [ - stellar.channel({ - commitmentKey, - onProgress(event) { - // event.type: "challenge" | "signed" - }, - }), - ], -}); - -// Make many requests — each signs a cumulative off-chain commitment -for (let i = 0; i < 100; i++) { - const res = await mppx.fetch("http://localhost:3003/data"); - console.log(i, await res.json()); -} -``` - -### Closing the channel (server-initiated): - -```js -import { close } from "@stellar/mpp/channel/server"; -import * as StellarSdk from "@stellar/stellar-sdk"; - -const txHash = await close({ - channel: process.env.CHANNEL_CONTRACT, - amount: lastCumulativeAmount, // bigint, total USDC owed in base units - signature: lastCommitmentSignature, // hex string from final commitment - feePayer: { envelopeSigner: StellarSdk.Keypair.fromSecret(process.env.FEE_PAYER_SECRET) }, - network: "stellar:testnet", -}); -// Single on-chain transaction settles the full session -console.log("Channel closed:", txHash); -``` - -**Env vars (server):** `CHANNEL_CONTRACT`, `COMMITMENT_PUBKEY`, `MPP_SECRET_KEY`, `FEE_PAYER_SECRET` -**Env vars (client):** `COMMITMENT_SECRET` - -## Packages and subpath imports - -```bash -npm install @stellar/mpp mppx @stellar/stellar-sdk -``` - -| Import path | Recommended import pattern | -|-------------|----------------------------| -| `@stellar/mpp/charge/server` | `import * as stellar from "@stellar/mpp/charge/server"` — use `stellar.charge(...)` | -| `@stellar/mpp/charge/client` | `import * as stellar from "@stellar/mpp/charge/client"` — use `stellar.charge(...)` | -| `@stellar/mpp/channel/server` | `import * as stellar from "@stellar/mpp/channel/server"` — use `stellar.channel(...)`, `stellar.close(...)`, `stellar.getChannelState(...)`, `stellar.watchChannel(...)` | -| `@stellar/mpp/channel/client` | `import * as stellar from "@stellar/mpp/channel/client"` — use `stellar.channel(...)` | -| `@stellar/mpp/channel` | Zod schema definitions for channel types | -| `mppx/express` | `import { Mppx } from "mppx/express"` — Express adapter; `Mppx.create(...)` returns per-route handlers | -| `mppx/server` | `import { Mppx, Store } from "mppx/server"` — framework-agnostic server + `Store` | -| `mppx/client` | `import { Mppx } from "mppx/client"` — client; also re-exported by `@stellar/mpp/charge/client` | - -> The bare `mppx` root does **not** export `Mppx` at all — always import it from the subpaths above. (`Store` *is* re-exported from the root and is the same object as `mppx/server`'s, but importing it from `mppx/server` keeps the server imports together.) - -## Testnet runbook - -**Steps shared with all protocols:** -1. Generate keypair + fund with Friendbot (see x402 testnet runbook in Part 1 above) -2. Add USDC trustline -3. Get testnet USDC from [Circle faucet](https://faucet.circle.com/) - -**Session mode only:** -4. Deploy the one-way-channel contract (see [stellar-mpp-sdk](https://github.com/stellar/stellar-mpp-sdk) for deploy script) -5. Generate a 64-char hex ed25519 seed for the commitment key: - ```bash - node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" - ``` -6. Derive the public key and fund the channel with USDC before making requests - -## Common pitfalls - -**Charge: server throws `A store is required for charge mode` at startup** -- Symptom: `Error: [stellar:charge] A store is required for charge mode. Provide a Store instance…` -- Fix: pass `store: Store.memory()` (dev) or a persistent store to `stellar.charge({ ... })` — charge mode requires one, not just session mode. - -**Install fails with `ERESOLVE`** -- Symptom: npm refuses to install `@stellar/mpp` alongside an existing stellar-sdk 13/14 -- Fix: `@stellar/mpp@0.7.x` pins `@stellar/stellar-sdk@^15.1.0`, and `mppx` expects `express@>=5` — align versions per the install note above. - -**Session: wrong commitment key format** -- Symptom: `Keypair.fromRawEd25519Seed` throws or signatures fail to verify -- Fix: the commitment key is a raw ed25519 seed as a 64-char hex string — not a Stellar `S...` secret key. Generate with `crypto.randomBytes(32).toString('hex')`. - -**Session: non-cumulative amounts** -- Symptom: server rejects commitments after the first request -- Fix: each commitment's `amount` must be the **running total** of all payments so far, not just the price of the current request. The server tracks the highest-seen commitment. - -**Session: deposit TTL expired** -- Symptom: `close()` fails or channel appears drained -- Fix: Contract storage has a TTL. Close the channel before it expires, or extend storage TTL via `bumpContractInstance`. Don't leave channels open indefinitely. - -**Charge: client has no XLM for fees** -- Symptom: `op_insufficient_balance` or fee errors on client-submitted transactions -- Fix: set `mode: "pull"` on the client and configure `feePayer` on the server so the server pays fees. The client only signs auth entries. - -**`Store.memory()` in production** -- Symptom: server loses track of channel state on restart, enables double-spend -- Fix: replace `Store.memory()` with a persistent store (database-backed) before going to production. +x402's `payTo` route config and MPP's `recipient` are always a classic account (`G...`). The SAC address only appears where the config names the settlement asset (x402's custom `asset` price config, MPP's `currency`). diff --git a/skills/agentic-payments/mpp.md b/skills/agentic-payments/mpp.md new file mode 100644 index 0000000..9faec24 --- /dev/null +++ b/skills/agentic-payments/mpp.md @@ -0,0 +1,282 @@ +# MPP — Machine Payments Protocol (Charge + Session) + +Facilitator-free machine payments settled directly on Stellar: per-request Charge mode and channel-backed Session mode. Companion to [SKILL.md](SKILL.md) (decision table, shared testnet setup, USDC addresses); the facilitator-based alternative lives in [x402.md](x402.md). + +## When to use MPP +MPP is the right choice when: +- You want **no facilitator dependency** — payments settle directly on Stellar via SAC transfers +- Your AI agent makes **many requests per session** — use Session mode (a payment channel under the hood) to pay off-chain and settle once +- You're building a Stellar-native payment stack without relying on third-party infrastructure + +Two modes: + +| Mode | On-chain txs | Best for | +|------|-------------|----------| +| **Charge** | One per request | Per-request payments, no pre-funding required | +| **Session** | One deposit + one close | High-frequency agents (100s of requests/session) | + +If you need zero-XLM clients or the simplest possible setup, use x402 ([x402.md](x402.md)) instead. + +## Charge mode: per-request payments + +Each request triggers a SAC token transfer settled on-chain. No facilitator. Server can optionally sponsor fees so clients don't need XLM. + +```bash +npm install express@^5 @stellar/mpp mppx @stellar/stellar-sdk@^15 dotenv +npm pkg set type=module +``` + +> **Version alignment matters:** `@stellar/mpp@0.7.x` pins `@stellar/stellar-sdk@^15.1.0` (installing alongside SDK 13/14 fails with `ERESOLVE`), and `mppx` expects `express@>=5`. + +**Server:** + +```js +// charge-server.js +import express from "express"; +import { Mppx } from "mppx/express"; +import { Store } from "mppx/server"; +import * as stellar from "@stellar/mpp/charge/server"; +import * as StellarSdk from "@stellar/stellar-sdk"; + +const USDC_SAC_TESTNET = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA"; +const RECIPIENT = process.env.STELLAR_RECIPIENT; // G... address + +const mppx = Mppx.create({ + secretKey: process.env.MPP_SECRET_KEY, // shared secret for credential verification + methods: [ + stellar.charge({ + recipient: RECIPIENT, + currency: USDC_SAC_TESTNET, + network: "stellar:testnet", + store: Store.memory(), // required in charge mode; dev only — use a persistent store in production + // optional: server pays network fees so clients don't need XLM + feePayer: process.env.FEE_PAYER_SECRET + ? { envelopeSigner: StellarSdk.Keypair.fromSecret(process.env.FEE_PAYER_SECRET) } + : undefined, + }), + ], +}); + +const app = express(); +app.use(express.json()); + +// Mppx.create returns per-intent Express handlers — mount one per paid route. +// The price is set here, per route, not in the method config. +app.get( + "/data", + mppx.charge({ amount: "0.001", description: "paid API call" }), + (req, res) => { + res.json({ result: "paid content", price: "$0.001 USDC" }); + }, +); + +app.listen(3002, () => console.log("MPP charge server on http://localhost:3002")); +``` + +**Client:** + +```js +// charge-client.js +import { Mppx } from "@stellar/mpp/charge/client"; // re-exports the client Mppx from mppx/client +import * as stellar from "@stellar/mpp/charge/client"; +import * as StellarSdk from "@stellar/stellar-sdk"; + +const keypair = StellarSdk.Keypair.fromSecret(process.env.STELLAR_SECRET_KEY); + +const mppx = Mppx.create({ + methods: [ + stellar.charge({ + keypair, + mode: "pull", // server assembles and broadcasts the transaction + onProgress(event) { + // event.type: "challenge" | "signing" | "signed" | "paying" | "confirming" | "paid" + if (event.type === "paid") console.log("Paid:", event.hash); + }, + }), + ], +}); + +// mppx wraps fetch — 402 handling is transparent +const res = await mppx.fetch("http://localhost:3002/data"); +console.log(await res.json()); +``` + +**Env vars (server):** `STELLAR_RECIPIENT`, `MPP_SECRET_KEY`, `FEE_PAYER_SECRET` (optional) +**Env vars (client):** `STELLAR_SECRET_KEY` + +**`mode: "pull"` vs `"push"`:** +- `"pull"` — client signs auth entries, server assembles + broadcasts (default; use with `feePayer`) +- `"push"` — client builds and broadcasts the transaction directly (client must have XLM for fees) + +## Session mode: high-frequency off-chain payments + +> **Naming:** current MPP material calls the payment intent a **Session**; it settles over a **one-way payment channel**. Older docs (including earlier versions of this skill) said "Channel mode" — treat that as a synonym. "Channel" below always refers to the settlement mechanism, not the mode. + +The client deploys a one-way payment channel contract, deposits USDC once, then signs **cumulative commitments** off-chain for each request. No transaction per request — only two on-chain txs total (deposit + close). Ideal for AI agents making hundreds of calls in a session. + +### Session lifecycle + +``` +1. Deploy channel contract (one-time) → C... contract address +2. Client deposits USDC into channel → on-chain tx +3. Per request: client signs commitment → off-chain (just a signature) + Amount is cumulative: each sig covers all previous payments + this one +4. Server closes channel when done → on-chain tx, settles total +``` + +### Prerequisites + +- Deploy a one-way-channel smart contract to get a `C...` contract address +- Generate an ed25519 keypair for commitment signing (see [stellar-mpp SDK](https://github.com/stellar/stellar-mpp-sdk)) +- Fund the channel with USDC before making requests + +### Server: + +```js +// channel-server.js +import express from "express"; +import { Mppx } from "mppx/express"; +import { Store } from "mppx/server"; +import * as stellar from "@stellar/mpp/channel/server"; + +const mppx = Mppx.create({ + secretKey: process.env.MPP_SECRET_KEY, + methods: [ + stellar.channel({ + channel: process.env.CHANNEL_CONTRACT, // C... contract address + commitmentKey: process.env.COMMITMENT_PUBKEY, // 64-char hex ed25519 public key + store: Store.memory(), // dev only — use persistent store in production + network: "stellar:testnet", + }), + ], +}); + +const app = express(); +app.use(express.json()); + +// Per-route handler, same adapter model as charge mode; price per route. +app.get( + "/data", + mppx.channel({ amount: "0.001", description: "paid API call" }), + (req, res) => { + res.json({ result: "paid content" }); + }, +); + +app.listen(3003); +``` + +### Client: + +```js +// channel-client.js +import { Mppx } from "mppx/client"; +import * as stellar from "@stellar/mpp/channel/client"; +import * as StellarSdk from "@stellar/stellar-sdk"; + +// commitment key must be a raw ed25519 seed — NOT a standard Stellar secret key +const commitmentKey = StellarSdk.Keypair.fromRawEd25519Seed( + Buffer.from(process.env.COMMITMENT_SECRET, "hex") // 64-char hex secret +); + +const mppx = Mppx.create({ + methods: [ + stellar.channel({ + commitmentKey, + onProgress(event) { + // event.type: "challenge" | "signed" + }, + }), + ], +}); + +// Make many requests — each signs a cumulative off-chain commitment +for (let i = 0; i < 100; i++) { + const res = await mppx.fetch("http://localhost:3003/data"); + console.log(i, await res.json()); +} +``` + +### Closing the channel (server-initiated): + +```js +import { close } from "@stellar/mpp/channel/server"; +import * as StellarSdk from "@stellar/stellar-sdk"; + +const txHash = await close({ + channel: process.env.CHANNEL_CONTRACT, + amount: lastCumulativeAmount, // bigint, total USDC owed in base units + signature: lastCommitmentSignature, // hex string from final commitment + feePayer: { envelopeSigner: StellarSdk.Keypair.fromSecret(process.env.FEE_PAYER_SECRET) }, + network: "stellar:testnet", +}); +// Single on-chain transaction settles the full session +console.log("Channel closed:", txHash); +``` + +**Env vars (server):** `CHANNEL_CONTRACT`, `COMMITMENT_PUBKEY`, `MPP_SECRET_KEY`, `FEE_PAYER_SECRET` +**Env vars (client):** `COMMITMENT_SECRET` + +## Packages and subpath imports + +```bash +npm install @stellar/mpp mppx @stellar/stellar-sdk +``` + +| Import path | Recommended import pattern | +|-------------|----------------------------| +| `@stellar/mpp/charge/server` | `import * as stellar from "@stellar/mpp/charge/server"` — use `stellar.charge(...)` | +| `@stellar/mpp/charge/client` | `import * as stellar from "@stellar/mpp/charge/client"` — use `stellar.charge(...)` | +| `@stellar/mpp/channel/server` | `import * as stellar from "@stellar/mpp/channel/server"` — use `stellar.channel(...)`, `stellar.close(...)`, `stellar.getChannelState(...)`, `stellar.watchChannel(...)` | +| `@stellar/mpp/channel/client` | `import * as stellar from "@stellar/mpp/channel/client"` — use `stellar.channel(...)` | +| `@stellar/mpp/channel` | Zod schema definitions for channel types | +| `mppx/express` | `import { Mppx } from "mppx/express"` — Express adapter; `Mppx.create(...)` returns per-route handlers | +| `mppx/server` | `import { Mppx, Store } from "mppx/server"` — framework-agnostic server + `Store` | +| `mppx/client` | `import { Mppx } from "mppx/client"` — client; also re-exported by `@stellar/mpp/charge/client` | + +> The bare `mppx` root does **not** export `Mppx` at all — always import it from the subpaths above. (`Store` *is* re-exported from the root and is the same object as `mppx/server`'s, but importing it from `mppx/server` keeps the server imports together.) + +## Testnet runbook + +**Steps shared with all protocols:** +1. Generate keypair + fund with Friendbot — see the [shared testnet setup in SKILL.md](SKILL.md#testnet-setup-shared) +2. Add USDC trustline (same shared setup) +3. Get testnet USDC from [Circle faucet](https://faucet.circle.com/) + +**Session mode only:** +4. Deploy the one-way-channel contract (see [stellar-mpp-sdk](https://github.com/stellar/stellar-mpp-sdk) for deploy script) +5. Generate a 64-char hex ed25519 seed for the commitment key: + ```bash + node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" + ``` +6. Derive the public key and fund the channel with USDC before making requests + +## Common pitfalls + +**Charge: server throws `A store is required for charge mode` at startup** +- Symptom: `Error: [stellar:charge] A store is required for charge mode. Provide a Store instance…` +- Fix: pass `store: Store.memory()` (dev) or a persistent store to `stellar.charge({ ... })` — charge mode requires one, not just session mode. + +**Install fails with `ERESOLVE`** +- Symptom: npm refuses to install `@stellar/mpp` alongside an existing stellar-sdk 13/14 +- Fix: `@stellar/mpp@0.7.x` pins `@stellar/stellar-sdk@^15.1.0`, and `mppx` expects `express@>=5` — align versions per the install note above. + +**Session: wrong commitment key format** +- Symptom: `Keypair.fromRawEd25519Seed` throws or signatures fail to verify +- Fix: the commitment key is a raw ed25519 seed as a 64-char hex string — not a Stellar `S...` secret key. Generate with `crypto.randomBytes(32).toString('hex')`. + +**Session: non-cumulative amounts** +- Symptom: server rejects commitments after the first request +- Fix: each commitment's `amount` must be the **running total** of all payments so far, not just the price of the current request. The server tracks the highest-seen commitment. + +**Session: deposit TTL expired** +- Symptom: `close()` fails or channel appears drained +- Fix: Contract storage has a TTL. Close the channel before it expires, or extend storage TTL via `bumpContractInstance`. Don't leave channels open indefinitely. + +**Charge: client has no XLM for fees** +- Symptom: `op_insufficient_balance` or fee errors on client-submitted transactions +- Fix: set `mode: "pull"` on the client and configure `feePayer` on the server so the server pays fees. The client only signs auth entries. + +**`Store.memory()` in production** +- Symptom: server loses track of channel state on restart, enables double-spend +- Fix: replace `Store.memory()` with a persistent store (database-backed) before going to production. diff --git a/skills/agentic-payments/x402.md b/skills/agentic-payments/x402.md new file mode 100644 index 0000000..d9ae98a --- /dev/null +++ b/skills/agentic-payments/x402.md @@ -0,0 +1,266 @@ +# x402 — Paid APIs + Agent Buyer Clients + +Sell paid APIs to AI agents and build agent buyer clients over HTTP 402, settled in USDC through the OpenZeppelin Channels facilitator. Companion to [SKILL.md](SKILL.md) (decision table, shared testnet setup, USDC addresses); the facilitator-free alternative lives in [mpp.md](mpp.md). + +## When to use x402 +x402 is the right choice when: +- You want the fastest path to a paid API — minimal code, no contract deployment +- You want clients (including AI agents) to pay with **zero XLM** — the OZ Channels facilitator sponsors all network fees +- You're building on top of an existing x402 ecosystem (Coinbase, other chains) + +Trade-off: you depend on OZ Channels (or a self-hosted relayer) for verification and settlement. If you need zero third-party dependency, use MPP Charge ([mpp.md](mpp.md)) instead. + +## How x402 works on Stellar + +``` +Client → GET /resource → Server +Client ← 402 Payment Required (payment requirements) ← Server +Client builds SAC USDC transfer +Client signs auth entries only (not the full tx envelope) +Client → GET /resource + X-PAYMENT header → Server +Server → OZ Channels /verify + /settle → Stellar (~5s) +Client ← 200 OK + resource +``` + +The key Stellar difference: clients sign **auth entries**, not full transaction envelopes. The facilitator assembles the transaction, pays fees, and submits. Clients need zero XLM. + +## Seller: monetize an Express API + +```bash +npm install @x402/express @x402/core @x402/stellar express dotenv +npm pkg set type=module +``` + +```js +// server.js +import "dotenv/config"; +import express from "express"; +import { paymentMiddleware, x402ResourceServer } from "@x402/express"; +import { HTTPFacilitatorClient } from "@x402/core/server"; +import { ExactStellarScheme } from "@x402/stellar/exact/server"; + +// Drive the CAIP-2 network ID from one place. Switching to mainnet means +// flipping STELLAR_NETWORK and FACILITATOR_URL in .env, nothing in code. +const NETWORK = process.env.STELLAR_NETWORK || "stellar:testnet"; + +if (!process.env.OZ_API_KEY) { + throw new Error( + "OZ_API_KEY is required. Generate one at https://channels.openzeppelin.com/testnet/gen (testnet) or https://channels.openzeppelin.com/gen (mainnet)." + ); +} + +const facilitator = new HTTPFacilitatorClient({ + url: process.env.FACILITATOR_URL ?? "https://channels.openzeppelin.com/x402/testnet", + // OZ Channels requires Bearer auth on both testnet and mainnet + createAuthHeaders: async () => { + const h = { Authorization: `Bearer ${process.env.OZ_API_KEY}` }; + return { verify: h, settle: h, supported: h }; + }, +}); + +const resourceServer = new x402ResourceServer(facilitator) + .register(NETWORK, new ExactStellarScheme()); + +const app = express(); + +app.use( + paymentMiddleware( + { + "GET /weather": { + accepts: { + scheme: "exact", + price: "$0.001", // human-readable, auto-converts to 7-decimal USDC units + network: NETWORK, + payTo: process.env.STELLAR_RECIPIENT, // recipient G... account + }, + description: "Current weather data", + }, + }, + resourceServer + ) +); + +app.get("/weather", (_req, res) => { + res.json({ city: "San Francisco", temp: 18, conditions: "Foggy" }); +}); + +app.listen(3001, () => console.log(`x402 server on http://localhost:3001 (${NETWORK})`)); +``` + +**Env vars:** +- `STELLAR_NETWORK` — CAIP-2 network ID; defaults to `stellar:testnet`. Set to `stellar:pubnet` for mainnet. +- `STELLAR_RECIPIENT` — your G... address (receives USDC, needs a USDC trustline) +- `OZ_API_KEY` — OZ Channels API key (**required on both testnet and mainnet**; generate at the link in the runbook below) +- `FACILITATOR_URL` — defaults to testnet URL above; set to `https://channels.openzeppelin.com/x402` for mainnet + +**Price format options:** +- `"$0.001"` — human-readable, auto-converts to 7-decimal USDC units +- `{ amount: "1000", asset: "ASSET_SAC_CONTRACT_ID" }` — explicit base units for non-USDC assets + +**`payTo` is the recipient's classic Stellar account (`G...`), not the USDC SAC contract address.** Sending USDC lands in the classic balance of the `payTo` account, which is why that account also needs a USDC trustline. The SAC contract address is what the protocol invokes `transfer` on; see "Two USDC addresses" below. + +## Buyer: agent client + +```bash +npm install @x402/fetch @x402/stellar dotenv +npm pkg set type=module +``` + +```js +// client.js +import "dotenv/config"; +import { wrapFetchWithPaymentFromConfig } from "@x402/fetch"; +import { createEd25519Signer } from "@x402/stellar"; +import { ExactStellarScheme } from "@x402/stellar/exact/client"; + +const NETWORK = process.env.STELLAR_NETWORK || "stellar:testnet"; + +// createEd25519Signer takes the raw S... secret string and the CAIP-2 network ID. +// Do NOT pre-wrap with Keypair.fromSecret or call getNetworkPassphrase yourself — +// the signer does both internally. +const signer = createEd25519Signer(process.env.STELLAR_SECRET_KEY, NETWORK); + +// wrapFetchWithPaymentFromConfig returns a fetch that handles 402 negotiation +// and auth-entry signing transparently. +const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, { + schemes: [{ network: NETWORK, client: new ExactStellarScheme(signer) }], +}); + +const res = await fetchWithPayment("http://localhost:3001/weather"); +console.log(await res.json()); +// Paid automatically: 402 negotiation + auth-entry signing under the hood +``` + +**Env vars:** +- `STELLAR_NETWORK` — CAIP-2 network ID; defaults to `stellar:testnet`. Must match the server's network. +- `STELLAR_SECRET_KEY` — your S... secret key (needs USDC trustline + balance) + +**Browser frontends:** this client uses Node `fetch` and `createEd25519Signer`, both of which run in Node. A vanilla browser cannot sign contract auth entries through a typical wallet extension without additional glue. For a browser payer, run the x402 client server-side and expose a thin proxy endpoint to the page, or wire up Wallets-Kit / Freighter with custom auth-entry signing. + +## Testnet runbook + +First complete the [shared testnet setup in SKILL.md](SKILL.md#testnet-setup-shared) — keypairs, XLM funding, USDC trustlines on **both** accounts, and testnet USDC from the Circle faucet (or run `setup.js` below). Then: + +1. **Generate an OZ Channels testnet API key** ([channels.openzeppelin.com/testnet/gen](https://channels.openzeppelin.com/testnet/gen)). **Required, not optional.** Without it the server crashes at startup with `Failed to initialize: no supported payment kinds loaded from any facilitator`. + +2. **Fill in `.env`** + ``` + STELLAR_NETWORK=stellar:testnet + STELLAR_RECIPIENT=G... (recipient public key) + STELLAR_SECRET_KEY=S... (payer secret key) + OZ_API_KEY=... + ``` + +3. **Run it** + ```bash + node server.js + # in another terminal + node client.js + ``` + +### Optional: setup.js to automate the shared setup + +Drop this in your project and run once. It generates keys, friendbots, and adds USDC trustlines (the shared setup steps 1–3), then writes a starter `.env` so you only need to do the two manual web steps afterward. + +```js +// setup.js +import fs from "fs/promises"; +import { + Keypair, Horizon, Networks, TransactionBuilder, Operation, Asset, BASE_FEE, +} from "@stellar/stellar-sdk"; + +const USDC_ISSUER = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"; +const horizon = new Horizon.Server("https://horizon-testnet.stellar.org"); + +const friendbot = (addr) => fetch(`https://friendbot.stellar.org?addr=${addr}`); + +async function addTrustline(kp) { + const acc = await horizon.loadAccount(kp.publicKey()); + const tx = new TransactionBuilder(acc, { fee: BASE_FEE, networkPassphrase: Networks.TESTNET }) + .addOperation(Operation.changeTrust({ asset: new Asset("USDC", USDC_ISSUER) })) + .setTimeout(60).build(); + tx.sign(kp); + return horizon.submitTransaction(tx); +} + +const recipient = Keypair.random(); +const payer = Keypair.random(); +await Promise.all([friendbot(recipient.publicKey()), friendbot(payer.publicKey())]); +await new Promise(r => setTimeout(r, 2000)); +await Promise.all([addTrustline(recipient), addTrustline(payer)]); + +await fs.writeFile(".env", `STELLAR_RECIPIENT=${recipient.publicKey()} +STELLAR_SECRET_KEY=${payer.secret()} +OZ_API_KEY= +`); + +console.log(`Fund payer with USDC: https://faucet.circle.com → ${payer.publicKey()}`); +console.log(`Get OZ key: https://channels.openzeppelin.com/testnet/gen → paste into OZ_API_KEY`); +``` + +## Mainnet checklist + +| Config | Value | +|--------|-------| +| Network ID | `stellar:pubnet` | +| RPC URL | Provider-specific endpoint (see [Stellar RPC providers directory](https://developers.stellar.org/docs/data/apis/rpc/providers)) | +| Facilitator URL | `https://channels.openzeppelin.com/x402` | +| USDC SAC | `USDC_PUBNET_ADDRESS` from `@x402/stellar` (currently `CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75`) | +| OZ Channels API key | Required ([channels.openzeppelin.com/gen](https://channels.openzeppelin.com/gen)) | +| Funding | Real USDC on mainnet (CEX, DEX, or bridge) | + +Always test on testnet first. To switch a working setup to mainnet, change only the `.env` (`STELLAR_NETWORK=stellar:pubnet`, `FACILITATOR_URL=https://channels.openzeppelin.com/x402`, mainnet `OZ_API_KEY`, and a mainnet `STELLAR_RECIPIENT`); the samples derive their network from `STELLAR_NETWORK`, so no code changes are needed. Both networks require an OZ Channels API key in the `Authorization: Bearer` header. + +## Key concepts + +**Auth entry signing** — On Stellar, x402 clients sign contract authorization entries, not full transaction envelopes. The facilitator assembles the complete transaction. This is lighter than EVM/Solana signing, and means clients never need to manage sequence numbers or pay fees. + +**Fee sponsorship** — OZ Channels pays all Stellar network fees (~$0.00001/tx). Clients need a funded wallet with USDC but zero XLM. + +**`exact-v2` scheme** — The Stellar x402 scheme version. Server advertises `scheme: "exact"` + `x402Version: 2`. Don't mix v1 and v2 packages. + +**SAC (Stellar Asset Contract)** — USDC on Stellar is a classic asset wrapped in a smart contract. x402 payments invoke `transfer` on the SAC. Any SEP-41 token works; USDC is the default. + +**Ledger expiration** — Auth entries include a `max_ledger` bound. Use `latestLedger + 12` (~1 minute at 5s/ledger). Expired entries fail at settlement. + +**CAIP-2 network IDs** — `stellar:testnet` and `stellar:pubnet`. These are the exact strings the protocol expects. + +## Common pitfalls + +**Auth entry expired on settle** +- Symptom: facilitator returns `isValid: false`, error mentions ledger expiration +- Fix: ensure client uses `latestLedger + 12` (or higher) as expiration; don't cache auth entries across requests + +**Wrong USDC decimal precision** +- Symptom: payment amount off by 10x or 100x +- Fix: Stellar USDC uses **7 decimal places** (not 6 like EVM USDC). `$0.001` = `10000` in base units. + +**V1/V2 package mismatch** +- Symptom: TypeScript errors or silent payment failures +- Fix: use all `@x402/*` packages at the same major version. V2 is multi-chain; don't import V1 `@x402/core` alongside V2 `@x402/stellar`. + +**Missing USDC trustline** +- Symptom: `op_no_trust` error during settlement +- Fix: add a USDC `changeTrust` operation before attempting any x402 payment (see testnet runbook above) + +**OZ Channels 401 on testnet or mainnet** +- Symptom: facilitator rejects with 401, server logs `Failed to initialize: no supported payment kinds loaded from any facilitator` +- Fix: an API key is required on **both** networks. Generate one at [channels.openzeppelin.com/testnet/gen](https://channels.openzeppelin.com/testnet/gen) (testnet) or [channels.openzeppelin.com/gen](https://channels.openzeppelin.com/gen) (mainnet), then set `OZ_API_KEY` and pass it via `createAuthHeaders` (see the Seller example). + +**Trustline missing on the recipient** +- Symptom: `op_no_trust` during settlement, even though the client has USDC +- Fix: the `payTo` account needs a USDC trustline too. The SAC `transfer` settles the underlying classic asset, which the recipient cannot hold without a trustline. Add `changeTrust` to both accounts during setup. + +**Trying to sign auth entries from a browser** +- Symptom: bundling errors, or a browser wallet that has no API to sign contract auth entries +- Fix: run the x402 client server-side (e.g. an Express route the browser calls), or use Wallets-Kit / Freighter with custom auth-entry signing. `@x402/fetch` + `createEd25519Signer` target Node and assume a raw secret key. + +**Passing a `Keypair` (or a network passphrase) to `createEd25519Signer`** +- Symptom: `TypeError: encoded argument must be of type String`, or `Error: Unknown Stellar network: Test SDF Network ; September 2015` +- Fix: the signer takes the raw `S...` secret string and a CAIP-2 network ID. Do **not** wrap with `Keypair.fromSecret` first, and do **not** pre-convert with `getNetworkPassphrase` — both are done internally. + ```js + // wrong + const signer = createEd25519Signer(Keypair.fromSecret(s), getNetworkPassphrase("stellar:testnet")); + // right + const signer = createEd25519Signer(s, "stellar:testnet"); + ``` From 650133c6f652474e6576f5f7faa0fbfea0066fc9 Mon Sep 17 00:00:00 2001 From: Kaan Kacar Date: Tue, 11 Aug 2026 03:19:10 +0300 Subject: [PATCH 4/5] Split data: move the legacy Horizon section to horizon.md SKILL.md drops to 407 lines and gains the task-to-file routing table; Horizon endpoints/operations/streaming/pagination move verbatim. --- skills/data/SKILL.md | 164 +++-------------------------------------- skills/data/horizon.md | 151 +++++++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+), 155 deletions(-) create mode 100644 skills/data/horizon.md diff --git a/skills/data/SKILL.md b/skills/data/SKILL.md index f73338c..c15c645 100644 --- a/skills/data/SKILL.md +++ b/skills/data/SKILL.md @@ -36,12 +36,15 @@ Stellar provides two API paradigms: **Recommendation**: Use Stellar RPC for all new projects. Use Horizon mainly for historical queries and legacy compatibility paths. -## Quick Navigation -- RPC methods and usage: [Stellar RPC](#stellar-rpc) -- Horizon endpoints and streaming: [Horizon API (Legacy)](#horizon-api-legacy) -- Migration strategy: [Migration: Horizon to RPC](#migration-horizon-to-rpc) -- Data history/indexing options: [Historical Data Access](#historical-data-access) -- Environment setup and endpoints: [Network Configuration](#network-configuration) +## Read the file that matches the task + +| Task | File | +|------|------| +| RPC methods and usage | [Stellar RPC](#stellar-rpc) (below) | +| Horizon endpoints, common operations, streaming, pagination | [horizon.md](horizon.md) | +| Migration strategy | [Migration: Horizon to RPC](#migration-horizon-to-rpc) (below) | +| Data history/indexing options | [Historical Data Access](#historical-data-access) (below) | +| Environment setup and endpoints | [Network Configuration](#network-configuration) (below) | ## Stellar RPC @@ -178,155 +181,6 @@ for (const event of events.events) { - **No streaming**: Poll for updates (no WebSocket) - **Contract-focused**: Limited classic Stellar data -## Horizon API (Legacy) - -### Endpoints - -| Network | Horizon URL | -|---------|-------------| -| Mainnet | `https://horizon.stellar.org` | -| Testnet | `https://horizon-testnet.stellar.org` | -| Local | `http://localhost:8000` | - -### Setup - -```typescript -import * as StellarSdk from "@stellar/stellar-sdk"; - -const server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org"); -``` - -### Common Operations - -#### Load Account - -```typescript -const account = await server.loadAccount(publicKey); -// Full account details including balances, signers, data -``` - -#### Get Account Balances - -```typescript -const account = await server.loadAccount(publicKey); -for (const balance of account.balances) { - if (balance.asset_type === "native") { - console.log("XLM:", balance.balance); - } else { - console.log(`${balance.asset_code}:`, balance.balance); - } -} -``` - -#### Get Transactions - -```typescript -// Account transactions -const transactions = await server - .transactions() - .forAccount(publicKey) - .order("desc") - .limit(10) - .call(); - -// Specific transaction -const tx = await server - .transactions() - .transaction(txHash) - .call(); -``` - -#### Get Operations - -```typescript -const operations = await server - .operations() - .forAccount(publicKey) - .order("desc") - .limit(20) - .call(); - -for (const op of operations.records) { - console.log(op.type, op.created_at); -} -``` - -#### Get Payments - -```typescript -const payments = await server - .payments() - .forAccount(publicKey) - .order("desc") - .call(); - -for (const payment of payments.records) { - if (payment.type === "payment") { - console.log( - `${payment.from} -> ${payment.to}: ${payment.amount} ${payment.asset_code || "XLM"}` - ); - } -} -``` - -#### Get Effects - -```typescript -const effects = await server - .effects() - .forAccount(publicKey) - .limit(50) - .call(); -``` - -#### Streaming (Server-Sent Events) - -```typescript -// Stream transactions -const closeHandler = server - .transactions() - .forAccount(publicKey) - .cursor("now") - .stream({ - onmessage: (tx) => { - console.log("New transaction:", tx.hash); - }, - onerror: (error) => { - console.error("Stream error:", error); - }, - }); - -// Close stream when done -closeHandler(); -``` - -#### Submit Transaction - -```typescript -try { - const result = await server.submitTransaction(signedTransaction); - console.log("Success:", result.hash); -} catch (error) { - if (error.response?.data?.extras?.result_codes) { - console.error("Error codes:", error.response.data.extras.result_codes); - } -} -``` - -### Pagination - -```typescript -// First page -let page = await server.transactions().forAccount(publicKey).limit(10).call(); - -// Next page -if (page.records.length > 0) { - page = await page.next(); -} - -// Previous page -page = await page.prev(); -``` ## Migration: Horizon to RPC diff --git a/skills/data/horizon.md b/skills/data/horizon.md new file mode 100644 index 0000000..3776543 --- /dev/null +++ b/skills/data/horizon.md @@ -0,0 +1,151 @@ +# Horizon API (Legacy) + +Horizon REST endpoints, common operations, streaming, and pagination. Companion to [SKILL.md](SKILL.md) — new projects should prefer Stellar RPC; see the [migration guide](SKILL.md#migration-horizon-to-rpc). + +### Endpoints + +| Network | Horizon URL | +|---------|-------------| +| Mainnet | `https://horizon.stellar.org` | +| Testnet | `https://horizon-testnet.stellar.org` | +| Local | `http://localhost:8000` | + +### Setup + +```typescript +import * as StellarSdk from "@stellar/stellar-sdk"; + +const server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org"); +``` + +### Common Operations + +#### Load Account + +```typescript +const account = await server.loadAccount(publicKey); +// Full account details including balances, signers, data +``` + +#### Get Account Balances + +```typescript +const account = await server.loadAccount(publicKey); +for (const balance of account.balances) { + if (balance.asset_type === "native") { + console.log("XLM:", balance.balance); + } else { + console.log(`${balance.asset_code}:`, balance.balance); + } +} +``` + +#### Get Transactions + +```typescript +// Account transactions +const transactions = await server + .transactions() + .forAccount(publicKey) + .order("desc") + .limit(10) + .call(); + +// Specific transaction +const tx = await server + .transactions() + .transaction(txHash) + .call(); +``` + +#### Get Operations + +```typescript +const operations = await server + .operations() + .forAccount(publicKey) + .order("desc") + .limit(20) + .call(); + +for (const op of operations.records) { + console.log(op.type, op.created_at); +} +``` + +#### Get Payments + +```typescript +const payments = await server + .payments() + .forAccount(publicKey) + .order("desc") + .call(); + +for (const payment of payments.records) { + if (payment.type === "payment") { + console.log( + `${payment.from} -> ${payment.to}: ${payment.amount} ${payment.asset_code || "XLM"}` + ); + } +} +``` + +#### Get Effects + +```typescript +const effects = await server + .effects() + .forAccount(publicKey) + .limit(50) + .call(); +``` + +#### Streaming (Server-Sent Events) + +```typescript +// Stream transactions +const closeHandler = server + .transactions() + .forAccount(publicKey) + .cursor("now") + .stream({ + onmessage: (tx) => { + console.log("New transaction:", tx.hash); + }, + onerror: (error) => { + console.error("Stream error:", error); + }, + }); + +// Close stream when done +closeHandler(); +``` + +#### Submit Transaction + +```typescript +try { + const result = await server.submitTransaction(signedTransaction); + console.log("Success:", result.hash); +} catch (error) { + if (error.response?.data?.extras?.result_codes) { + console.error("Error codes:", error.response.data.extras.result_codes); + } +} +``` + +### Pagination + +```typescript +// First page +let page = await server.transactions().forAccount(publicKey).limit(10).call(); + +// Next page +if (page.records.length > 0) { + page = await page.next(); +} + +// Previous page +page = await page.prev(); +``` From 8c558f24165b456d408270c31486397546695743 Mon Sep 17 00:00:00 2001 From: Kaan Kacar Date: Tue, 11 Aug 2026 03:19:10 +0300 Subject: [PATCH 5/5] Add evals: 24 scenarios, grading tiers, and runner docs Three scenarios per skill plus cross-skill routing checks and an off-topic negative control, in the {skills, query, expected_behavior} format with optional machine_checkable assertions. evals/README.md documents the tiers (compile checks, LLM-judged behavior, trigger checks), the baseline process, and how to run a scenario; the root README links it and documents the 500-line router convention. Scenario expectations reflect current protocol reality rather than the July proposal where they diverged: Noir/UltraHonk verifies on-chain since Protocol 26 (#72), MPP Channel mode is now Session (#71), and getLedgers depth is provider-retention dependent (#73). --- README.md | 21 ++++-- evals/README.md | 73 +++++++++++++++++++ .../agentic-payments/01-monetize-express.json | 15 ++++ .../02-high-frequency-session.json | 11 +++ .../agentic-payments/03-signer-throws.json | 10 +++ .../assets/01-freezable-stablecoin.json | 12 +++ evals/scenarios/assets/02-op-no-trust.json | 11 +++ .../scenarios/assets/03-usdc-in-contract.json | 11 +++ .../scenarios/dapp/01-freighter-payment.json | 15 ++++ evals/scenarios/dapp/02-contract-invoke.json | 14 ++++ evals/scenarios/dapp/03-network-config.json | 14 ++++ .../data/01-historical-transactions.json | 11 +++ evals/scenarios/data/02-live-payments.json | 11 +++ .../data/03-contract-storage-read.json | 13 ++++ .../routing/01-dapp-plus-payments.json | 11 +++ .../scenarios/routing/02-rwa-compliance.json | 12 +++ .../routing/03-negative-control-pdf.json | 9 +++ .../smart-contracts/01-token-admin-mint.json | 16 ++++ .../smart-contracts/02-auth-tests.json | 15 ++++ .../smart-contracts/03-ttl-archival.json | 12 +++ .../standards/01-fiat-onramp-kyc.json | 11 +++ .../standards/02-nft-standard-status.json | 10 +++ .../standards/03-contract-event-indexers.json | 11 +++ .../zk-proofs/01-circom-groth16.json | 14 ++++ .../scenarios/zk-proofs/02-noir-onchain.json | 12 +++ .../zk-proofs/03-private-airdrop.json | 11 +++ 26 files changed, 379 insertions(+), 7 deletions(-) create mode 100644 evals/README.md create mode 100644 evals/scenarios/agentic-payments/01-monetize-express.json create mode 100644 evals/scenarios/agentic-payments/02-high-frequency-session.json create mode 100644 evals/scenarios/agentic-payments/03-signer-throws.json create mode 100644 evals/scenarios/assets/01-freezable-stablecoin.json create mode 100644 evals/scenarios/assets/02-op-no-trust.json create mode 100644 evals/scenarios/assets/03-usdc-in-contract.json create mode 100644 evals/scenarios/dapp/01-freighter-payment.json create mode 100644 evals/scenarios/dapp/02-contract-invoke.json create mode 100644 evals/scenarios/dapp/03-network-config.json create mode 100644 evals/scenarios/data/01-historical-transactions.json create mode 100644 evals/scenarios/data/02-live-payments.json create mode 100644 evals/scenarios/data/03-contract-storage-read.json create mode 100644 evals/scenarios/routing/01-dapp-plus-payments.json create mode 100644 evals/scenarios/routing/02-rwa-compliance.json create mode 100644 evals/scenarios/routing/03-negative-control-pdf.json create mode 100644 evals/scenarios/smart-contracts/01-token-admin-mint.json create mode 100644 evals/scenarios/smart-contracts/02-auth-tests.json create mode 100644 evals/scenarios/smart-contracts/03-ttl-archival.json create mode 100644 evals/scenarios/standards/01-fiat-onramp-kyc.json create mode 100644 evals/scenarios/standards/02-nft-standard-status.json create mode 100644 evals/scenarios/standards/03-contract-event-indexers.json create mode 100644 evals/scenarios/zk-proofs/01-circom-groth16.json create mode 100644 evals/scenarios/zk-proofs/02-noir-onchain.json create mode 100644 evals/scenarios/zk-proofs/03-private-airdrop.json diff --git a/README.md b/README.md index 7d12230..5b47d55 100644 --- a/README.md +++ b/README.md @@ -77,16 +77,17 @@ Copy the `skills/` directory contents to your assistant's skills location. ``` skills/ -├── smart-contracts/ # Stellar smart contracts — SKILL.md entry + development/testing/security files -├── dapp/SKILL.md # Frontend, wallets (Freighter, Wallets Kit), signing, smart accounts +├── smart-contracts/ # Stellar smart contracts — SKILL.md router + development/testing/security files +├── dapp/ # Frontend — SKILL.md router + react / data-fetching / smart-accounts files ├── assets/SKILL.md # Stellar Assets, trustlines, SAC bridge -├── data/SKILL.md # Stellar RPC (preferred) + Horizon (legacy), indexing -├── agentic-payments/SKILL.md # x402 + MPP (Charge + Channel) for AI/machine payments -├── zk-proofs/SKILL.md # ZK verification (BLS12-381 Groth16), Circom/Noir/RISC Zero walkthroughs -└── standards/SKILL.md # SEPs, CAPs, ecosystem projects, curated reference links +├── data/ # Stellar RPC (preferred) — SKILL.md router + horizon (legacy) file +├── agentic-payments/ # AI/machine payments — SKILL.md router + x402 / mpp files +├── zk-proofs/SKILL.md # ZK verification (BLS12-381/BN254 Groth16, UltraHonk), Circom/Noir/RISC Zero +├── standards/ # SEPs & CAPs — SKILL.md router + ecosystem / resources files +└── cross-chain/ # Cross-chain — SKILL.md router + cctp file ``` -Each sub-skill is a self-contained Agent Skill with its own frontmatter. Cross-references link related skills (e.g., the `agentic-payments` skill points to `smart-contracts` for the SACs the protocols call, and to `assets` for USDC). The AI reads only the sub-skills relevant to the task at hand. +Each sub-skill is a self-contained Agent Skill with its own frontmatter. Larger skills follow [Anthropic's progressive-disclosure guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): a sub-500-line `SKILL.md` router with a task-to-file table, plus companion files (one level deep) that load only when the task needs them. Cross-references link related skills (e.g., the `agentic-payments` skill points to `smart-contracts` for the SACs the protocols call, and to `assets` for USDC). The AI reads only the files relevant to the task at hand. ## Example Prompts @@ -112,6 +113,12 @@ Contributions are welcome! Please ensure any updates reflect current Stellar eco - Focus on practical, actionable guidance - Include code examples where helpful - Cite official documentation when possible +- Keep each `SKILL.md` body under ~500 lines — move deep dives into companion files routed by the task table +- When a change touches what a skill teaches, update or add the matching scenario under [`evals/`](evals/README.md) in the same PR + +## Evaluations + +[`evals/`](evals/README.md) holds ~3 task scenarios per skill (plus cross-skill routing checks and a negative control), each encoding a mistake agents actually make without the skill. Three grading tiers: machine-checkable compile checks, LLM-judged behavior assertions, and skill-trigger checks. See [evals/README.md](evals/README.md) for the format and how to run them. ## Resources diff --git a/evals/README.md b/evals/README.md new file mode 100644 index 0000000..62d3925 --- /dev/null +++ b/evals/README.md @@ -0,0 +1,73 @@ +# Skill Evaluations + +Representative task scenarios for every skill in this repo, following [Anthropic's evaluation-driven skill authoring guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration). Each scenario encodes a mistake an agent actually makes *without* the skill — several come from real failure modes (the #41 compile bugs, documented pitfalls in agentic-payments, the ZK curve trap), not imagined ones. Run them before publishing skill changes so regressions get caught here instead of by users. + +## Scenario format + +One JSON file per scenario under `scenarios//`: + +```json +{ + "skills": ["zk-proofs"], + "query": "I have a Noir circuit that proves age >= 18. Verify the proof on-chain on Stellar.", + "expected_behavior": [ + "States that Noir's UltraHonk/BN254 output verifies on-chain via the community rs-soroban-ultrahonk verifier...", + "Does not hand-roll a fake UltraHonk verifier contract from scratch" + ] +} +``` + +| Field | Meaning | +|-------|---------| +| `skills` | Which skill(s) should load for this query. Empty array + `"negative": true` = no Stellar skill should load. | +| `query` | The user prompt, verbatim. | +| `expected_behavior` | Assertions about the response, graded by a human or an LLM judge. | +| `machine_checkable` | (optional) Assertions a script can verify without a judge — compile checks, real CLI syntax. | +| `negative` | (optional) This is an off-topic control; loading any Stellar skill is a failure. | + +`scenarios/routing/` holds cross-skill scenarios that no single-skill eval catches: multi-skill loads and the off-topic negative control. + +## Grading tiers + +1. **Machine-checkable** (strongest — run in CI): generated Rust compiles with `cargo build --target wasm32v1-none`, generated TypeScript passes `tsc --noEmit`, CLI commands match real `stellar` syntax. This tier alone would have caught every snippet bug fixed in #41. +2. **Behavior assertions**: the `expected_behavior` strings, graded by an LLM judge (or a human) against the transcript. +3. **Trigger checks**: the right skill loaded, the right companion file was read, and no skill loads for off-topic queries. + +## Running an eval + +Evals exercise an *agent using the skills*, so the harness is any agent with the skills installed (Claude Code shown): + +```bash +# 1. Install the skills under test (from your working tree, not the published copy) +# e.g. symlink ./skills/* into ~/.claude/skills/ or use the plugin install path in the README + +# 2. Run one scenario headlessly and capture the transcript +q=$(python3 -c "import json;print(json.load(open('evals/scenarios/dapp/01-freighter-payment.json'))['query'])") +claude -p "$q" > /tmp/eval-transcript.txt + +# 3. Tier 1 — extract any generated code from the transcript and compile it +# Rust: cargo build --target wasm32v1-none --release +# TypeScript: tsc --noEmit (with the packages the scenario names installed) + +# 4. Tier 2 — grade expected_behavior against the transcript (LLM judge or human). +# A judge prompt as simple as "Here is a transcript and a list of expected +# behaviors; for each, answer pass/fail with a one-line quote as evidence" +# works well. + +# 5. Tier 3 — check the transcript's skill loads: the scenario's `skills` all +# loaded, nothing loaded for the negative control. +``` + +## Baselines: prove each eval discriminates + +Before trusting a scenario, run it **without** the skills installed and keep the failing transcript under `evals/baseline//.md`. That proves the eval discriminates (an unskilled model fails it), and tells us which evals to retire as base models improve — an eval every unskilled model passes measures nothing. + +## CI guidance + +- Tier 1 (compile checks) is cheap and deterministic — run on every PR that touches `skills/`. +- Tiers 2 and 3 need an agent + judge — run as a manually triggered workflow to keep costs sane. + +## Keeping scenarios honest + +- When a skill's facts change (a CAP ships, an API renames), update the affected scenario **in the same PR** — a stale eval that punishes the *correct* new answer is worse than no eval. Example: the Noir scenario expected "not natively possible" until Protocol 25/26 shipped BN254 + MSM host functions; it now expects the on-chain path. +- Scenario queries are user-voice and deliberately underspecified; do not "fix" them to hint at the answer. diff --git a/evals/scenarios/agentic-payments/01-monetize-express.json b/evals/scenarios/agentic-payments/01-monetize-express.json new file mode 100644 index 0000000..61b225a --- /dev/null +++ b/evals/scenarios/agentic-payments/01-monetize-express.json @@ -0,0 +1,15 @@ +{ + "skills": [ + "agentic-payments" + ], + "query": "Monetize my Express API so AI agents can pay per request.", + "expected_behavior": [ + "Uses the decision table and picks x402 for the lowest-friction facilitator flow (or states why MPP fits better)", + "Requires OZ_API_KEY on both testnet and mainnet for the OZ Channels facilitator", + "payTo is a classic G... account that holds a USDC trustline (not the SAC C... address)", + "Prices like $0.001 convert at 7 decimals (10000 base units), not 6 like EVM USDC" + ], + "machine_checkable": [ + "Generated server passes tsc --noEmit / node --check against the @x402/* packages" + ] +} diff --git a/evals/scenarios/agentic-payments/02-high-frequency-session.json b/evals/scenarios/agentic-payments/02-high-frequency-session.json new file mode 100644 index 0000000..b9721f4 --- /dev/null +++ b/evals/scenarios/agentic-payments/02-high-frequency-session.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "agentic-payments" + ], + "query": "My AI agent makes about 500 API calls per session. What's the right way to charge it on Stellar?", + "expected_behavior": [ + "Picks MPP Session mode (channel-backed; historically called Channel mode) — one deposit + one close instead of 500 on-chain transactions", + "States that each commitment amount is the cumulative running total, not the per-request price", + "Warns that Store.memory() is dev-only and a persistent store is required in production" + ] +} diff --git a/evals/scenarios/agentic-payments/03-signer-throws.json b/evals/scenarios/agentic-payments/03-signer-throws.json new file mode 100644 index 0000000..cf75fb5 --- /dev/null +++ b/evals/scenarios/agentic-payments/03-signer-throws.json @@ -0,0 +1,10 @@ +{ + "skills": [ + "agentic-payments" + ], + "query": "createEd25519Signer throws \"encoded argument must be of type String\" in my x402 client. Why?", + "expected_behavior": [ + "Identifies that the signer takes the raw S... secret string plus a CAIP-2 network ID (stellar:testnet / stellar:pubnet)", + "Removes the Keypair.fromSecret wrapping and any getNetworkPassphrase pre-conversion — both are done internally" + ] +} diff --git a/evals/scenarios/assets/01-freezable-stablecoin.json b/evals/scenarios/assets/01-freezable-stablecoin.json new file mode 100644 index 0000000..cc909a2 --- /dev/null +++ b/evals/scenarios/assets/01-freezable-stablecoin.json @@ -0,0 +1,12 @@ +{ + "skills": [ + "assets" + ], + "query": "Issue a stablecoin on Stellar that we can freeze if a holder's account is compromised.", + "expected_behavior": [ + "Separates issuer and distributor accounts", + "Sets AUTH_REQUIRED and AUTH_REVOCABLE flags on the issuer for freeze capability", + "Publishes asset metadata via stellar.toml (SEP-1)", + "Does not write a custom smart contract when a classic asset with flags does the job" + ] +} diff --git a/evals/scenarios/assets/02-op-no-trust.json b/evals/scenarios/assets/02-op-no-trust.json new file mode 100644 index 0000000..e6a5418 --- /dev/null +++ b/evals/scenarios/assets/02-op-no-trust.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "assets" + ], + "query": "My USDC payment on Stellar keeps failing with op_no_trust. What do I do?", + "expected_behavior": [ + "Diagnoses the missing trustline on the destination account", + "Adds a changeTrust operation (or asks the recipient to) before sending", + "Adds a check-before-send pattern rather than retrying blindly" + ] +} diff --git a/evals/scenarios/assets/03-usdc-in-contract.json b/evals/scenarios/assets/03-usdc-in-contract.json new file mode 100644 index 0000000..0331d5f --- /dev/null +++ b/evals/scenarios/assets/03-usdc-in-contract.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "assets" + ], + "query": "Use USDC inside my Stellar smart contract to accept deposits.", + "expected_behavior": [ + "Uses the Stellar Asset Contract (SAC) for USDC rather than reinventing a token contract", + "Derives the contract address for the asset (asset.contractId() / stellar contract id asset)", + "Calls it through token::Client (SEP-41 interface)" + ] +} diff --git a/evals/scenarios/dapp/01-freighter-payment.json b/evals/scenarios/dapp/01-freighter-payment.json new file mode 100644 index 0000000..41d1084 --- /dev/null +++ b/evals/scenarios/dapp/01-freighter-payment.json @@ -0,0 +1,15 @@ +{ + "skills": [ + "dapp" + ], + "query": "Build a Next.js page that connects the Freighter wallet and sends 10 XLM to another address.", + "expected_behavior": [ + "Uses the error-object @stellar/freighter-api pattern ({ address, error } returns), not try/catch around bare returns", + "Validates or passes the network passphrase explicitly when signing", + "Builds the payment with TransactionBuilder + Operation.payment and waits for confirmation after submission", + "Marks wallet-touching components as client components (\"use client\")" + ], + "machine_checkable": [ + "Generated TypeScript passes tsc --noEmit against @stellar/stellar-sdk and @stellar/freighter-api" + ] +} diff --git a/evals/scenarios/dapp/02-contract-invoke.json b/evals/scenarios/dapp/02-contract-invoke.json new file mode 100644 index 0000000..f4b1ec2 --- /dev/null +++ b/evals/scenarios/dapp/02-contract-invoke.json @@ -0,0 +1,14 @@ +{ + "skills": [ + "dapp" + ], + "query": "Invoke a method on a deployed Stellar smart contract from the browser and show the result.", + "expected_behavior": [ + "Prefers contract.Client (simulation preview via tx.result, then signAndSend) or the simulate → assemble/prepare → sign → send pipeline", + "Polls transaction status (pollTransaction / getTransaction) instead of assuming immediate success", + "Does not hand-build ScVals when contract.Client or queryContract would do" + ], + "machine_checkable": [ + "Generated TypeScript passes tsc --noEmit" + ] +} diff --git a/evals/scenarios/dapp/03-network-config.json b/evals/scenarios/dapp/03-network-config.json new file mode 100644 index 0000000..6e2423b --- /dev/null +++ b/evals/scenarios/dapp/03-network-config.json @@ -0,0 +1,14 @@ +{ + "skills": [ + "dapp" + ], + "query": "Set up my app's Stellar network configuration so it works on testnet and mainnet.", + "expected_behavior": [ + "Testnet runs without the mainnet RPC env var being set (mainnet env resolved lazily, only when selected)", + "Throws a clear error for unknown network names instead of silently defaulting", + "Uses a provider-specific mainnet RPC URL rather than inventing a public SDF mainnet RPC" + ], + "machine_checkable": [ + "Generated TypeScript passes tsc --noEmit" + ] +} diff --git a/evals/scenarios/data/01-historical-transactions.json b/evals/scenarios/data/01-historical-transactions.json new file mode 100644 index 0000000..c94aee2 --- /dev/null +++ b/evals/scenarios/data/01-historical-transactions.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "data" + ], + "query": "Get all transactions for a Stellar account from 3 months ago.", + "expected_behavior": [ + "Recognizes that most RPC methods only cover the retention window (~7 days) and does not query getTransactions for 3-month-old data", + "Routes to Horizon full history, Hubble (BigQuery), or a data-lake-backed getLedgers provider", + "If getLedgers is proposed, checks getHealth().oldestLedger (or provider retention) first instead of assuming genesis depth" + ] +} diff --git a/evals/scenarios/data/02-live-payments.json b/evals/scenarios/data/02-live-payments.json new file mode 100644 index 0000000..d612e39 --- /dev/null +++ b/evals/scenarios/data/02-live-payments.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "data" + ], + "query": "Watch for live incoming payments to my Stellar address and react to each one.", + "expected_behavior": [ + "Offers Horizon streaming (SSE) or RPC polling and states the tradeoff (RPC has no native streaming)", + "Handles reconnection/cursor resumption so no payments are missed", + "Does not invent a WebSocket API for Stellar RPC" + ] +} diff --git a/evals/scenarios/data/03-contract-storage-read.json b/evals/scenarios/data/03-contract-storage-read.json new file mode 100644 index 0000000..a32f7a7 --- /dev/null +++ b/evals/scenarios/data/03-contract-storage-read.json @@ -0,0 +1,13 @@ +{ + "skills": [ + "data" + ], + "query": "Read a value directly from a Stellar smart contract's storage.", + "expected_behavior": [ + "Uses getLedgerEntries with a contractData LedgerKey (correct durability) and decodes with scValToNative", + "Mentions the simpler alternative for exposed getters (simulate the getter / queryContract) where applicable" + ], + "machine_checkable": [ + "Generated TypeScript passes tsc --noEmit" + ] +} diff --git a/evals/scenarios/routing/01-dapp-plus-payments.json b/evals/scenarios/routing/01-dapp-plus-payments.json new file mode 100644 index 0000000..b109567 --- /dev/null +++ b/evals/scenarios/routing/01-dapp-plus-payments.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "dapp", + "agentic-payments" + ], + "query": "Build a dapp where users pay per API call with USDC on Stellar.", + "expected_behavior": [ + "Loads both the dapp skill (wallet, signing, frontend) and the agentic-payments skill (x402/MPP paywall)", + "Splits responsibilities correctly: payment protocol server-side, wallet UX client-side" + ] +} diff --git a/evals/scenarios/routing/02-rwa-compliance.json b/evals/scenarios/routing/02-rwa-compliance.json new file mode 100644 index 0000000..3e15d20 --- /dev/null +++ b/evals/scenarios/routing/02-rwa-compliance.json @@ -0,0 +1,12 @@ +{ + "skills": [ + "assets", + "standards" + ], + "query": "Tokenize a real-world asset on Stellar with compliance controls.", + "expected_behavior": [ + "Starts from the assets skill (classic asset + authorization flags / SAC), not a custom contract by default", + "Consults standards for SEP-57 (T-REX regulated token patterns, Draft) and flags its draft status", + "Escalates to a custom contract only for requirements flags cannot express" + ] +} diff --git a/evals/scenarios/routing/03-negative-control-pdf.json b/evals/scenarios/routing/03-negative-control-pdf.json new file mode 100644 index 0000000..68fd421 --- /dev/null +++ b/evals/scenarios/routing/03-negative-control-pdf.json @@ -0,0 +1,9 @@ +{ + "skills": [], + "negative": true, + "query": "Help me parse this PDF and extract the tables into CSV.", + "expected_behavior": [ + "No Stellar skill loads for this off-topic query", + "The answer contains no unprompted Stellar content" + ] +} diff --git a/evals/scenarios/smart-contracts/01-token-admin-mint.json b/evals/scenarios/smart-contracts/01-token-admin-mint.json new file mode 100644 index 0000000..4e602d8 --- /dev/null +++ b/evals/scenarios/smart-contracts/01-token-admin-mint.json @@ -0,0 +1,16 @@ +{ + "skills": [ + "smart-contracts" + ], + "query": "Write a Stellar smart contract for a token with an admin who can mint new tokens.", + "expected_behavior": [ + "Uses __constructor for initialization, not a guarded initialize() function", + "Defines a typed DataKey enum for storage keys", + "Calls admin.require_auth() on the mint path", + "Uses checked arithmetic (no unchecked add/sub on balances)", + "Compiles for the wasm32v1-none target with #![no_std] and soroban-sdk types" + ], + "machine_checkable": [ + "Generated contract compiles: cargo build --target wasm32v1-none --release" + ] +} diff --git a/evals/scenarios/smart-contracts/02-auth-tests.json b/evals/scenarios/smart-contracts/02-auth-tests.json new file mode 100644 index 0000000..07ea69e --- /dev/null +++ b/evals/scenarios/smart-contracts/02-auth-tests.json @@ -0,0 +1,15 @@ +{ + "skills": [ + "smart-contracts" + ], + "query": "Add tests to my Stellar contract, including tests that authorization is actually enforced.", + "expected_behavior": [ + "Registers the contract with env.register and a constructor-args tuple (not deprecated register_contract)", + "Uses mock_auths or mock_all_auths, paired with an env.auths() assertion that the expected auth was recorded", + "Reads the testing companion file (skills/smart-contracts/testing.md) rather than improvising", + "Includes a negative test: the call without authorization fails" + ], + "machine_checkable": [ + "Generated test module compiles and runs: cargo test" + ] +} diff --git a/evals/scenarios/smart-contracts/03-ttl-archival.json b/evals/scenarios/smart-contracts/03-ttl-archival.json new file mode 100644 index 0000000..cfd731c --- /dev/null +++ b/evals/scenarios/smart-contracts/03-ttl-archival.json @@ -0,0 +1,12 @@ +{ + "skills": [ + "smart-contracts" + ], + "query": "My Stellar contract calls started failing after a few weeks of inactivity and its data seems to be missing. What's going on?", + "expected_behavior": [ + "Diagnoses storage TTL expiry / state archival as the cause, not data loss or a network bug", + "Distinguishes instance, persistent, and temporary storage lifetimes", + "Recommends extend_ttl in hot paths and/or restoring archived entries (RestoreFootprint)", + "Does not recommend redeploying the contract as the primary fix" + ] +} diff --git a/evals/scenarios/standards/01-fiat-onramp-kyc.json b/evals/scenarios/standards/01-fiat-onramp-kyc.json new file mode 100644 index 0000000..56ebd0c --- /dev/null +++ b/evals/scenarios/standards/01-fiat-onramp-kyc.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "standards" + ], + "query": "Which Stellar standard should I use for a fiat on-ramp that needs KYC?", + "expected_behavior": [ + "Names SEP-6 (API-first) or SEP-24 (hosted interactive) for deposit/withdrawal, plus SEP-12 for KYC data", + "Explains the API-vs-hosted distinction so the user can pick", + "Points at the SEP documents rather than paraphrasing requirements from memory" + ] +} diff --git a/evals/scenarios/standards/02-nft-standard-status.json b/evals/scenarios/standards/02-nft-standard-status.json new file mode 100644 index 0000000..4b225d8 --- /dev/null +++ b/evals/scenarios/standards/02-nft-standard-status.json @@ -0,0 +1,10 @@ +{ + "skills": [ + "standards" + ], + "query": "Is there an NFT standard on Stellar, and is it final?", + "expected_behavior": [ + "Names SEP-50 (Non-Fungible Tokens) and reports it as Draft", + "Recommends verifying the live status in stellar-protocol before building against it, rather than asserting finality either way" + ] +} diff --git a/evals/scenarios/standards/03-contract-event-indexers.json b/evals/scenarios/standards/03-contract-event-indexers.json new file mode 100644 index 0000000..1250a65 --- /dev/null +++ b/evals/scenarios/standards/03-contract-event-indexers.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "standards" + ], + "query": "What indexers can I use for Stellar smart contract events?", + "expected_behavior": [ + "Names Mercury, SubQuery, and/or Goldsky from the ecosystem catalog", + "Links the official indexer directory for the full list", + "Reads the ecosystem companion file rather than answering from memory alone" + ] +} diff --git a/evals/scenarios/zk-proofs/01-circom-groth16.json b/evals/scenarios/zk-proofs/01-circom-groth16.json new file mode 100644 index 0000000..e4e32cd --- /dev/null +++ b/evals/scenarios/zk-proofs/01-circom-groth16.json @@ -0,0 +1,14 @@ +{ + "skills": [ + "zk-proofs" + ], + "query": "Verify a Circom Groth16 proof on-chain on Stellar.", + "expected_behavior": [ + "Keeps the circuit curve and the verifier contract on the same curve: compiles with -p bls12381 to match the canonical BLS12-381 example verifier, or knowingly pairs default bn128 output with a BN254 verifier (CAP-0074, Protocol 25+)", + "Cites CAP-0059 for BLS12-381 availability (Protocol 22+)", + "Includes the trusted-setup (powers of tau + phase 2) and off-chain verify sanity step before going on-chain" + ], + "machine_checkable": [ + "Referenced stellar contract / snarkjs / circom commands match real CLI syntax" + ] +} diff --git a/evals/scenarios/zk-proofs/02-noir-onchain.json b/evals/scenarios/zk-proofs/02-noir-onchain.json new file mode 100644 index 0000000..cd4ca9e --- /dev/null +++ b/evals/scenarios/zk-proofs/02-noir-onchain.json @@ -0,0 +1,12 @@ +{ + "skills": [ + "zk-proofs" + ], + "query": "I have a Noir circuit that proves age >= 18. Verify the proof on-chain on Stellar.", + "expected_behavior": [ + "States that Noir's UltraHonk/BN254 output verifies on-chain via the community rs-soroban-ultrahonk verifier, and that it needs Protocol 26+ (CAP-0074 base ops plus CAP-0080 MSM/Fr host functions)", + "Flags the verifier's maturity (young, community-maintained — check audit status before mainnet)", + "Does not hand-roll a fake UltraHonk verifier contract from scratch", + "Offers the alternatives with tradeoffs: re-express the statement as a Circom Groth16 circuit, or the attestation-oracle pattern with its trust assumption stated explicitly" + ] +} diff --git a/evals/scenarios/zk-proofs/03-private-airdrop.json b/evals/scenarios/zk-proofs/03-private-airdrop.json new file mode 100644 index 0000000..a647dd1 --- /dev/null +++ b/evals/scenarios/zk-proofs/03-private-airdrop.json @@ -0,0 +1,11 @@ +{ + "skills": [ + "zk-proofs" + ], + "query": "Design a private airdrop on Stellar where eligible users claim without revealing which allowlist entry they are.", + "expected_behavior": [ + "Validates public-input semantics in the contract (which Merkle root, which recipient, which amount) — not just proof validity", + "Uses a nullifier set for anti-replay so each entry claims once", + "Separates verifier (cryptographic validity) from policy/application logic" + ] +}