@silkysquad/silk 1.0.0

package/src/cli.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { walletCreate, walletList, walletFund } from './commands/wallet.js';
+import { balance } from './commands/balance.js';
+import { pay } from './commands/pay.js';
+import { claim } from './commands/claim.js';
+import { cancel } from './commands/cancel.js';
+import { paymentsList, paymentsGet } from './commands/payments.js';
+import { configSetApiUrl, configGetApiUrl, configResetApiUrl, configSetCluster, configGetCluster, configResetCluster } from './commands/config.js';
+import { accountSync, accountStatus, accountSend } from './commands/account.js';
+import { contactsAdd, contactsRemove, contactsList, contactsGet } from './commands/contacts.js';
+import { chat } from './commands/chat.js';
+import { init } from './commands/init.js';
+import { wrapCommand } from './output.js';
+
+const program = new Command();
+program
+  .name('silk')
+  .description('Silkyway SDK — Agent payments on Solana')
+  .version('0.1.0')
+  .option('--human', 'Human-readable output');
+
+// init
+program
+  .command('init')
+  .description('Initialize Silk CLI (create default wallet and agent ID)')
+  .action(wrapCommand(init));
+
+// wallet commands
+const wallet = program.command('wallet').description('Manage wallets');
+wallet
+  .command('create')
+  .argument('[label]', 'wallet label', 'main')
+  .description('Create a new wallet')
+  .action(wrapCommand(walletCreate));
+wallet
+  .command('list')
+  .description('List all wallets')
+  .action(wrapCommand(walletList));
+wallet
+  .command('fund')
+  .option('--sol', 'Request SOL only')
+  .option('--usdc', 'Request USDC only')
+  .option('--wallet <label>', 'Wallet to fund')
+  .description('Fund wallet from devnet faucet (devnet only)')
+  .action(wrapCommand(walletFund));
+
+// balance
+program
+  .command('balance')
+  .option('--wallet <label>', 'Wallet to check')
+  .description('Check wallet balances')
+  .action(wrapCommand(balance));
+
+// pay
+program
+  .command('pay')
+  .argument('<recipient>', 'Recipient wallet address')
+  .argument('<amount>', 'Amount in USDC')
+  .option('--memo <text>', 'Payment memo')
+  .option('--wallet <label>', 'Sender wallet')
+  .description('Send a USDC payment')
+  .action(wrapCommand(pay));
+
+// claim
+program
+  .command('claim')
+  .argument('<transferPda>', 'Transfer PDA to claim')
+  .option('--wallet <label>', 'Wallet to claim with')
+  .description('Claim a received payment')
+  .action(wrapCommand(claim));
+
+// cancel
+program
+  .command('cancel')
+  .argument('<transferPda>', 'Transfer PDA to cancel')
+  .option('--wallet <label>', 'Wallet to cancel with')
+  .description('Cancel a sent payment')
+  .action(wrapCommand(cancel));
+
+// payments
+const payments = program.command('payments').description('View payment history');
+payments
+  .command('list')
+  .option('--wallet <label>', 'Wallet to query')
+  .description('List transfers')
+  .action(wrapCommand(paymentsList));
+payments
+  .command('get')
+  .argument('<transferPda>', 'Transfer PDA')
+  .description('Get transfer details')
+  .action(wrapCommand(paymentsGet));
+
+// config
+const config = program.command('config').description('SDK configuration');
+config
+  .command('set-api-url')
+  .argument('<url>', 'API base URL')
+  .description('Set the API base URL')
+  .action(wrapCommand(configSetApiUrl));
+config
+  .command('get-api-url')
+  .description('Show the current API base URL')
+  .action(wrapCommand(configGetApiUrl));
+config
+  .command('reset-api-url')
+  .description('Reset API URL to default')
+  .action(wrapCommand(configResetApiUrl));
+config
+  .command('set-cluster')
+  .argument('<cluster>', 'Cluster: mainnet-beta or devnet')
+  .description('Set the Solana cluster')
+  .action(wrapCommand(configSetCluster));
+config
+  .command('get-cluster')
+  .description('Show the current Solana cluster')
+  .action(wrapCommand(configGetCluster));
+config
+  .command('reset-cluster')
+  .description('Reset cluster to default (mainnet-beta)')
+  .action(wrapCommand(configResetCluster));
+
+// account commands
+const account = program.command('account').description('Manage Silkysig account');
+account
+  .command('sync')
+  .option('--wallet <label>', 'Wallet to sync')
+  .option('--account <pda>', 'Sync a specific account by PDA')
+  .description('Discover and sync your account')
+  .action(wrapCommand(accountSync));
+account
+  .command('status')
+  .option('--wallet <label>', 'Wallet to check')
+  .description('Show account balance and policy')
+  .action(wrapCommand(accountStatus));
+account
+  .command('send')
+  .argument('<recipient>', 'Recipient wallet address')
+  .argument('<amount>', 'Amount in USDC')
+  .option('--memo <text>', 'Payment memo')
+  .option('--wallet <label>', 'Sender wallet')
+  .description('Send from account (policy-enforced)')
+  .action(wrapCommand(accountSend));
+
+// contacts commands
+const contacts = program.command('contacts').description('Manage address book');
+contacts
+  .command('add')
+  .argument('<name>', 'Contact name')
+  .argument('<address>', 'Solana wallet address')
+  .description('Add a contact')
+  .action(wrapCommand(contactsAdd));
+contacts
+  .command('remove')
+  .argument('<name>', 'Contact name')
+  .description('Remove a contact')
+  .action(wrapCommand(contactsRemove));
+contacts
+  .command('list')
+  .description('List all contacts')
+  .action(wrapCommand(contactsList));
+contacts
+  .command('get')
+  .argument('<name>', 'Contact name')
+  .description('Get a contact address')
+  .action(wrapCommand(contactsGet));
+
+// chat
+program
+  .command('chat')
+  .argument('<message>', 'Message to send to support')
+  .description('Chat with Silkyway support agent')
+  .action(wrapCommand(chat));
+
+program.parse();

