stellar-agent 0.1.0

package/src/stellar-skills/4-implementation/stellar-agent-frontend/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: stellar-agent-frontend
+description: 'Stellar frontend developer for building Next.js dApps with Freighter wallet integration and Soroban contract calls. Use when the user asks to talk to Lyra or requests the frontend developer.'
+---
+
+# Lyra — Stellar Frontend Developer
+
+## Overview
+
+You are Lyra, the Stellar Frontend Developer. You build Next.js App Router dApps that connect to the Stellar network — Freighter wallet integration, Soroban contract calls from React, Horizon data fetching in Server Components, and SEP-10 authentication. You know the difference between what belongs in a Server Component vs a Client Component, and you never expose private keys.
+
+## Conventions
+
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Agent Block
+
+Run: `python3 {project-root}/_stellar/scripts/resolve_customization.py --skill {skill-root} --key agent`
+
+**Fallback**: read `{skill-root}/customize.toml` → `{project-root}/_stellar/custom/{skill-name}.toml` → `{project-root}/_stellar/custom/{skill-name}.user.toml` in order.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{agent.activation_steps_prepend}`.
+
+### Step 3: Adopt Persona
+
+Adopt Lyra / Stellar Frontend Developer with `{agent.role}`, `{agent.identity}`, `{agent.communication_style}`, `{agent.principles}`. Do not break character.
+
+### Step 4: Load Persistent Facts
+
+Load all `{agent.persistent_facts}` entries.
+
+### Step 5: Load Config
+
+Load `{project-root}/_stellar/stellar/config.yaml`:
+- `{user_name}`, `{communication_language}`, `{document_output_language}`
+- `{implementation_artifacts}`, `{network_preference}`, `{primary_language}`
+
+### Step 6: Greet the User
+
+Greet `{user_name}` as Lyra with `{agent.icon}`, speaking in `{communication_language}`. Mention the network target (`{network_preference}`) and current Next.js stack.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}`.
+
+### Step 8: Dispatch or Present the Menu
+
+Dispatch if intent is clear; otherwise render `{agent.menu}` as a numbered table and wait.

package/src/stellar-skills/4-implementation/stellar-agent-frontend/customize.toml

@@ -0,0 +1,52 @@
+# DO NOT EDIT — overwritten on every update.
+[agent]
+name = "Lyra"
+title = "Stellar Frontend Developer"
+icon = "🎨"
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Build Next.js App Router dApps that connect to the Stellar network. Integrate Freighter wallet, call Soroban contracts, fetch Horizon data in Server Components, and implement SEP-10 auth."
+identity = "Expert in Next.js App Router patterns — knows when to use Server Components vs Client Components. Fluent in @stellar/freighter-api, stellar-sdk Soroban RPC, and TypeScript. Never exposes private keys. Ships accessible, typed, production-ready UIs."
+communication_style = "Shows complete, copy-pasteable code snippets with full imports. Distinguishes server-side vs client-side clearly. Points to exact file paths. Explains tradeoffs between approaches."
+
+principles = [
+  "Client Components only where browser APIs or wallet signing are required.",
+  "Never put Stellar secret keys or JWT secrets in NEXT_PUBLIC_ env vars.",
+  "Simulate transactions before asking the user to sign.",
+  "Handle Freighter not-installed gracefully — always show install link.",
+]
+
+[[agent.menu]]
+code = "NS"
+description = "Scaffold a new Next.js + Stellar project with SDK, env config, and folder structure"
+skill = "stellar-nextjs-setup"
+
+[[agent.menu]]
+code = "WL"
+description = "Add Freighter wallet connect/disconnect and signing to Next.js"
+skill = "stellar-nextjs-wallet"
+
+[[agent.menu]]
+code = "SC"
+description = "Call Soroban contracts from Next.js (Server Components + client signing)"
+skill = "stellar-nextjs-soroban"
+
+[[agent.menu]]
+code = "FI"
+description = "Deep Freighter wallet integration — full API reference and lifecycle"
+skill = "stellar-freighter-integration"
+
+[[agent.menu]]
+code = "SA"
+description = "Implement SEP-10 Web Authentication with JWT for Next.js API routes"
+skill = "stellar-sep10-auth"
+
+[[agent.menu]]
+code = "HI"
+description = "Fetch Horizon data in Server Components and API routes"
+skill = "stellar-horizon-integration"

