stellar-agent 0.1.0

package/src/stellar-skills/4-implementation/stellar-freighter-integration/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: stellar-freighter-integration
+description: 'Deep Freighter wallet integration covering installation, connection lifecycle, network verification, transaction signing, and blob signing. Use when the user needs to integrate the Freighter browser wallet into their Stellar dApp.'
+---
+
+# Freighter Wallet Integration
+
+## Purpose
+
+Wire up the Freighter browser extension wallet for full dApp authentication, transaction signing, and network management.
+
+## On Activation
+
+Load `{network_preference}` and `{primary_language}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+## Installation
+
+```bash
+npm install @stellar/freighter-api bignumber.js stellar-sdk
+```
+
+## Core API Reference
+
+| Function | Purpose |
+|---|---|
+| `isConnected()` | Check if Freighter extension is installed |
+| `isAllowed()` | Check if dApp has permission to access Freighter |
+| `setAllowed()` | Request dApp permission (shows Freighter popup) |
+| `getPublicKey()` | Get the active account's public key |
+| `getNetworkDetails()` | Get current network info (passphrase, URL) |
+| `signTransaction(xdr, opts)` | Sign a transaction XDR |
+| `signBlob(blob, opts)` | Sign arbitrary data (for SEP-10) |
+| `addToken(opts)` | Add a Soroban token to Freighter's asset list |
+
+## Workflow
+
+### Step 1: Detect Freighter Installation
+
+```typescript
+import { isConnected } from '@stellar/freighter-api';
+
+async function detectFreighter(): Promise<boolean> {
+  try {
+    return await isConnected();
+  } catch {
+    return false; // extension not installed
+  }
+}
+```
+
+If not installed, direct the user to `https://www.freighter.app/`.
+
+### Step 2: Connection Lifecycle
+
+```typescript
+import { isConnected, isAllowed, setAllowed, getPublicKey, getNetworkDetails } from '@stellar/freighter-api';
+
+interface WalletConnection {
+  publicKey: string;
+  network: string;
+  networkPassphrase: string;
+  networkUrl: string;
+}
+
+async function connectWallet(expectedPassphrase: string): Promise<WalletConnection> {
+  const installed = await isConnected();
+  if (!installed) throw new Error('Freighter not installed');
+
+  // Request permission if not already granted
+  const allowed = await isAllowed();
+  if (!allowed) {
+    await setAllowed(); // shows Freighter popup
+  }
+
+  const publicKey = await getPublicKey();
+  const networkDetails = await getNetworkDetails();
+
+  // Verify user is on the correct network
+  if (networkDetails.networkPassphrase !== expectedPassphrase) {
+    throw new Error(
+      `Wrong network. Expected ${expectedPassphrase}, ` +
+      `got ${networkDetails.networkPassphrase}. ` +
+      `Please switch networks in Freighter.`
+    );
+  }
+
+  return {
+    publicKey,
+    network: networkDetails.network,
+    networkPassphrase: networkDetails.networkPassphrase,
+    networkUrl: networkDetails.networkUrl,
+  };
+}
+```
+
+### Step 3: Sign a Transaction
+
+```typescript
+import { signTransaction } from '@stellar/freighter-api';
+import { TransactionBuilder } from 'stellar-sdk';
+
+async function signWithFreighter(
+  txXdr: string,
+  publicKey: string,
+  networkPassphrase: string
+): Promise<string> {
+  // Returns signed XDR string
+  const signedXdr = await signTransaction(txXdr, {
+    accountToSign: publicKey,     // ensure correct account signs
+    networkPassphrase,
+  });
+  return signedXdr;
+}
+
+// Reconstruct the signed Transaction object
+const signedTx = TransactionBuilder.fromXDR(signedXdr, networkPassphrase);
+```
+
+### Step 4: Sign a Blob (for SEP-10 / arbitrary data)
+
+```typescript
+import { signBlob } from '@stellar/freighter-api';
+
+async function signChallenge(
+  blob: string, // base64-encoded bytes
+  publicKey: string
+): Promise<string> {
+  const result = await signBlob(blob, { accountToSign: publicKey });
+  return result; // base64-encoded signature
+}
+```
+
+### Step 5: Add a Soroban Token to Freighter
+
+After deploying a Soroban token contract, register it in the user's Freighter asset list:
+
+```typescript
+import { addToken } from '@stellar/freighter-api';
+
+await addToken({
+  contractId: 'C...', // contract ID on the network
+  network: 'TESTNET', // 'TESTNET' | 'PUBLIC'
+});
+```
+
+### Step 6: Handle Common Errors
+
+| Error message | Cause | Fix |
+|---|---|---|
+| `"Freighter is not connected"` | Extension not installed | Show install link |
+| `"User declined"` | User rejected the popup | Show retry button |
+| `"Wrong network"` | Mismatch between dApp and Freighter | Prompt user to switch network in extension |
+| `"Could not retrieve account"` | Freighter is locked | Prompt user to unlock Freighter |
+| `signTransaction` throws | User rejected signing | Catch and show error toast |
+
+### Step 7: Network Passphrases Reference
+
+```typescript
+const PASSPHRASES = {
+  mainnet: 'Public Global Stellar Network ; September 2015',
+  testnet: 'Test SDF Network ; September 2015',
+  futurenet: 'Test SDF Future Network ; October 2022',
+  // local standalone:
+  local: 'Standalone Network ; February 2017',
+};
+```
+
+### Step 8: Vanilla JS Integration (non-framework)
+
+```html
+<script type="module">
+import {
+  isConnected, setAllowed, getPublicKey, signTransaction
+} from 'https://unpkg.com/@stellar/freighter-api@latest/src/index.js';
+
+document.getElementById('connect-btn').addEventListener('click', async () => {
+  const installed = await isConnected();
+  if (!installed) {
+    alert('Please install Freighter from freighter.app');
+    return;
+  }
+  await setAllowed();
+  const key = await getPublicKey();
+  document.getElementById('wallet-display').textContent = key.slice(0, 8) + '...';
+});
+</script>
+```
+
+### Next Steps
+
+- `stellar-nextjs-wallet` — wrap this in a Next.js hook and context
+- `stellar-sep10-auth` — use `signBlob` for SEP-10 web authentication
+- `stellar-create-transaction` — build the transactions to sign

