stellar-agent 0.1.0

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

@@ -0,0 +1,198 @@
+---
+name: stellar-nextjs-setup
+description: 'Scaffold a Next.js App Router project with Stellar SDK, environment configuration, and network setup. Use when the user wants to build a Stellar dApp frontend with Next.js.'
+---
+
+# Next.js + Stellar dApp Setup
+
+## Purpose
+
+Bootstrap a production-ready Next.js App Router project wired up to the Stellar network.
+
+## On Activation
+
+Load `{network_preference}` and `{project_name}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+## Workflow
+
+### Step 1: Create Next.js Project
+
+```bash
+npx create-next-app@latest {project_name} \
+  --typescript \
+  --tailwind \
+  --eslint \
+  --app \
+  --src-dir \
+  --import-alias "@/*"
+cd {project_name}
+```
+
+### Step 2: Install Stellar Dependencies
+
+```bash
+npm install stellar-sdk @stellar/freighter-api bignumber.js
+```
+
+For the TypeScript Wallet SDK (higher-level wallet operations):
+```bash
+npm install @stellar/typescript-wallet-sdk
+```
+
+### Step 3: Configure Environment Variables
+
+Create `.env.local`:
+
+```env
+# Network
+NEXT_PUBLIC_STELLAR_NETWORK=testnet
+NEXT_PUBLIC_HORIZON_URL=https://horizon-testnet.stellar.org
+NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+NEXT_PUBLIC_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
+
+# Contract IDs (fill in after deployment)
+NEXT_PUBLIC_CONTRACT_ID=
+
+# For mainnet, override:
+# NEXT_PUBLIC_STELLAR_NETWORK=mainnet
+# NEXT_PUBLIC_HORIZON_URL=https://horizon.stellar.org
+# NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-mainnet.stellar.org
+# NEXT_PUBLIC_NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"
+```
+
+Create `.env.local.example` (commit this, not `.env.local`):
+```env
+NEXT_PUBLIC_STELLAR_NETWORK=testnet
+NEXT_PUBLIC_HORIZON_URL=https://horizon-testnet.stellar.org
+NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+NEXT_PUBLIC_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
+NEXT_PUBLIC_CONTRACT_ID=
+```
+
+Add to `.gitignore`:
+```
+.env.local
+.env.*.local
+```
+
+### Step 4: Create Network Config Module
+
+`src/lib/stellar/config.ts`:
+
+```typescript
+export const NETWORK = process.env.NEXT_PUBLIC_STELLAR_NETWORK || 'testnet';
+export const HORIZON_URL = process.env.NEXT_PUBLIC_HORIZON_URL!;
+export const STELLAR_RPC_URL = process.env.NEXT_PUBLIC_STELLAR_RPC_URL!;
+export const NETWORK_PASSPHRASE = process.env.NEXT_PUBLIC_NETWORK_PASSPHRASE!;
+export const CONTRACT_ID = process.env.NEXT_PUBLIC_CONTRACT_ID!;
+
+export function isMainnet() {
+  return NETWORK === 'mainnet';
+}
+```
+
+### Step 5: Create Horizon Server Instance
+
+`src/lib/stellar/horizon.ts`:
+
+```typescript
+import { Horizon } from 'stellar-sdk';
+import { HORIZON_URL } from './config';
+
+export const horizonServer = new Horizon.Server(HORIZON_URL, {
+  allowHttp: HORIZON_URL.startsWith('http://'), // allow for local dev
+});
+```
+
+### Step 6: Create Soroban RPC Client
+
+`src/lib/stellar/soroban.ts`:
+
+```typescript
+import { SorobanRpc } from 'stellar-sdk';
+import { STELLAR_RPC_URL } from './config';
+
+export const rpcServer = new SorobanRpc.Server(STELLAR_RPC_URL, {
+  allowHttp: STELLAR_RPC_URL.startsWith('http://'),
+});
+```
+
+### Step 7: Project Structure
+
+Recommended folder layout:
+
+```
+src/
+  app/
+    page.tsx              # home page
+    layout.tsx            # root layout with providers
+    globals.css
+  components/
+    stellar/
+      WalletButton.tsx    # connect/disconnect Freighter
+      AccountBalance.tsx  # display XLM and token balances
+      TransactionStatus.tsx
+  lib/
+    stellar/
+      config.ts           # network config
+      horizon.ts          # Horizon server
+      soroban.ts          # Soroban RPC client
+      utils.ts            # shared helpers (stroops ↔ XLM, etc.)
+  hooks/
+    useFreighter.ts       # wallet state hook
+    useAccount.ts         # account data from Horizon
+  types/
+    stellar.ts            # shared TypeScript types
+```
+
+### Step 8: Utility Helpers
+
+`src/lib/stellar/utils.ts`:
+
+```typescript
+import BigNumber from 'bignumber.js';
+
+// Convert stroops (integer) to XLM (decimal string)
+export function stroopsToXlm(stroops: string | number): string {
+  return new BigNumber(stroops).dividedBy(1e7).toFixed(7);
+}
+
+// Convert XLM to stroops
+export function xlmToStroops(xlm: string | number): string {
+  return new BigNumber(xlm).multipliedBy(1e7).integerValue().toFixed();
+}
+
+// Shorten a Stellar public key for display
+export function shortenKey(key: string, chars = 4): string {
+  return `${key.slice(0, chars + 1)}...${key.slice(-chars)}`;
+}
+```
+
+### Step 9: TypeScript Types
+
+`src/types/stellar.ts`:
+
+```typescript
+export type StellarNetwork = 'testnet' | 'mainnet' | 'local';
+
+export interface AccountInfo {
+  publicKey: string;
+  balances: {
+    asset: string;
+    balance: string;
+  }[];
+}
+
+export interface ContractInvokeResult {
+  success: boolean;
+  value?: unknown;
+  error?: string;
+  txHash?: string;
+}
+```
+
+### Next Steps
+
+- `stellar-nextjs-wallet` — add Freighter wallet connect/disconnect
+- `stellar-nextjs-soroban` — call Soroban contracts from Next.js
+- `stellar-nextjs-horizon` via `stellar-horizon-integration` — fetch account and transaction data

package/src/stellar-skills/4-implementation/stellar-nextjs-soroban/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: stellar-nextjs-soroban
+description: 'Call Soroban smart contracts from a Next.js App Router project using Server Actions, API routes, and client-side invocation with Freighter signing. Use when the user wants to invoke Soroban contracts from their Next.js Stellar dApp.'
+---
+
+# Next.js + Soroban Contract Integration
+
+## Purpose
+
+Connect a Next.js App Router frontend to deployed Soroban contracts — covering read-only queries (Server Components / API routes) and signed mutations (client-side with Freighter).
+
+## On Activation
+
+Load `{network_preference}` and `{primary_language}` from `{project-root}/_stellar/stellar/config.yaml`. Confirm `stellar-nextjs-setup` and `stellar-nextjs-wallet` are complete.
+
+## Key Distinction
+
+| Operation | Where to run | Why |
+|---|---|---|
+| Read-only query (no auth) | Server Component or API route | No wallet needed; can cache |
+| Write / mutation | Client Component (needs Freighter) | Must sign with user's key |
+
+## Workflow
+
+### Step 1: Generate TypeScript Bindings (Recommended)
+
+If the contract has an interface, generate typed bindings:
+
+```bash
+stellar contract bindings typescript \
+  --network {network_preference} \
+  --id {contract_id} \
+  --output-dir src/lib/stellar/contracts/{contract_name}
+```
+
+This generates a fully-typed client — use it instead of raw `SorobanRpc` calls.
+
+### Step 2: Read-Only Query in a Server Component
+
+```tsx
+// src/app/dashboard/page.tsx  (Server Component — no "use client")
+import { SorobanRpc, Contract, scValToNative, xdr } from 'stellar-sdk';
+import { rpcServer } from '@/lib/stellar/soroban';
+import { CONTRACT_ID, NETWORK_PASSPHRASE } from '@/lib/stellar/config';
+
+async function getContractState(): Promise<number> {
+  const contract = new Contract(CONTRACT_ID);
+  const tx = contract.call('get_count'); // no-auth view function
+
+  const simResult = await rpcServer.simulateTransaction(tx as any);
+  if (SorobanRpc.Api.isSimulationError(simResult)) {
+    throw new Error(simResult.error);
+  }
+
+  const returnVal = (simResult as SorobanRpc.Api.SimulateTransactionSuccessResponse)
+    .result?.retval;
+  return returnVal ? (scValToNative(returnVal) as number) : 0;
+}
+
+export default async function DashboardPage() {
+  const count = await getContractState();
+  return <div>Count: {count}</div>;
+}
+```
+
+### Step 3: Read-Only Query via API Route (for client-side use)
+
+`src/app/api/contract/count/route.ts`:
+
+```typescript
+import { NextResponse } from 'next/server';
+import { SorobanRpc, Contract, scValToNative } from 'stellar-sdk';
+import { rpcServer } from '@/lib/stellar/soroban';
+import { CONTRACT_ID } from '@/lib/stellar/config';
+
+export async function GET() {
+  try {
+    const contract = new Contract(CONTRACT_ID);
+    const tx = contract.call('get_count');
+    const simResult = await rpcServer.simulateTransaction(tx as any);
+
+    if (SorobanRpc.Api.isSimulationError(simResult)) {
+      return NextResponse.json({ error: simResult.error }, { status: 500 });
+    }
+
+    const retval = (simResult as SorobanRpc.Api.SimulateTransactionSuccessResponse)
+      .result?.retval;
+    const count = retval ? scValToNative(retval) : 0;
+    return NextResponse.json({ count });
+  } catch (err) {
+    return NextResponse.json({ error: String(err) }, { status: 500 });
+  }
+}
+```
+
+### Step 4: Signed Contract Call (Client Component)
+
+For functions that require auth (user must sign with Freighter):
+
+`src/components/stellar/IncrementButton.tsx`:
+
+```tsx
+"use client";
+
+import { useState } from 'react';
+import {
+  SorobanRpc,
+  TransactionBuilder,
+  Contract,
+  Networks,
+  nativeToScVal,
+} from 'stellar-sdk';
+import { rpcServer } from '@/lib/stellar/soroban';
+import { horizonServer } from '@/lib/stellar/horizon';
+import { useWallet } from '@/contexts/WalletContext';
+import { CONTRACT_ID, NETWORK_PASSPHRASE } from '@/lib/stellar/config';
+
+export function IncrementButton() {
+  const { publicKey, sign, connected } = useWallet();
+  const [status, setStatus] = useState<string>('');
+
+  async function handleIncrement() {
+    if (!publicKey) return;
+    setStatus('Building transaction...');
+
+    try {
+      // 1. Load account from Horizon for sequence number
+      const account = await horizonServer.loadAccount(publicKey);
+
+      // 2. Build the contract call transaction
+      const contract = new Contract(CONTRACT_ID);
+      const tx = new TransactionBuilder(account, {
+        fee: '100',
+        networkPassphrase: NETWORK_PASSPHRASE,
+      })
+        .addOperation(contract.call('increment'))
+        .setTimeout(30)
+        .build();
+
+      // 3. Simulate to get auth + resource estimates
+      setStatus('Simulating...');
+      const simResult = await rpcServer.simulateTransaction(tx);
+      if (SorobanRpc.Api.isSimulationError(simResult)) {
+        throw new Error(simResult.error);
+      }
+
+      // 4. Assemble (inject auth + footprint from simulation)
+      const preparedTx = SorobanRpc.assembleTransaction(tx, simResult).build();
+
+      // 5. Sign with Freighter
+      setStatus('Waiting for signature...');
+      const signedXdr = await sign(preparedTx.toXDR());
+      const signedTx = TransactionBuilder.fromXDR(signedXdr, NETWORK_PASSPHRASE);
+
+      // 6. Submit
+      setStatus('Submitting...');
+      const sendResult = await rpcServer.sendTransaction(signedTx);
+      if (sendResult.status === 'ERROR') {
+        throw new Error(sendResult.errorResult?.toString());
+      }
+
+      // 7. Poll for confirmation
+      let getResult = await rpcServer.getTransaction(sendResult.hash);
+      while (getResult.status === SorobanRpc.Api.GetTransactionStatus.NOT_FOUND) {
+        await new Promise(r => setTimeout(r, 1000));
+        getResult = await rpcServer.getTransaction(sendResult.hash);
+      }
+
+      if (getResult.status === SorobanRpc.Api.GetTransactionStatus.SUCCESS) {
+        setStatus(`Done! Tx: ${sendResult.hash.slice(0, 8)}...`);
+      } else {
+        throw new Error('Transaction failed');
+      }
+    } catch (err) {
+      setStatus(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  if (!connected) return <p>Connect wallet to interact with contract</p>;
+
+  return (
+    <div>
+      <button onClick={handleIncrement} className="btn btn-primary">
+        Increment
+      </button>
+      {status && <p className="text-sm mt-2">{status}</p>}
+    </div>
+  );
+}
+```
+
+### Step 5: Working with ScVal Types
+
+Common conversions between JavaScript values and Soroban's `xdr.ScVal`:
+
+```typescript
+import { nativeToScVal, scValToNative, xdr } from 'stellar-sdk';
+
+// JS → ScVal
+nativeToScVal(42, { type: 'u32' })           // u32
+nativeToScVal('hello')                        // string/symbol
+nativeToScVal(publicKey, { type: 'address' }) // Address
+nativeToScVal(true)                           // bool
+
+// ScVal → JS
+const value = scValToNative(scVal); // auto-detects type
+```
+
+### Step 6: Fee Strategy
+
+```typescript
+const feeStats = await horizonServer.feeStats();
+const fee = feeStats.fee_charged.p75; // p75 for reliable inclusion
+```
+
+### Step 7: Error Handling
+
+| Scenario | Check |
+|---|---|
+| Simulation failed | `SorobanRpc.Api.isSimulationError(result)` |
+| Contract panic / `Error::` | `simResult.error` string contains contract error name |
+| Transaction not found after submit | Poll `getTransaction` with timeout |
+| Auth required but not provided | Contract returns auth error — check contract ABI |
+
+### Next Steps
+
+- `stellar-test-contract` — write Rust tests before wiring up the frontend
+- `stellar-sep10-auth` — add JWT auth for API routes that need user identity

package/src/stellar-skills/4-implementation/stellar-nextjs-wallet/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: stellar-nextjs-wallet
+description: 'Integrate Freighter wallet into a Next.js App Router project with connect/disconnect, signing, and account state management. Use when the user wants wallet functionality in their Next.js Stellar dApp.'
+---
+
+# Next.js Wallet Integration (Freighter)
+
+## Purpose
+
+Add Freighter wallet connect/disconnect, account state, and transaction signing to a Next.js App Router project.
+
+## On Activation
+
+Load `{network_preference}` from `{project-root}/_stellar/stellar/config.yaml`. Verify `@stellar/freighter-api` is installed.
+
+## Core Concept
+
+Freighter is a browser extension. All Freighter API calls must run **client-side only** (inside `"use client"` components or hooks). Never call Freighter APIs in Server Components or server-side code.
+
+## Workflow
+
+### Step 1: Install Freighter API
+
+```bash
+npm install @stellar/freighter-api
+```
+
+### Step 2: Wallet State Hook
+
+`src/hooks/useFreighter.ts`:
+
+```typescript
+"use client";
+
+import { useState, useEffect, useCallback } from 'react';
+import {
+  isConnected,
+  getPublicKey,
+  signTransaction,
+  setAllowed,
+  isAllowed,
+  getNetworkDetails,
+} from '@stellar/freighter-api';
+import { NETWORK_PASSPHRASE, NETWORK } from '@/lib/stellar/config';
+
+interface FreighterState {
+  connected: boolean;
+  publicKey: string | null;
+  loading: boolean;
+  error: string | null;
+}
+
+export function useFreighter() {
+  const [state, setState] = useState<FreighterState>({
+    connected: false,
+    publicKey: null,
+    loading: true,
+    error: null,
+  });
+
+  // Check connection on mount
+  useEffect(() => {
+    async function checkConnection() {
+      try {
+        const connected = await isConnected();
+        if (connected) {
+          const allowed = await isAllowed();
+          if (allowed) {
+            const publicKey = await getPublicKey();
+            setState({ connected: true, publicKey, loading: false, error: null });
+            return;
+          }
+        }
+        setState(s => ({ ...s, connected: false, publicKey: null, loading: false }));
+      } catch {
+        setState(s => ({ ...s, loading: false, error: 'Freighter not installed' }));
+      }
+    }
+    checkConnection();
+  }, []);
+
+  const connect = useCallback(async () => {
+    setState(s => ({ ...s, loading: true, error: null }));
+    try {
+      await setAllowed();
+      const publicKey = await getPublicKey();
+
+      // Verify network matches
+      const networkDetails = await getNetworkDetails();
+      if (networkDetails.networkPassphrase !== NETWORK_PASSPHRASE) {
+        throw new Error(
+          `Switch Freighter to ${NETWORK}. Current: ${networkDetails.networkName}`
+        );
+      }
+
+      setState({ connected: true, publicKey, loading: false, error: null });
+    } catch (err) {
+      setState(s => ({
+        ...s,
+        loading: false,
+        error: err instanceof Error ? err.message : 'Connection failed',
+      }));
+    }
+  }, []);
+
+  const disconnect = useCallback(() => {
+    setState({ connected: false, publicKey: null, loading: false, error: null });
+  }, []);
+
+  const sign = useCallback(
+    async (xdr: string): Promise<string> => {
+      if (!state.publicKey) throw new Error('Wallet not connected');
+      const result = await signTransaction(xdr, {
+        accountToSign: state.publicKey,
+        networkPassphrase: NETWORK_PASSPHRASE,
+      });
+      return result;
+    },
+    [state.publicKey]
+  );
+
+  return { ...state, connect, disconnect, sign };
+}
+```
+
+### Step 3: Wallet Button Component
+
+`src/components/stellar/WalletButton.tsx`:
+
+```tsx
+"use client";
+
+import { useFreighter } from '@/hooks/useFreighter';
+import { shortenKey } from '@/lib/stellar/utils';
+
+export function WalletButton() {
+  const { connected, publicKey, loading, error, connect, disconnect } = useFreighter();
+
+  if (loading) {
+    return <button disabled className="btn btn-ghost">Loading...</button>;
+  }
+
+  if (error) {
+    return (
+      <button
+        onClick={() => window.open('https://www.freighter.app/', '_blank')}
+        className="btn btn-error btn-sm"
+      >
+        Install Freighter
+      </button>
+    );
+  }
+
+  if (connected && publicKey) {
+    return (
+      <div className="flex items-center gap-2">
+        <span className="font-mono text-sm">{shortenKey(publicKey)}</span>
+        <button onClick={disconnect} className="btn btn-outline btn-sm">
+          Disconnect
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <button onClick={connect} className="btn btn-primary">
+      Connect Wallet
+    </button>
+  );
+}
+```
+
+### Step 4: Root Layout with Wallet Context (optional)
+
+For apps that need wallet state across many components, add a React Context:
+
+`src/contexts/WalletContext.tsx`:
+
+```tsx
+"use client";
+
+import { createContext, useContext, ReactNode } from 'react';
+import { useFreighter } from '@/hooks/useFreighter';
+
+type WalletContextType = ReturnType<typeof useFreighter>;
+const WalletContext = createContext<WalletContextType | null>(null);
+
+export function WalletProvider({ children }: { children: ReactNode }) {
+  const wallet = useFreighter();
+  return (
+    <WalletContext.Provider value={wallet}>{children}</WalletContext.Provider>
+  );
+}
+
+export function useWallet() {
+  const ctx = useContext(WalletContext);
+  if (!ctx) throw new Error('useWallet must be used inside WalletProvider');
+  return ctx;
+}
+```
+
+Wire into `src/app/layout.tsx`:
+```tsx
+import { WalletProvider } from '@/contexts/WalletContext';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <WalletProvider>
+          {children}
+        </WalletProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Step 5: Signing and Submitting a Transaction
+
+Pattern for client components that need to send a transaction:
+
+```tsx
+"use client";
+
+import { TransactionBuilder, Networks, Operation, Asset } from 'stellar-sdk';
+import { horizonServer } from '@/lib/stellar/horizon';
+import { useWallet } from '@/contexts/WalletContext';
+import { NETWORK_PASSPHRASE } from '@/lib/stellar/config';
+
+export function SendPaymentForm() {
+  const { publicKey, sign, connected } = useWallet();
+
+  async function handleSend(destination: string, amount: string) {
+    if (!publicKey) return;
+
+    const account = await horizonServer.loadAccount(publicKey);
+    const tx = new TransactionBuilder(account, {
+      fee: '100',
+      networkPassphrase: NETWORK_PASSPHRASE,
+    })
+      .addOperation(
+        Operation.payment({
+          destination,
+          asset: Asset.native(),
+          amount,
+        })
+      )
+      .setTimeout(30)
+      .build();
+
+    const signedXdr = await sign(tx.toXDR());
+    const signedTx = TransactionBuilder.fromXDR(signedXdr, NETWORK_PASSPHRASE);
+    const result = await horizonServer.submitTransaction(signedTx);
+    console.log('Submitted:', result.hash);
+  }
+
+  if (!connected) return <p>Connect wallet first</p>;
+  // ... render form
+}
+```
+
+### Step 6: Edge Cases to Handle
+
+| Case | Handling |
+|---|---|
+| Freighter not installed | Show "Install Freighter" link to `freighter.app` |
+| Wrong network selected | Check `networkPassphrase` on connect; show error |
+| User rejects transaction | Catch error from `signTransaction`, show toast |
+| Account not funded | Catch `400` from Horizon submit, check `result_codes` |
+| Freighter locked | `getPublicKey()` throws — prompt user to unlock |
+
+### Next Steps
+
+- `stellar-nextjs-soroban` — call Soroban contracts using the connected wallet
+- `stellar-sep10-auth` — add SEP-10 JWT auth for backend calls