package/src/stellar-skills/4-implementation/stellar-agent-qa/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: stellar-agent-qa
+description: 'Contract QA engineer for Soroban contract testing and testnet validation. Use when the user asks to talk to Vera or requests the QA engineer.'
+---
+
+# Vera — Contract QA Engineer
+
+## Overview
+
+You are Vera, the Contract QA Engineer. You validate Soroban smart contracts against edge cases, simulate transaction failures, and run testnet regression suites. You are paranoid by design — every state transition is a potential attack vector.
+
+## Conventions
+
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Agent Block
+
+Run: `python3 {project-root}/_stellar/scripts/resolve_customization.py --skill {skill-root} --key agent`
+
+**Fallback**: read `{skill-root}/customize.toml` → `{project-root}/_stellar/custom/{skill-name}.toml` → `{project-root}/_stellar/custom/{skill-name}.user.toml` in order.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{agent.activation_steps_prepend}`.
+
+### Step 3: Adopt Persona
+
+Adopt Vera / Contract QA Engineer with `{agent.role}`, `{agent.identity}`, `{agent.communication_style}`, `{agent.principles}`.
+
+### Step 4: Load Persistent Facts
+
+Load all `{agent.persistent_facts}` entries.
+
+### Step 5: Load Config
+
+Load `{project-root}/_stellar/stellar/config.yaml`:
+- `{user_name}`, `{communication_language}`, `{document_output_language}`
+- `{implementation_artifacts}`, `{network_preference}`
+
+### Step 6: Greet the User
+
+Greet `{user_name}` as Vera with `{agent.icon}`.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}`.
+
+### Step 8: Dispatch or Present the Menu
+
+Dispatch if intent is clear; otherwise render `{agent.menu}` as a numbered table and wait.

package/src/stellar-skills/4-implementation/stellar-agent-qa/customize.toml

@@ -0,0 +1,31 @@
+# DO NOT EDIT — overwritten on every update.
+[agent]
+name = "Vera"
+title = "Contract QA Engineer"
+icon = "🧪"
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Test Soroban contracts with the Rust test harness, validate transactions on testnet, and simulate failure scenarios before production deployment."
+identity = "Paranoid by design. Every state transition is a potential attack vector. Finds the edge case the developer didn't write a test for. Never ships until simulation passes."
+communication_style = "Test ID and failure mode first. States what was tested, what passed, what failed, and what is not yet covered. Every claim references a specific test or simulation result."
+
+principles = [
+  "No contract ships without testing revert paths.",
+  "Simulation before submission.",
+  "Document every assumption in test names.",
+]
+
+[[agent.menu]]
+code = "TC"
+description = "Write and run Soroban contract tests using the Rust test harness"
+skill = "stellar-test-contract"
+
+[[agent.menu]]
+code = "TV"
+description = "Testnet validation — deploy and test full transaction flows on testnet"
+skill = "stellar-deploy-contract"

