@caypo/mpp-canton 0.1.0

package/src/__tests__/server.test.ts

@@ -0,0 +1,361 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cantonServer, MppVerificationError, type CantonMppServerConfig } from "../server.js";
+import type { CantonCredentialPayload, CantonRequest } from "../schemas.js";
+import type { CredentialData } from "mppx";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const GATEWAY_PARTY = "Gateway::1220bbbb";
+const AGENT_PARTY = "Agent::1220aaaa";
+
+const serverConfig: CantonMppServerConfig = {
+  ledgerUrl: "http://localhost:7575",
+  token: "server-jwt",
+  userId: "ledger-api-user",
+  recipientPartyId: GATEWAY_PARTY,
+  network: "testnet",
+};
+
+function makeCredential(
+  overrides?: Partial<CantonCredentialPayload>,
+  requestOverrides?: Partial<CantonRequest>,
+): CredentialData<CantonCredentialPayload, CantonRequest> {
+  return {
+    challenge: {
+      request: {
+        amount: "1.50",
+        currency: "USDCx",
+        recipient: GATEWAY_PARTY,
+        network: "testnet",
+        expiry: 300,
+        ...requestOverrides,
+      },
+    },
+    payload: {
+      updateId: "upd-123",
+      completionOffset: 42,
+      sender: AGENT_PARTY,
+      commandId: "cmd-456",
+      ...overrides,
+    },
+  };
+}
+
+function makeTransactionResponse(holdingAmount: string, recipientParty: string, senderParty: string) {
+  return {
+    updateId: "upd-123",
+    eventsById: {
+      "evt-1": {
+        exercisedEvent: {
+          contractId: "factory-cid",
+          choice: "TransferFactory_Transfer",
+          actingParties: [senderParty],
+        },
+      },
+      "evt-2": {
+        createdEvent: {
+          contractId: "new-holding",
+          templateId: "Splice.Api.Token.HoldingV1:Holding",
+          createArgument: { amount: holdingAmount, owner: recipientParty },
+          witnessParties: [recipientParty],
+          signatories: [recipientParty],
+          observers: [],
+        },
+      },
+    },
+    rootEventIds: ["evt-1"],
+  };
+}
+
+const mockFetch = vi.fn<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>();
+
+beforeEach(() => {
+  vi.stubGlobal("fetch", mockFetch);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// cantonServer — verify — success
+// ---------------------------------------------------------------------------
+
+describe("cantonServer.verify — success", () => {
+  it("returns receipt on valid credential", async () => {
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse(makeTransactionResponse("1.50", GATEWAY_PARTY, AGENT_PARTY)),
+    );
+
+    const server = cantonServer(serverConfig);
+    const receipt = await server.verify({ credential: makeCredential() });
+
+    expect(receipt.method).toBe("canton");
+    expect(receipt.reference).toBe("upd-123");
+    expect(receipt.status).toBe("success");
+    expect(receipt.timestamp).toBeTruthy();
+  });
+
+  it("accepts overpayment (amount > required)", async () => {
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse(makeTransactionResponse("5.00", GATEWAY_PARTY, AGENT_PARTY)),
+    );
+
+    const server = cantonServer(serverConfig);
+    const receipt = await server.verify({ credential: makeCredential() });
+
+    expect(receipt.status).toBe("success");
+  });
+
+  it("fetches transaction with correct URL and auth header", async () => {
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse(makeTransactionResponse("1.50", GATEWAY_PARTY, AGENT_PARTY)),
+    );
+
+    const server = cantonServer(serverConfig);
+    await server.verify({ credential: makeCredential() });
+
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe("http://localhost:7575/v2/updates/transaction-by-id/upd-123");
+    expect((init?.headers as Record<string, string>).Authorization).toBe("Bearer server-jwt");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// cantonServer — verify — error cases
+// ---------------------------------------------------------------------------
+
+describe("cantonServer.verify — network mismatch", () => {
+  it("throws MppVerificationError on wrong network", async () => {
+    const server = cantonServer(serverConfig);
+
+    try {
+      await server.verify({
+        credential: makeCredential({}, { network: "mainnet" }),
+      });
+      expect.fail("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(MppVerificationError);
+      expect((err as MppVerificationError).problemCode).toBe("verification-failed");
+      expect((err as MppVerificationError).message).toContain("Network mismatch");
+    }
+  });
+});
+
+describe("cantonServer.verify — recipient mismatch", () => {
+  it("throws MppVerificationError on wrong recipient", async () => {
+    const server = cantonServer(serverConfig);
+
+    try {
+      await server.verify({
+        credential: makeCredential({}, { recipient: "Other::1220cccc" }),
+      });
+      expect.fail("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(MppVerificationError);
+      expect((err as MppVerificationError).problemCode).toBe("verification-failed");
+      expect((err as MppVerificationError).message).toContain("Recipient mismatch");
+    }
+  });
+});
+
+describe("cantonServer.verify — transaction not found", () => {
+  it("throws when ledger returns 404", async () => {
+    mockFetch.mockResolvedValueOnce(new Response("Not found", { status: 404 }));
+
+    const server = cantonServer(serverConfig);
+
+    try {
+      await server.verify({ credential: makeCredential() });
+      expect.fail("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(MppVerificationError);
+      expect((err as MppVerificationError).problemCode).toBe("verification-failed");
+      expect((err as MppVerificationError).message).toContain("Transaction not found");
+    }
+  });
+});
+
+describe("cantonServer.verify — insufficient amount", () => {
+  it("throws when received less than required", async () => {
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse(makeTransactionResponse("0.50", GATEWAY_PARTY, AGENT_PARTY)),
+    );
+
+    const server = cantonServer(serverConfig);
+
+    try {
+      await server.verify({ credential: makeCredential() });
+      expect.fail("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(MppVerificationError);
+      expect((err as MppVerificationError).problemCode).toBe("payment-insufficient");
+      expect((err as MppVerificationError).message).toContain("Payment insufficient");
+    }
+  });
+});
+
+describe("cantonServer.verify — no holding for recipient", () => {
+  it("throws when no created Holding event for gateway party", async () => {
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse({
+        updateId: "upd-123",
+        eventsById: {
+          "evt-1": {
+            exercisedEvent: {
+              contractId: "factory-cid",
+              choice: "TransferFactory_Transfer",
+              actingParties: [AGENT_PARTY],
+            },
+          },
+          // Holding created for wrong party
+          "evt-2": {
+            createdEvent: {
+              contractId: "new-holding",
+              templateId: "Splice.Api.Token.HoldingV1:Holding",
+              createArgument: { amount: "1.50", owner: "Other::1220dddd" },
+              witnessParties: ["Other::1220dddd"],
+              signatories: ["Other::1220dddd"],
+              observers: [],
+            },
+          },
+        },
+        rootEventIds: ["evt-1"],
+      }),
+    );
+
+    const server = cantonServer(serverConfig);
+
+    try {
+      await server.verify({ credential: makeCredential() });
+      expect.fail("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(MppVerificationError);
+      expect((err as MppVerificationError).message).toContain("No holding created for recipient");
+    }
+  });
+});
+
+describe("cantonServer.verify — sender mismatch", () => {
+  it("throws when sender did not exercise the transfer", async () => {
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse({
+        updateId: "upd-123",
+        eventsById: {
+          // Different party exercised
+          "evt-1": {
+            exercisedEvent: {
+              contractId: "factory-cid",
+              choice: "TransferFactory_Transfer",
+              actingParties: ["Intruder::1220eeee"],
+            },
+          },
+          "evt-2": {
+            createdEvent: {
+              contractId: "new-holding",
+              templateId: "Splice.Api.Token.HoldingV1:Holding",
+              createArgument: { amount: "1.50", owner: GATEWAY_PARTY },
+              witnessParties: [GATEWAY_PARTY],
+              signatories: [GATEWAY_PARTY],
+              observers: [],
+            },
+          },
+        },
+        rootEventIds: ["evt-1"],
+      }),
+    );
+
+    const server = cantonServer(serverConfig);
+
+    try {
+      await server.verify({ credential: makeCredential() });
+      expect.fail("should throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(MppVerificationError);
+      expect((err as MppVerificationError).problemCode).toBe("verification-failed");
+      expect((err as MppVerificationError).message).toContain("Sender mismatch");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Round-trip test
+// ---------------------------------------------------------------------------
+
+describe("round-trip: client credential → server verify", () => {
+  it("full flow succeeds", async () => {
+    // --- Client side: 3 fetch calls ---
+    // 1. getLedgerEnd
+    mockFetch.mockResolvedValueOnce(jsonResponse({ offset: 100 }));
+    // 2. queryActiveContracts
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse({
+        contractEntry: [
+          {
+            createdEvent: {
+              contractId: "hold-rt",
+              templateId: "Splice.Api.Token.HoldingV1:Holding",
+              createArgument: { amount: "10.000000", owner: AGENT_PARTY },
+              witnessParties: [AGENT_PARTY],
+              signatories: [AGENT_PARTY],
+              observers: [],
+            },
+          },
+        ],
+      }),
+    );
+    // 3. submitAndWait
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse({ updateId: "upd-roundtrip", completionOffset: 101 }),
+    );
+
+    // Create credential via client
+    const { cantonClient: makeClient } = await import("../client.js");
+    const client = makeClient({
+      ledgerUrl: "http://localhost:7575",
+      token: "agent-jwt",
+      userId: "ledger-api-user",
+      partyId: AGENT_PARTY,
+      network: "testnet",
+    });
+
+    const credentialStr = await client.createCredential({
+      challenge: {
+        request: {
+          amount: "2.00",
+          currency: "USDCx" as const,
+          recipient: GATEWAY_PARTY,
+          network: "testnet" as const,
+          expiry: 300,
+        },
+      },
+    });
+
+    // --- Server side: 1 fetch call ---
+    // Deserialize to get the payload
+    const { Credential } = await import("mppx");
+    const decoded = Credential.deserialize<CantonCredentialPayload, CantonRequest>(credentialStr);
+
+    // Mock the transaction fetch for server verification
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse(makeTransactionResponse("2.00", GATEWAY_PARTY, AGENT_PARTY)),
+    );
+
+    const { cantonServer: makeServer } = await import("../server.js");
+    const server = makeServer(serverConfig);
+    const receipt = await server.verify({ credential: decoded });
+
+    expect(receipt.method).toBe("canton");
+    expect(receipt.reference).toBe("upd-roundtrip");
+    expect(receipt.status).toBe("success");
+  });
+});

package/src/client.ts

@@ -0,0 +1,198 @@
+/**
+ * Canton MPP client — used by agents to pay for services.
+ *
+ * Flow:
+ * 1. Receive 402 challenge with amount, recipient, network
+ * 2. Validate network matches agent config
+ * 3. Query agent's USDCx holdings via Ledger API
+ * 4. Select holdings covering the required amount
+ * 5. Exercise TransferFactory_Transfer (1-step, requires recipient TransferPreapproval)
+ * 6. Return serialized credential with updateId + completionOffset
+ */
+
+import { Credential, Method, type Challenge } from "mppx";
+import { cantonMethod } from "./method.js";
+import type { CantonRequest } from "./schemas.js";
+
+const USDCX_HOLDING_TEMPLATE_ID = "Splice.Api.Token.HoldingV1:Holding";
+const TRANSFER_FACTORY_TEMPLATE_ID = "Splice.Api.Token.TransferFactoryV1:TransferFactory";
+const USDCX_INSTRUMENT_ID = "USDCx";
+
+export type CantonNetwork = "mainnet" | "testnet" | "devnet";
+
+export interface CantonMppClientConfig {
+  ledgerUrl: string;
+  token: string;
+  userId: string;
+  partyId: string;
+  network: CantonNetwork;
+}
+
+interface HoldingContract {
+  contractId: string;
+  amount: string;
+}
+
+async function fetchJson(url: string, token: string, init?: RequestInit): Promise<unknown> {
+  const response = await fetch(url, {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+      ...(init?.headers as Record<string, string>),
+    },
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`Canton API error: HTTP ${response.status} — ${text}`);
+  }
+
+  return response.json();
+}
+
+async function getLedgerEnd(config: CantonMppClientConfig): Promise<number> {
+  const data = (await fetchJson(`${config.ledgerUrl}/v2/state/ledger-end`, config.token)) as {
+    offset: number;
+  };
+  return data.offset;
+}
+
+async function queryHoldings(config: CantonMppClientConfig): Promise<HoldingContract[]> {
+  const offset = await getLedgerEnd(config);
+
+  const data = (await fetchJson(`${config.ledgerUrl}/v2/state/active-contracts`, config.token, {
+    method: "POST",
+    body: JSON.stringify({
+      eventFormat: {
+        filtersByParty: {
+          [config.partyId]: {
+            cumulative: [
+              {
+                identifierFilter: {
+                  TemplateFilter: {
+                    value: { templateId: USDCX_HOLDING_TEMPLATE_ID },
+                  },
+                },
+              },
+            ],
+          },
+        },
+        verbose: true,
+      },
+      activeAtOffset: offset,
+    }),
+  })) as {
+    contractEntry?: Array<{
+      createdEvent?: { contractId: string; createArgument: { amount: string } };
+    }>;
+  };
+
+  return (data.contractEntry ?? [])
+    .filter((e) => e.createdEvent != null)
+    .map((e) => ({
+      contractId: e.createdEvent!.contractId,
+      amount: e.createdEvent!.createArgument.amount,
+    }));
+}
+
+function selectHoldings(
+  holdings: HoldingContract[],
+  requiredAmount: string,
+): string[] {
+  if (holdings.length === 0) {
+    throw new Error(`Insufficient balance: no holdings available`);
+  }
+
+  // Sort descending
+  const sorted = [...holdings].sort(
+    (a, b) => parseFloat(b.amount) - parseFloat(a.amount),
+  );
+
+  // Try single holding
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    if (parseFloat(sorted[i].amount) >= parseFloat(requiredAmount)) {
+      return [sorted[i].contractId];
+    }
+  }
+
+  // Accumulate multiple
+  let total = 0;
+  const selected: string[] = [];
+  for (const h of sorted) {
+    selected.push(h.contractId);
+    total += parseFloat(h.amount);
+    if (total >= parseFloat(requiredAmount)) {
+      return selected;
+    }
+  }
+
+  throw new Error(
+    `Insufficient balance: have ${total}, need ${requiredAmount}`,
+  );
+}
+
+export function cantonClient(config: CantonMppClientConfig) {
+  return Method.toClient(cantonMethod, {
+    async createCredential({ challenge }: { challenge: Challenge<CantonRequest> }) {
+      // 1. Validate network
+      if (challenge.request.network !== config.network) {
+        throw new Error(
+          `Network mismatch: challenge requires ${challenge.request.network}, agent configured for ${config.network}`,
+        );
+      }
+
+      // 2. Query holdings
+      const holdings = await queryHoldings(config);
+
+      // 3. Select holdings covering amount
+      const selectedCids = selectHoldings(holdings, challenge.request.amount);
+
+      // 4. Generate commandId
+      const commandId = crypto.randomUUID();
+
+      // 5. Exercise TransferFactory_Transfer
+      const result = (await fetchJson(
+        `${config.ledgerUrl}/v2/commands/submit-and-wait`,
+        config.token,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            commands: [
+              {
+                ExerciseCommand: {
+                  templateId: TRANSFER_FACTORY_TEMPLATE_ID,
+                  contractId: selectedCids[0],
+                  choice: "TransferFactory_Transfer",
+                  choiceArgument: {
+                    sender: config.partyId,
+                    receiver: challenge.request.recipient,
+                    amount: challenge.request.amount,
+                    instrumentId: USDCX_INSTRUMENT_ID,
+                    inputHoldingCids: selectedCids,
+                    meta: {},
+                  },
+                },
+              },
+            ],
+            userId: config.userId,
+            commandId,
+            actAs: [config.partyId],
+            readAs: [config.partyId],
+          }),
+        },
+      )) as { updateId: string; completionOffset: number };
+
+      // 6. Return serialized credential
+      return Credential.serialize({
+        challenge,
+        payload: {
+          updateId: result.updateId,
+          completionOffset: result.completionOffset,
+          sender: config.partyId,
+          commandId,
+        },
+      });
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @caypo/mpp-canton — MPP payment method for Canton Network.
+ * Uses CIP-56 TransferPreapproval for 1-step transfers.
+ */
+
+export const MPP_CANTON_VERSION = "0.1.0";
+
+// Method definition
+export { cantonMethod } from "./method.js";
+
+// Schemas for reuse
+export {
+  credentialPayloadSchema,
+  receiptSchema,
+  requestSchema,
+} from "./schemas.js";
+export type {
+  CantonCredentialPayload,
+  CantonReceipt,
+  CantonRequest,
+} from "./schemas.js";
+
+// Client (agent side)
+export { cantonClient } from "./client.js";
+export type { CantonMppClientConfig } from "./client.js";
+
+// Server (gateway side)
+export { cantonServer, MppVerificationError } from "./server.js";
+export type { CantonMppServerConfig } from "./server.js";

package/src/method.ts

@@ -0,0 +1,21 @@
+/**
+ * Canton MPP method definition.
+ *
+ * Defines the "canton" payment method using the mppx Method.from() pattern.
+ * The method specifies the request and credential schemas that both
+ * client (agent) and server (gateway) use.
+ */
+
+import { Method } from "mppx";
+import { credentialPayloadSchema, requestSchema } from "./schemas.js";
+
+export const cantonMethod = Method.from({
+  intent: "charge",
+  name: "canton",
+  schema: {
+    credential: {
+      payload: credentialPayloadSchema,
+    },
+    request: requestSchema,
+  },
+});

package/src/schemas.ts

@@ -0,0 +1,33 @@
+/**
+ * Zod schemas for Canton MPP payment method.
+ * Exported separately for reuse in validation, gateway middleware, etc.
+ */
+
+import { z } from "zod";
+
+export const requestSchema = z.object({
+  amount: z.string().regex(/^\d+\.?\d{0,10}$/, "Invalid amount format"),
+  currency: z.enum(["USDCx", "CC"]),
+  recipient: z.string().min(1, "Recipient party ID required"),
+  network: z.enum(["mainnet", "testnet", "devnet"]),
+  description: z.string().optional(),
+  expiry: z.number().int().min(1).max(3600).default(300),
+});
+
+export const credentialPayloadSchema = z.object({
+  updateId: z.string().min(1, "updateId required"),
+  completionOffset: z.number().int(),
+  sender: z.string().min(1, "Sender party ID required"),
+  commandId: z.string().min(1, "commandId required"),
+});
+
+export const receiptSchema = z.object({
+  method: z.literal("canton"),
+  reference: z.string().min(1),
+  status: z.enum(["success", "failed"]),
+  timestamp: z.string(),
+});
+
+export type CantonRequest = z.infer<typeof requestSchema>;
+export type CantonCredentialPayload = z.infer<typeof credentialPayloadSchema>;
+export type CantonReceipt = z.infer<typeof receiptSchema>;