x402-engineer 0.1.0

package/AGENT.md

@@ -0,0 +1,102 @@
+# x402 Engineer
+
+> A helpful guide for adding HTTP 402 micropayments to any API using the x402 protocol on Stellar.
+
+## What I Do
+
+I help you add pay-per-request billing to API endpoints using the x402 protocol and USDC on Stellar testnet. I explain what I'm doing and why at each step -- think of me as a senior dev pairing with you on your first x402 integration.
+
+## Commands
+
+### `/x402:init` -- Bootstrap x402
+
+Sets up x402 payment protection in your project. Detects your framework (Next.js, Express, Fastify, or Hono), installs the correct x402 packages, and scaffolds configuration files.
+
+**Creates:**
+- Route config file (`lib/x402/config.ts`) with `routesConfig` and env var exports
+- Server/middleware file (`lib/x402/server.ts`) with framework-specific adapter
+- `.env.example` with required variables (SERVER_STELLAR_ADDRESS, FACILITATOR_URL, FACILITATOR_API_KEY)
+- For Fastify: custom `FastifyAdapter` (because `@x402/fastify` is not published on npm)
+
+**Idempotent:** Detects existing setup and skips what already exists.
+
+### `/x402:add-paywall` -- Protect an endpoint
+
+Wraps an API endpoint with x402 payment middleware. Discovers endpoints in your project, shows their protection status, and lets you choose which to protect.
+
+**How it works:**
+- Next.js: wraps the route handler inline with `withPayment()` or `withX402()`
+- Express/Fastify/Hono: adds the route to `routesConfig` (middleware handles the rest)
+
+**Idempotent:** Detects `// x402: payment-protected endpoint` markers and routesConfig entries. Already-protected endpoints are skipped.
+
+### `/x402:debug` -- Diagnose issues
+
+Runs a comprehensive static analysis checklist covering:
+1. Environment variables (set, format-valid)
+2. Dependencies (installed, correct versions)
+3. Code structure (config file, server file, import paths, price format)
+4. Framework detection (correct adapter for detected framework)
+
+**Output:** `[PASS]` / `[FAIL]` / `[WARN]` for each check with actionable fix instructions.
+
+### `/x402:explain` -- Understand your setup
+
+Generates a live overview of how x402 is wired in your project:
+- Protected endpoints table (method, path, price, asset, network)
+- 6-step payment flow diagram
+- Framework and adapter details
+- Configuration file locations
+
+**Dynamic:** Reads your codebase fresh on every invocation. Always reflects current state.
+
+### Recommended progression
+
+```
+/x402:init -> /x402:add-paywall -> /x402:explain -> /x402:debug
+```
+
+Start with `init` for new projects, or `add-paywall` if already set up.
+
+## Protocol Flow
+
+Every x402 payment follows this lifecycle:
+
+```
+Client Request -> 402 Response -> Sign Payment -> Retry with X-Payment -> Verify via Facilitator -> Settle -> Return Resource
+```
+
+1. **Client sends request** to a protected endpoint (no payment header)
+2. **Server returns HTTP 402** with payment requirements in response headers
+3. **Client signs a payment** using their Stellar wallet (USDC amount specified by server)
+4. **Client retries** the same request with `X-Payment` header containing the signed payment
+5. **Facilitator verifies** the payment signature and settles the transaction on Stellar
+6. **Server returns the resource** after facilitator confirms payment
+
+## What I Know
+
+- **x402 protocol**: Payment header format, facilitator API, middleware patterns
+- **Stellar testnet**: Account creation, USDC trustlines, transaction signing, Friendbot funding
+- **Frameworks**: Next.js (App Router), Express, Fastify, Hono -- server middleware patterns
+- **Skills**: x402-stellar (protocol reference), stellar-dev (blockchain reference)
+
+## What I Defer
+
+- **Mainnet deployment**: Use Stellar documentation for production network configuration
+- **Custom pricing models**: Beyond simple per-request pricing, consult x402 protocol spec
+- **Unsupported frameworks**: For frameworks not listed above, I'll adapt patterns but recommend checking framework docs
+- **Token economics**: For complex payment models, see tokenomics resources
+
+## Skills
+
+This agent ships with six skill packs:
+
+**Reference skills:**
+- **x402-stellar** -- Protocol patterns, API reference, setup guides for Stellar micropayments
+- **stellar-dev** -- Stellar/Soroban development: SDK usage, assets, contracts, testing, security
+
+**Command skills:**
+- **x402-init** -- `/x402:init` slash command
+- **x402-add-paywall** -- `/x402:add-paywall` slash command
+- **x402-debug** -- `/x402:debug` slash command
+- **x402-explain** -- `/x402:explain` slash command