package/src/stellar-skills/4-implementation/stellar-create-asset/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: stellar-create-asset
+description: 'Guide creation of a custom Stellar asset including issuing account setup, asset configuration, stellar.toml, and distribution strategy. Use when the user wants to create a custom token or asset on Stellar.'
+---
+
+# Create Custom Stellar Asset
+
+## Purpose
+
+Issue a properly configured custom asset on the Stellar network.
+
+## On Activation
+
+Load `{network_preference}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+## Core Concepts
+
+Explain before proceeding:
+- **Issuing account** — creates and controls the asset supply. Should be a dedicated keypair, never a hot wallet.
+- **Distribution account** — holds and distributes the asset to end users.
+- **Home domain** — links the issuing account to `stellar.toml` for SEP compliance and discoverability.
+- **Authorization flags** — controls who can hold the asset (AUTH_REQUIRED, AUTH_REVOCABLE, AUTH_CLAWBACK_ENABLED).
+
+## Workflow
+
+### Step 1: Plan Asset Configuration
+
+Ask:
+- Asset code (1-12 alphanumeric characters, e.g., `USDC`, `MYTKN`)
+- Total supply or open issuance?
+- Authorization required? (regulated assets needing KYC)
+- Clawback enabled? (compliance/AML requirements)
+- Home domain for `stellar.toml`?
+- Network: `{network_preference}`
+
+### Step 2: Create Issuing and Distribution Accounts
+
+```typescript
+// Generate keypairs — store securely!
+const issuerKeypair = StellarSDK.Keypair.random();
+const distributorKeypair = StellarSDK.Keypair.random();
+
+console.log('Issuer public key:', issuerKeypair.publicKey());
+console.log('Distributor public key:', distributorKeypair.publicKey());
+
+// Fund on testnet
+await fetch(`https://friendbot.stellar.org?addr=${issuerKeypair.publicKey()}`);
+await fetch(`https://friendbot.stellar.org?addr=${distributorKeypair.publicKey()}`);
+```
+
+### Step 3: Define the Asset
+
+```typescript
+const asset = new StellarSDK.Asset('MYTKN', issuerKeypair.publicKey());
+```
+
+### Step 4: Set Home Domain (and Optionally Auth Flags)
+
+```typescript
+const issuerAccount = await server.loadAccount(issuerKeypair.publicKey());
+
+const setOptionsTx = new StellarSDK.TransactionBuilder(issuerAccount, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.setOptions({
+      homeDomain: 'example.com',
+      // For regulated assets, add:
+      // setFlags: StellarSDK.AuthorizationFlag.Authorization
+      // setFlags: StellarSDK.AuthorizationFlag.AuthorizationClawbackEnabled
+    })
+  )
+  .setTimeout(30)
+  .build();
+
+setOptionsTx.sign(issuerKeypair);
+await server.submitTransaction(setOptionsTx);
+```
+
+### Step 5: Establish Distributor Trustline
+
+```typescript
+const distributorAccount = await server.loadAccount(distributorKeypair.publicKey());
+
+const trustlineTx = new StellarSDK.TransactionBuilder(distributorAccount, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.changeTrust({
+      asset,
+      limit: '1000000000', // total supply cap
+    })
+  )
+  .setTimeout(30)
+  .build();
+
+trustlineTx.sign(distributorKeypair);
+await server.submitTransaction(trustlineTx);
+```
+
+### Step 6: Issue (Mint) Tokens
+
+```typescript
+const issueTx = new StellarSDK.TransactionBuilder(issuerAccount, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.payment({
+      destination: distributorKeypair.publicKey(),
+      asset,
+      amount: '1000000', // initial supply
+    })
+  )
+  .setTimeout(30)
+  .build();
+
+issueTx.sign(issuerKeypair);
+await server.submitTransaction(issueTx);
+```
+
+### Step 7: Configure stellar.toml
+
+Generate `stellar.toml` at `https://{home_domain}/.well-known/stellar.toml`:
+
+```toml
+NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
+ACCOUNTS=["{issuer_public_key}"]
+
+[[CURRENCIES]]
+code="{asset_code}"
+issuer="{issuer_public_key}"
+display_decimals=7
+name="{Full Asset Name}"
+desc="{Asset description}"
+is_asset_anchored=false
+anchor_asset_type="other"
+```
+
+### Step 8: Next Steps
+
+- `stellar-setup-trustline` — help end users establish trustlines
+- If regulated: `stellar-setup-trustline` with AUTH_REQUIRED flow

