stellar-agent 0.1.0

package/src/stellar-skills/4-implementation/stellar-sep10-auth/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: stellar-sep10-auth
+description: 'Implement SEP-10 Web Authentication for Stellar dApps — challenge/response flow, JWT issuance, and backend verification. Use when the user needs to authenticate users by their Stellar account without sharing private keys.'
+---
+
+# SEP-10 Web Authentication
+
+## Purpose
+
+Implement the Stellar SEP-10 standard to authenticate users by proving ownership of a Stellar account. Issues a JWT for subsequent API calls.
+
+## On Activation
+
+Load `{network_preference}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+## How SEP-10 Works
+
+1. **Client** requests a challenge from the server, providing their public key
+2. **Server** builds a Stellar transaction encoding a random nonce — signed by the server's keypair — and returns it as XDR
+3. **Client** signs the challenge transaction with their wallet (Freighter)
+4. **Server** verifies both signatures, checks nonce/expiry, issues a JWT
+5. **Client** sends the JWT in `Authorization: Bearer {token}` on subsequent API requests
+
+## Backend Setup (Node.js / Next.js API Routes)
+
+### Step 1: Install Dependencies
+
+```bash
+yarn add express jsonwebtoken stellar-sdk
+# or for Next.js only:
+npm install jsonwebtoken stellar-sdk
+npm install --save-dev @types/jsonwebtoken
+```
+
+### Step 2: Environment Variables
+
+```env
+# Server-side only (no NEXT_PUBLIC_ prefix)
+SEP10_SERVER_SECRET=S...          # Stellar keypair secret key for signing challenges
+SEP10_HOME_DOMAIN=yourdomain.com  # must match stellar.toml WEB_AUTH_ENDPOINT host
+JWT_SECRET=your-jwt-secret-here   # random 32+ char string
+JWT_EXPIRES_IN=24h
+```
+
+### Step 3: Challenge Endpoint
+
+`src/app/api/auth/challenge/route.ts`:
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  Keypair, TransactionBuilder, Networks, Operation,
+  Account, StrKey, BASE_FEE,
+} from 'stellar-sdk';
+
+const SERVER_KEYPAIR = Keypair.fromSecret(process.env.SEP10_SERVER_SECRET!);
+const HOME_DOMAIN = process.env.SEP10_HOME_DOMAIN!;
+const NETWORK_PASSPHRASE = process.env.NEXT_PUBLIC_NETWORK_PASSPHRASE!;
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const clientPublicKey = searchParams.get('account');
+
+  if (!clientPublicKey || !StrKey.isValidEd25519PublicKey(clientPublicKey)) {
+    return NextResponse.json({ error: 'Invalid account' }, { status: 400 });
+  }
+
+  // SEP-10 requires a fake account with sequence 0
+  const serverAccount = new Account(SERVER_KEYPAIR.publicKey(), '-1');
+
+  const now = Math.floor(Date.now() / 1000);
+  const tx = new TransactionBuilder(serverAccount, {
+    fee: BASE_FEE,
+    networkPassphrase: NETWORK_PASSPHRASE,
+    timebounds: {
+      minTime: now,
+      maxTime: now + 300, // 5 minute window
+    },
+  })
+    .addOperation(
+      Operation.manageData({
+        name: `${HOME_DOMAIN} auth`,
+        value: Buffer.from(crypto.getRandomValues(new Uint8Array(48))).toString('base64'),
+        source: clientPublicKey, // operation source = client account
+      })
+    )
+    .addOperation(
+      Operation.manageData({
+        name: 'web_auth_domain',
+        value: HOME_DOMAIN,
+        source: SERVER_KEYPAIR.publicKey(),
+      })
+    )
+    .build();
+
+  tx.sign(SERVER_KEYPAIR);
+
+  return NextResponse.json({
+    transaction: tx.toXDR(),
+    network_passphrase: NETWORK_PASSPHRASE,
+  });
+}
+```
+
+### Step 4: Token Endpoint
+
+`src/app/api/auth/token/route.ts`:
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { TransactionBuilder, Keypair, StrKey } from 'stellar-sdk';
+import jwt from 'jsonwebtoken';
+
+const SERVER_KEYPAIR = Keypair.fromSecret(process.env.SEP10_SERVER_SECRET!);
+const HOME_DOMAIN = process.env.SEP10_HOME_DOMAIN!;
+const NETWORK_PASSPHRASE = process.env.NEXT_PUBLIC_NETWORK_PASSPHRASE!;
+const JWT_SECRET = process.env.JWT_SECRET!;
+
+export async function POST(request: NextRequest) {
+  const { transaction } = await request.json();
+
+  try {
+    const tx = TransactionBuilder.fromXDR(transaction, NETWORK_PASSPHRASE);
+
+    // 1. Verify server signature
+    const serverSigned = tx.signatures.some(sig =>
+      SERVER_KEYPAIR.verify(tx.hash(), sig.signature())
+    );
+    if (!serverSigned) {
+      return NextResponse.json({ error: 'Invalid server signature' }, { status: 400 });
+    }
+
+    // 2. Extract client public key from first operation's source
+    const clientKey = (tx.operations[0] as any).source;
+    if (!clientKey || !StrKey.isValidEd25519PublicKey(clientKey)) {
+      return NextResponse.json({ error: 'Missing client source account' }, { status: 400 });
+    }
+
+    // 3. Verify client signature
+    const clientKeypair = Keypair.fromPublicKey(clientKey);
+    const clientSigned = tx.signatures.some(sig => {
+      try {
+        return clientKeypair.verify(tx.hash(), sig.signature());
+      } catch {
+        return false;
+      }
+    });
+    if (!clientSigned) {
+      return NextResponse.json({ error: 'Client signature missing or invalid' }, { status: 400 });
+    }
+
+    // 4. Verify timebounds not expired
+    const now = Math.floor(Date.now() / 1000);
+    const { minTime, maxTime } = tx.timeBounds!;
+    if (now < Number(minTime) || now > Number(maxTime)) {
+      return NextResponse.json({ error: 'Challenge expired' }, { status: 400 });
+    }
+
+    // 5. Issue JWT
+    const token = jwt.sign(
+      { sub: clientKey, iss: HOME_DOMAIN },
+      JWT_SECRET,
+      { expiresIn: process.env.JWT_EXPIRES_IN || '24h' }
+    );
+
+    return NextResponse.json({ token });
+  } catch (err) {
+    return NextResponse.json({ error: String(err) }, { status: 400 });
+  }
+}
+```
+
+### Step 5: Client-Side SEP-10 Flow
+
+`src/lib/stellar/sep10.ts`:
+
+```typescript
+import { TransactionBuilder } from 'stellar-sdk';
+import { NETWORK_PASSPHRASE } from './config';
+
+export async function authenticate(
+  publicKey: string,
+  signFn: (xdr: string) => Promise<string>
+): Promise<string> {
+  // 1. Get challenge
+  const chalRes = await fetch(`/api/auth/challenge?account=${publicKey}`);
+  if (!chalRes.ok) throw new Error('Failed to get challenge');
+  const { transaction } = await chalRes.json();
+
+  // 2. Sign with wallet (Freighter)
+  const signedXdr = await signFn(transaction);
+
+  // 3. Submit signed challenge
+  const tokenRes = await fetch('/api/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ transaction: signedXdr }),
+  });
+  if (!tokenRes.ok) throw new Error('Authentication failed');
+  const { token } = await tokenRes.json();
+  return token;
+}
+```
+
+### Step 6: Protect API Routes
+
+Middleware helper for authenticated routes:
+
+```typescript
+import jwt from 'jsonwebtoken';
+import { NextRequest } from 'next/server';
+
+export function verifyJwt(request: NextRequest): string | null {
+  const auth = request.headers.get('Authorization');
+  if (!auth?.startsWith('Bearer ')) return null;
+  try {
+    const payload = jwt.verify(auth.slice(7), process.env.JWT_SECRET!) as jwt.JwtPayload;
+    return payload.sub ?? null; // returns the Stellar public key
+  } catch {
+    return null;
+  }
+}
+```
+
+Usage in protected routes:
+```typescript
+export async function GET(request: NextRequest) {
+  const publicKey = verifyJwt(request);
+  if (!publicKey) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  // publicKey is the authenticated Stellar account
+}
+```
+
+### Step 7: stellar.toml Entry
+
+Add to your `/.well-known/stellar.toml`:
+```toml
+WEB_AUTH_ENDPOINT="https://yourdomain.com/api/auth/challenge"
+SIGNING_KEY="G..."   # SERVER_KEYPAIR public key
+```
+
+### Reference
+
+- Full spec: [SEP-10](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md)
+- Related: SEP-24 (hosted deposit/withdraw), SEP-31 (cross-border payments)
+
+### Next Steps
+
+- Use the JWT from `authenticate()` in fetch headers for all protected API calls
+- `stellar-nextjs-wallet` — hook the auth flow into the wallet connect button

package/src/stellar-skills/4-implementation/stellar-setup-environment/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: stellar-setup-environment
+description: 'Set up a complete local Stellar development environment including the Docker quickstart bundle, Stellar CLI, Rust toolchain, and SDK installation. Use when the user wants to set up their local Stellar development environment.'
+---
+
+# Set Up Stellar Development Environment
+
+## Purpose
+
+Configure a fully working local Stellar development environment for Soroban and Classic Stellar development.
+
+## On Activation
+
+Load `{network_preference}` and `{primary_language}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+## Workflow
+
+### Step 1: Detect Current State
+
+Run `stellar doctor` if already installed:
+
+```bash
+stellar doctor
+```
+
+Report what's installed and what's missing. If everything is green, skip to the verification step.
+
+### Step 2: Install Rust (for Soroban)
+
+```bash
+# Install Rust via rustup
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Add the WASM compile target
+rustup target add wasm32-unknown-unknown
+
+# Verify
+rustc --version
+cargo --version
+```
+
+### Step 3: Install Stellar CLI
+
+```bash
+# Install via cargo (recommended — always gets latest stable)
+cargo install --locked stellar-cli --features opt
+
+# Verify installation
+stellar --version
+
+# Diagnose environment
+stellar doctor
+```
+
+### Step 4: Install Docker (for Local Network)
+
+**macOS:** Install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get update
+sudo apt-get install docker-ce docker-ce-cli containerd.io
+sudo usermod -aG docker $USER  # run without sudo
+```
+
+Verify: `docker --version`
+
+### Step 5: Start Local Stellar Network
+
+**Option A: Stellar CLI (recommended)**
+```bash
+stellar network container start local
+```
+
+**Option B: Docker directly**
+```bash
+docker run --rm -it \
+  -p 8000:8000 \
+  --name stellar \
+  stellar/quickstart:testing \
+  --local \
+  --enable-stellar-rpc
+```
+
+The quickstart bundle includes:
+- **Stellar Core** — validates and applies transactions
+- **Horizon** — REST API at `http://localhost:8000`
+- **Stellar RPC** — contract invocation at `http://localhost:8000/soroban/rpc`
+- **Friendbot** — testnet faucet at `http://localhost:8000/friendbot`
+
+Verify: `curl http://localhost:8000/`
+
+### Step 6: Configure Stellar CLI Networks
+
+```bash
+# Add local network
+stellar network add local \
+  --rpc-url http://localhost:8000/soroban/rpc \
+  --network-passphrase "Standalone Network ; February 2017"
+
+# Testnet is pre-configured, but you can add it explicitly:
+stellar network add testnet \
+  --rpc-url https://soroban-testnet.stellar.org \
+  --network-passphrase "Test SDF Network ; September 2015"
+```
+
+### Step 7: Create Development Keypairs
+
+```bash
+# Generate a new keypair and fund it
+stellar keys generate dev-account --network local
+stellar keys fund dev-account --network local
+
+# View the address
+stellar keys address dev-account
+```
+
+### Step 8: Install JS/TS SDK (if applicable)
+
+```bash
+npm install @stellar/stellar-sdk
+# or
+yarn add @stellar/stellar-sdk
+# or
+bun add @stellar/stellar-sdk
+```
+
+### Step 9: Install Python SDK (if applicable)
+
+```bash
+pip install stellar-sdk
+```
+
+### Step 8b: Install TypeScript Wallet SDK (optional)
+
+```bash
+yarn add @stellar/typescript-wallet-sdk
+```
+
+### Step 10: End-to-End Verification
+
+Deploy the hello-world contract to local network:
+
+```bash
+stellar contract init hello-world
+cd hello-world
+stellar contract build
+stellar contract deploy \
+  --wasm target/wasm32-unknown-unknown/release/hello_world.wasm \
+  --source dev-account \
+  --network local
+stellar contract invoke \
+  --id {contract_id} \
+  --source dev-account \
+  --network local \
+  -- hello --to World
+```
+
+Expected output: `["Hello, World!"]`
+
+### Step 11: Document Setup
+
+Save environment details to `{project-root}/_stellar-output/project-knowledge/environment-guide.md`.