package/src/stellar-skills/4-implementation/stellar-horizon-integration/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: stellar-horizon-integration
+description: 'Integrate with the Stellar Horizon REST API for account queries, transaction streaming, order book data, and fee estimation. Use when the user needs to interact with Stellar Horizon or stream network data.'
+---
+
+# Stellar Horizon Integration
+
+## Purpose
+
+Guide Horizon API integration for data-intensive Stellar dApp features.
+
+## On Activation
+
+Load `{network_preference}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+Set Horizon URL based on network:
+- `testnet` → `https://horizon-testnet.stellar.org`
+- `mainnet` → `https://horizon.stellar.org`
+- `local` → `http://localhost:8000`
+
+## Core Patterns
+
+### SDK Setup
+
+```typescript
+import * as StellarSDK from '@stellar/stellar-sdk';
+
+const server = new StellarSDK.Horizon.Server(
+  'https://horizon-testnet.stellar.org'
+);
+```
+
+### Account Data
+
+```typescript
+const account = await server.loadAccount(publicKey);
+// Returns: balances, sequence, flags, signers, data, home_domain
+
+// Find a specific balance
+const usdcBalance = account.balances.find(
+  b => b.asset_code === 'USDC' && b.asset_issuer === issuerPublicKey
+);
+console.log('USDC balance:', usdcBalance?.balance);
+```
+
+### Transaction History
+
+```typescript
+const transactions = await server
+  .transactions()
+  .forAccount(publicKey)
+  .limit(20)
+  .order('desc')
+  .call();
+
+for (const tx of transactions.records) {
+  console.log(tx.hash, tx.created_at, tx.successful);
+}
+```
+
+### Real-Time Transaction Streaming (Server-Sent Events)
+
+```typescript
+let eventSource: EventSource | null = null;
+
+function startStream(publicKey: string) {
+  eventSource = server
+    .transactions()
+    .forAccount(publicKey)
+    .cursor('now')
+    .stream({
+      onmessage: (tx) => {
+        console.log('New transaction:', tx.hash);
+        // Update UI state here
+      },
+      onerror: (err) => {
+        console.error('Stream error:', err);
+        // Reconnect after delay
+        setTimeout(() => startStream(publicKey), 5000);
+      },
+    });
+}
+
+function stopStream() {
+  eventSource?.();  // close function returned by stream()
+}
+```
+
+### Payment History
+
+```typescript
+const payments = await server
+  .payments()
+  .forAccount(publicKey)
+  .limit(10)
+  .order('desc')
+  .call();
+
+for (const payment of payments.records) {
+  if (payment.type === 'payment') {
+    console.log(`${payment.from} → ${payment.to}: ${payment.amount} ${payment.asset_code || 'XLM'}`);
+  }
+}
+```
+
+### Order Book
+
+```typescript
+const orderBook = await server
+  .orderbook(
+    new StellarSDK.Asset('USD', issuerPublicKey),
+    StellarSDK.Asset.native()
+  )
+  .call();
+
+console.log('Bids:', orderBook.bids.slice(0, 5));
+console.log('Asks:', orderBook.asks.slice(0, 5));
+```
+
+### Fee Statistics
+
+```typescript
+const feeStats = await server.feeStats();
+
+// Use p75 for reliable inclusion without overpaying
+const recommendedFee = feeStats.fee_charged.p75;
+console.log('Recommended fee (stroops):', recommendedFee);
+// Convert to XLM: parseInt(recommendedFee) / 10_000_000
+```
+
+### Liquidity Pool Query
+
+```typescript
+const pool = await server
+  .liquidityPools()
+  .liquidityPoolId(poolId)
+  .call();
+
+console.log('Reserves:', pool.reserves);
+console.log('Total shares:', pool.total_shares);
+```
+
+## Workflow
+
+### Step 1: Identify Integration Needs
+
+Ask what data the dApp needs:
+- Account balances and flags
+- Transaction submission only
+- Real-time transaction streaming
+- Order book and trade data
+- Historical payment data
+
+### Step 2: Configure the Client
+
+```typescript
+// With retry logic for mainnet
+const server = new StellarSDK.Horizon.Server(
+  'https://horizon.stellar.org',
+  { allowHttp: false }
+);
+```
+
+### Step 3: Implement Data Layer
+
+Build typed wrapper functions around Horizon calls with proper error handling:
+
+```typescript
+async function getAccountBalance(publicKey: string, assetCode: string, issuer: string): Promise<string> {
+  try {
+    const account = await server.loadAccount(publicKey);
+    const balance = account.balances.find(
+      b => 'asset_code' in b && b.asset_code === assetCode && b.asset_issuer === issuer
+    );
+    return balance?.balance ?? '0';
+  } catch (error) {
+    if (error instanceof StellarSDK.NotFoundError) return '0';
+    throw error;
+  }
+}
+```
+
+### Step 4: Handle Pagination
+
+```typescript
+// Fetch all records across pages
+async function fetchAll<T>(
+  builder: StellarSDK.Horizon.CallBuilder<StellarSDK.Horizon.ServerApi.CollectionPage<T>>
+): Promise<T[]> {
+  const records: T[] = [];
+  let page = await builder.call();
+  while (page.records.length > 0) {
+    records.push(...page.records);
+    page = await page.next();
+  }
+  return records;
+}
+```

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