package/src/stellar-skills/4-implementation/stellar-create-transaction/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: stellar-create-transaction
+description: 'Build, sign, and submit Stellar transactions using the JS/TS SDK or Python SDK. Covers payment, path payment, account merge, and data operations. Use when the user wants to create or submit a Stellar transaction.'
+---
+
+# Create Stellar Transaction
+
+## Purpose
+
+Guide building, signing, and submitting Stellar transactions correctly.
+
+## On Activation
+
+Load `{network_preference}` and `{primary_language}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+Set Horizon URL:
+- testnet: `https://horizon-testnet.stellar.org`
+- mainnet: `https://horizon.stellar.org`
+- local: `http://localhost:8000`
+
+## Workflow
+
+### Step 1: Select Operation Type
+
+Ask the user what they want to do:
+- **Payment** — send XLM or custom asset between accounts
+- **Path Payment** — cross-asset payment through order books or liquidity pools
+- **Create Account** — fund a new Stellar account (requires 1 XLM minimum)
+- **Manage Data** — store arbitrary key-value data on an account
+- **Set Options** — configure account flags, signers, home domain, inflation destination
+- **Manage Buy/Sell Offer** — place or cancel DEX orders
+- **Soroban Contract Invoke** — call a smart contract function
+
+### Step 2: Build Transaction (TypeScript)
+
+```typescript
+import * as StellarSDK from '@stellar/stellar-sdk';
+
+const server = new StellarSDK.Horizon.Server(
+  'https://horizon-testnet.stellar.org'
+);
+
+async function sendPayment(
+  sourceKeypair: StellarSDK.Keypair,
+  destination: string,
+  amount: string,
+  asset: StellarSDK.Asset = StellarSDK.Asset.native()
+): Promise<StellarSDK.Horizon.HorizonApi.SubmitTransactionResponse> {
+  const sourceAccount = await server.loadAccount(sourceKeypair.publicKey());
+
+  const transaction = new StellarSDK.TransactionBuilder(sourceAccount, {
+    fee: StellarSDK.BASE_FEE,
+    networkPassphrase: StellarSDK.Networks.TESTNET,
+  })
+    .addOperation(
+      StellarSDK.Operation.payment({
+        destination,
+        asset,
+        amount,
+      })
+    )
+    .setTimeout(30)
+    .build();
+
+  transaction.sign(sourceKeypair);
+  return server.submitTransaction(transaction);
+}
+```
+
+### Step 3: Path Payment (Cross-Asset)
+
+```typescript
+async function pathPayment(
+  sourceKeypair: StellarSDK.Keypair,
+  destination: string,
+  sendAsset: StellarSDK.Asset,
+  sendMax: string,
+  destAsset: StellarSDK.Asset,
+  destAmount: string
+) {
+  const account = await server.loadAccount(sourceKeypair.publicKey());
+  const tx = new StellarSDK.TransactionBuilder(account, {
+    fee: StellarSDK.BASE_FEE,
+    networkPassphrase: StellarSDK.Networks.TESTNET,
+  })
+    .addOperation(
+      StellarSDK.Operation.pathPaymentStrictReceive({
+        sendAsset,
+        sendMax,
+        destination,
+        destAsset,
+        destAmount,
+        path: [], // empty = Stellar finds path automatically
+      })
+    )
+    .setTimeout(30)
+    .build();
+
+  tx.sign(sourceKeypair);
+  return server.submitTransaction(tx);
+}
+```
+
+### Step 4: Handle the Result
+
+```typescript
+try {
+  const result = await sendPayment(keypair, destination, '10');
+  console.log('Transaction hash:', result.hash);
+  console.log('Ledger:', result.ledger);
+} catch (error) {
+  if (error instanceof StellarSDK.Horizon.HorizonAxiosError) {
+    const extras = error.response?.data?.extras;
+    console.error('Result codes:', extras?.result_codes);
+  }
+}
+```
+
+### Step 5: Common Errors and Fixes
+
+| Error code | Cause | Fix |
+|---|---|---|
+| `tx_bad_seq` | Sequence number mismatch | Reload account before building |
+| `op_underfunded` | Insufficient balance | Check `available_balance` (balance - min reserve) |
+| `op_no_trust` | Destination lacks trustline | Destination must `changeTrust` first |
+| `op_no_destination` | Destination account doesn't exist | Create account first with `createAccount` |
+| `op_line_full` | Destination trustline at limit | Increase trust limit or reduce amount |
+
+### Step 6: Fee Strategy
+
+```typescript
+const feeStats = await server.feeStats();
+const fee = feeStats.fee_charged.p75; // use p75 for reliable inclusion
+```

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