package/src/stellar-skills/4-implementation/stellar-setup-trustline/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: stellar-setup-trustline
+description: 'Set up trustlines for custom Stellar assets, handle authorization for regulated assets, and manage trustline limits. Use when the user needs to configure an account to hold a custom Stellar asset.'
+---
+
+# Set Up Trustline
+
+## Purpose
+
+Configure trustlines so accounts can hold and receive custom Stellar assets.
+
+## On Activation
+
+Load `{network_preference}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+## Concepts
+
+- A **trustline** is an explicit opt-in by an account to hold a specific custom asset.
+- The account must maintain enough XLM to cover the **base reserve** (0.5 XLM per trustline).
+- If the issuing account has `AUTH_REQUIRED` set, the issuer must separately authorize each trustline.
+
+## Workflow
+
+### Step 1: Gather Information
+
+Collect from user:
+- Asset code and issuer public key (e.g., `USDC:GABCDE...`)
+- Account that needs the trustline
+- Trust limit (or leave blank for maximum: `922337203685.4775807`)
+- Does the asset have `AUTH_REQUIRED`? (check via Horizon: `GET /accounts/{issuer}`)
+
+### Step 2: Check Account Balance
+
+```typescript
+const account = await server.loadAccount(accountPublicKey);
+const xlmBalance = account.balances.find(b => b.asset_type === 'native');
+console.log('XLM balance:', xlmBalance?.balance);
+// Ensure at least 0.5 XLM above minimum reserve
+```
+
+### Step 3: Create Trustline
+
+```typescript
+const asset = new StellarSDK.Asset(assetCode, issuerPublicKey);
+
+const tx = new StellarSDK.TransactionBuilder(account, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.changeTrust({
+      asset,
+      limit: '1000000', // omit for maximum limit
+    })
+  )
+  .setTimeout(30)
+  .build();
+
+tx.sign(accountKeypair);
+await server.submitTransaction(tx);
+```
+
+### Step 4: Authorize Trustline (AUTH_REQUIRED Assets)
+
+If the asset has `AUTH_REQUIRED`, the issuer must authorize each new trustline:
+
+```typescript
+const issuerAccount = await server.loadAccount(issuerPublicKey);
+
+const authTx = new StellarSDK.TransactionBuilder(issuerAccount, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.setTrustLineFlags({
+      trustor: accountPublicKey,
+      asset,
+      flags: {
+        authorized: true,
+        authorizedToMaintainLiabilities: false,
+      },
+    })
+  )
+  .setTimeout(30)
+  .build();
+
+authTx.sign(issuerKeypair);
+await server.submitTransaction(authTx);
+```
+
+### Step 5: Verify
+
+```typescript
+const updatedAccount = await server.loadAccount(accountPublicKey);
+const trustline = updatedAccount.balances.find(
+  b => b.asset_code === assetCode && b.asset_issuer === issuerPublicKey
+);
+console.log('Trustline:', trustline);
+// { balance: '0.0000000', limit: '1000000.0000000', is_authorized: true }
+```
+
+### Step 6: Remove Trustline (if needed)
+
+```typescript
+// Set limit to '0' to remove — only works if balance is zero
+StellarSDK.Operation.changeTrust({ asset, limit: '0' })
+```

package/src/stellar-skills/4-implementation/stellar-test-contract/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: stellar-test-contract
+description: 'Write and run comprehensive Soroban contract tests using the Rust test harness and soroban_sdk testutils. Use when the user wants to test a Soroban smart contract.'
+---
+
+# Test Soroban Contract
+
+## Purpose
+
+Achieve comprehensive contract coverage using the Soroban Rust test framework.
+
+## On Activation
+
+Load config from `{project-root}/_stellar/stellar/config.yaml`.
+
+## Core Testing Patterns
+
+### Test Environment Setup
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use soroban_sdk::{testutils::Address as _, Address, Env};
+
+    fn setup() -> (Env, Address, MyContractClient<'static>) {
+        let env = Env::default();
+        env.mock_all_auths();
+        let contract_id = env.register(MyContract, ());
+        let client = MyContractClient::new(&env, &contract_id);
+        let admin = Address::generate(&env);
+        (env, admin, client)
+    }
+
+    #[test]
+    fn test_initialize_sets_admin() {
+        let (env, admin, client) = setup();
+        client.initialize(&admin);
+        assert_eq!(client.get_admin(), admin);
+    }
+}
+```
+
+### Authorization Testing
+
+```rust
+#[test]
+fn test_transfer_requires_from_auth() {
+    let env = Env::default();
+    env.mock_all_auths();
+    let contract_id = env.register(MyContract, ());
+    let client = MyContractClient::new(&env, &contract_id);
+    let from = Address::generate(&env);
+    let to = Address::generate(&env);
+
+    client.transfer(&from, &to, &100i128);
+
+    // Verify the authorization was required
+    assert_auth!(env, from, contract_id, "transfer");
+}
+```
+
+### Error Path Testing
+
+```rust
+#[test]
+fn test_withdraw_fails_when_insufficient_balance() {
+    let (env, admin, client) = setup();
+    client.initialize(&admin);
+    let user = Address::generate(&env);
+
+    let result = client.try_withdraw(&user, &1000i128);
+    assert_eq!(result, Err(Ok(ContractError::InsufficientBalance)));
+}
+```
+
+### Event Testing
+
+```rust
+#[test]
+fn test_deposit_emits_event() {
+    let (env, admin, client) = setup();
+    client.initialize(&admin);
+    let user = Address::generate(&env);
+
+    client.deposit(&user, &500i128);
+
+    let events = env.events().all();
+    assert_eq!(events.len(), 1);
+    // Assert event data matches expected values
+}
+```
+
+### Storage Expiration Testing
+
+```rust
+#[test]
+fn test_persistent_storage_survives_archival() {
+    let env = Env::default();
+    env.mock_all_auths();
+    let contract_id = env.register(MyContract, ());
+    let client = MyContractClient::new(&env, &contract_id);
+
+    // Simulate ledger advancement
+    env.ledger().with_mut(|l| {
+        l.sequence_number += 100_000;
+        l.timestamp += 100_000;
+    });
+
+    // Persistent data should still be accessible
+    let balance = client.get_balance(&Address::generate(&env));
+    assert_eq!(balance, 0i128);
+}
+```
+
+## Workflow
+
+### Step 1: Identify Test Cases
+
+For each contract function, enumerate:
+- Happy path (valid inputs, expected output)
+- Authorization failures (wrong signer, missing auth)
+- Input validation failures (negative amount, zero, overflow)
+- State-dependent failures (already initialized, not initialized, paused)
+- Edge cases (max values, empty collections)
+
+### Step 2: Implement Tests
+
+Write one test per scenario. Test names must describe expected behavior:
+`test_deposit_fails_when_paused` — not `test_deposit_2`.
+
+### Step 3: Run Tests
+
+```bash
+cargo test
+cargo test -- --nocapture  # for event/log debugging
+cargo test test_deposit     # run specific test
+```
+
+### Step 4: Coverage Review
+
+Walk through each storage key and each event emission — confirm a test exercises each path.
+
+### Step 5: Next Steps
+
+After tests pass, proceed to `stellar-deploy-contract` for testnet deployment.