@@ -0,0 +1,102 @@
+---
+name: stellar-init-contract
+description: 'Initialize a new Soroban smart contract project with correct Rust workspace structure, Cargo.toml configuration, and hello-world contract scaffold. Use when the user wants to start a new Soroban contract.'
+---
+
+# Initialize Soroban Contract
+
+## Purpose
+
+Scaffold a complete Soroban smart contract project ready for development.
+
+## On Activation
+
+Load config from `{project-root}/_stellar/stellar/config.yaml` and resolve `{network_preference}` and `{primary_language}`.
+
+## Workflow
+
+### Step 1: Gather Context
+
+Ask the user:
+- Contract name (kebab-case, becomes the Rust crate name)
+- Contract purpose in one sentence
+- Network target: confirm `{network_preference}` or override
+- Standalone contract or part of a multi-contract workspace?
+
+### Step 2: Prerequisites Check
+
+Verify the user has the Stellar CLI and Rust toolchain installed:
+
+```bash
+stellar --version
+cargo --version
+rustup target list --installed | grep wasm32-unknown-unknown
+```
+
+If missing, direct them to `stellar-setup-environment` first.
+
+### Step 3: Initialize the Contract
+
+```bash
+stellar contract init {contract_name}
+```
+
+This creates:
+```
+{contract_name}/
+  Cargo.toml          # crate manifest with soroban-sdk dependency
+  src/
+    lib.rs            # contract entrypoint
+  Makefile            # build/test shortcuts
+```
+
+Explain each file's role and each macro in `lib.rs`:
+- `#[contract]` — marks the struct as a Soroban contract
+- `#[contractimpl]` — marks the implementation block with contract functions
+- `#[contracttype]` — derives Soroban storage encoding for custom types
+
+### Step 4: Multi-Contract Workspace (if applicable)
+
+Show how to set up a Cargo workspace with a root `Cargo.toml`:
+
+```toml
+[workspace]
+members = [
+  "contracts/contract-a",
+  "contracts/contract-b",
+]
+resolver = "2"
+```
+
+And per-contract `Cargo.toml`:
+
+```toml
+[package]
+name = "{contract_name}"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+soroban-sdk = { version = "22", features = ["testutils"] }
+
+[dev-dependencies]
+soroban-sdk = { version = "22", features = ["testutils"] }
+```
+
+### Step 5: Verify Setup
+
+```bash
+cd {contract_name}
+cargo build --target wasm32-unknown-unknown --release
+```
+
+A successful build produces `target/wasm32-unknown-unknown/release/{contract_name}.wasm`.
+
+### Step 6: Next Steps
+
+Suggest:
+- `stellar-write-contract` — implement the contract logic
+- `stellar-test-contract` — write tests before implementing

