@rebelfi/agent-sdk 1.0.1

package/README.md

@@ -0,0 +1,337 @@
+<h1 align="center">@rebelfi/agent-sdk</h1>
+
+<p align="center">
+  <strong>Give your AI agent a bank account on Solana. One command.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@rebelfi/agent-sdk"><img src="https://img.shields.io/npm/v/@rebelfi/agent-sdk" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@rebelfi/agent-sdk"><img src="https://img.shields.io/npm/dm/@rebelfi/agent-sdk" alt="npm downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
+  <a href="https://github.com/silkysquad/silk/stargazers"><img src="https://img.shields.io/github/stars/silkysquad/silk?style=social" alt="GitHub stars" /></a>
+</p>
+
+---
+
+TypeScript SDK and CLI for AI agent payments on Solana. Policy-controlled accounts with on-chain spending limits, time-locked escrow transfers, transaction verification, and conditional payment flows — for Claude, GPT, LangChain, and any autonomous agent.
+
+## Why This Exists
+
+Giving an agent a wallet keypair is like handing an employee an envelope of cash. It works, technically. But one hallucination, one prompt injection, one compromised dependency — and the entire balance is gone in a single transaction.
+
+Current mitigations are all inadequate:
+
+| Approach | Problem |
+|----------|---------|
+| Human-in-the-loop | Defeats the purpose of automation |
+| Rate limits in agent code | Not enforceable — the agent can be modified or bypassed |
+| Custodial APIs | You're trusting a third party with your funds |
+
+**The insight:** agent financial safety is an infrastructure problem, not an AI alignment problem.
+
+RebelFi replaces wallets with **policy-controlled accounts** — on-chain Solana programs that enforce spending rules at the protocol level. The chain itself rejects transactions that exceed limits. Not the agent's code. Not an API layer. Not a human reviewer.
+
+```
+Agent:   "Send $10,000 to some address"
+Chain:   Transaction rejected. Operator limit: $100/tx.
+```
+
+Prompt injection can't drain funds beyond policy limits. Hallucinating agents can't make catastrophic financial decisions. Compromised agent keys are damage-limited by policy. Humans set policies once, then trust the chain — not the agent.
+
+## Quick Start
+
+```bash
+npm install @rebelfi/agent-sdk
+
+# Initialize — creates a wallet and agent ID
+rebel init
+
+# Switch to devnet for testing
+rebel config set-cluster devnet
+
+# Fund your wallet (devnet only)
+rebel wallet fund --sol --usdc
+
+# Send your first payment
+rebel pay <recipient> 10 --memo "first payment"
+```
+
+That's it. Wallet created, funded, payment sent — under 2 minutes.
+
+## Features
+
+### Policy-Controlled Accounts
+
+Managed token accounts with operator delegation and per-transaction spending limits. Account owners (humans) set policies; agents operate within them.
+
+```bash
+# Discover your on-chain account
+rebel account sync
+
+# Check balance and policy info
+rebel account status
+# → Balance: 500.00 USDC | Policy: max $100.00/tx
+
+# Send within limits — works
+rebel account send <recipient> 50
+
+# Exceed limits — rejected on-chain
+rebel account send <recipient> 200
+# → REJECTED: amount $200.00 exceeds per-transaction limit of $100.00
+```
+
+### Escrow Payments
+
+Time-locked USDC transfers via the Handshake protocol. Sender deposits to escrow, recipient claims. Sender can cancel before claim.
+
+```bash
+rebel pay <recipient> 25 --memo "Invoice #42"
+rebel claim <transferPda>
+rebel cancel <transferPda>
+rebel payments list
+```
+
+### Transaction Verification
+
+Decode and analyze any Solana transaction before signing. Supports System, SPL Token, ATA, Compute Budget, Memo, Handshake, RebelSig, and Jupiter programs.
+
+```typescript
+import { analyzeTransaction, verifyIntent } from '@rebelfi/agent-sdk';
+
+// Human-readable breakdown of any transaction
+const analysis = await analyzeTransaction(txBase64);
+console.log(analysis.summary);
+// → "Handshake transfer of 100 USDC from Alice to Bob"
+
+// Verify a transaction matches your intent
+const result = await verifyIntent(txBase64, {
+  type: 'transfer_from_account',
+  owner: 'owner...',
+  recipient: 'recipient...',
+  amount: '50',
+  token: 'USDC',
+});
+
+if (!result.verified) {
+  console.error('Mismatch:', result.discrepancies);
+}
+```
+
+Risk flags are surfaced automatically:
+
+| Severity | Example |
+|----------|---------|
+| `error` | Unknown program in transaction |
+| `warning` | Fee payer differs from signer |
+| `info` | Priority fee set |
+
+### Cross-Chain Intent Framework
+
+Type-safe intent definitions with constraint support. Currently implements Solana, extensible to EVM chains.
+
+```typescript
+import type { SingleIntent } from '@rebelfi/agent-sdk';
+
+const swap: SingleIntent = {
+  chain: 'solana',
+  signer: 'agent...',
+  action: 'swap',
+  tokenIn: { tokenSymbol: 'USDC' },
+  tokenOut: { tokenSymbol: 'SOL' },
+  amountIn: { lte: '500' },    // constrained amounts
+  slippage: 0.5,
+};
+```
+
+Supported actions: `transfer`, `swap`, `stake`, `lend`, `borrow`, `approve`, `withdraw`, `custom`.
+
+### Conditional Flows
+
+Multi-step workflows with conditions, intents, and compute steps. Built-in templates for common patterns.
+
+```bash
+# Limit order: buy SOL when price drops below $120
+rebel flows create limit-order \
+  --sell "500 USDC" --buy SOL --price 120 \
+  --slippage 0.5 --expires 7d
+
+rebel flows list
+rebel flows evaluate    # run heartbeat
+```
+
+Conditions: `price_below`, `price_above`, `time_reached`, `balance_above`.
+
+### Contacts
+
+Local address book for named recipients.
+
+```bash
+rebel contacts add alice <address>
+rebel pay alice 10    # resolves by name
+```
+
+## How It Works
+
+```
+Your Agent (Claude, GPT, LangChain, CrewAI, custom)
+    │
+    ▼
+rebel CLI  /  @rebelfi/agent-sdk library
+    │
+    ├── Local wallet management (keys never leave your machine)
+    ├── Transaction verification (decode before signing)
+    ├── Intent matching and risk flagging
+    │
+    ▼
+RebelFi API (transaction builder)
+    │
+    ▼
+Solana
+    ├── Handshake — time-locked escrow transfers
+    └── RebelSig  — policy-controlled accounts with operator delegation
+```
+
+Private keys never leave the agent's machine. The API builds unsigned transactions; the SDK signs locally and submits.
+
+## Comparison
+
+| | rebel | Raw @solana/web3.js | Centralized Payment APIs |
+|---|---|---|---|
+| Spending limits | On-chain enforced per-tx | None | API-level (bypassable) |
+| Prompt injection safe | Chain rejects over-limit txs | Full key access, no limits | Trust the provider |
+| Escrow payments | Built-in (Handshake) | Build from scratch | Varies |
+| Self-custody | Yes, local keys | Yes | No |
+| Tx verification | Built-in decoder + risk flags | Manual parsing | N/A |
+| Time to first payment | 2 minutes | Hours | Minutes |
+| Open source | MIT | Yes | Usually no |
+
+## Use With AI Agents
+
+The SDK is designed for AI agent frameworks. Here's a typical integration pattern:
+
+```typescript
+import {
+  loadConfig,
+  getApiUrl,
+  getApiKey,
+  createHttpClient,
+  verifyIntent,
+} from '@rebelfi/agent-sdk';
+
+// In your Claude/GPT/LangChain tool handler
+async function handlePayment(recipient: string, amount: number, memo: string) {
+  const config = loadConfig();
+  const client = createHttpClient({
+    baseUrl: getApiUrl(config),
+    apiKey: getApiKey(config),
+  });
+
+  // Build, verify, sign, submit
+  // Policy-controlled — agent can't exceed human-set limits
+  const res = await client.post('/api/transfer/create', {
+    recipient,
+    amount,
+    memo,
+  });
+
+  // Verify the transaction matches your intent before signing
+  const check = await verifyIntent(res.data.transaction, {
+    type: 'create_transfer',
+    sender: config.wallets[0].address,
+    recipient,
+    amount: String(amount),
+    token: 'USDC',
+  });
+
+  if (!check.verified) throw new Error('Transaction mismatch');
+  return res.data;
+}
+```
+
+Works with **Claude** (tool use / MCP), **GPT** (function calling), **LangChain**, **CrewAI**, **AutoGPT**, and any framework that supports tool/function definitions.
+
+### MCP Integration
+
+The SDK can be exposed as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server, giving Claude, Cursor, and other AI coding tools direct access to payments, account management, and transaction verification as tools. Build your own MCP wrapper or check the docs for the reference implementation.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `rebel init` | Create wallet + agent ID |
+| `rebel auth register\|status\|revoke` | API key management |
+| `rebel wallet create\|list\|fund` | Wallet operations |
+| `rebel balance` | Check balances |
+| `rebel pay <to> <amount>` | Send USDC payment |
+| `rebel claim <pda>` | Claim a received payment |
+| `rebel cancel <pda>` | Cancel a sent payment |
+| `rebel payments list\|get` | Payment history |
+| `rebel account sync\|status\|events\|deposit\|withdraw\|send` | RebelSig account |
+| `rebel contacts add\|remove\|list\|get` | Address book |
+| `rebel flows create\|list\|get\|cancel\|evaluate` | Conditional flows |
+| `rebel config set-cluster\|get-cluster\|reset-cluster` | Configuration |
+| `rebel chat <message>` | Support chat |
+
+All commands support `--human` for human-readable output (default is JSON).
+
+## Library API
+
+```typescript
+import {
+  // Config & client
+  loadConfig, saveConfig, getWallet, getApiUrl, getApiKey,
+  createHttpClient,
+
+  // Contacts
+  loadContacts, addContact, resolveRecipient,
+
+  // Transaction verification (V1 — Solana)
+  analyzeTransaction, verifyIntent,
+
+  // Intent framework (V2 — cross-chain)
+  verifyIntent as verifyIntentV2,
+  evaluateConstraint,
+
+  // Flows
+  loadFlows, addFlow, executeHeartbeat, createLimitOrder,
+
+  // Errors
+  SdkError, toSdkError,
+} from '@rebelfi/agent-sdk';
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `REBEL_API_URL` | Override the API endpoint |
+| `REBEL_API_KEY` | Provide API key without local config |
+
+## Development
+
+```bash
+bun run build          # Dual ESM + CJS build
+bun run dev            # TypeScript watch mode
+bun run test           # Vitest (single run)
+bun run test:watch     # Vitest watch mode
+bun run clean          # Remove dist/
+```
+
+## Links
+
+- [Documentation](https://docs.silkyway.ai)
+- [GitHub Issues](https://github.com/silkysquad/silk/issues)
+- [npm](https://www.npmjs.com/package/@rebelfi/agent-sdk)
+- [Twitter](https://x.com/silkyway)
+
+---
+
+<p align="center">
+  If you find this useful, please consider giving it a star — it helps others discover the project.
+  <br /><br />
+  <a href="https://github.com/silkysquad/silk">Star on GitHub</a>
+</p>
+
+## License
+
+MIT

package/dist/amount-utils.d.ts

@@ -0,0 +1,9 @@
+export interface DecimalValue {
+    int: bigint;
+    scale: number;
+}
+export declare function parseDecimal(value: string | number): DecimalValue | null;
+export declare function compareDecimals(a: DecimalValue, b: DecimalValue): number;
+export declare function formatUnits(amount: bigint, decimals: number): string;
+export declare function withinRelativeTolerance(expected: DecimalValue, actual: DecimalValue, tolerance: DecimalValue): boolean;
+export declare function extractAmountFromHuman(amountHuman: string | undefined): string | null;

package/dist/amount-utils.js

@@ -0,0 +1,80 @@
+const DECIMAL_RE = /^-?\d+(?:\.\d+)?$/;
+export function parseDecimal(value) {
+    const input = String(value).trim();
+    if (!DECIMAL_RE.test(input)) {
+        return null;
+    }
+    const negative = input.startsWith('-');
+    const unsigned = negative ? input.slice(1) : input;
+    const [wholeRaw, fractionRaw = ''] = unsigned.split('.');
+    const whole = stripLeadingZeros(wholeRaw);
+    const fraction = stripTrailingZeros(fractionRaw);
+    const digits = `${whole}${fraction}`;
+    const int = BigInt(digits === '' ? '0' : digits) * (negative ? -1n : 1n);
+    return { int, scale: fraction.length };
+}
+export function compareDecimals(a, b) {
+    const scale = Math.max(a.scale, b.scale);
+    const aInt = scaleDecimal(a, scale);
+    const bInt = scaleDecimal(b, scale);
+    if (aInt === bInt)
+        return 0;
+    return aInt > bInt ? 1 : -1;
+}
+export function formatUnits(amount, decimals) {
+    if (decimals <= 0) {
+        return amount.toString();
+    }
+    const negative = amount < 0n;
+    const absAmount = negative ? -amount : amount;
+    const base = 10n ** BigInt(decimals);
+    const whole = absAmount / base;
+    const fraction = absAmount % base;
+    if (fraction === 0n) {
+        return `${negative ? '-' : ''}${whole.toString()}`;
+    }
+    const fractionStr = fraction.toString().padStart(decimals, '0').replace(/0+$/, '');
+    return `${negative ? '-' : ''}${whole.toString()}.${fractionStr}`;
+}
+export function withinRelativeTolerance(expected, actual, tolerance) {
+    if (tolerance.int < 0n)
+        return false;
+    const valueScale = Math.max(expected.scale, actual.scale);
+    const expectedInt = scaleDecimal(expected, valueScale);
+    const actualInt = scaleDecimal(actual, valueScale);
+    if (expectedInt === 0n) {
+        return actualInt === 0n;
+    }
+    const diff = abs(actualInt - expectedInt);
+    const tolDen = 10n ** BigInt(tolerance.scale);
+    const lhs = diff * tolDen;
+    const rhs = abs(expectedInt) * tolerance.int;
+    return lhs <= rhs;
+}
+export function extractAmountFromHuman(amountHuman) {
+    if (!amountHuman)
+        return null;
+    const [amount] = amountHuman.trim().split(/\s+/);
+    if (!amount || !DECIMAL_RE.test(amount)) {
+        return null;
+    }
+    return amount;
+}
+function scaleDecimal(value, targetScale) {
+    if (targetScale < value.scale) {
+        throw new Error('targetScale must be >= current scale');
+    }
+    const multiplier = 10n ** BigInt(targetScale - value.scale);
+    return value.int * multiplier;
+}
+function stripLeadingZeros(value) {
+    const stripped = value.replace(/^0+/, '');
+    return stripped === '' ? '0' : stripped;
+}
+function stripTrailingZeros(value) {
+    return value.replace(/0+$/, '');
+}
+function abs(value) {
+    return value < 0n ? -value : value;
+}
+//# sourceMappingURL=amount-utils.js.map

package/dist/amount-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount-utils.js","sourceRoot":"","sources":["../src/amount-utils.ts"],"names":[],"mappings":"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"}

package/dist/cjs/amount-utils.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDecimal = parseDecimal;
+exports.compareDecimals = compareDecimals;
+exports.formatUnits = formatUnits;
+exports.withinRelativeTolerance = withinRelativeTolerance;
+exports.extractAmountFromHuman = extractAmountFromHuman;
+const DECIMAL_RE = /^-?\d+(?:\.\d+)?$/;
+function parseDecimal(value) {
+    const input = String(value).trim();
+    if (!DECIMAL_RE.test(input)) {
+        return null;
+    }
+    const negative = input.startsWith('-');
+    const unsigned = negative ? input.slice(1) : input;
+    const [wholeRaw, fractionRaw = ''] = unsigned.split('.');
+    const whole = stripLeadingZeros(wholeRaw);
+    const fraction = stripTrailingZeros(fractionRaw);
+    const digits = `${whole}${fraction}`;
+    const int = BigInt(digits === '' ? '0' : digits) * (negative ? -1n : 1n);
+    return { int, scale: fraction.length };
+}
+function compareDecimals(a, b) {
+    const scale = Math.max(a.scale, b.scale);
+    const aInt = scaleDecimal(a, scale);
+    const bInt = scaleDecimal(b, scale);
+    if (aInt === bInt)
+        return 0;
+    return aInt > bInt ? 1 : -1;
+}
+function formatUnits(amount, decimals) {
+    if (decimals <= 0) {
+        return amount.toString();
+    }
+    const negative = amount < 0n;
+    const absAmount = negative ? -amount : amount;
+    const base = 10n ** BigInt(decimals);
+    const whole = absAmount / base;
+    const fraction = absAmount % base;
+    if (fraction === 0n) {
+        return `${negative ? '-' : ''}${whole.toString()}`;
+    }
+    const fractionStr = fraction.toString().padStart(decimals, '0').replace(/0+$/, '');
+    return `${negative ? '-' : ''}${whole.toString()}.${fractionStr}`;
+}
+function withinRelativeTolerance(expected, actual, tolerance) {
+    if (tolerance.int < 0n)
+        return false;
+    const valueScale = Math.max(expected.scale, actual.scale);
+    const expectedInt = scaleDecimal(expected, valueScale);
+    const actualInt = scaleDecimal(actual, valueScale);
+    if (expectedInt === 0n) {
+        return actualInt === 0n;
+    }
+    const diff = abs(actualInt - expectedInt);
+    const tolDen = 10n ** BigInt(tolerance.scale);
+    const lhs = diff * tolDen;
+    const rhs = abs(expectedInt) * tolerance.int;
+    return lhs <= rhs;
+}
+function extractAmountFromHuman(amountHuman) {
+    if (!amountHuman)
+        return null;
+    const [amount] = amountHuman.trim().split(/\s+/);
+    if (!amount || !DECIMAL_RE.test(amount)) {
+        return null;
+    }
+    return amount;
+}
+function scaleDecimal(value, targetScale) {
+    if (targetScale < value.scale) {
+        throw new Error('targetScale must be >= current scale');
+    }
+    const multiplier = 10n ** BigInt(targetScale - value.scale);
+    return value.int * multiplier;
+}
+function stripLeadingZeros(value) {
+    const stripped = value.replace(/^0+/, '');
+    return stripped === '' ? '0' : stripped;
+}
+function stripTrailingZeros(value) {
+    return value.replace(/0+$/, '');
+}
+function abs(value) {
+    return value < 0n ? -value : value;
+}
+//# sourceMappingURL=amount-utils.js.map

package/dist/cjs/amount-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount-utils.js","sourceRoot":"","sources":["../../src/amount-utils.ts"],"names":[],"mappings":"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"}