npm package: @spx-network/sdk
Description: SPX Protocol SDK — streaming payments for the Solana agent economy
Latest version: 0.1.0

# @spx/sdk

Streaming payments for the Solana agent economy. Collapse millions of micropayments into single on-chain settlements.

## Install

```bash
npm install @spx/sdk
```

## Quick Start — Provider (get paid)

Add SPX payment verification to any Express API:

```typescript
import express from "express";
import { spxMiddleware } from "@spx/sdk/server";

const app = express();

// Verify vouchers on every request — Ed25519 check, no RPC, microseconds
app.use("/api", spxMiddleware({
  agentPublicKeys: {
    // escrow pubkey → agent's Ed25519 public key
    "EscrowPubkeyHere...": new Uint8Array([/* 32 bytes */]),
  },
  onVoucher: (voucher, amount) => {
    console.log(`Earned ${amount} tokens`);
  },
}));

app.get("/api/data", (req, res) => {
  res.json({ result: "paid content" });
});

app.listen(3000);
```

Requests without a valid `X-SPX-Voucher` header get a `402 Payment Required` response.

## Quick Start — Agent (pay for services)

```typescript
import { SpxClient } from "@spx/sdk/client";
import { PublicKey } from "@solana/web3.js";

const client = new SpxClient({
  agentSecretKey: myAgentKeypair.secretKey, // Ed25519 keypair
  escrowKey: new PublicKey("MyEscrowPDA..."),
  escrowCreatedAt: 1700000000n, // from on-chain escrow account
});

// Sign a voucher (off-chain, instant, no tx)
const { header } = client.pay(
  new PublicKey("ServicePubkey..."),
  1000n // amount in token units
);

// Attach to any HTTP request
const response = await fetch("https://api.example.com/data", {
  headers: { "X-SPX-Voucher": header },
});
```

## How It Works

1. **Owner** creates an escrow on Solana and deposits USDC
2. **Agent** signs cumulative vouchers off-chain (Ed25519, instant)
3. **Service** verifies vouchers locally (no RPC call — microseconds)
4. **Service** batch-settles on-chain when ready (N vouchers → 1 transaction)

Only the latest voucher per escrow matters. 1 million API calls = 1 settlement transaction.

## Settlement

Services collect vouchers and settle periodically:

```typescript
import { buildSettleInstructions } from "@spx/sdk";
import { Connection, Transaction } from "@solana/web3.js";

const verifier = new SpxVerifier({ agentPublicKeys: { ... } });

// After accumulating vouchers...
const vouchers = verifier.getSettleableVouchers();

for (const voucher of vouchers) {
  const [ed25519Ix, settleIx] = buildSettleInstructions({
    voucher,
    agentPublicKey, // 32 bytes
    service: serviceKeypair.publicKey,
    serviceTokenAccount,
    escrow: voucher.escrowKey,
    vault: escrowVault,
    treasuryTokenAccount,
    mint: usdcMint,
  });

  const tx = new Transaction().add(ed25519Ix, settleIx);
  // sign and send...
}
```

## API Reference

### Vouchers
- `signVoucher(params)` → `SpxVoucher` — sign a voucher with agent keypair
- `verifyVoucher(voucher, agentPublicKey)` → `boolean` — local Ed25519 check
- `serializeVoucher(voucher)` → `string` — base64 for HTTP headers
- `deserializeVoucher(encoded)` → `SpxVoucher` — parse from HTTP header
- `buildVoucherMessage(...)` → `Buffer` — raw 110-byte message

### Client
- `new SpxClient({ agentSecretKey, escrowKey, escrowCreatedAt })` — create client
- `SpxClient.fromChain({ connection, agentSecretKey, owner, label })` — create from on-chain state
- `client.pay(serviceKey, amount)` → `{ voucher, header }` — sign and serialize

### Server
- `new SpxVerifier({ agentPublicKeys })` — create verifier
- `verifier.verify(headerValue)` → `VerifyResult` — verify a voucher
- `verifier.getSettleableVouchers()` → `SpxVoucher[]` — latest per escrow
- `spxMiddleware({ agentPublicKeys, onVoucher })` — Express middleware

### PDAs
- `findEscrowPda(owner, label)` → `[PublicKey, bump]`
- `findSettlementPda(escrow, service)` → `[PublicKey, bump]`
- `findConfigPda()` → `[PublicKey, bump]`

### Settlement
- `buildEd25519Instruction(agentPublicKey, message, signature)` → `TransactionInstruction`
- `buildSettleInstruction(params)` → `TransactionInstruction`
- `buildSettleInstructions(params)` → `[TransactionInstruction, TransactionInstruction]`

## Protocol

SPX Program ID: `56xJw72Lc1yDC6QwV8xNhiU6dDgUT1E9Ybh1nSxD4QZW`

Voucher format (110 bytes):
```
SPX_VOUCHER_V1 (14) | escrow (32) | created_at (8 i64 BE)
| service (32) | amount (8 u64 BE) | cumulative (8 u64 BE) | nonce (8 u64 BE)
```

## License

MIT