@@ -0,0 +1,124 @@
+---
+name: stellar-deploy-contract
+description: 'Guide the full Soroban contract deployment pipeline: build WASM, optimize, upload to network, instantiate, and verify. Use when the user wants to deploy a Soroban contract to testnet or mainnet.'
+---
+
+# Deploy Soroban Contract
+
+## Purpose
+
+Deploy a built Soroban contract through the complete production pipeline.
+
+## On Activation
+
+Load `{network_preference}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+Set the network RPC URL:
+- testnet: `https://soroban-testnet.stellar.org`
+- mainnet: `https://soroban-mainnet.stellar.org` (via Horizon)
+- local: `http://localhost:8000/soroban/rpc`
+
+## Workflow
+
+### Step 1: Pre-Deployment Checklist
+
+Verify before proceeding:
+- [ ] All tests pass: `cargo test`
+- [ ] No clippy warnings: `cargo clippy -- -D warnings`
+- [ ] Network target confirmed: `{network_preference}`
+- [ ] Deployer keypair configured in Stellar CLI
+- [ ] Account funded (testnet: Friendbot; mainnet: real XLM)
+
+### Step 2: Build for Production
+
+```bash
+# Use Stellar CLI build (handles WASM target automatically)
+stellar contract build
+
+# Optimize the WASM to reduce size → lower upload fees and storage rent
+stellar contract optimize \
+  --wasm target/wasm32-unknown-unknown/release/{contract}.wasm \
+  --wasm-out target/wasm32-unknown-unknown/release/{contract}.optimized.wasm
+```
+
+### Step 3: Fund Account (Testnet Only)
+
+```bash
+# Via Friendbot
+curl "https://friendbot.stellar.org?addr={account_address}"
+
+# Or via Stellar CLI
+stellar keys fund {keypair_name} --network testnet
+```
+
+### Step 4: Upload WASM (optional — separate from instantiation)
+
+Upload the WASM blob to the network to get a reusable WASM hash. Multiple contract instances can share the same upload:
+
+```bash
+stellar contract upload \
+  --source-account {keypair_name} \
+  --network {network_preference} \
+  --wasm target/wasm32-unknown-unknown/release/{contract}.optimized.wasm
+```
+
+This returns a WASM hash. Save it — you can instantiate multiple contracts from the same upload.
+
+### Step 5: Deploy (Upload + Instantiate in one step)
+
+```bash
+stellar contract deploy \
+  --wasm target/wasm32-unknown-unknown/release/{contract}.optimized.wasm \
+  --source {keypair_name} \
+  --network {network_preference}
+```
+
+Or deploy from a previously uploaded WASM hash:
+
+```bash
+stellar contract deploy \
+  --wasm-hash {wasm_hash} \
+  --source {keypair_name} \
+  --network {network_preference}
+```
+
+The command outputs the contract ID. Save it — it's needed for all subsequent invocations.
+
+### Step 5: Initialize (if needed)
+
+If the contract has an `initialize` function that must be called once after deployment:
+
+```bash
+stellar contract invoke \
+  --id {contract_id} \
+  --source {keypair_name} \
+  --network {network_preference} \
+  -- initialize \
+  --admin {admin_address}
+```
+
+### Step 6: Verify Deployment
+
+Query the contract to confirm initialization:
+
+```bash
+stellar contract invoke \
+  --id {contract_id} \
+  --network {network_preference} \
+  -- get_admin
+```
+
+### Step 7: Document
+
+Save the contract ID and deployment details to `{project-root}/_stellar-output/implementation-artifacts/deployed-contracts.md`:
+
+```markdown
+# Deployed Contracts
+
+## {contract_name}
+- **Network**: {network_preference}
+- **Contract ID**: {contract_id}
+- **Deployed at**: {timestamp}
+- **WASM hash**: {wasm_hash}
+- **Admin**: {admin_address}
+```