memeputer 1.5.0 → 2.0.0

package/dist/cli.mjs

@@ -0,0 +1,2068 @@
+#!/usr/bin/env node
+// src/cli.mts
+import { Connection, Keypair } from "@solana/web3.js";
+import { readFileSync } from "fs";
+
+// src/internal/canonical.ts
+var DOMAIN_PREFIX = "memeputer.com/v1\n";
+var ENC = new TextEncoder();
+function normalizePath(path) {
+  if (path.includes("#")) {
+    throw new Error('canonical(): path must not contain a fragment "#"');
+  }
+  const qIdx = path.indexOf("?");
+  if (qIdx === -1) return path;
+  const pathname = path.slice(0, qIdx);
+  const queryRaw = path.slice(qIdx + 1);
+  if (queryRaw.length === 0) return pathname;
+  const parts = queryRaw.split("&").sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  return `${pathname}?${parts.join("&")}`;
+}
+function canonical(input) {
+  if (typeof input.path !== "string" || !input.path.startsWith("/")) {
+    throw new Error('canonical(): path must start with "/"');
+  }
+  const normalizedPath = normalizePath(input.path);
+  const domainBytes = ENC.encode(DOMAIN_PREFIX);
+  const methodPathBytes = ENC.encode(`${input.method} ${normalizedPath}
+`);
+  const bodyBytes = encodeBody(input.body);
+  const out = new Uint8Array(domainBytes.length + methodPathBytes.length + bodyBytes.length);
+  out.set(domainBytes, 0);
+  out.set(methodPathBytes, domainBytes.length);
+  out.set(bodyBytes, domainBytes.length + methodPathBytes.length);
+  return out;
+}
+function encodeBody(body) {
+  if (body === null || body === void 0) return new Uint8Array(0);
+  return ENC.encode(deterministicStringify(body));
+}
+function deterministicStringify(v) {
+  if (v === null) return "null";
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new Error("canonical: non-finite number not allowed");
+    return JSON.stringify(v);
+  }
+  if (typeof v === "bigint") {
+    throw new Error("canonical: bigint not allowed \u2014 caller must stringify big numbers");
+  }
+  if (typeof v === "string" || typeof v === "boolean") return JSON.stringify(v);
+  if (Array.isArray(v)) {
+    return `[${v.map(deterministicStringify).join(",")}]`;
+  }
+  if (typeof v === "object") {
+    const obj = v;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const k of keys) {
+      const val = obj[k];
+      if (val === void 0) continue;
+      parts.push(`${JSON.stringify(k)}:${deterministicStringify(val)}`);
+    }
+    return `{${parts.join(",")}}`;
+  }
+  throw new Error(`canonical: unsupported type ${typeof v}`);
+}
+
+// src/client.ts
+import bs58 from "bs58";
+
+// src/errors.ts
+var MemeputerApiError = class extends Error {
+  constructor(code, message, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "MemeputerApiError";
+  }
+  code;
+  status;
+  details;
+};
+
+// src/x402.ts
+async function registerWithX402(client, body, xPayment) {
+  return client.unsignedRequestWithHeaders(
+    "POST",
+    "/v1/agents",
+    body,
+    { "X-PAYMENT": xPayment }
+  );
+}
+
+// src/agents.ts
+var AgentsNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * POST /v1/agents — x402 USDC payment required. xPayment header constructed
+   * by the caller via @openfacilitator/sdk's createPayment helper. BLOCKER #3:
+   * register sends ONLY `X-PAYMENT` — NO canonical-sig X-Memeputer-* headers.
+   */
+  register(body, xPayment) {
+    return registerWithX402(this.client, body, xPayment);
+  }
+  /**
+   * PATCH /v1/agents/:wallet — signed; at least one field required.
+   * Server enforces `verifiedWallet === pathWallet` (NOT_OWNER 403 otherwise).
+   */
+  patch(wallet, body) {
+    return this.client.signedRequest("PATCH", `/v1/agents/${wallet}`, body);
+  }
+  /** GET /v1/agents/:wallet — public read; returns profile + active rooms. */
+  get(wallet) {
+    return this.client.get(`/v1/agents/${wallet}`);
+  }
+  /**
+   * Returns whether (wallet, mint) is currently eligible to post in the room.
+   *
+   * Reads `GET /v1/rooms/:mint/members?wallet=<w>&limit=1`. The wallet query
+   * filter is added in Plan 06-02 Task 0 (BLOCKER #2 / RESEARCH Open Q2
+   * RESOLVED — narrowest possible blast radius vs. a new /v1/eligibility
+   * endpoint).
+   *
+   * Response shape from the API:
+   *   { owner: ApiAgentSummary, members: { items: ApiAgentSummary[], next_cursor: null } }
+   * When `wallet === owner.wallet` the row comes from `owner` (the API does
+   * NOT include the owner in `members.items` per D-10 owner-exclusion).
+   * Otherwise the row comes from `members.items[0]` (length 0 if non-member).
+   *
+   * `next_cursor` is always null in this code path (the server suppresses it
+   * when `?wallet=` is set — Task 0 GREEN).
+   */
+  async eligibility(wallet, mint) {
+    const page = await this.client.get(`/v1/rooms/${mint}/members`, { wallet, limit: "1" });
+    const row = page.owner?.wallet === wallet ? page.owner : page.members?.items?.[0];
+    if (!row) return { eligible: false, balance: "0" };
+    return { eligible: !!row.eligible, balance: row.balance };
+  }
+};
+
+// src/rooms.ts
+import {
+  PublicKey as PublicKey3,
+  SystemProgram,
+  TransactionMessage,
+  VersionedTransaction
+} from "@solana/web3.js";
+import {
+  AnchorProvider,
+  Program
+} from "@coral-xyz/anchor";
+
+// src/internal/vault-pda.ts
+import { PublicKey as PublicKey2 } from "@solana/web3.js";
+
+// src/internal/constants.ts
+import { PublicKey } from "@solana/web3.js";
+var MEMEPUTER_VAULT_PROGRAM_ID = new PublicKey(
+  "HBpnezcpn854wGbUCDdUNj6xG83rngyQrA4Pj9FH1UX9"
+);
+
+// src/internal/vault-pda.ts
+function deriveFeeLedgerPDA(mint) {
+  return PublicKey2.findProgramAddressSync(
+    [Buffer.from("fee_ledger"), mint.toBuffer()],
+    MEMEPUTER_VAULT_PROGRAM_ID
+  );
+}
+function deriveFeeVaultPDA(mint) {
+  return PublicKey2.findProgramAddressSync(
+    [Buffer.from("fee_vault"), mint.toBuffer()],
+    MEMEPUTER_VAULT_PROGRAM_ID
+  );
+}
+function derivePlatformConfigPDA() {
+  return PublicKey2.findProgramAddressSync(
+    [Buffer.from("platform_config")],
+    MEMEPUTER_VAULT_PROGRAM_ID
+  );
+}
+
+// src/vault/idl.json
+var idl_default = {
+  address: "HBpnezcpn854wGbUCDdUNj6xG83rngyQrA4Pj9FH1UX9",
+  metadata: {
+    name: "memeputer_vault",
+    version: "0.1.0",
+    spec: "0.1.0",
+    description: "Memeputer creator-fee vault (DBC + DAMM v2 unified claim)"
+  },
+  instructions: [
+    {
+      name: "claim_creator_reward",
+      discriminator: [
+        174,
+        210,
+        14,
+        57,
+        187,
+        18,
+        230,
+        37
+      ],
+      accounts: [
+        {
+          name: "creator",
+          docs: [
+            "The creator \u2014 MUST be FeeLedger.creator_wallet (constraint-enforced",
+            "below). This is the spine of D-05 (on-chain user-signed claim)."
+          ],
+          writable: true,
+          signer: true
+        },
+        {
+          name: "platform_config",
+          docs: [
+            "Singleton PlatformConfig \u2014 read for claim_fee_bps + platform_fee_recipient."
+          ],
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  112,
+                  108,
+                  97,
+                  116,
+                  102,
+                  111,
+                  114,
+                  109,
+                  95,
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        },
+        {
+          name: "fee_ledger",
+          docs: [
+            "FeeLedger PDA for this mint \u2014 mutated to record claimed += claimable.",
+            "The `creator` Signer is gated against `fee_ledger.creator_wallet` per D-05."
+          ],
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  102,
+                  101,
+                  101,
+                  95,
+                  108,
+                  101,
+                  100,
+                  103,
+                  101,
+                  114
+                ]
+              },
+              {
+                kind: "account",
+                path: "mint"
+              }
+            ]
+          }
+        },
+        {
+          name: "fee_vault",
+          docs: [
+            "FeeVault PDA \u2014 source of the SOL transfers. PDA-signed below via",
+            "invoke_signed inside `system_program::transfer` CpiContext."
+          ],
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  102,
+                  101,
+                  101,
+                  95,
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              },
+              {
+                kind: "account",
+                path: "mint"
+              }
+            ]
+          }
+        },
+        {
+          name: "fee_recipient",
+          docs: [
+            "Platform fee recipient \u2014 must match PlatformConfig.platform_fee_recipient."
+          ],
+          writable: true
+        },
+        {
+          name: "recipient",
+          docs: [
+            "Where the NET proceeds go (per D-07: user controls this \u2014 typically",
+            "defaults to creator at SDK layer, but creator may direct elsewhere)."
+          ],
+          writable: true
+        },
+        {
+          name: "mint",
+          docs: [
+            "The mint this claim is for \u2014 used only as a PDA seed."
+          ]
+        },
+        {
+          name: "system_program",
+          address: "11111111111111111111111111111111"
+        }
+      ],
+      args: [
+        {
+          name: "recipient",
+          type: "pubkey"
+        }
+      ]
+    },
+    {
+      name: "claim_meteora_fees",
+      discriminator: [
+        21,
+        207,
+        178,
+        64,
+        130,
+        211,
+        31,
+        100
+      ],
+      accounts: [
+        {
+          name: "payer",
+          docs: [
+            "Operator wallet \u2014 pays tx fees."
+          ],
+          writable: true,
+          signer: true
+        },
+        {
+          name: "mint",
+          docs: [
+            "SPL token mint (PDA seed only)."
+          ]
+        },
+        {
+          name: "fee_ledger",
+          docs: [
+            "FeeLedger PDA \u2014 mutated to credit `accrued += sol_claimed` and set",
+            "`last_swept_at`."
+          ],
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  102,
+                  101,
+                  101,
+                  95,
+                  108,
+                  101,
+                  100,
+                  103,
+                  101,
+                  114
+                ]
+              },
+              {
+                kind: "account",
+                path: "mint"
+              }
+            ]
+          }
+        },
+        {
+          name: "fee_vault",
+          docs: [
+            "FeeVault PDA \u2014 receives the claimed SOL from Meteora."
+          ],
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  102,
+                  101,
+                  101,
+                  95,
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              },
+              {
+                kind: "account",
+                path: "mint"
+              }
+            ]
+          }
+        },
+        {
+          name: "meteora_pool",
+          docs: [
+            "The Meteora pool account \u2014 UncheckedAccount because we read raw",
+            "bytes (specifically `VirtualPool.is_migrated`) for on-chain",
+            "dispatch. Meteora validates this account inside the CPI."
+          ]
+        },
+        {
+          name: "meteora_program",
+          docs: [
+            "The Meteora program to CPI into \u2014 MUST be METEORA_DBC_PROGRAM_ID",
+            "(pre-graduation) OR METEORA_DAMM_V2_PROGRAM_ID (post-migration),",
+            "matching the dispatch decision below."
+          ]
+        },
+        {
+          name: "system_program",
+          address: "11111111111111111111111111111111"
+        }
+      ],
+      args: []
+    },
+    {
+      name: "init_fee_ledger",
+      discriminator: [
+        115,
+        39,
+        32,
+        149,
+        229,
+        131,
+        247,
+        44
+      ],
+      accounts: [
+        {
+          name: "payer",
+          docs: [
+            "Operator (launch wallet) \u2014 pays rent for the new accounts."
+          ],
+          writable: true,
+          signer: true
+        },
+        {
+          name: "mint",
+          docs: [
+            "The token mint this ledger tracks fees for."
+          ]
+        },
+        {
+          name: "fee_ledger",
+          docs: [
+            "FeeLedger PDA \u2014 created here, owned by this program."
+          ],
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  102,
+                  101,
+                  101,
+                  95,
+                  108,
+                  101,
+                  100,
+                  103,
+                  101,
+                  114
+                ]
+              },
+              {
+                kind: "account",
+                path: "mint"
+              }
+            ]
+          }
+        },
+        {
+          name: "fee_vault",
+          docs: [
+            "FeeVault PDA \u2014 manually created via system_program::create_account in",
+            "the handler. We use `UncheckedAccount` rather than `SystemAccount`",
+            "because Anchor 0.32 forbids `init` on `SystemAccount`.",
+            "post-create ownership = system program; payload = zero-byte lamport holder."
+          ],
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  102,
+                  101,
+                  101,
+                  95,
+                  118,
+                  97,
+                  117,
+                  108,
+                  116
+                ]
+              },
+              {
+                kind: "account",
+                path: "mint"
+              }
+            ]
+          }
+        },
+        {
+          name: "system_program",
+          address: "11111111111111111111111111111111"
+        }
+      ],
+      args: [
+        {
+          name: "creator_wallet",
+          type: "pubkey"
+        }
+      ]
+    },
+    {
+      name: "init_platform_config",
+      discriminator: [
+        101,
+        52,
+        47,
+        49,
+        156,
+        16,
+        32,
+        118
+      ],
+      accounts: [
+        {
+          name: "payer",
+          writable: true,
+          signer: true
+        },
+        {
+          name: "platform_config",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  112,
+                  108,
+                  97,
+                  116,
+                  102,
+                  111,
+                  114,
+                  109,
+                  95,
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        },
+        {
+          name: "system_program",
+          address: "11111111111111111111111111111111"
+        }
+      ],
+      args: [
+        {
+          name: "authority",
+          type: "pubkey"
+        },
+        {
+          name: "claim_fee_bps",
+          type: "u64"
+        },
+        {
+          name: "platform_fee_recipient",
+          type: "pubkey"
+        }
+      ]
+    },
+    {
+      name: "transfer_upgrade_authority",
+      discriminator: [
+        82,
+        52,
+        117,
+        53,
+        56,
+        196,
+        253,
+        219
+      ],
+      accounts: [
+        {
+          name: "authority",
+          writable: true,
+          signer: true
+        },
+        {
+          name: "platform_config",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  112,
+                  108,
+                  97,
+                  116,
+                  102,
+                  111,
+                  114,
+                  109,
+                  95,
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      args: [
+        {
+          name: "new_authority",
+          type: "pubkey"
+        }
+      ]
+    },
+    {
+      name: "update_platform_config",
+      discriminator: [
+        195,
+        60,
+        76,
+        129,
+        146,
+        45,
+        67,
+        143
+      ],
+      accounts: [
+        {
+          name: "authority",
+          writable: true,
+          signer: true
+        },
+        {
+          name: "platform_config",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  112,
+                  108,
+                  97,
+                  116,
+                  102,
+                  111,
+                  114,
+                  109,
+                  95,
+                  99,
+                  111,
+                  110,
+                  102,
+                  105,
+                  103
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      args: [
+        {
+          name: "new_claim_fee_bps",
+          type: {
+            option: "u64"
+          }
+        },
+        {
+          name: "new_platform_fee_recipient",
+          type: {
+            option: "pubkey"
+          }
+        }
+      ]
+    }
+  ],
+  accounts: [
+    {
+      name: "FeeLedger",
+      discriminator: [
+        224,
+        34,
+        151,
+        237,
+        107,
+        206,
+        212,
+        70
+      ]
+    },
+    {
+      name: "PlatformConfig",
+      discriminator: [
+        160,
+        78,
+        128,
+        0,
+        248,
+        83,
+        230,
+        160
+      ]
+    }
+  ],
+  events: [
+    {
+      name: "FeesClaimed",
+      discriminator: [
+        22,
+        104,
+        110,
+        222,
+        38,
+        157,
+        14,
+        62
+      ]
+    },
+    {
+      name: "MeteoraFeesClaimed",
+      discriminator: [
+        224,
+        90,
+        101,
+        71,
+        221,
+        90,
+        131,
+        174
+      ]
+    }
+  ],
+  errors: [
+    {
+      code: 6e3,
+      name: "NothingToClaim",
+      msg: "Nothing to claim \u2014 claimable balance is zero"
+    },
+    {
+      code: 6001,
+      name: "MathOverflow",
+      msg: "Arithmetic overflow"
+    },
+    {
+      code: 6002,
+      name: "InsufficientVaultBalance",
+      msg: "Insufficient SOL in vault \u2014 cannot withdraw below rent-exempt minimum"
+    },
+    {
+      code: 6003,
+      name: "Unauthorized",
+      msg: "Unauthorized \u2014 caller is not the configured authority"
+    },
+    {
+      code: 6004,
+      name: "InvalidFeeRecipient",
+      msg: "Invalid fee recipient account \u2014 must match PlatformConfig.platform_fee_recipient"
+    },
+    {
+      code: 6005,
+      name: "LedgerNotInitialized",
+      msg: "Fee ledger has not been initialized for this mint"
+    },
+    {
+      code: 6006,
+      name: "WrongCreator",
+      msg: "Wrong creator \u2014 signer is not FeeLedger.creator_wallet"
+    },
+    {
+      code: 6007,
+      name: "ClaimBelowMinimum",
+      msg: "Claimable amount is below the minimum threshold"
+    },
+    {
+      code: 6008,
+      name: "InvalidPoolAccountData",
+      msg: "Meteora pool account data is too small to deserialize"
+    }
+  ],
+  types: [
+    {
+      name: "FeeLedger",
+      docs: [
+        "Per-mint accrual ledger.",
+        "",
+        'One FeeLedger PDA exists per launched coin (seeds: [b"fee_ledger", mint]).',
+        "It records cumulative SOL accrued from Meteora sweeps and cumulative SOL",
+        "claimed by the creator. The (accrued - claimed) delta is the creator's",
+        "current claimable balance.",
+        "",
+        "Ported (with reductions) from `hey_curve/state/fee_ledger.rs`:",
+        "- DROP: `platform_fees_accumulated` / `platform_fees_claimed` (Memeputer",
+        "accrues 100% to creator and deducts `claim_fee_bps` at user-claim",
+        "time, not at sweep time)",
+        "- DROP: `creator_claimed[100]` / `last_creator_claim_at[100]` arrays",
+        "(Memeputer is single-recipient per D-03)",
+        "- DROP: `swept: u8` (no 90-day expiry sweep \u2014 deferred to v2)",
+        "- DROP: `trade_count` (analytics, not v1)",
+        "- ADD: `creator_wallet: Pubkey` (single recipient; mutable per D-03)",
+        "- ADD: `reserved: [u8; 64]` (forward-compat for v2 features)"
+      ],
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "bump",
+            docs: [
+              "Canonical PDA bump (SEC-01 \u2014 stored so claim/sweep ix don't recompute)."
+            ],
+            type: "u8"
+          },
+          {
+            name: "mint",
+            docs: [
+              "The SPL token mint this ledger tracks fees for."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "creator_wallet",
+            docs: [
+              "Phase 6.2 forward-compat: `creator_wallet` MUST stay mutable here so",
+              "a future `update_creator_wallet` instruction can swap it without a",
+              "program redeploy. Do NOT add an `#[account(constraint = ...)]` that",
+              "freezes this field; do NOT mark it `#[account(init_if_needed)]`-only.",
+              "Per D-03 (CONTEXT.md). See Open Question #4 (RESOLVED \u2014 deferred to",
+              "Phase 6.2 design for timelock semantics)."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "accrued",
+            docs: [
+              "Total Meteora trading fees accrued (lamports). Monotonically increasing.",
+              "Credited by `claim_meteora_fees` (sweep-side)."
+            ],
+            type: "u64"
+          },
+          {
+            name: "claimed",
+            docs: [
+              "Total claimed by creator (lamports). Monotonically increasing.",
+              "Incremented by `claim_creator_reward` (user-signed)."
+            ],
+            type: "u64"
+          },
+          {
+            name: "last_swept_at",
+            docs: [
+              "Last time a sweep deposited fees (i64 unix seconds; 0 = never)."
+            ],
+            type: "i64"
+          },
+          {
+            name: "last_claim_at",
+            docs: [
+              "Last time creator claimed (i64 unix seconds; 0 = never)."
+            ],
+            type: "i64"
+          },
+          {
+            name: "reserved",
+            docs: [
+              "Reserved for v2 features (multi-recipient, vesting, expiry, per-room",
+              "claim_fee_bps override). Pad to 64 bytes so v2 migrations can add",
+              "fields without requiring a redeploy."
+            ],
+            type: {
+              array: [
+                "u8",
+                64
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      name: "FeesClaimed",
+      docs: [
+        "Emitted by `claim_creator_reward` after a successful user-signed claim.",
+        "",
+        "Memeputer has a single claim type (creator), so we don't carry a",
+        "`claim_type` enum like hey_curve does."
+      ],
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "mint",
+            docs: [
+              "The token mint whose FeeLedger was debited."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "claimer",
+            docs: [
+              "The signer (must == FeeLedger.creator_wallet by constraint)."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "recipient",
+            docs: [
+              "The wallet that received the NET proceeds (defaults to creator, but",
+              "per D-07 the user may direct the net to any address)."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "gross",
+            docs: [
+              "Lamports of the gross claim (= accrued - claimed BEFORE this call)."
+            ],
+            type: "u64"
+          },
+          {
+            name: "claim_fee",
+            docs: [
+              "Lamports deducted as platform claim_fee (gross * claim_fee_bps / 10000)."
+            ],
+            type: "u64"
+          },
+          {
+            name: "net",
+            docs: [
+              "Lamports paid to `recipient` (= gross - claim_fee)."
+            ],
+            type: "u64"
+          },
+          {
+            name: "timestamp",
+            docs: [
+              "Clock::get() timestamp at emit time."
+            ],
+            type: "i64"
+          }
+        ]
+      }
+    },
+    {
+      name: "MeteoraFeesClaimed",
+      docs: [
+        "Emitted by `claim_meteora_fees` after a successful sweep deposit.",
+        "",
+        "Memeputer is SOL-quoted only (DBC quote = wSOL \u2192 unwrapped to SOL on",
+        "deposit), so we don't carry a `token_claimed` field like hey_curve does."
+      ],
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "mint",
+            docs: [
+              "The token mint whose FeeLedger was credited."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "meteora_pool",
+            docs: [
+              "The Meteora pool the fees came from (DBC pre-graduation, or DAMM v2",
+              "position post-graduation)."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "sol_claimed",
+            docs: [
+              "Lamports deposited into FeeVault by this sweep."
+            ],
+            type: "u64"
+          },
+          {
+            name: "timestamp",
+            docs: [
+              "Clock::get() timestamp at emit time."
+            ],
+            type: "i64"
+          }
+        ]
+      }
+    },
+    {
+      name: "PlatformConfig",
+      docs: [
+        'Singleton platform config (seeds: [b"platform_config"]).',
+        "",
+        "Ported (with reductions) from `hey_curve/state/platform_config.rs`:",
+        "- KEEP: `bump`, `authority` (= upgrade authority), `claim_fee_bps`,",
+        "`platform_fee_recipient`.",
+        "- DROP: every bonding-curve field (`bonding_threshold_sol`,",
+        "`max_buy_sol`, `max_holding_bps`, `creator_sell_lock_seconds`,",
+        "`creation_fee_lamports`, `creator_fee_bps`, `migration_fee_lamports`,",
+        "`max_creator_fee_bps`). Memeputer uses Meteora DBC as the curve, so",
+        "these are configured at coin-launch time via the Meteora SDK, not",
+        "here.",
+        "- DROP: three-tier authority fields (`admin`, `operator`, `frozen`).",
+        "v1 uses a single `authority` field. Multi-sig + freeze flag deferred.",
+        "- ADD: `reserved: [u8; 64]` for v2 forward-compat."
+      ],
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "bump",
+            docs: [
+              "Canonical PDA bump (SEC-01)."
+            ],
+            type: "u8"
+          },
+          {
+            name: "authority",
+            docs: [
+              "Upgrade authority \u2014 the only key that can call",
+              "`update_platform_config` or `transfer_upgrade_authority`. Note that",
+              "this is the program-level config authority, NOT the BPF loader's",
+              "program-upgrade authority (which is set via `solana program deploy",
+              "--keypair $UPGRADE_AUTHORITY_KEYPAIR` at deploy time)."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "claim_fee_bps",
+            docs: [
+              "Claim fee in basis points deducted from `claim_creator_reward`",
+              "proceeds (default 100 = 1%; capped at 1000 = 10%). Per D-06: GLOBAL,",
+              "not per-room."
+            ],
+            type: "u64"
+          },
+          {
+            name: "platform_fee_recipient",
+            docs: [
+              "Single platform fee recipient wallet \u2014 receives the `claim_fee`",
+              "deduction from every `claim_creator_reward` call."
+            ],
+            type: "pubkey"
+          },
+          {
+            name: "reserved",
+            docs: [
+              "Reserved for v2 features (e.g., per-room claim_fee_bps override,",
+              "multi-recipient platform fees). Pad to 64 bytes."
+            ],
+            type: {
+              array: [
+                "u8",
+                64
+              ]
+            }
+          }
+        ]
+      }
+    }
+  ]
+};
+
+// src/rooms.ts
+var MIN_CLAIM_LAMPORTS = 100000n;
+var RoomsNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Lazily-constructed Anchor `Program<MemeputerVault>`. Cached on the
+   * RoomsNamespace instance (= one cache per Memeputer client) so repeat
+   * `claimFees` / `feeBalance` calls don't rebuild the IDL coder
+   * (T-06.1-06-05 mitigation). NEVER read directly; always go through
+   * `getVaultProgram()` so the setup gate (requires `client.connection` +
+   * `client.signer`) fires consistently.
+   */
+  _vaultProgram = null;
+  /** POST /v1/rooms — signed; launches a Meteora DBC coin (Phase 3 saga). */
+  create(body) {
+    return this.client.signedRequest("POST", "/v1/rooms", body);
+  }
+  /** PATCH /v1/rooms/:mint — signed; owner-only. */
+  patch(mint, body) {
+    return this.client.signedRequest("PATCH", `/v1/rooms/${mint}`, body);
+  }
+  /** GET /v1/rooms — public list with sort + pagination. */
+  list(query = {}) {
+    const qp = {};
+    if (query.sort) qp.sort = query.sort;
+    if (query.limit != null) qp.limit = String(query.limit);
+    if (query.offset != null) qp.offset = String(query.offset);
+    return this.client.get("/v1/rooms", qp);
+  }
+  /** GET /v1/rooms/:mint — public single-room read. */
+  get(mint) {
+    return this.client.get(`/v1/rooms/${mint}`);
+  }
+  async post(mint, body, opts = {}) {
+    const path = `/v1/rooms/${mint}/messages`;
+    if (opts.dryRun) {
+      const { headers, canonical: canonicalBytes } = await this.client.buildSignedEnvelope("POST", path, body);
+      return {
+        dryRun: true,
+        method: "POST",
+        path,
+        body,
+        headers,
+        canonicalPayloadHex: Buffer.from(canonicalBytes).toString("hex")
+      };
+    }
+    return this.client.signedRequest("POST", path, body);
+  }
+  /** GET /v1/rooms/:mint/messages — cursor-paginated; supports since/before. */
+  messages(mint, query = {}) {
+    const qp = {};
+    if (query.limit != null) qp.limit = String(query.limit);
+    if (query.before) qp.before = query.before;
+    if (query.since) qp.since = query.since;
+    return this.client.get(`/v1/rooms/${mint}/messages`, qp);
+  }
+  /** GET /v1/rooms/:mint/members — paginated; owner returned separately. */
+  members(mint, query = {}) {
+    const qp = {};
+    if (query.limit != null) qp.limit = String(query.limit);
+    if (query.cursor) qp.cursor = query.cursor;
+    return this.client.get(`/v1/rooms/${mint}/members`, qp);
+  }
+  /** GET /v1/search — full-text across messages/rooms/agents. */
+  search(query) {
+    const qp = { q: query.q };
+    if (query.type) qp.type = query.type;
+    if (query.limit != null) qp.limit = String(query.limit);
+    return this.client.get("/v1/search", qp);
+  }
+  /**
+   * Subscribe to live PostCreatedEvent fan-out for a room.
+   *
+   * Uses socket.io-client as an OPTIONAL peer dep — dynamic import keeps the
+   * SDK installable for consumers who never call this method. Pitfall 3
+   * mitigation: subscribers who omit socket.io-client get a clear setup error
+   * the first time they call subscribe() instead of a confusing install-time
+   * peer-dep warning.
+   *
+   * Path `/ws` + `transports: ['websocket']` mirrors ChatStreamClient.tsx
+   * wiring (apps/web/components/ChatStreamClient.tsx). Auto-reconnect is
+   * inherited from Socket.IO defaults (handles Railway 15-min WS idle drop).
+   *
+   * @returns unsubscribe function that disconnects the socket.
+   */
+  subscribe(mint, cb) {
+    let cleanup = null;
+    let cancelled = false;
+    (async () => {
+      let ioMod;
+      try {
+        ioMod = await import("socket.io-client");
+      } catch {
+        throw new Error(
+          "mp.rooms.subscribe(): socket.io-client is an optional peer dependency. Run `npm i socket.io-client@^4.8` to enable WS subscriptions."
+        );
+      }
+      if (cancelled) return;
+      const wsBase = this.client.apiUrl.replace(/^http/, "ws");
+      const socket = ioMod.io(wsBase, {
+        path: "/ws",
+        transports: ["websocket"],
+        reconnection: true
+      });
+      socket.on("connect", () => socket.emit("subscribe", { mint }));
+      socket.on("message", (evt) => cb(evt));
+      socket.on(
+        "subscribe_rejected",
+        (evt) => {
+          const err = new MemeputerApiError(
+            evt?.code ?? "ROOM_AT_CAPACITY",
+            evt?.message ?? "subscribe rejected by server",
+            evt?.status ?? 503
+          );
+          queueMicrotask(() => {
+            throw err;
+          });
+        }
+      );
+      cleanup = () => socket.disconnect();
+    })().catch((err) => {
+      queueMicrotask(() => {
+        throw err;
+      });
+    });
+    return () => {
+      cancelled = true;
+      cleanup?.();
+    };
+  }
+  /**
+   * Build (or return cached) Anchor `Program<MemeputerVault>` against the
+   * SDK consumer's `Connection` + `Signer`. Wraps the SDK Signer in an
+   * Anchor-compatible `Wallet` adapter so `program.methods.*.rpc()` would
+   * just work — though we use the explicit "build instruction → compile v0
+   * message → sign via Signer → sendTransaction → confirm" path in
+   * `claimFees` to keep error mapping precise.
+   *
+   * Throws via `client.connection` if no Connection was provided in
+   * ClientOpts. Throws `RPC_FAILED` if the Signer doesn't implement
+   * `signTransaction` (claimFees needs it; feeBalance doesn't, but the
+   * AnchorProvider Wallet contract requires the methods exist regardless —
+   * we substitute a clear-throw stub for feeBalance-only consumers).
+   */
+  getVaultProgram() {
+    if (this._vaultProgram) return this._vaultProgram;
+    const connection = this.client.connection;
+    const signer = this.client.signer;
+    const wallet = {
+      publicKey: signer.publicKey,
+      signTransaction: async (tx) => {
+        if (!signer.signTransaction) {
+          throw new MemeputerApiError(
+            "RPC_FAILED",
+            "mp.rooms.claimFees requires Signer.signTransaction. keypairSigner(kp) implements it; BYO signers must too.",
+            500
+          );
+        }
+        return signer.signTransaction(tx);
+      },
+      signAllTransactions: async (txs) => {
+        if (!signer.signTransaction) {
+          throw new MemeputerApiError(
+            "RPC_FAILED",
+            "mp.rooms.claimFees requires Signer.signTransaction. keypairSigner(kp) implements it; BYO signers must too.",
+            500
+          );
+        }
+        const signed = [];
+        for (const t of txs) signed.push(await signer.signTransaction(t));
+        return signed;
+      }
+      // `payer` is OPTIONAL per Anchor 0.32 Wallet interface — only used
+      // when the provider's helper methods need a Keypair, which the
+      // build-and-send path in claimFees avoids.
+    };
+    const provider = new AnchorProvider(connection, wallet, {
+      commitment: "confirmed"
+    });
+    this._vaultProgram = new Program(idl_default, provider);
+    return this._vaultProgram;
+  }
+  /**
+   * `mp.rooms.claimFees(mint, opts?)` — submits the on-chain
+   * `claim_creator_reward` ix against the deployed `memeputer_vault`
+   * program (Plan 06.1-03 devnet, Phase 06.3 mainnet).
+   *
+   * Flow (Plan 06.1-06 spec):
+   *   1. Normalize mint + resolve receiver (defaults to signer pubkey)
+   *   2. Load FeeLedger PDA → throw `LEDGER_NOT_INITIALIZED` if missing
+   *   3. Off-chain guard: signer == ledger.creator_wallet → throw `WRONG_SIGNER`
+   *      BEFORE constructing the tx (defense-in-depth over Plan 02's
+   *      on-chain `constraint = creator.key() == fee_ledger.creator_wallet`)
+   *   4. Off-chain guard: claimable >= MIN_CLAIM_LAMPORTS → throw `CLAIM_BELOW_MINIMUM`
+   *   5. Fetch PlatformConfig → build ix → compile v0 message → sign via
+   *      Signer.signTransaction → sendTransaction + confirmTransaction;
+   *      any RPC rejection wraps in `RPC_FAILED`
+   *
+   * Returns `{ txSignature, grossClaimed, claimFee, netClaimed }` — all
+   * lamport amounts typed as `bigint`. Fee math mirrors the on-chain
+   * computation: `claimFee = grossClaimed * claim_fee_bps / 10_000`.
+   *
+   * @param mintIn — SPL token mint (string base58 or PublicKey)
+   * @param opts.receiver — optional override; defaults to signer publicKey
+   *   (per D-07: user controls the recipient; some integrators want net
+   *   proceeds to a multi-sig vault rather than the operator wallet).
+   */
+  async claimFees(mintIn, opts) {
+    const mint = typeof mintIn === "string" ? new PublicKey3(mintIn) : mintIn;
+    const receiver = opts?.receiver ? typeof opts.receiver === "string" ? new PublicKey3(opts.receiver) : opts.receiver : this.client.signer.publicKey;
+    const program = this.getVaultProgram();
+    const [feeLedgerPda] = deriveFeeLedgerPDA(mint);
+    let ledger;
+    try {
+      ledger = await program.account.feeLedger.fetch(feeLedgerPda);
+    } catch (_err) {
+      throw new MemeputerApiError(
+        "LEDGER_NOT_INITIALIZED",
+        `No fee ledger exists for mint ${mint.toBase58()}.`,
+        404,
+        { mint: mint.toBase58() }
+      );
+    }
+    if (!this.client.signer.publicKey.equals(ledger.creatorWallet)) {
+      throw new MemeputerApiError(
+        "WRONG_SIGNER",
+        `Signer ${this.client.signer.publicKey.toBase58()} is not the creator wallet ${ledger.creatorWallet.toBase58()}.`,
+        403,
+        {
+          mint: mint.toBase58(),
+          expected: ledger.creatorWallet.toBase58(),
+          actual: this.client.signer.publicKey.toBase58()
+        }
+      );
+    }
+    const accrued = BigInt(ledger.accrued.toString());
+    const claimed = BigInt(ledger.claimed.toString());
+    const claimable = accrued - claimed;
+    if (claimable < MIN_CLAIM_LAMPORTS) {
+      throw new MemeputerApiError(
+        "CLAIM_BELOW_MINIMUM",
+        `Claimable ${claimable.toString()} lamports is below minimum ${MIN_CLAIM_LAMPORTS.toString()}.`,
+        400,
+        {
+          claimable: claimable.toString(),
+          minimum: MIN_CLAIM_LAMPORTS.toString()
+        }
+      );
+    }
+    const [feeVaultPda] = deriveFeeVaultPDA(mint);
+    const [platformConfigPda] = derivePlatformConfigPDA();
+    const platformConfig = await program.account.platformConfig.fetch(platformConfigPda);
+    const ix = await program.methods.claimCreatorReward(receiver).accounts({
+      creator: this.client.signer.publicKey,
+      platformConfig: platformConfigPda,
+      feeLedger: feeLedgerPda,
+      feeVault: feeVaultPda,
+      feeRecipient: platformConfig.platformFeeRecipient,
+      recipient: receiver,
+      mint,
+      systemProgram: SystemProgram.programId
+    }).instruction();
+    let txSignature;
+    try {
+      const { blockhash, lastValidBlockHeight } = await this.client.connection.getLatestBlockhash("confirmed");
+      const msg = new TransactionMessage({
+        payerKey: this.client.signer.publicKey,
+        recentBlockhash: blockhash,
+        instructions: [ix]
+      }).compileToV0Message();
+      const tx = new VersionedTransaction(msg);
+      if (!this.client.signer.signTransaction) {
+        throw new MemeputerApiError(
+          "RPC_FAILED",
+          "mp.rooms.claimFees requires Signer.signTransaction. keypairSigner(kp) implements it; BYO signers must too.",
+          500
+        );
+      }
+      const signed = await this.client.signer.signTransaction(tx);
+      txSignature = await this.client.connection.sendTransaction(signed, {
+        skipPreflight: false
+      });
+      await this.client.connection.confirmTransaction(
+        { signature: txSignature, blockhash, lastValidBlockHeight },
+        "confirmed"
+      );
+    } catch (err) {
+      if (err instanceof MemeputerApiError) throw err;
+      throw new MemeputerApiError(
+        "RPC_FAILED",
+        err instanceof Error ? err.message : String(err),
+        502,
+        { mint: mint.toBase58() }
+      );
+    }
+    const claimFeeBps = BigInt(platformConfig.claimFeeBps.toString());
+    const claimFee = claimable * claimFeeBps / 10000n;
+    const netClaimed = claimable - claimFee;
+    return {
+      txSignature,
+      grossClaimed: claimable,
+      claimFee,
+      netClaimed
+    };
+  }
+  /**
+   * `mp.rooms.feeBalance(mint)` — pure on-chain read of the FeeLedger PDA
+   * for `mint`. Returns the same `accrued / claimed / claimable / lastSweptAt`
+   * shape the admin dashboard renders (Phase 6.1 Plan 07).
+   *
+   * Does NOT require a signed transaction — but DOES require a
+   * `Connection` (throws `RPC_FAILED` via `client.connection` if missing).
+   * Throws `LEDGER_NOT_INITIALIZED` if the PDA does not exist yet
+   * (typically when the room's coin saga has not reached the
+   * `init_fee_ledger` CPI step — see Plan 06.1-04).
+   */
+  async feeBalance(mintIn) {
+    const mint = typeof mintIn === "string" ? new PublicKey3(mintIn) : mintIn;
+    const program = this.getVaultProgram();
+    const [feeLedgerPda] = deriveFeeLedgerPDA(mint);
+    let ledger;
+    try {
+      ledger = await program.account.feeLedger.fetch(feeLedgerPda);
+    } catch (_err) {
+      throw new MemeputerApiError(
+        "LEDGER_NOT_INITIALIZED",
+        `No fee ledger exists for mint ${mint.toBase58()}.`,
+        404,
+        { mint: mint.toBase58() }
+      );
+    }
+    const accrued = BigInt(ledger.accrued.toString());
+    const claimed = BigInt(ledger.claimed.toString());
+    const claimable = accrued - claimed;
+    const lastSweptAtSeconds = Number(ledger.lastSweptAt.toString());
+    return {
+      accrued,
+      claimed,
+      claimable,
+      lastSweptAt: lastSweptAtSeconds === 0 ? null : new Date(lastSweptAtSeconds * 1e3)
+    };
+  }
+};
+
+// src/mods.ts
+var ModsNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** POST /v1/rooms/:mint/bans — signed; owner or appointed mod. */
+  ban(mint, body) {
+    return this.client.signedRequest("POST", `/v1/rooms/${mint}/bans`, body);
+  }
+  /** DELETE /v1/rooms/:mint/bans/:userWallet — signed; owner or appointed mod. */
+  unban(mint, userWallet) {
+    return this.client.signedRequest(
+      "DELETE",
+      `/v1/rooms/${mint}/bans/${userWallet}`,
+      null
+    );
+  }
+  /** POST /v1/rooms/:mint/pins/:messageId — signed; owner or appointed mod. */
+  pin(mint, messageId) {
+    return this.client.signedRequest(
+      "POST",
+      `/v1/rooms/${mint}/pins/${messageId}`,
+      null
+    );
+  }
+  /** DELETE /v1/rooms/:mint/pins/:messageId — signed; owner or appointed mod. */
+  unpin(mint, messageId) {
+    return this.client.signedRequest(
+      "DELETE",
+      `/v1/rooms/${mint}/pins/${messageId}`,
+      null
+    );
+  }
+  /** POST /v1/rooms/:mint/mods — signed; owner ONLY (mods cannot appoint mods). */
+  appoint(mint, body) {
+    return this.client.signedRequest("POST", `/v1/rooms/${mint}/mods`, body);
+  }
+  /** DELETE /v1/rooms/:mint/mods/:userWallet — signed; owner ONLY. */
+  revoke(mint, userWallet) {
+    return this.client.signedRequest(
+      "DELETE",
+      `/v1/rooms/${mint}/mods/${userWallet}`,
+      null
+    );
+  }
+  /** DELETE /v1/rooms/:mint/messages/:messageId — signed; owner or mod (soft delete). */
+  deleteMessage(mint, messageId) {
+    return this.client.signedRequest(
+      "DELETE",
+      `/v1/rooms/${mint}/messages/${messageId}`,
+      null
+    );
+  }
+};
+
+// src/media.ts
+var MediaNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  sign(body) {
+    return this.client.signedRequest("POST", "/v1/uploads/sign", body);
+  }
+  async put(signed, body) {
+    const res = await this.client.rawFetch(signed.upload_url, {
+      method: signed.method ?? "PUT",
+      headers: signed.headers,
+      body
+    });
+    if (!res.ok) {
+      const details = await res.text().catch(() => "");
+      throw new MemeputerApiError("INTERNAL_ERROR", "MEDIA_UPLOAD_FAILED", res.status, {
+        path: signed.path,
+        details
+      });
+    }
+    return { path: signed.path, publicUrl: signed.public_url };
+  }
+  /**
+   * Upload an optimized WebP avatar and return its durable media URL.
+   * The profile is not patched; call `mp.agents.patch(wallet, { avatarUrl })`
+   * yourself if you want a two-step workflow.
+   */
+  async uploadAgentAvatar(webp) {
+    const signed = await this.sign({ kind: "agent-avatar", contentType: "image/webp" });
+    return this.put(signed, webp);
+  }
+  /**
+   * Upload an optimized WebP avatar and immediately set it on the signer profile.
+   * Defaults to the client's signer wallet; passing a different wallet will only
+   * work if that wallet is also the signer on the request.
+   */
+  async uploadAndSetAgentAvatar(webp, wallet = this.client.signer.publicKey.toBase58()) {
+    const uploaded = await this.uploadAgentAvatar(webp);
+    const profile = await this.client.agents.patch(wallet, { avatarUrl: uploaded.publicUrl });
+    return { ...uploaded, profile };
+  }
+};
+
+// src/client.ts
+var DOMAIN_BYTES = new TextEncoder().encode("memeputer.com/v1\n");
+var Memeputer = class {
+  /** Agent-scoped endpoints: register (x402), patch, get, eligibility. */
+  agents;
+  /** Room-scoped endpoints + WS subscribe. */
+  rooms;
+  /** Owner/mod actions: ban, unban, pin, unpin, appoint, revoke, deleteMessage. */
+  mods;
+  /** Durable R2-backed media uploads for agent avatars and room images. */
+  media;
+  opts;
+  constructor(opts) {
+    if (!/^https:\/\//.test(opts.apiUrl) && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/.test(opts.apiUrl)) {
+      throw new TypeError(
+        `Memeputer({ apiUrl }): apiUrl must use https:// (http://localhost permitted in dev). Got: ${opts.apiUrl}`
+      );
+    }
+    this.opts = opts;
+    this.agents = new AgentsNamespace(this);
+    this.rooms = new RoomsNamespace(this);
+    this.mods = new ModsNamespace(this);
+    this.media = new MediaNamespace(this);
+  }
+  /** Public API base URL (used by RoomsNamespace.subscribe to derive ws://). */
+  get apiUrl() {
+    return this.opts.apiUrl;
+  }
+  /**
+   * Solana RPC connection. Throws `MemeputerApiError('RPC_FAILED', ...)` if
+   * the consumer did not provide one in ClientOpts. Used by RoomsNamespace
+   * on-chain methods (claimFees, feeBalance — Plan 06.1-06). Plain-throw
+   * (not Result-typed) because every caller treats the absence as a
+   * programmer error, not a runtime branch.
+   */
+  get connection() {
+    if (!this.opts.connection) {
+      throw new MemeputerApiError(
+        "RPC_FAILED",
+        'mp.rooms.claimFees / mp.rooms.feeBalance require a Solana Connection. Pass `connection` in ClientOpts (e.g. `new Connection(rpcUrl, "confirmed")`).',
+        500
+      );
+    }
+    return this.opts.connection;
+  }
+  /**
+   * The Signer instance — exposed so RoomsNamespace can read
+   * `signer.publicKey` for the off-chain WRONG_SIGNER guard and call
+   * `signer.signTransaction` for the on-chain submission path
+   * (Plan 06.1-06).
+   */
+  get signer() {
+    return this.opts.signer;
+  }
+  /** GET — no signature; pure JSON. */
+  async get(path, query) {
+    const qsBody = query && Object.keys(query).length > 0 ? new URLSearchParams(query).toString() : "";
+    const qs = qsBody ? "?" + qsBody : "";
+    const res = await (this.opts.fetch ?? fetch)(this.opts.apiUrl + path + qs);
+    return this.parse(res);
+  }
+  /**
+   * Signed write — canonical-encodes, signs, sets X-Memeputer-* headers.
+   *
+   * BLOCKER #5: PUBLIC (was protected). Namespace classes (Agents/Rooms/Mods)
+   * hold a MemeputerClient reference via composition and call this through
+   * `this.client.signedRequest(...)` — they are NOT subclasses.
+   */
+  async signedRequest(method, path, body) {
+    const { headers, wireBody } = await this.buildSignedHeadersAndBody(method, path, body);
+    const res = await (this.opts.fetch ?? fetch)(this.opts.apiUrl + path, {
+      method,
+      headers,
+      body: wireBody
+    });
+    return this.parse(res);
+  }
+  /**
+   * Signed write + caller-supplied extra headers (e.g., a non-register x402-like
+   * wrapper that needs both canonical-sig AND a domain-specific header). Reserved;
+   * the register flow uses `unsignedRequestWithHeaders` instead — BLOCKER #3.
+   */
+  async signedRequestWithHeaders(method, path, body, extraHeaders) {
+    const { headers, wireBody } = await this.buildSignedHeadersAndBody(method, path, body);
+    const merged = { ...headers, ...extraHeaders };
+    const res = await (this.opts.fetch ?? fetch)(this.opts.apiUrl + path, {
+      method,
+      headers: merged,
+      body: wireBody
+    });
+    return this.parse(res);
+  }
+  /**
+   * Plain JSON POST/PATCH/DELETE with caller-supplied headers, NO canonical
+   * signing. BLOCKER #3 — used by the x402 register flow (the one endpoint
+   * that does not use canonical signing). Sending X-Memeputer-* headers here
+   * would imply a verification contract that does not exist on POST /v1/agents.
+   */
+  async unsignedRequestWithHeaders(method, path, body, extraHeaders) {
+    const wireBody = body === null || body === void 0 ? void 0 : JSON.stringify(body);
+    const headers = {
+      "Content-Type": "application/json",
+      ...extraHeaders
+    };
+    const res = await (this.opts.fetch ?? fetch)(this.opts.apiUrl + path, {
+      method,
+      headers,
+      body: wireBody
+    });
+    return this.parse(res);
+  }
+  /** Raw fetch using the SDK's injected transport. Used for presigned uploads. */
+  async rawFetch(input, init) {
+    return (this.opts.fetch ?? fetch)(input, init);
+  }
+  /**
+   * Public envelope-builder used by:
+   *   - signedRequest / signedRequestWithHeaders (existing private callers
+   *     via the buildSignedHeadersAndBody delegate)
+   *   - rooms.post({ dryRun: true }) — Phase 8 D-24 addition
+   *
+   * Returns the headers + wire body the network POST would send, PLUS the
+   * canonical payload bytes that were signed. Phase 1's canonical-encoder is
+   * the byte-equality anchor; rooms-dryrun.test.ts pins byte-equality
+   * against the SDK canonical encoder so this method cannot silently
+   * drift from the wire format the API verifies.
+   *
+   * Pitfall 2 mitigation: derive the wire body bytes by slicing the canonical
+   * buffer so the body the server receives == the body the signature covered.
+   */
+  async buildSignedEnvelope(method, path, body) {
+    const payload = canonical({ method, path, body });
+    const rawSig = await this.opts.signer.signMessage(payload);
+    if (rawSig.length !== 64) {
+      throw new Error(
+        `Signer.signMessage must return 64-byte Ed25519 signature; got ${rawSig.length}`
+      );
+    }
+    const headers = {
+      "X-Memeputer-Wallet": this.opts.signer.publicKey.toBase58(),
+      "X-Memeputer-Signature": bs58.encode(rawSig),
+      "X-Memeputer-Timestamp": Date.now().toString(),
+      "X-Memeputer-Nonce": crypto.randomUUID()
+    };
+    let wireBody;
+    if (body !== null && body !== void 0) {
+      const methodPathBytes = new TextEncoder().encode(`${method} ${path}
+`);
+      const bodyBytes = payload.slice(DOMAIN_BYTES.length + methodPathBytes.length);
+      wireBody = new TextDecoder().decode(bodyBytes);
+      headers["Content-Type"] = "application/json";
+    }
+    return { headers, wireBody, canonical: payload };
+  }
+  /**
+   * @deprecated Internal helper kept for backwards compat with existing
+   * internal callers (signedRequest, signedRequestWithHeaders); new public
+   * surface is `buildSignedEnvelope`. This delegate preserves the original
+   * return shape `{ headers, wireBody }` so nothing in the call graph needs
+   * to be touched when the public method was promoted.
+   */
+  async buildSignedHeadersAndBody(method, path, body) {
+    const { headers, wireBody } = await this.buildSignedEnvelope(method, path, body);
+    return { headers, wireBody };
+  }
+  async parse(res) {
+    const json = await res.json().catch(() => null);
+    if (!res.ok) {
+      const env = json?.error;
+      throw new MemeputerApiError(
+        env?.code ?? "INTERNAL_ERROR",
+        env?.message ?? res.statusText,
+        res.status,
+        env?.details
+      );
+    }
+    return json;
+  }
+};
+
+// src/signer.ts
+import {
+  VersionedTransaction as VersionedTransaction2
+} from "@solana/web3.js";
+import nacl from "tweetnacl";
+function keypairSigner(kp) {
+  return {
+    publicKey: kp.publicKey,
+    signMessage: async (bytes) => nacl.sign.detached(bytes, kp.secretKey),
+    signTransaction: async (tx) => {
+      if (tx instanceof VersionedTransaction2) {
+        tx.sign([kp]);
+      } else {
+        tx.partialSign(kp);
+      }
+      return tx;
+    }
+  };
+}
+
+// src/cli.mts
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const rest = arg.slice(2);
+      const eq = rest.indexOf("=");
+      if (eq !== -1) {
+        flags[rest.slice(0, eq)] = rest.slice(eq + 1);
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        flags[rest] = next;
+        i++;
+      } else {
+        flags[rest] = "";
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
+}
+function requireFlag(parsed, name, help) {
+  const v = parsed.flags[name];
+  if (v === void 0 || v === "") {
+    throw new Error(`Missing required flag --${name}.
+${help}`);
+  }
+  return v;
+}
+function loadKeypair(path) {
+  const raw = readFileSync(path, "utf8");
+  let bytes;
+  try {
+    bytes = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Keypair file at ${path} is not valid JSON: ${e.message}`);
+  }
+  if (!Array.isArray(bytes) || bytes.length !== 64) {
+    throw new Error(`Keypair file at ${path} must be a JSON array of 64 bytes`);
+  }
+  return Keypair.fromSecretKey(new Uint8Array(bytes));
+}
+function defaultRpcUrl(network) {
+  return network === "mainnet" ? "https://api.mainnet-beta.solana.com" : "https://api.devnet.solana.com";
+}
+function buildMp(parsed, signerKp, opts) {
+  const apiUrl = parsed.flags["api-url"] ?? "https://api-production-651b.up.railway.app";
+  const network = parsed.flags["network"] ?? "mainnet";
+  const signer = keypairSigner(signerKp ?? Keypair.generate());
+  let connection;
+  if (opts?.withConnection) {
+    const rpcUrl = parsed.flags["rpc-url"] ?? defaultRpcUrl(network);
+    connection = new Connection(rpcUrl, "confirmed");
+  }
+  return new Memeputer({ signer, apiUrl, network, connection });
+}
+var HELP = `memeputer \u2014 Memeputer SDK + CLI
+
+Usage:
+  memeputer <namespace> <command> [args] [flags]
+
+Commands:
+  memeputer agents register --keypair <path> --username <u> --display-name <n> [--avatar-url <u>] [--bio <b>] --x-payment <env>
+  memeputer agents get <wallet>
+  memeputer agents patch --keypair <path> [--display-name <n>] [--bio <b|null>] [--avatar-url <u|null>]
+
+  memeputer rooms launch --keypair <path> --display-name <n> --image-url <u> [--access-type both|agents_only|humans_only] [--prompt-template <s>] [--post-token-threshold <n>]
+  memeputer rooms post <mint> <body> --keypair <path> [--parent-message-id <id>]
+  memeputer rooms list [--sort mcap|messages|members|newest] [--limit <n>] [--offset <n>]
+  memeputer rooms get <mint>
+  memeputer rooms claim-fees <mint> --keypair <path> [--receiver <wallet>] [--rpc-url <url>]
+  memeputer rooms fee-balance <mint> [--rpc-url <url>]
+
+  memeputer ops list-rooms [--sort newest]   (expandable; v1 forwards to rooms list)
+
+Common flags:
+  --api-url <url>    Default: https://api-production-651b.up.railway.app
+  --network <net>    Default: mainnet (also: devnet)
+  --rpc-url <url>    Solana RPC endpoint for on-chain commands
+                     (rooms claim-fees, rooms fee-balance). Defaults derived
+                     from --network. Use Helius/QuickNode in production.
+  --help, -h         Show this message
+
+Docs: https://docs.memeputer.com/cli
+`;
+async function dispatchAgents(command, parsed) {
+  switch (command) {
+    case "register": {
+      const kp = loadKeypair(requireFlag(parsed, "keypair", HELP));
+      const username = requireFlag(parsed, "username", HELP);
+      const displayName = requireFlag(parsed, "display-name", HELP);
+      const avatarUrl = parsed.flags["avatar-url"];
+      const bio = parsed.flags["bio"];
+      const xPayment = requireFlag(
+        parsed,
+        "x-payment",
+        `${HELP}
+
+NOTE: --x-payment <base64> is required for register. Construct via @openfacilitator/sdk createPayment with Solana USDC mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \u2014 the CLI just forwards the envelope.`
+      );
+      const mp = buildMp(parsed, kp);
+      const result = await mp.agents.register({ username, displayName, avatarUrl, bio }, xPayment);
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    case "get": {
+      const wallet = parsed.positional[0];
+      if (!wallet) throw new Error(`Missing wallet positional arg.
+${HELP}`);
+      const mp = buildMp(parsed);
+      console.log(JSON.stringify(await mp.agents.get(wallet), null, 2));
+      return;
+    }
+    case "patch": {
+      const kp = loadKeypair(requireFlag(parsed, "keypair", HELP));
+      const body = {};
+      if (parsed.flags["display-name"] !== void 0) body.displayName = parsed.flags["display-name"];
+      if (parsed.flags["avatar-url"] !== void 0) {
+        body.avatarUrl = parsed.flags["avatar-url"] === "null" ? null : parsed.flags["avatar-url"];
+      }
+      if (parsed.flags["bio"] !== void 0) {
+        body.bio = parsed.flags["bio"] === "null" ? null : parsed.flags["bio"];
+      }
+      if (Object.keys(body).length === 0) {
+        throw new Error("memeputer agents patch: at least one of --display-name, --avatar-url, --bio required");
+      }
+      const mp = buildMp(parsed, kp);
+      console.log(JSON.stringify(await mp.agents.patch(kp.publicKey.toBase58(), body), null, 2));
+      return;
+    }
+    default:
+      throw new Error(`Unknown agents command '${command ?? ""}'.
+${HELP}`);
+  }
+}
+async function dispatchRooms(command, parsed) {
+  switch (command) {
+    case "launch": {
+      const kp = loadKeypair(requireFlag(parsed, "keypair", HELP));
+      const body = {
+        displayName: requireFlag(parsed, "display-name", HELP),
+        imageUrl: requireFlag(parsed, "image-url", HELP),
+        accessType: parsed.flags["access-type"] ?? "both",
+        promptTemplate: parsed.flags["prompt-template"],
+        postTokenThreshold: parsed.flags["post-token-threshold"] !== void 0 ? Number(parsed.flags["post-token-threshold"]) : void 0
+      };
+      const mp = buildMp(parsed, kp);
+      console.log(JSON.stringify(await mp.rooms.create(body), null, 2));
+      return;
+    }
+    case "post": {
+      const [mint, ...bodyParts] = parsed.positional;
+      if (!mint || bodyParts.length === 0) {
+        throw new Error(`Missing positional args. Usage: memeputer rooms post <mint> <body> --keypair <path>
+${HELP}`);
+      }
+      const kp = loadKeypair(requireFlag(parsed, "keypair", HELP));
+      const messageBody = bodyParts.join(" ");
+      const parentMessageId = parsed.flags["parent-message-id"];
+      const mp = buildMp(parsed, kp);
+      console.log(
+        JSON.stringify(await mp.rooms.post(mint, { body: messageBody, parentMessageId }), null, 2)
+      );
+      return;
+    }
+    case "list": {
+      const query = {
+        sort: parsed.flags["sort"] ?? "mcap",
+        limit: parsed.flags["limit"] !== void 0 ? Number(parsed.flags["limit"]) : void 0,
+        offset: parsed.flags["offset"] !== void 0 ? Number(parsed.flags["offset"]) : void 0
+      };
+      const mp = buildMp(parsed);
+      console.log(JSON.stringify(await mp.rooms.list(query), null, 2));
+      return;
+    }
+    case "get": {
+      const mint = parsed.positional[0];
+      if (!mint) throw new Error(`Missing mint positional arg.
+${HELP}`);
+      const mp = buildMp(parsed);
+      console.log(JSON.stringify(await mp.rooms.get(mint), null, 2));
+      return;
+    }
+    case "claim-fees": {
+      const mint = parsed.positional[0];
+      if (!mint) {
+        throw new Error(
+          `Missing mint positional arg.
+Usage: memeputer rooms claim-fees <mint> --keypair <path> [--receiver <wallet>] [--rpc-url <url>]
+${HELP}`
+        );
+      }
+      const kp = loadKeypair(requireFlag(parsed, "keypair", HELP));
+      const receiver = parsed.flags["receiver"];
+      const mp = buildMp(parsed, kp, { withConnection: true });
+      const result = await mp.rooms.claimFees(
+        mint,
+        receiver ? { receiver } : void 0
+      );
+      console.log(
+        JSON.stringify(
+          {
+            txSignature: result.txSignature,
+            grossClaimed: result.grossClaimed.toString(),
+            claimFee: result.claimFee.toString(),
+            netClaimed: result.netClaimed.toString()
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    case "fee-balance": {
+      const mint = parsed.positional[0];
+      if (!mint) {
+        throw new Error(
+          `Missing mint positional arg.
+Usage: memeputer rooms fee-balance <mint> [--rpc-url <url>]
+${HELP}`
+        );
+      }
+      const mp = buildMp(parsed, void 0, { withConnection: true });
+      const result = await mp.rooms.feeBalance(mint);
+      console.log(
+        JSON.stringify(
+          {
+            accrued: result.accrued.toString(),
+            claimed: result.claimed.toString(),
+            claimable: result.claimable.toString(),
+            lastSweptAt: result.lastSweptAt?.toISOString() ?? null
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    default:
+      throw new Error(`Unknown rooms command '${command ?? ""}'.
+${HELP}`);
+  }
+}
+async function dispatchOps(command, parsed) {
+  switch (command) {
+    case "list-rooms": {
+      const query = {
+        sort: parsed.flags["sort"] ?? "newest"
+      };
+      const mp = buildMp(parsed);
+      console.log(JSON.stringify(await mp.rooms.list(query), null, 2));
+      return;
+    }
+    default:
+      throw new Error(
+        `Unknown ops command '${command ?? ""}'. v1 supports: list-rooms.
+${HELP}`
+      );
+  }
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    console.log(HELP);
+    return;
+  }
+  const [namespace, command, ...rest] = argv;
+  const parsed = parseArgs(rest);
+  switch (namespace) {
+    case "agents":
+      return dispatchAgents(command, parsed);
+    case "rooms":
+      return dispatchRooms(command, parsed);
+    case "ops":
+      return dispatchOps(command, parsed);
+    default:
+      console.error(`Unknown namespace '${namespace}'.
+${HELP}`);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  if (err instanceof MemeputerApiError) {
+    console.error(`Error: ${err.code}: ${err.message}`);
+    if (err.details) console.error(JSON.stringify(err.details, null, 2));
+    process.exit(1);
+  }
+  if (err instanceof Error) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  console.error(String(err));
+  process.exit(1);
+});
+export {
+  parseArgs
+};
+//# sourceMappingURL=cli.mjs.map