package/README.md

@@ -0,0 +1,43 @@
+# @x402/engineer
+
+Claude Code skill pack for adding x402 micropayments to any API endpoint in seconds.
+
+## Install
+
+```bash
+npx @x402/engineer install
+```
+
+This registers x402 skills and slash commands into your Claude Code environment (`~/.claude/`).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/x402:init` | Bootstrap x402 in your project (deps, env template, route config) |
+| `/x402:add-paywall` | Wrap an endpoint with payment middleware (idempotent) |
+| `/x402:debug` | Diagnose payment flow issues (headers, facilitator, wallet) |
+| `/x402:explain` | Generate explanation of how x402 is wired in your codebase |
+
+## Supported Frameworks
+
+- Next.js (App Router)
+- Express
+- Fastify
+- Hono
+
+## Prerequisites
+
+- [Claude Code](https://claude.ai/code) installed and configured
+- Node.js >= 18
+- A Stellar wallet and OZ Channels facilitator credentials (see `/x402:init` for guided setup)
+
+## Uninstall
+
+```bash
+npx @x402/engineer uninstall
+```
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/install.ts
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+
+// src/paths.ts
+var import_node_path = __toESM(require("path"), 1);
+var import_node_os = __toESM(require("os"), 1);
+var PACKAGE_ROOT = import_node_path.default.resolve(__dirname, "..");
+var PATHS = {
+  packageRoot: PACKAGE_ROOT,
+  packageSkills: import_node_path.default.join(PACKAGE_ROOT, "skills"),
+  packageCommands: import_node_path.default.join(PACKAGE_ROOT, "commands"),
+  packageAgent: import_node_path.default.join(PACKAGE_ROOT, "AGENT.md"),
+  claudeDir: import_node_path.default.join(import_node_os.default.homedir(), ".claude"),
+  skillsDir: import_node_path.default.join(import_node_os.default.homedir(), ".claude", "skills"),
+  commandsDir: import_node_path.default.join(import_node_os.default.homedir(), ".claude", "commands"),
+  manifest: import_node_path.default.join(import_node_os.default.homedir(), ".claude", "skills", "x402-manifest.json")
+};
+
+// src/manifest.ts
+var import_node_fs = __toESM(require("fs"), 1);
+function readManifest(manifestPath) {
+  try {
+    const raw = import_node_fs.default.readFileSync(manifestPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function writeManifest(manifestPath, manifest) {
+  import_node_fs.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+}
+
+// src/install.ts
+function install(pathsOverride) {
+  const p = pathsOverride ?? PATHS;
+  const existing = readManifest(p.manifest);
+  const isUpdate = existing !== null;
+  const version = JSON.parse(
+    import_node_fs2.default.readFileSync(import_node_path2.default.join(p.packageRoot, "package.json"), "utf-8")
+  ).version;
+  import_node_fs2.default.mkdirSync(p.skillsDir, { recursive: true });
+  import_node_fs2.default.mkdirSync(p.commandsDir, { recursive: true });
+  const installedSkills = [];
+  const installedCommands = [];
+  const skillDirs = import_node_fs2.default.readdirSync(p.packageSkills, { withFileTypes: true }).filter((d) => d.isDirectory());
+  for (const dir of skillDirs) {
+    const src = import_node_path2.default.join(p.packageSkills, dir.name);
+    const dest = import_node_path2.default.join(p.skillsDir, dir.name);
+    import_node_fs2.default.cpSync(src, dest, { recursive: true, force: true });
+    installedSkills.push(dest);
+    const verb = isUpdate ? "Updated" : "Installed";
+    console.log(`  \u2713 ${verb} ${dir.name} skill`);
+  }
+  if (import_node_fs2.default.existsSync(import_node_path2.default.join(p.packageCommands, "x402"))) {
+    const src = import_node_path2.default.join(p.packageCommands, "x402");
+    const dest = import_node_path2.default.join(p.commandsDir, "x402");
+    import_node_fs2.default.cpSync(src, dest, { recursive: true, force: true });
+    installedCommands.push(dest);
+    const verb = isUpdate ? "Updated" : "Installed";
+    console.log(`  \u2713 ${verb} x402 commands`);
+  }
+  writeManifest(p.manifest, {
+    version,
+    installedAt: existing?.installedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    paths: { skills: installedSkills, commands: installedCommands }
+  });
+  console.log("");
+  console.log("  Run /x402:init to get started");
+}
+
+// src/uninstall.ts
+var import_node_fs3 = __toESM(require("fs"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+function uninstall(pathsOverride) {
+  const p = pathsOverride ?? PATHS;
+  const manifest = readManifest(p.manifest);
+  if (!manifest) {
+    console.log("  x402 engineer is not installed");
+    return;
+  }
+  for (const skillPath of manifest.paths.skills) {
+    if (import_node_fs3.default.existsSync(skillPath)) {
+      import_node_fs3.default.rmSync(skillPath, { recursive: true, force: true });
+      console.log(`  \u2713 Removed ${import_node_path3.default.basename(skillPath)} skill`);
+    }
+  }
+  for (const cmdPath of manifest.paths.commands) {
+    if (import_node_fs3.default.existsSync(cmdPath)) {
+      import_node_fs3.default.rmSync(cmdPath, { recursive: true, force: true });
+      console.log(`  \u2713 Removed ${import_node_path3.default.basename(cmdPath)} commands`);
+    }
+  }
+  import_node_fs3.default.rmSync(p.manifest, { force: true });
+  console.log("");
+  console.log("  x402 engineer uninstalled");
+}
+
+// src/cli.ts
+var command = process.argv[2];
+switch (command) {
+  case "install":
+    install();
+    break;
+  case "uninstall":
+    uninstall();
+    break;
+  default:
+    console.log("Usage: npx @x402/engineer <install|uninstall>");
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "x402-engineer",
+  "version": "0.1.0",
+  "description": "Claude Code skill pack for adding x402 micropayments to any API endpoint",
+  "license": "MIT",
+  "type": "module",
+  "bin": "dist/cli.cjs",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types/index.ts"
+  },
+  "types": "./src/index.ts",
+  "files": [
+    "dist/",
+    "skills/",
+    "commands/",
+    "AGENT.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "x402",
+    "micropayments",
+    "stellar",
+    "claude-code",
+    "skill-pack",
+    "api-monetization"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/x402/engineer",
+    "directory": "packages/engineer"
+  },
+  "devDependencies": {
+    "@x402/tsconfig": "*",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/stellar-dev/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: stellar-dev
+description: End-to-end Stellar development playbook. Covers Soroban smart contracts (Rust SDK), Stellar CLI, JavaScript/Python/Go SDKs for client apps, Stellar RPC (preferred) and Horizon API (legacy), Stellar Assets vs Soroban tokens (SAC bridge), wallet integration (Freighter, Stellar Wallets Kit), smart accounts with passkeys, status-sensitive zero-knowledge proof patterns, testing strategies, security patterns, and common pitfalls. Optimized for payments, asset tokenization, DeFi, privacy-aware applications, and financial applications. Use when building on Stellar, Soroban, or working with XLM, Stellar Assets, trustlines, anchors, SEPs, ZK proofs, or the Stellar RPC/Horizon APIs.
+user-invocable: true
+argument-hint: "[task-description]"
+triggers:
+  - /x402:init
+  - /x402:debug
+  - stellar
+  - soroban
+  - xlm
+  - trustline
+---
+
+# Stellar Development Skill (Soroban-first)
+
+## What this Skill is for
+Use this Skill when the user asks for:
+- Soroban smart contract development (Rust)
+- Stellar dApp frontend work (React / Next.js / Node.js)
+- Wallet connection + signing flows (Freighter, etc.)
+- Transaction building / sending / confirmation
+- Stellar Asset issuance and management
+- Client SDK usage (JavaScript, Python, Go, Rust)
+- Zero-knowledge proof verification (where supported by target network/protocol)
+- Privacy-preserving applications (privacy pools, confidential tokens)
+- Local testing and deployment
+- Security hardening and audit-style reviews
+
+## What this Skill is NOT for
+- Bitcoin, Ethereum, Solana, or other non-Stellar blockchain development
+- Stellar node/validator operation (see [validators docs](https://developers.stellar.org/docs/validators))
+- General Rust programming unrelated to Soroban
+- Stellar protocol governance or CAP authoring
+
+## Default stack decisions (opinionated)
+
+### 1. Smart Contracts: Soroban (Rust)
+- Use Soroban SDK (`soroban-sdk` crate) for all smart contract development
+- Contracts compile to WebAssembly (WASM)
+- Use `#![no_std]` - standard library not available
+- 64KB contract size limit - use release optimizations
+- Prefer Stellar Assets over custom token contracts when possible
+
+### 2. Client SDK: stellar-sdk (JavaScript) first
+- Use `@stellar/stellar-sdk` for browser and Node.js applications
+- Supports both Stellar RPC and legacy Horizon API
+- Full transaction building, signing, and submission
+- Soroban contract deployment and invocation
+
+### 3. API Access: Stellar RPC first (Horizon legacy-focused)
+- **Prefer Stellar RPC** for new projects (JSON-RPC, real-time state)
+- **Horizon API** remains available for legacy compatibility and historical-query workflows
+- RPC: 7-day history for most methods; `getLedgers` queries back to genesis (Infinite Scroll)
+- Use Hubble/Galexie for comprehensive historical data beyond RPC
+
+### 4. Token Strategy: Stellar Assets first
+- **Prefer Stellar Assets** (classic issuance + trustlines) for fungible tokens
+- Built-in ecosystem support (wallets, exchanges, anchors)
+- Stellar Asset Contracts (SAC) provide Soroban interoperability
+- Use custom Soroban tokens only for complex logic requirements
+
+### 5. Testing
+- **Local**: Use Stellar Quickstart Docker for local network
+- **Testnet**: Use Testnet with Friendbot for funding
+- **Unit tests**: Compile to native for fast iteration
+- **Integration tests**: Deploy to local/testnet
+
+### 6. Wallet Integration
+- **Freighter** is the primary browser wallet
+- Use Stellar Wallets Kit for multi-wallet support
+- Wallet Standard for consistent connection patterns
+
+### 7. Freshness policy
+- Verify volatile facts (protocol support, RPC endpoints, CAP/SEP status, SDK API changes) against official docs before asserting them as current.
+
+## Operating procedure (how to execute tasks)
+
+### 1. Classify the task layer
+- Smart contract layer (Soroban/Rust)
+- Client SDK/scripts layer (JS/Python/Go)
+- Frontend/wallet layer
+- Asset management layer (issuance, trustlines)
+- Testing/CI layer
+- Infrastructure (RPC/Horizon/indexing)
+
+### Quick routing
+- Need custom on-chain logic? → [contracts-soroban.md](contracts-soroban.md)
+- Building a frontend/dApp? → [frontend-stellar-sdk.md](frontend-stellar-sdk.md)
+- Issuing or managing tokens? → [stellar-assets.md](stellar-assets.md)
+- Zero-knowledge proofs or privacy? → [zk-proofs.md](zk-proofs.md)
+- Setting up tests/CI? → [testing.md](testing.md)
+- Querying chain data or indexing? → [api-rpc-horizon.md](api-rpc-horizon.md) (also see [Data Docs](https://developers.stellar.org/docs/data))
+- Security review? → [security.md](security.md)
+- Hit an error? → [common-pitfalls.md](common-pitfalls.md)
+- Need upgrade/factory/governance/DeFi architecture patterns? → [advanced-patterns.md](advanced-patterns.md)
+- Need SEP/CAP guidance and standards links? → [standards-reference.md](standards-reference.md)
+
+### 2. Pick the right building blocks
+- Contracts: Soroban Rust SDK + Stellar CLI
+- Frontend: stellar-sdk (JS) + Freighter/Wallets Kit
+- Backend: stellar-sdk (JS/Python/Go) + RPC
+- Assets: Classic operations or SAC for Soroban interop
+- Testing: Quickstart (local) or Testnet
+
+### 3. Implement with Stellar-specific correctness
+Always be explicit about:
+- Network passphrase (Mainnet vs Testnet vs local)
+- Source account + sequence number
+- Fee + resource limits (for Soroban)
+- Authorization requirements
+- Trustline status for assets
+- Contract storage types (temporary vs persistent vs instance)
+
+### 4. Add tests
+- Unit tests: Native compilation with `#[test]`
+- Integration tests: Local Quickstart or Testnet
+- Contract tests: Use `Env` from soroban-sdk
+- Frontend tests: Mock wallet/RPC interactions
+
+### 5. Deliverables expectations
+When you implement changes, provide:
+- Exact files changed + diffs
+- Commands to install/build/test/deploy
+- Network configuration (passphrase, RPC endpoint)
+- Risk notes for signing/fees/storage/authorization
+
+## Progressive disclosure (read when needed)
+- Smart contracts: [contracts-soroban.md](contracts-soroban.md)
+- Frontend + wallets: [frontend-stellar-sdk.md](frontend-stellar-sdk.md)
+- Testing strategy: [testing.md](testing.md)
+- Stellar Assets: [stellar-assets.md](stellar-assets.md)
+- Zero-knowledge proofs: [zk-proofs.md](zk-proofs.md)
+- API access (RPC/Horizon): [api-rpc-horizon.md](api-rpc-horizon.md)
+- Security checklist: [security.md](security.md)
+- Common pitfalls: [common-pitfalls.md](common-pitfalls.md)
+- Advanced architecture patterns: [advanced-patterns.md](advanced-patterns.md)
+- SEP/CAP standards map: [standards-reference.md](standards-reference.md)
+- Ecosystem projects: [ecosystem.md](ecosystem.md)
+- Reference links: [resources.md](resources.md)
+
+## Keywords
+stellar, soroban, xlm, smart contracts, rust, wasm, webassembly, rpc, horizon,
+freighter, stellar-sdk, soroban-sdk, stellar-cli, trustline, anchor, sep, passkey,
+smart wallet, sac, stellar asset contract, defi, token, nft, scaffold stellar, constructor, upgrade, factory, governance, standards,
+zero-knowledge, zk, zk-snark, groth16, bn254, poseidon, pairing, privacy, confidential, noir, risc zero, privacy pool, merkle tree

package/skills/stellar-dev/advanced-patterns.md

@@ -0,0 +1,188 @@
+# Advanced Soroban Patterns
+
+## When to use this guide
+Use this guide for higher-complexity contract architecture:
+- Upgrades and migrations
+- Factory/deployer systems
+- Governance and timelocks
+- DeFi primitives (vaults, pools, oracles)
+- Regulated token/compliance workflows
+- Resource and storage optimization
+
+Use `contracts-soroban.md` for core contract syntax and day-to-day patterns.
+
+## Design principles
+- Prefer simple state machines over implicit behavior.
+- Minimize privileged entrypoints and protect all privileged actions with explicit auth.
+- Keep upgrades predictable: version metadata + migration plan + rollback strategy.
+- Use idempotent migrations and fail fast on incompatible versions.
+- Separate protocol/business logic from governance/admin logic when possible.
+
+## Upgradeability patterns
+
+### 1) Explicit upgrade policy
+- Decide early whether the contract is mutable or immutable.
+- If mutable, implement an `upgrade` entrypoint guarded by admin or governance.
+- If immutable, do not expose upgrade capability.
+
+### 2) Version tracking
+Track both runtime and code version:
+- Contract metadata (`contractmeta!`) for binary version
+- Storage key for migration/application version
+
+```rust
+#![no_std]
+use soroban_sdk::{contract, contractimpl, contractmeta, contracttype, Address, BytesN, Env};
+
+contractmeta!(key = "binver", val = "1.0.0");
+
+#[contracttype]
+#[derive(Clone)]
+pub enum DataKey {
+    Admin,
+    AppVersion,
+}
+
+#[contract]
+pub struct Upgradeable;
+
+#[contractimpl]
+impl Upgradeable {
+    pub fn __constructor(env: Env, admin: Address) {
+        env.storage().instance().set(&DataKey::Admin, &admin);
+        env.storage().instance().set(&DataKey::AppVersion, &1u32);
+    }
+
+    pub fn upgrade(env: Env, new_wasm_hash: BytesN<32>) {
+        let admin: Address = env.storage().instance().get(&DataKey::Admin).unwrap();
+        admin.require_auth();
+        env.deployer().update_current_contract_wasm(new_wasm_hash);
+    }
+}
+```
+
+### 3) Migration entrypoint
+- Add a dedicated `migrate` function after upgrades.
+- Ensure migration is monotonic (`new_version > current_version`).
+- Treat migrations as one-way and idempotent.
+
+## Factory and deployment patterns
+
+### Factory contract responsibilities
+- Authorize who can deploy instances.
+- Derive deterministic addresses with salts when needed.
+- Emit events for deployments (indexing/ops observability).
+- Keep deployment logic separate from instance business logic.
+
+```rust
+#![no_std]
+use soroban_sdk::{contract, contractimpl, Address, BytesN, Env, Val, Vec};
+
+#[contract]
+pub struct Factory;
+
+#[contractimpl]
+impl Factory {
+    pub fn deploy(
+        env: Env,
+        owner: Address,
+        wasm_hash: BytesN<32>,
+        salt: BytesN<32>,
+        constructor_args: Vec<Val>,
+    ) -> Address {
+        owner.require_auth();
+        env.deployer()
+            .with_address(env.current_contract_address(), salt)
+            .deploy_v2(wasm_hash, constructor_args)
+    }
+}
+```
+
+Operational note:
+- Keep a registry (or emit canonical deployment events) to avoid orphaned instances.
+
+## Governance patterns
+
+### Timelock for sensitive actions
+Use a timelock for upgrades and major config changes:
+- `propose_*` stores pending action + execute ledger
+- `execute_*` enforces delay
+- `cancel_*` allows governance abort
+
+### Multisig and role separation
+- Separate roles: proposer, approver, executor.
+- Define threshold and signer rotation process.
+- Record proposal state in persistent storage and prevent replay.
+
+Checklist:
+- Proposal uniqueness and replay protection
+- Expiry semantics
+- Clear cancellation path
+- Explicit event emission
+
+## DeFi primitives
+
+### Vaults
+- Track `total_assets` and `total_shares` with careful rounding rules.
+- Use conservative math for mint/redeem conversions.
+- Enforce pause/emergency controls for admin-level intervention.
+
+### Pools/AMMs
+- Define invariant and fee accounting precisely.
+- Protect against stale pricing and manipulation.
+- Include slippage checks on all user-facing swaps.
+
+### Oracle integration
+- Require freshness constraints (ledger/time bounds).
+- Prefer median/multi-source feeds for critical operations.
+- Add circuit breakers for extreme price movement.
+
+## Compliance-oriented token design
+
+Common regulated features:
+- Allowlist/denylist checks before transfer
+- Jurisdiction or investor-class restrictions
+- Forced transfer/freeze authority with auditable governance
+- Off-chain identity references (never store sensitive PII directly)
+
+Implementation guidance:
+- Keep compliance policy in dedicated modules/entrypoints.
+- Emit policy decision events for traceability.
+- Treat privileged compliance actions as high-risk operations requiring strong auth.
+
+## Resource optimization
+
+### Storage
+- Use `instance` for global config.
+- Use `persistent` for critical user state.
+- Use `temporary` only for disposable data.
+- Extend TTL strategically, not on every call.
+
+### Compute
+- Avoid unbounded loops over user-controlled collections.
+- Prefer bounded batch operations.
+- Reduce cross-contract calls in hot paths.
+
+### Contract size
+- Keep release profile optimized (`opt-level = "z"`, `lto = true`, `panic = "abort"`).
+- Split concerns across contracts when near Wasm size limits.
+
+## Security review checklist for advanced architectures
+- Access control is explicit on every privileged path.
+- Upgrade and migration are both tested (happy path + failure path).
+- Timelock and governance logic is replay-safe.
+- External dependency assumptions are documented.
+- Emergency controls and incident runbooks are defined.
+- Events cover operationally important transitions.
+
+## Testing strategy for advanced patterns
+- Unit tests for role checks, invariants, and edge-case math.
+- Integration tests for multi-step governance flows.
+- Upgrade tests from old state snapshots to new versions.
+- Negative tests for unauthorized and malformed calls.
+
+## Related docs
+- Core contract development: `contracts-soroban.md`
+- Security checks: `security.md`
+- Testing approach: `testing.md`
+- Standards references: `standards-reference.md`