package/src/stellar-skills/4-implementation/stellar-liquidity-pool/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: stellar-liquidity-pool
+description: 'Create and interact with Stellar AMM liquidity pools including deposit, withdrawal, and swap operations through the DEX. Use when the user wants to work with Stellar liquidity pools or the Stellar DEX.'
+---
+
+# Stellar Liquidity Pool
+
+## Purpose
+
+Guide creation and interaction with Stellar's built-in AMM liquidity pools.
+
+## On Activation
+
+Load `{network_preference}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+## Core Concepts
+
+- Stellar uses a **constant-product AMM** (`x * y = k`) for liquidity pools.
+- Pool IDs are **deterministic** from the asset pair — compute them, don't guess.
+- The fee is **0.3%** per swap (fee parameter = 30 in basis points / 100).
+- Liquidity positions are represented as **Liquidity Pool Share assets**.
+- Both assets in the pool must be sorted lexicographically (the SDK handles this).
+
+## Workflow
+
+### Step 1: Determine Operation
+
+Ask the user:
+- Create a new pool and provide initial liquidity?
+- Deposit into an existing pool?
+- Withdraw from a pool?
+- Swap via a pool (path payment)?
+
+### Step 2: Compute Pool ID
+
+Assets in a pool must be sorted lexicographically. Use `Asset.compare()` to ensure correct ordering:
+
+```typescript
+const rawA = new StellarSDK.Asset('USD', issuerPublicKey);
+const rawB = StellarSDK.Asset.native(); // XLM
+
+// Always sort — pool ID depends on asset order
+const [assetA, assetB] = StellarSDK.Asset.compare(rawA, rawB) <= 0
+  ? [rawA, rawB]
+  : [rawB, rawA];
+
+const liquidityPoolId = StellarSDK.getLiquidityPoolId(
+  'constant_product',
+  {
+    assetA,
+    assetB,
+    fee: StellarSDK.LiquidityPoolFeeV18,  // 30 (0.3%)
+  }
+);
+console.log('Pool ID:', liquidityPoolId);
+```
+
+### Step 3: Create Pool Share Trustline
+
+Before depositing, establish a trustline for the pool share asset:
+
+```typescript
+const poolShareAsset = new StellarSDK.LiquidityPoolAsset(assetA, assetB, 30);
+
+const account = await server.loadAccount(providerPublicKey);
+const tx = new StellarSDK.TransactionBuilder(account, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.changeTrust({ asset: poolShareAsset })
+  )
+  .setTimeout(30)
+  .build();
+
+tx.sign(providerKeypair);
+await server.submitTransaction(tx);
+```
+
+### Step 4: Deposit Liquidity
+
+```typescript
+const depositTx = new StellarSDK.TransactionBuilder(account, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.liquidityPoolDeposit({
+      liquidityPoolId,
+      maxAmountA: '1000',    // max of assetA to deposit
+      maxAmountB: '1000',    // max of assetB to deposit
+      minPrice: { n: 1, d: 2 },  // min price ratio A/B (0.5)
+      maxPrice: { n: 2, d: 1 },  // max price ratio A/B (2.0)
+    })
+  )
+  .setTimeout(30)
+  .build();
+
+depositTx.sign(providerKeypair);
+await server.submitTransaction(depositTx);
+```
+
+The `minPrice`/`maxPrice` protect against front-running by bounding the accepted deposit ratio.
+
+### Step 5: Withdraw Liquidity
+
+```typescript
+const withdrawTx = new StellarSDK.TransactionBuilder(account, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.liquidityPoolWithdraw({
+      liquidityPoolId,
+      amount: '500',       // pool shares to burn
+      minAmountA: '400',   // minimum assetA to receive
+      minAmountB: '400',   // minimum assetB to receive
+    })
+  )
+  .setTimeout(30)
+  .build();
+
+withdrawTx.sign(providerKeypair);
+await server.submitTransaction(withdrawTx);
+```
+
+### Step 6: Swap via Pool (Path Payment)
+
+```typescript
+// Buy exactly 100 USD, paying at most 110 XLM
+const swapTx = new StellarSDK.TransactionBuilder(account, {
+  fee: StellarSDK.BASE_FEE,
+  networkPassphrase: StellarSDK.Networks.TESTNET,
+})
+  .addOperation(
+    StellarSDK.Operation.pathPaymentStrictReceive({
+      sendAsset: StellarSDK.Asset.native(),
+      sendMax: '110',
+      destination: accountPublicKey,
+      destAsset: assetA,
+      destAmount: '100',
+      path: [], // empty = Stellar automatically routes through pools
+    })
+  )
+  .setTimeout(30)
+  .build();
+```
+
+### Step 7: Query Pool State
+
+```typescript
+const pool = await server.liquidityPools().liquidityPoolId(liquidityPoolId).call();
+console.log('Reserves:', pool.reserves);
+console.log('Total shares:', pool.total_shares);
+console.log('Fee:', pool.fee_bp, 'basis points');
+```