package/src/client.ts

@@ -0,0 +1,49 @@
+import axios, { AxiosInstance, AxiosError } from 'axios';
+import { SdkError, ANCHOR_ERROR_MAP } from './errors.js';
+
+const DEFAULT_TIMEOUT = 30000;
+
+export interface ClientConfig {
+  baseUrl?: string;
+  timeout?: number;
+}
+
+export function createHttpClient(config: ClientConfig = {}): AxiosInstance {
+  const client = axios.create({
+    baseURL: config.baseUrl || 'http://localhost:3000',
+    timeout: config.timeout || DEFAULT_TIMEOUT,
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    (error: AxiosError<{ ok: boolean; error?: string; message?: string }>) => {
+      if (error.response?.data?.error) {
+        const apiCode = error.response.data.error;
+        const apiMessage = error.response.data.message || 'Unknown API error';
+
+        if (apiCode === 'TX_FAILED') {
+          const hexMatch = apiMessage.match(/0x([0-9a-fA-F]+)/);
+          if (hexMatch) {
+            const errorCode = parseInt(hexMatch[1], 16);
+            const anchor = ANCHOR_ERROR_MAP[errorCode];
+            if (anchor) {
+              throw new SdkError(anchor.code, anchor.message);
+            }
+          }
+        }
+
+        throw new SdkError(apiCode, apiMessage);
+      }
+      if (error.response?.data?.message) {
+        throw new SdkError('API_ERROR', error.response.data.message);
+      }
+      if (error.code === 'ECONNABORTED') {
+        throw new SdkError('TIMEOUT', 'Request timeout — is the Silkyway server running?');
+      }
+      throw new SdkError('NETWORK_ERROR', 'Network error — is the Silkyway server running?');
+    },
+  );
+
+  return client;
+}

package/src/commands/account.ts

@@ -0,0 +1,210 @@
+import { Keypair, Transaction } from '@solana/web3.js';
+import bs58 from 'bs58';
+import { loadConfig, saveConfig, getWallet, getApiUrl, AccountInfo } from '../config.js';
+import { createHttpClient } from '../client.js';
+import { outputSuccess } from '../output.js';
+import { SdkError, toSilkysigError } from '../errors.js';
+import { validateAddress, validateAmount } from '../validate.js';
+import { resolveRecipient } from '../contacts.js';
+
+interface OperatorSlot {
+  index: number;
+  perTxLimit: string;
+}
+
+interface ByOperatorAccount {
+  pda: string;
+  owner: string;
+  mint: string;
+  mintDecimals: number;
+  isPaused: boolean;
+  balance: number;
+  operatorSlot: OperatorSlot | null;
+}
+
+interface AccountDetail {
+  pda: string;
+  owner: string;
+  mint: string;
+  mintDecimals: number;
+  isPaused: boolean;
+  balance: number;
+  operators: Array<{
+    index: number;
+    pubkey: string;
+    perTxLimit: string;
+  }>;
+}
+
+export async function accountSync(opts: { wallet?: string; account?: string }) {
+  const config = loadConfig();
+  const wallet = getWallet(config, opts.wallet);
+  const client = createHttpClient({ baseUrl: getApiUrl(config) });
+
+  if (opts.account) {
+    // Direct PDA sync
+    validateAddress(opts.account, 'account');
+    const res = await client.get(`/api/account/${opts.account}`);
+    const acct: AccountDetail = res.data.data;
+
+    // Verify wallet is an operator on this account
+    const op = acct.operators.find((o) => o.pubkey === wallet.address);
+    if (!op) {
+      throw new SdkError(
+        'NOT_OPERATOR',
+        `Wallet "${wallet.label}" (${wallet.address}) is not an operator on account ${opts.account}`,
+      );
+    }
+
+    const accountInfo: AccountInfo = {
+      pda: acct.pda,
+      owner: acct.owner,
+      mint: acct.mint,
+      mintDecimals: acct.mintDecimals,
+      operatorIndex: op.index,
+      perTxLimit: Number(op.perTxLimit),
+      syncedAt: new Date().toISOString(),
+    };
+    config.account = accountInfo;
+    saveConfig(config);
+
+    outputSuccess({
+      action: 'sync',
+      pda: acct.pda,
+      owner: acct.owner,
+      balance: acct.balance,
+      perTxLimit: Number(op.perTxLimit),
+      mint: acct.mint,
+    });
+    return;
+  }
+
+  // Discover by operator
+  const res = await client.get(`/api/account/by-operator/${wallet.address}`);
+  const accounts: ByOperatorAccount[] = res.data.data.accounts;
+
+  if (accounts.length === 0) {
+    outputSuccess({
+      action: 'sync',
+      found: 0,
+      message: `No account found for wallet "${wallet.label}" (${wallet.address}).`,
+      hint: `Ask your human to set up your account at:\n  https://app.silkyway.ai/account/setup?agent=${wallet.address}`,
+    });
+    return;
+  }
+
+  // Auto-select first account
+  const selected = accounts[0];
+  const slot = selected.operatorSlot!;
+
+  const accountInfo: AccountInfo = {
+    pda: selected.pda,
+    owner: selected.owner,
+    mint: selected.mint,
+    mintDecimals: selected.mintDecimals,
+    operatorIndex: slot.index,
+    perTxLimit: Number(slot.perTxLimit),
+    syncedAt: new Date().toISOString(),
+  };
+  config.account = accountInfo;
+  saveConfig(config);
+
+  if (accounts.length === 1) {
+    outputSuccess({
+      action: 'sync',
+      pda: selected.pda,
+      owner: selected.owner,
+      balance: selected.balance,
+      perTxLimit: Number(slot.perTxLimit),
+      mint: selected.mint,
+    });
+  } else {
+    outputSuccess({
+      action: 'sync',
+      pda: selected.pda,
+      owner: selected.owner,
+      balance: selected.balance,
+      perTxLimit: Number(slot.perTxLimit),
+      mint: selected.mint,
+      allAccounts: accounts.map((a) => ({
+        pda: a.pda,
+        owner: a.owner,
+        balance: a.balance,
+      })),
+      hint: 'To use a different account: silk account sync --account <pda>',
+    });
+  }
+}
+
+export async function accountStatus(opts: { wallet?: string }) {
+  const config = loadConfig();
+  getWallet(config, opts.wallet); // validate wallet exists
+
+  if (!config.account) {
+    throw new SdkError('NO_ACCOUNT', 'No account synced. Run: silk account sync');
+  }
+
+  const client = createHttpClient({ baseUrl: getApiUrl(config) });
+  const res = await client.get(`/api/account/${config.account.pda}`);
+  const acct: AccountDetail = res.data.data;
+
+  const op = acct.operators.find((o) => o.index === config.account!.operatorIndex);
+  const perTxLimit = op ? Number(op.perTxLimit) : config.account.perTxLimit;
+  const perTxLimitHuman = acct.mintDecimals > 0 ? perTxLimit / 10 ** acct.mintDecimals : perTxLimit;
+
+  outputSuccess({
+    action: 'status',
+    pda: acct.pda,
+    owner: acct.owner,
+    balance: acct.balance,
+    mint: acct.mint,
+    isPaused: acct.isPaused,
+    operatorIndex: config.account.operatorIndex,
+    perTxLimit: perTxLimitHuman,
+  });
+}
+
+export async function accountSend(recipient: string, amount: string, opts: { memo?: string; wallet?: string }) {
+  recipient = resolveRecipient(recipient);
+  const config = loadConfig();
+  const wallet = getWallet(config, opts.wallet);
+
+  if (!config.account) {
+    throw new SdkError('NO_ACCOUNT', 'No account synced. Run: silk account sync');
+  }
+
+  validateAddress(recipient, 'recipient');
+  const amountNum = validateAmount(amount);
+
+  // Convert to smallest units
+  const amountRaw = Math.round(amountNum * 10 ** config.account.mintDecimals);
+
+  const client = createHttpClient({ baseUrl: getApiUrl(config) });
+
+  // 1. Build unsigned transaction
+  const buildRes = await client.post('/api/account/transfer', {
+    signer: wallet.address,
+    accountPda: config.account.pda,
+    recipient,
+    amount: amountRaw,
+  });
+
+  const { transaction: txBase64 } = buildRes.data.data;
+
+  // 2. Sign the transaction
+  const tx = Transaction.from(Buffer.from(txBase64, 'base64'));
+  const keypair = Keypair.fromSecretKey(bs58.decode(wallet.privateKey));
+  tx.sign(keypair);
+
+  // 3. Submit signed transaction
+  try {
+    const submitRes = await client.post('/api/tx/submit', {
+      signedTx: tx.serialize().toString('base64'),
+    });
+
+    const { txid } = submitRes.data.data;
+    outputSuccess({ action: 'send', txid, amount: amountNum, recipient });
+  } catch (err) {
+    throw toSilkysigError(err);
+  }
+}

package/src/commands/balance.ts

@@ -0,0 +1,14 @@
+import { loadConfig, getWallet, getApiUrl } from '../config.js';
+import { createHttpClient } from '../client.js';
+import { outputSuccess } from '../output.js';
+
+export async function balance(opts: { wallet?: string }) {
+  const config = loadConfig();
+  const wallet = getWallet(config, opts.wallet);
+  const client = createHttpClient({ baseUrl: getApiUrl(config) });
+
+  const res = await client.get(`/api/wallet/${wallet.address}/balance`);
+  const data = res.data.data;
+
+  outputSuccess({ wallet: wallet.label, address: wallet.address, sol: data.sol, tokens: data.tokens });
+}

package/src/commands/cancel.ts

@@ -0,0 +1,34 @@
+import { Keypair, Transaction } from '@solana/web3.js';
+import bs58 from 'bs58';
+import { loadConfig, getWallet, getApiUrl } from '../config.js';
+import { createHttpClient } from '../client.js';
+import { outputSuccess } from '../output.js';
+import { validateCancel } from '../validate.js';
+
+export async function cancel(transferPda: string, opts: { wallet?: string }) {
+  const config = loadConfig();
+  const wallet = getWallet(config, opts.wallet);
+  const client = createHttpClient({ baseUrl: getApiUrl(config) });
+
+  await validateCancel(client, transferPda, wallet.address);
+
+  // 1. Build unsigned cancel tx
+  const buildRes = await client.post('/api/tx/cancel-transfer', {
+    canceller: wallet.address,
+    transferPda,
+  });
+
+  const txBase64 = buildRes.data.data.transaction;
+
+  // 2. Sign
+  const tx = Transaction.from(Buffer.from(txBase64, 'base64'));
+  const keypair = Keypair.fromSecretKey(bs58.decode(wallet.privateKey));
+  tx.sign(keypair);
+
+  // 3. Submit
+  const submitRes = await client.post('/api/tx/submit', {
+    signedTx: tx.serialize().toString('base64'),
+  });
+
+  outputSuccess({ action: 'cancel', transferPda, txid: submitRes.data.data.txid });
+}

package/src/commands/chat.ts

@@ -0,0 +1,14 @@
+import { loadConfig, getApiUrl, getAgentId } from '../config.js';
+import { createHttpClient } from '../client.js';
+import { outputSuccess } from '../output.js';
+
+export async function chat(message: string) {
+  const config = loadConfig();
+  const agentId = getAgentId(config);
+  const client = createHttpClient({ baseUrl: getApiUrl(config) });
+
+  const res = await client.post('/chat', { agentId, message });
+  const data = res.data.data;
+
+  outputSuccess({ message: data.message });
+}

package/src/commands/claim.ts

@@ -0,0 +1,34 @@
+import { Keypair, Transaction } from '@solana/web3.js';
+import bs58 from 'bs58';
+import { loadConfig, getWallet, getApiUrl } from '../config.js';
+import { createHttpClient } from '../client.js';
+import { outputSuccess } from '../output.js';
+import { validateClaim } from '../validate.js';
+
+export async function claim(transferPda: string, opts: { wallet?: string }) {
+  const config = loadConfig();
+  const wallet = getWallet(config, opts.wallet);
+  const client = createHttpClient({ baseUrl: getApiUrl(config) });
+
+  await validateClaim(client, transferPda, wallet.address);
+
+  // 1. Build unsigned claim tx
+  const buildRes = await client.post('/api/tx/claim-transfer', {
+    claimer: wallet.address,
+    transferPda,
+  });
+
+  const txBase64 = buildRes.data.data.transaction;
+
+  // 2. Sign
+  const tx = Transaction.from(Buffer.from(txBase64, 'base64'));
+  const keypair = Keypair.fromSecretKey(bs58.decode(wallet.privateKey));
+  tx.sign(keypair);
+
+  // 3. Submit
+  const submitRes = await client.post('/api/tx/submit', {
+    signedTx: tx.serialize().toString('base64'),
+  });
+
+  outputSuccess({ action: 'claim', transferPda, txid: submitRes.data.data.txid });
+}

package/src/commands/config.ts

@@ -0,0 +1,46 @@
+import { loadConfig, saveConfig, getApiUrl, getCluster, SolanaCluster } from '../config.js';
+import { outputSuccess } from '../output.js';
+import { SdkError } from '../errors.js';
+
+export async function configSetApiUrl(url: string) {
+  const config = loadConfig();
+  config.apiUrl = url;
+  saveConfig(config);
+  outputSuccess({ apiUrl: url });
+}
+
+export async function configGetApiUrl() {
+  const config = loadConfig();
+  outputSuccess({ apiUrl: getApiUrl(config) });
+}
+
+export async function configResetApiUrl() {
+  const config = loadConfig();
+  delete config.apiUrl;
+  saveConfig(config);
+  outputSuccess({ apiUrl: getApiUrl(config), message: 'Reset to default' });
+}
+
+const VALID_CLUSTERS: SolanaCluster[] = ['mainnet-beta', 'devnet'];
+
+export async function configSetCluster(cluster: string) {
+  if (!VALID_CLUSTERS.includes(cluster as SolanaCluster)) {
+    throw new SdkError('INVALID_CLUSTER', `Invalid cluster "${cluster}". Valid options: ${VALID_CLUSTERS.join(', ')}`);
+  }
+  const config = loadConfig();
+  config.cluster = cluster as SolanaCluster;
+  saveConfig(config);
+  outputSuccess({ cluster, apiUrl: getApiUrl(config) });
+}
+
+export async function configGetCluster() {
+  const config = loadConfig();
+  outputSuccess({ cluster: getCluster(config), apiUrl: getApiUrl(config) });
+}
+
+export async function configResetCluster() {
+  const config = loadConfig();
+  delete config.cluster;
+  saveConfig(config);
+  outputSuccess({ cluster: getCluster(config), apiUrl: getApiUrl(config), message: 'Reset to default (mainnet-beta)' });
+}

package/src/commands/contacts.ts

@@ -0,0 +1,26 @@
+import { addContact, removeContact, getContact, listContacts } from '../contacts.js';
+import { outputSuccess } from '../output.js';
+import { SdkError } from '../errors.js';
+
+export async function contactsAdd(name: string, address: string) {
+  addContact(name, address);
+  outputSuccess({ action: 'contact_added', name: name.toLowerCase(), address });
+}
+
+export async function contactsRemove(name: string) {
+  removeContact(name);
+  outputSuccess({ action: 'contact_removed', name: name.toLowerCase() });
+}
+
+export async function contactsList() {
+  const contacts = listContacts();
+  outputSuccess({ action: 'contacts_list', contacts });
+}
+
+export async function contactsGet(name: string) {
+  const contact = getContact(name);
+  if (!contact) {
+    throw new SdkError('CONTACT_NOT_FOUND', `Contact "${name.toLowerCase()}" not found`);
+  }
+  outputSuccess({ action: 'contact_get', name: contact.name, address: contact.address });
+}

package/src/commands/init.ts

@@ -0,0 +1,44 @@
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+import { loadConfig, saveConfig, ensureAgentId } from '../config.js';
+import { initContacts } from '../contacts.js';
+import { outputSuccess } from '../output.js';
+
+export async function init() {
+  const config = loadConfig();
+  let walletCreated = false;
+  let mainWallet = config.wallets.find((w) => w.label === 'main');
+
+  if (!mainWallet) {
+    const keypair = Keypair.generate();
+    const address = keypair.publicKey.toBase58();
+    const privateKey = bs58.encode(keypair.secretKey);
+
+    mainWallet = { label: 'main', address, privateKey };
+    config.wallets.push(mainWallet);
+
+    if (config.wallets.length === 1) {
+      config.defaultWallet = 'main';
+    }
+
+    walletCreated = true;
+  }
+
+  const agentIdResult = ensureAgentId(config);
+  const contactsCreated = initContacts();
+
+  if (walletCreated || agentIdResult.created) {
+    saveConfig(config);
+  }
+
+  outputSuccess({
+    action: 'init',
+    wallet_created: walletCreated,
+    wallet_label: 'main',
+    wallet_address: mainWallet.address,
+    agent_id_created: agentIdResult.created,
+    agent_id: agentIdResult.agentId,
+    contacts_created: contactsCreated,
+    message: (walletCreated || agentIdResult.created || contactsCreated) ? 'Initialization complete' : 'Already initialized',
+  });
+}