Refine Stellar dev skill docs and integrate PR #3 content

README.md

@@ -1,6 +1,6 @@
 # Stellar Development Skill
 
-A comprehensive AI skill for modern Stellar development (January 2026 best practices).
+A comprehensive AI skill for modern Stellar development with current best practices.
 
 Inspired by [solana-foundation/solana-dev-skill](https://github.com/solana-foundation/solana-dev-skill) and [cloudflare/skills](https://github.com/cloudflare/skills).
 
@@ -64,9 +64,12 @@ skill/
 ├── frontend-stellar-sdk.md     # Frontend integration patterns
 ├── testing.md                  # Testing strategies
 ├── stellar-assets.md           # Asset issuance and management
+├── zk-proofs.md                # ZK proof architecture and verification patterns
 ├── api-rpc-horizon.md          # API access (RPC/Horizon)
 ├── security.md                 # Security checklist
 ├── common-pitfalls.md          # Common issues and solutions
+├── advanced-patterns.md        # Advanced Soroban architecture patterns
+├── standards-reference.md      # SEP/CAP standards quick reference
 ├── ecosystem.md                # DeFi protocols, wallets, tools, projects
 └── resources.md                # Curated reference links
 ```

skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stellar-dev
-description: End-to-end Stellar development playbook (Jan 2026). 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, zero-knowledge proofs (Protocol 25 X-Ray, BN254, Poseidon), testing strategies, security patterns, and common pitfalls. Optimized for payments, asset tokenization, DeFi, privacy-preserving applications, and financial applications. Use when building on Stellar, Soroban, or working with XLM, Stellar Assets, trustlines, anchors, SEPs, ZK proofs, privacy pools, or the Stellar RPC/Horizon APIs.
+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]"
 ---
@@ -15,7 +15,7 @@ Use this Skill when the user asks for:
 - Transaction building / sending / confirmation
 - Stellar Asset issuance and management
 - Client SDK usage (JavaScript, Python, Go, Rust)
-- Zero-knowledge proof verification (BN254, Poseidon, Groth16)
+- 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
@@ -41,9 +41,9 @@ Use this Skill when the user asks for:
 - Full transaction building, signing, and submission
 - Soroban contract deployment and invocation
 
-### 3. API Access: Stellar RPC first (Horizon deprecated)
+### 3. API Access: Stellar RPC first (Horizon legacy-focused)
 - **Prefer Stellar RPC** for new projects (JSON-RPC, real-time state)
-- **Horizon API** is deprecated but maintained for legacy compatibility
+- **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
 
@@ -64,6 +64,9 @@ Use this Skill when the user asks for:
 - 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
@@ -83,6 +86,8 @@ Use this Skill when the user asks for:
 - 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
@@ -122,12 +127,13 @@ When you implement changes, provide:
 - 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,
-zero-knowledge, zk, zk-snark, groth16, bn254, poseidon, pairing, privacy, confidential,
-x-ray, protocol 25, noir, risc zero, privacy pool, merkle tree
+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

skill/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`

skill/api-rpc-horizon.md

@@ -7,17 +7,26 @@ Stellar provides two API paradigms:
 | API | Status | Use Case |
 |-----|--------|----------|
 | **Stellar RPC** | Preferred | Soroban, real-time state, new projects |
-| **Horizon** | Deprecated (maintained) | Historical data, legacy applications |
+| **Horizon** | Legacy-focused | Historical data, legacy applications |
 
-**Recommendation**: Use Stellar RPC for all new projects. Use Horizon only for historical queries or legacy compatibility.
+**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)
 
 ## Stellar RPC
 
 ### Endpoints
 
+> Note: SDF directly provides Futurenet public RPC. For Mainnet RPC, select a provider from the [RPC providers directory](https://developers.stellar.org/docs/data/apis/rpc/providers).
+
 | Network | RPC URL |
 |---------|---------|
-| Mainnet | `https://soroban.stellar.org` |
+| Mainnet | Provider-specific endpoint (see [RPC providers directory](https://developers.stellar.org/docs/data/apis/rpc/providers)) |
 | Testnet | `https://soroban-testnet.stellar.org` |
 | Futurenet | `https://rpc-futurenet.stellar.org` |
 | Local | `http://localhost:8000/soroban/rpc` |
@@ -144,7 +153,7 @@ for (const event of events.events) {
 - **No streaming**: Poll for updates (no WebSocket)
 - **Contract-focused**: Limited classic Stellar data
 
-## Horizon API (Deprecated)
+## Horizon API (Legacy)
 
 ### Endpoints
 
@@ -394,6 +403,7 @@ See the full indexer directory: https://developers.stellar.org/docs/data/indexer
 ## Network Configuration
 
 > For a React/Next.js-specific setup, see [frontend-stellar-sdk.md](frontend-stellar-sdk.md).
+> For mainnet RPC, set `STELLAR_MAINNET_RPC_URL` from a provider in the [RPC providers directory](https://developers.stellar.org/docs/data/apis/rpc/providers).
 
 ### Environment-Based Setup
 
@@ -408,9 +418,15 @@ type NetworkConfig = {
   friendbotUrl: string | null;
 };
 
+const requireEnv = (name: string): string => {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing required env var: ${name}`);
+  return value;
+};
+
 const configs: Record<string, NetworkConfig> = {
   mainnet: {
-    rpcUrl: "https://soroban.stellar.org",
+    rpcUrl: requireEnv("STELLAR_MAINNET_RPC_URL"),
     horizonUrl: "https://horizon.stellar.org",
     networkPassphrase: StellarSdk.Networks.PUBLIC,
     friendbotUrl: null,