quorum-sdk 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @agent-multisig/sdk
+
+TypeScript SDK for the Agent Multisig Coordination API.
+
+Enables AI agents to participate in multi-signature Bitcoin transactions.
+
+## Installation
+
+```bash
+npm install @agent-multisig/sdk
+```
+
+## Quick Start
+
+```typescript
+import { AgentMultisig } from '@agent-multisig/sdk';
+
+const client = new AgentMultisig({
+  apiUrl: 'https://agent-multisig-api-production.up.railway.app',
+  apiKey: 'your-api-key'  // optional
+});
+
+// Quick setup: register agents and create multisig in one call
+const { multisig, agents } = await client.quickSetup({
+  name: 'AI Treasury',
+  threshold: 2,
+  signers: [
+    { name: 'TreasuryBot', provider: 'aibtc', publicKey: '...' },
+    { name: 'AuditBot', provider: 'aibtc', publicKey: '...' },
+    { name: 'BackupBot', provider: 'aibtc', publicKey: '...' },
+  ],
+  network: 'mainnet'
+});
+
+console.log('Fund this address:', multisig.address);
+// => bc1p6f4vmxvwnpgrgmmc4653u28jxlrf3enh0qwcev6safpcfy4y8gdqfcnjf6
+```
+
+## Creating a Spend Proposal
+
+```typescript
+// Create a proposal to spend from the multisig
+const proposal = await client.createProposal({
+  multisigId: multisig.id,
+  to: 'bc1qpzlw29z50cz7ysjpsaqggtscya3p6ggehnsp2g',
+  amount: 10000  // satoshis
+});
+
+console.log('PSBT to sign:', proposal.psbtHex);
+```
+
+## Signing
+
+```typescript
+// Each agent signs the proposal
+await client.signProposal({
+  proposalId: proposal.id,
+  agentId: agents[0].id,
+  signature: 'schnorr_signature_hex...'
+});
+
+await client.signProposal({
+  proposalId: proposal.id,
+  agentId: agents[1].id,
+  signature: 'schnorr_signature_hex...'
+});
+
+// Once threshold is met, broadcast
+const { txid } = await client.broadcastProposal(proposal.id);
+console.log('Transaction broadcast:', txid);
+```
+
+## Waiting for Confirmation
+
+```typescript
+// Wait for the proposal to be confirmed on-chain
+const confirmed = await client.waitForProposal(proposal.id, 'confirmed', {
+  timeoutMs: 600000,  // 10 minutes
+  pollIntervalMs: 10000  // check every 10 seconds
+});
+
+console.log('Confirmed in txid:', confirmed.txid);
+```
+
+## Real-World Example
+
+This SDK was used to execute a real 2-of-3 multisig transaction on Bitcoin mainnet:
+
+**Funding TX:** [3222492b...](https://mempool.space/tx/3222492b560eb8b6898746ea11f3b4eed1dbf5fff21df75b581eea701edd0222)  
+**Spend TX:** [8b371247...](https://mempool.space/tx/8b3712476f38b1563ce1b7b8f521ea4ee2fec1fdd249f535f1d5f5f0125040d4)
+
+20,000 sats → 2-of-3 Taproot multisig → Signed by 2 agents → Confirmed in block 937432.
+
+## API Reference
+
+### `new AgentMultisig(config)`
+
+Create a new client instance.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `apiUrl` | `string` | API base URL |
+| `apiKey` | `string?` | Optional API key |
+| `timeout` | `number?` | Request timeout in ms (default: 30000) |
+
+### Agents
+
+- `registerAgent(input)` - Register a new agent
+- `getAgent(agentId)` - Get agent by ID
+- `listAgents()` - List all agents
+
+### Multisigs
+
+- `createMultisig(input)` - Create a new multisig
+- `getMultisig(multisigId)` - Get multisig by ID
+- `listMultisigs()` - List all multisigs
+- `getMultisigBalance(multisigId)` - Get balance and UTXOs
+
+### Proposals
+
+- `createProposal(input)` - Create a spend proposal
+- `getProposal(proposalId)` - Get proposal by ID
+- `listProposals(multisigId?)` - List proposals
+- `signProposal(input)` - Submit a signature
+- `broadcastProposal(proposalId)` - Broadcast when ready
+
+### Convenience
+
+- `quickSetup(input)` - Register agents + create multisig in one call
+- `waitForProposal(id, status, options)` - Poll until status reached
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,250 @@
+/**
+ * Agent Multisig SDK
+ *
+ * TypeScript client for the Agent Multisig Coordination API.
+ * Enables AI agents to participate in multi-signature Bitcoin transactions.
+ *
+ * @example
+ * ```typescript
+ * import { AgentMultisig } from '@agent-multisig/sdk';
+ *
+ * const client = new AgentMultisig({
+ *   apiUrl: 'https://agent-multisig-api-production.up.railway.app',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Register an agent
+ * const agent = await client.registerAgent({
+ *   name: 'TreasuryBot',
+ *   provider: 'aibtc',
+ *   publicKey: '9350761ae700acd872510de161bca0b90b78ddc007936674b318be8a50c531b5'
+ * });
+ *
+ * // Create a 2-of-3 multisig
+ * const multisig = await client.createMultisig({
+ *   name: 'AI Treasury',
+ *   threshold: 2,
+ *   agents: [agent1.id, agent2.id, agent3.id],
+ *   network: 'mainnet'
+ * });
+ *
+ * // Create a spend proposal
+ * const proposal = await client.createProposal({
+ *   multisigId: multisig.id,
+ *   to: 'bc1q...',
+ *   amount: 10000
+ * });
+ *
+ * // Sign the proposal
+ * await client.signProposal(proposal.id, agent.id, signature);
+ * ```
+ */
+interface AgentMultisigConfig {
+    apiUrl: string;
+    apiKey?: string;
+    timeout?: number;
+}
+interface Agent {
+    id: string;
+    name: string;
+    provider: 'aibtc' | 'agentkit' | 'crossmint' | 'clawcash' | 'bankr' | 'custom';
+    publicKey: string;
+    chain: 'bitcoin' | 'stacks' | 'evm' | 'solana';
+    createdAt: string;
+}
+interface RegisterAgentInput {
+    name: string;
+    provider: Agent['provider'];
+    publicKey: string;
+    chain?: Agent['chain'];
+    webhookUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Multisig {
+    id: string;
+    name: string;
+    address: string;
+    threshold: number;
+    totalSigners: number;
+    agents: string[];
+    network: 'mainnet' | 'testnet' | 'signet';
+    chain: 'bitcoin' | 'stacks' | 'evm' | 'solana';
+    scriptHex?: string;
+    createdAt: string;
+}
+interface CreateMultisigInput {
+    name: string;
+    threshold: number;
+    agents: string[];
+    network?: 'mainnet' | 'testnet' | 'signet';
+    chain?: Multisig['chain'];
+}
+interface Proposal {
+    id: string;
+    multisigId: string;
+    type: 'spend' | 'custom';
+    status: 'pending' | 'ready' | 'broadcast' | 'confirmed' | 'failed';
+    to?: string;
+    amount?: number;
+    psbtHex?: string;
+    signatures: ProposalSignature[];
+    txid?: string;
+    createdAt: string;
+    expiresAt?: string;
+}
+interface ProposalSignature {
+    agentId: string;
+    signature: string;
+    signedAt: string;
+}
+interface CreateProposalInput {
+    multisigId: string;
+    to: string;
+    amount: number;
+    memo?: string;
+}
+interface SignProposalInput {
+    proposalId: string;
+    agentId: string;
+    signature: string;
+}
+declare class AgentMultisigError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
+}
+declare class AgentMultisig {
+    private apiUrl;
+    private apiKey?;
+    private timeout;
+    constructor(config: AgentMultisigConfig);
+    private request;
+    health(): Promise<{
+        status: string;
+        version: string;
+    }>;
+    /**
+     * Register a new agent with the coordination API.
+     */
+    registerAgent(input: RegisterAgentInput): Promise<Agent>;
+    /**
+     * Get an agent by ID.
+     */
+    getAgent(agentId: string): Promise<Agent>;
+    /**
+     * List all registered agents.
+     */
+    listAgents(): Promise<Agent[]>;
+    /**
+     * Create a new multisig wallet.
+     *
+     * @example
+     * ```typescript
+     * const multisig = await client.createMultisig({
+     *   name: 'AI Treasury',
+     *   threshold: 2,
+     *   agents: ['agent_abc', 'agent_def', 'agent_ghi'],
+     *   network: 'mainnet'
+     * });
+     * console.log('Fund this address:', multisig.address);
+     * ```
+     */
+    createMultisig(input: CreateMultisigInput): Promise<Multisig>;
+    /**
+     * Get a multisig by ID.
+     */
+    getMultisig(multisigId: string): Promise<Multisig>;
+    /**
+     * List all multisigs.
+     */
+    listMultisigs(): Promise<Multisig[]>;
+    /**
+     * Get the balance of a multisig wallet.
+     */
+    getMultisigBalance(multisigId: string): Promise<{
+        confirmed: number;
+        unconfirmed: number;
+        utxos: Array<{
+            txid: string;
+            vout: number;
+            value: number;
+        }>;
+    }>;
+    /**
+     * Create a spend proposal for a multisig.
+     *
+     * @example
+     * ```typescript
+     * const proposal = await client.createProposal({
+     *   multisigId: 'msig_xyz',
+     *   to: 'bc1qpzlw29z50cz7ysjpsaqggtscya3p6ggehnsp2g',
+     *   amount: 10000  // satoshis
+     * });
+     * console.log('PSBT to sign:', proposal.psbtHex);
+     * ```
+     */
+    createProposal(input: CreateProposalInput): Promise<Proposal>;
+    /**
+     * Get a proposal by ID.
+     */
+    getProposal(proposalId: string): Promise<Proposal>;
+    /**
+     * List proposals, optionally filtered by multisig.
+     */
+    listProposals(multisigId?: string): Promise<Proposal[]>;
+    /**
+     * Sign a proposal with an agent's key.
+     *
+     * @example
+     * ```typescript
+     * // Agent signs the PSBT and submits signature
+     * const signature = await myWallet.signPsbt(proposal.psbtHex);
+     * await client.signProposal({
+     *   proposalId: proposal.id,
+     *   agentId: myAgent.id,
+     *   signature: signature
+     * });
+     * ```
+     */
+    signProposal(input: SignProposalInput): Promise<Proposal>;
+    /**
+     * Broadcast a fully-signed proposal.
+     */
+    broadcastProposal(proposalId: string): Promise<{
+        txid: string;
+    }>;
+    /**
+     * Create a multisig and register agents in one call.
+     *
+     * @example
+     * ```typescript
+     * const { multisig, agents } = await client.quickSetup({
+     *   name: 'Quick Treasury',
+     *   threshold: 2,
+     *   signers: [
+     *     { name: 'Bot1', provider: 'aibtc', publicKey: '...' },
+     *     { name: 'Bot2', provider: 'aibtc', publicKey: '...' },
+     *     { name: 'Bot3', provider: 'aibtc', publicKey: '...' },
+     *   ]
+     * });
+     * ```
+     */
+    quickSetup(input: {
+        name: string;
+        threshold: number;
+        signers: RegisterAgentInput[];
+        network?: 'mainnet' | 'testnet' | 'signet';
+    }): Promise<{
+        multisig: Multisig;
+        agents: Agent[];
+    }>;
+    /**
+     * Wait for a proposal to reach a target status.
+     */
+    waitForProposal(proposalId: string, targetStatus: Proposal['status'], options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<Proposal>;
+}
+
+export { type Agent, AgentMultisig, type AgentMultisigConfig, AgentMultisigError, type CreateMultisigInput, type CreateProposalInput, type Multisig, type Proposal, type ProposalSignature, type RegisterAgentInput, type SignProposalInput, AgentMultisig as default };

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Agent Multisig SDK
+ *
+ * TypeScript client for the Agent Multisig Coordination API.
+ * Enables AI agents to participate in multi-signature Bitcoin transactions.
+ *
+ * @example
+ * ```typescript
+ * import { AgentMultisig } from '@agent-multisig/sdk';
+ *
+ * const client = new AgentMultisig({
+ *   apiUrl: 'https://agent-multisig-api-production.up.railway.app',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Register an agent
+ * const agent = await client.registerAgent({
+ *   name: 'TreasuryBot',
+ *   provider: 'aibtc',
+ *   publicKey: '9350761ae700acd872510de161bca0b90b78ddc007936674b318be8a50c531b5'
+ * });
+ *
+ * // Create a 2-of-3 multisig
+ * const multisig = await client.createMultisig({
+ *   name: 'AI Treasury',
+ *   threshold: 2,
+ *   agents: [agent1.id, agent2.id, agent3.id],
+ *   network: 'mainnet'
+ * });
+ *
+ * // Create a spend proposal
+ * const proposal = await client.createProposal({
+ *   multisigId: multisig.id,
+ *   to: 'bc1q...',
+ *   amount: 10000
+ * });
+ *
+ * // Sign the proposal
+ * await client.signProposal(proposal.id, agent.id, signature);
+ * ```
+ */
+interface AgentMultisigConfig {
+    apiUrl: string;
+    apiKey?: string;
+    timeout?: number;
+}
+interface Agent {
+    id: string;
+    name: string;
+    provider: 'aibtc' | 'agentkit' | 'crossmint' | 'clawcash' | 'bankr' | 'custom';
+    publicKey: string;
+    chain: 'bitcoin' | 'stacks' | 'evm' | 'solana';
+    createdAt: string;
+}
+interface RegisterAgentInput {
+    name: string;
+    provider: Agent['provider'];
+    publicKey: string;
+    chain?: Agent['chain'];
+    webhookUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Multisig {
+    id: string;
+    name: string;
+    address: string;
+    threshold: number;
+    totalSigners: number;
+    agents: string[];
+    network: 'mainnet' | 'testnet' | 'signet';
+    chain: 'bitcoin' | 'stacks' | 'evm' | 'solana';
+    scriptHex?: string;
+    createdAt: string;
+}
+interface CreateMultisigInput {
+    name: string;
+    threshold: number;
+    agents: string[];
+    network?: 'mainnet' | 'testnet' | 'signet';
+    chain?: Multisig['chain'];
+}
+interface Proposal {
+    id: string;
+    multisigId: string;
+    type: 'spend' | 'custom';
+    status: 'pending' | 'ready' | 'broadcast' | 'confirmed' | 'failed';
+    to?: string;
+    amount?: number;
+    psbtHex?: string;
+    signatures: ProposalSignature[];
+    txid?: string;
+    createdAt: string;
+    expiresAt?: string;
+}
+interface ProposalSignature {
+    agentId: string;
+    signature: string;
+    signedAt: string;
+}
+interface CreateProposalInput {
+    multisigId: string;
+    to: string;
+    amount: number;
+    memo?: string;
+}
+interface SignProposalInput {
+    proposalId: string;
+    agentId: string;
+    signature: string;
+}
+declare class AgentMultisigError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
+}
+declare class AgentMultisig {
+    private apiUrl;
+    private apiKey?;
+    private timeout;
+    constructor(config: AgentMultisigConfig);
+    private request;
+    health(): Promise<{
+        status: string;
+        version: string;
+    }>;
+    /**
+     * Register a new agent with the coordination API.
+     */
+    registerAgent(input: RegisterAgentInput): Promise<Agent>;
+    /**
+     * Get an agent by ID.
+     */
+    getAgent(agentId: string): Promise<Agent>;
+    /**
+     * List all registered agents.
+     */
+    listAgents(): Promise<Agent[]>;
+    /**
+     * Create a new multisig wallet.
+     *
+     * @example
+     * ```typescript
+     * const multisig = await client.createMultisig({
+     *   name: 'AI Treasury',
+     *   threshold: 2,
+     *   agents: ['agent_abc', 'agent_def', 'agent_ghi'],
+     *   network: 'mainnet'
+     * });
+     * console.log('Fund this address:', multisig.address);
+     * ```
+     */
+    createMultisig(input: CreateMultisigInput): Promise<Multisig>;
+    /**
+     * Get a multisig by ID.
+     */
+    getMultisig(multisigId: string): Promise<Multisig>;
+    /**
+     * List all multisigs.
+     */
+    listMultisigs(): Promise<Multisig[]>;
+    /**
+     * Get the balance of a multisig wallet.
+     */
+    getMultisigBalance(multisigId: string): Promise<{
+        confirmed: number;
+        unconfirmed: number;
+        utxos: Array<{
+            txid: string;
+            vout: number;
+            value: number;
+        }>;
+    }>;
+    /**
+     * Create a spend proposal for a multisig.
+     *
+     * @example
+     * ```typescript
+     * const proposal = await client.createProposal({
+     *   multisigId: 'msig_xyz',
+     *   to: 'bc1qpzlw29z50cz7ysjpsaqggtscya3p6ggehnsp2g',
+     *   amount: 10000  // satoshis
+     * });
+     * console.log('PSBT to sign:', proposal.psbtHex);
+     * ```
+     */
+    createProposal(input: CreateProposalInput): Promise<Proposal>;
+    /**
+     * Get a proposal by ID.
+     */
+    getProposal(proposalId: string): Promise<Proposal>;
+    /**
+     * List proposals, optionally filtered by multisig.
+     */
+    listProposals(multisigId?: string): Promise<Proposal[]>;
+    /**
+     * Sign a proposal with an agent's key.
+     *
+     * @example
+     * ```typescript
+     * // Agent signs the PSBT and submits signature
+     * const signature = await myWallet.signPsbt(proposal.psbtHex);
+     * await client.signProposal({
+     *   proposalId: proposal.id,
+     *   agentId: myAgent.id,
+     *   signature: signature
+     * });
+     * ```
+     */
+    signProposal(input: SignProposalInput): Promise<Proposal>;
+    /**
+     * Broadcast a fully-signed proposal.
+     */
+    broadcastProposal(proposalId: string): Promise<{
+        txid: string;
+    }>;
+    /**
+     * Create a multisig and register agents in one call.
+     *
+     * @example
+     * ```typescript
+     * const { multisig, agents } = await client.quickSetup({
+     *   name: 'Quick Treasury',
+     *   threshold: 2,
+     *   signers: [
+     *     { name: 'Bot1', provider: 'aibtc', publicKey: '...' },
+     *     { name: 'Bot2', provider: 'aibtc', publicKey: '...' },
+     *     { name: 'Bot3', provider: 'aibtc', publicKey: '...' },
+     *   ]
+     * });
+     * ```
+     */
+    quickSetup(input: {
+        name: string;
+        threshold: number;
+        signers: RegisterAgentInput[];
+        network?: 'mainnet' | 'testnet' | 'signet';
+    }): Promise<{
+        multisig: Multisig;
+        agents: Agent[];
+    }>;
+    /**
+     * Wait for a proposal to reach a target status.
+     */
+    waitForProposal(proposalId: string, targetStatus: Proposal['status'], options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<Proposal>;
+}
+
+export { type Agent, AgentMultisig, type AgentMultisigConfig, AgentMultisigError, type CreateMultisigInput, type CreateProposalInput, type Multisig, type Proposal, type ProposalSignature, type RegisterAgentInput, type SignProposalInput, AgentMultisig as default };