@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/mandates/binding.ts

@@ -0,0 +1,280 @@
+// MetalAccount mandate ABI, typed agent keys, references, self-calls and pulls.
+
+import { type Address, type Hex, concat, encodeFunctionData, encodePacked, keccak256, parseAbi, size, slice } from "viem";
+
+/** Domain tag for the payment-only ERC-1271 path on MetalAccount. */
+export const MANDATE_SIGNATURE_TAG: Hex = "0x4d4e4454";
+
+export const mandateBindingAbi = parseAbi([
+  "struct Pull { address token; address to; uint256 value; uint256 validAfter; uint256 validBefore; bytes32 nonce; }",
+  "struct L3a { string nonce; string iss; bytes16 merchantSalt; bytes16 paymentSalt; bytes32 transactionId; bytes32 r; bytes32 s; string payee; address linkedPayee; }",
+  "struct Constraints { address token; uint256 perPaymentCap; uint256 budget; uint256 expiry; uint256 recurrenceStart; uint256 recurrenceEnd; uint256 maxOccurrences; }",
+  "struct Payee { address account; bytes32 sdHash; string object; }",
+  "struct Terms { string kid; string instrument; string currency; uint256 unitsPerMinor; Payee[] payees; bytes32 openSdHash; }",
+  "struct PayeeTerms { bytes32 sdHash; string object; }",
+  "struct MandateState { address principal; bool revoked; bytes32 agentX; bytes32 agentY; string kid; bytes32 openSdHash; uint64 boundBlock; uint64 occurrences; uint128 spent; }",
+  "function mandateReference(address principal, bytes agentKey, bytes32 hashC) pure returns (bytes32)",
+  "function mandates(bytes32 ref) view returns (MandateState)",
+  "function payee(bytes32 ref, address account) view returns (PayeeTerms)",
+  "function mandateOfPrefix(bytes12 prefix) view returns (bytes32)",
+  "function digestUsed(bytes20 l3aDigest) view returns (bool)",
+  "function bind(bytes32 hashC, bytes32 issuerKey, bytes agentKey, Constraints c, Terms t) returns (bytes32)",
+  "function replace(bytes32 predecessor, bytes32 hashC, bytes32 issuerKey, bytes agentKey, Constraints c, Terms t) returns (bytes32 successor)",
+  "function revoke(bytes32 ref)",
+  "function isValidSignature(bytes32 hash, bytes blob) view returns (bytes4)",
+  "function check(Pull p, L3a l) view returns (uint8)",
+  "function pull(Pull p, L3a l) returns (bool paid)",
+  "event MandateBound(bytes32 indexed ref, bytes32 hashC, bytes32 issuerKey, bytes agentKey, Constraints constraints, Terms terms)",
+  "event MandatePayment(bytes32 indexed ref, address indexed to, bytes20 l3aDigest, bytes agentKey, uint256 amount, uint256 spent, uint256 occurrences)",
+  "event MandateRefused(bytes32 indexed ref, address indexed to, bytes20 l3aDigest, bytes agentKey, uint256 amount, uint8 reason)",
+  "event MandateRevoked(bytes32 indexed ref)",
+  "event MandateReplaced(bytes32 indexed predecessor, bytes32 indexed successor)",
+  "error OnlySelf()",
+  "error MissingCredentialHash()",
+  "error MissingIssuerKey()",
+  "error InvalidBudget()",
+  "error InvalidRecurrence()",
+  "error AlreadyExpired()",
+  "error InvalidAgentKey()",
+  "error InvalidTerms()",
+  "error PrefixTaken()",
+  "error UnknownMandate()",
+  "error AlreadyRevoked()",
+  "error TokenChanged()",
+  "error SuccessorExhausted()",
+  "error BadAgentSignature()",
+  "error NonceAlreadyUsed()",
+  "error NotYetValid()",
+  "error RefusalLimitReached()",
+]);
+
+/** `MandateTypes.Reason` in declaration order, which is the order Mandate Binding checks them in; `None` is a pass. */
+export const REASONS = [
+  "None",
+  "NoMandate",
+  "Revoked",
+  "Expired",
+  "BadSignature",
+  "NonceUsed",
+  "OutsideWindow",
+  "PayeeNotAllowed",
+  "OverPerPaymentCap",
+  "OverBudget",
+  "OutsideRecurrence",
+  "OverOccurrences",
+] as const;
+
+export type ReasonName = (typeof REASONS)[number];
+
+export function reasonName(reason: number): ReasonName {
+  const name = REASONS[reason];
+  if (name === undefined) throw new Error(`unknown Reason ${reason}`);
+  return name;
+}
+
+/** Each refusal as the facilitator answers it and `metal-agent` prints it: its x402 reason, and what it means. */
+export const REFUSALS: Record<Exclude<ReasonName, "None">, { reason: string; meaning: string }> = {
+  NoMandate: { reason: "mandate_not_bound", meaning: "no such mandate is bound on the account" },
+  Revoked: { reason: "mandate_revoked", meaning: "the mandate is revoked, or replaced: the agent pays under the credential that replaced it" },
+  Expired: { reason: "mandate_expired", meaning: "the mandate has expired" },
+  BadSignature: { reason: "mandate_bad_signature", meaning: "the payment is not signed by the mandate key" },
+  NonceUsed: { reason: "mandate_nonce_used", meaning: "this payment was already made or refused" },
+  OutsideWindow: { reason: "mandate_outside_window", meaning: "the payment's validity window is not open" },
+  PayeeNotAllowed: { reason: "mandate_payee_not_listed", meaning: "the payee is not one the mandate allows" },
+  OverPerPaymentCap: { reason: "mandate_cap_exceeded", meaning: "the amount is above the mandate's per-payment cap" },
+  OverBudget: { reason: "mandate_budget_spent", meaning: "the amount would take the mandate past its budget" },
+  OutsideRecurrence: { reason: "mandate_outside_recurrence", meaning: "the mandate has not started yet, or its dates have ended" },
+  OverOccurrences: { reason: "mandate_occurrences_used", meaning: "the mandate's payment count is used up" },
+};
+
+/** `mandate_cap_exceeded (the amount is above the mandate's per-payment cap)`: a refusal as a person reads it. */
+export function describeRefusal(reason: Exclude<ReasonName, "None">): string {
+  const { reason: name, meaning } = REFUSALS[reason];
+  return `${name} (${meaning})`;
+}
+
+/** The Mandate Binding reason behind an x402 refusal, or `undefined` for one that is not a mandate's. */
+export function refusalOf(reason: string): Exclude<ReasonName, "None"> | undefined {
+  return (Object.keys(REFUSALS) as Exclude<ReasonName, "None">[]).find((name) => REFUSALS[name].reason === reason);
+}
+
+/** Amounts in the token's base units; times are inclusive Unix seconds. The budget is the most all payments may add up to over the mandate's life; it never resets. */
+export interface Constraints {
+  token: Address;
+  perPaymentCap: bigint;
+  budget: bigint;
+  expiry: bigint;
+  recurrenceStart: bigint;
+  recurrenceEnd: bigint;
+  maxOccurrences: bigint;
+}
+
+/** An allowed payee's rebuild terms: the L3a `sd_hash` over L2 and its disclosure, and its payee object as L2 serialises it. */
+export interface Payee {
+  account: Address;
+  sdHash: Hex;
+  object: string;
+}
+
+/**
+ * What every per-payment mandate under a mandate is rebuilt from, besides the
+ * transfer and the agent's own fields. A mandate names its payees, or names
+ * none and carries `openSdHash`, the L3a `sd_hash` over L2 with no payee
+ * disclosed, under which the agent pays any address.
+ */
+export interface Terms {
+  /** The agent key's `kid`, its RFC 7638 thumbprint. */
+  kid: string;
+  /** The payment instrument object, compact JSON as L2 serialises it. */
+  instrument: string;
+  currency: string;
+  /** Token base units per minor unit of `currency`. */
+  unitsPerMinor: bigint;
+  payees: readonly Payee[];
+  /** Zero when the mandate names its payees. */
+  openSdHash: Hex;
+}
+
+/** The fields of an ERC-3009 authorisation from the principal's account. */
+export interface Pull {
+  token: Address;
+  to: Address;
+  value: bigint;
+  validAfter: bigint;
+  validBefore: bigint;
+  nonce: Hex;
+}
+
+/**
+ * What the agent chose in one per-payment mandate (L3a); the transfer and the
+ * bound terms fix the rest. `payee` and `linkedPayee` are empty (`""` and the
+ * zero address) for a payee in the set.
+ */
+export interface L3aFields {
+  nonce: string;
+  iss: string;
+  merchantSalt: Hex;
+  paymentSalt: Hex;
+  transactionId: Hex;
+  r: Hex;
+  s: Hex;
+  payee: string;
+  linkedPayee: Address;
+}
+
+/** A P-256 agent key by its affine coordinates, the only key type Mandate Binding binds. */
+export interface AgentKey {
+  x: Hex;
+  y: Hex;
+}
+
+const KEY_P256 = "0x01";
+
+/** `0x01 ‖ x ‖ y`, 65 bytes. */
+export function encodeAgentKey(key: AgentKey): Hex {
+  if (size(key.x) !== 32 || size(key.y) !== 32) throw new Error("P-256 coordinates are 32 bytes each");
+  return concat([KEY_P256, key.x, key.y]).toLowerCase() as Hex;
+}
+
+export function decodeAgentKey(encoded: Hex): AgentKey {
+  if (size(encoded) !== 65 || slice(encoded, 0, 1) !== KEY_P256) throw new Error(`not a typed P-256 agent key: ${encoded}`);
+  return { x: slice(encoded, 1, 33), y: slice(encoded, 33, 65) };
+}
+
+export function sameAgentKey(a: AgentKey, b: AgentKey): boolean {
+  return encodeAgentKey(a) === encodeAgentKey(b);
+}
+
+/** `keccak256(principal ‖ typed agent key ‖ hash(C))`, tightly packed. */
+export function mandateReference(principal: Address, agentKey: AgentKey, hashC: Hex): Hex {
+  return keccak256(encodePacked(["address", "bytes", "bytes32"], [principal, encodeAgentKey(agentKey), hashC]));
+}
+
+/** The 12 bytes of a reference every payment under it carries at the front of its nonce. */
+export function referencePrefix(refOrNonce: Hex): Hex {
+  return slice(refOrNonce, 0, 12).toLowerCase() as Hex;
+}
+
+/**
+ * Gas for the calls built here. Metal's `eth_fillTransaction` fills a zero fee
+ * and a fee-carrying `eth_estimateGas` fails, so every call carries its limit.
+ * A direct pull rebuilds the L3a and runs the P-256 check (441,600 gas on
+ * Metal) and the transfer. A bind or replace stores the terms it carries, so
+ * its gas scales with its calldata: `BINDING_GAS_PER_BYTE` per byte.
+ */
+export const MANDATE_GAS = {
+  revoke: 100_000n,
+  pull: 900_000n,
+} as const;
+
+/**
+ * Gas per calldata byte of a bind or replace. Storing the terms costs about
+ * 810 per byte on Metal, measured from one payee (2,244 bytes, 1,170,948 gas)
+ * to twenty (8,932 bytes, 6,573,273 gas); 950 leaves room for longer payee
+ * objects, whose bytes are stored too.
+ */
+export const BINDING_GAS_PER_BYTE = 950n;
+
+function bindingCall(to: Address, data: Hex): MandateCall {
+  return call(to, data, BigInt(size(data)) * BINDING_GAS_PER_BYTE);
+}
+
+/** What Metal charges per gas, in `*USDZ` base units. */
+export const FEE_PER_GAS = 1n;
+
+/** A call with its gas and fees; the sender adds its nonce and the chain id. */
+export interface MandateCall {
+  to: Address;
+  data: Hex;
+  gas: bigint;
+  maxFeePerGas: bigint;
+  maxPriorityFeePerGas: bigint;
+}
+
+function call(to: Address, data: Hex, gas: bigint): MandateCall {
+  return { to, data, gas, maxFeePerGas: FEE_PER_GAS, maxPriorityFeePerGas: FEE_PER_GAS };
+}
+
+function termsArg(t: Terms) {
+  return { ...t, payees: t.payees.map((p) => ({ ...p })) };
+}
+
+/** What `bind` and `replace` take besides the predecessor. */
+export interface Binding {
+  principal: Address;
+  hashC: Hex;
+  /** The RFC 7638 thumbprint of the key that signed C's issuer layer, as 32 bytes. */
+  issuerKey: Hex;
+  agentKey: AgentKey;
+  constraints: Constraints;
+  terms: Terms;
+}
+
+/** The principal's call to its own account binding a mandate. */
+export function bindCall(b: Binding): MandateCall {
+  const data = encodeFunctionData({
+    abi: mandateBindingAbi,
+    functionName: "bind",
+    args: [b.hashC, b.issuerKey, encodeAgentKey(b.agentKey), b.constraints, termsArg(b.terms)],
+  });
+  return bindingCall(b.principal, data);
+}
+
+/** The principal's call binding a successor, carrying the period's spend and occurrences, and revoking `predecessor` with it. */
+export function replaceCall(predecessor: Hex, b: Binding): MandateCall {
+  const data = encodeFunctionData({
+    abi: mandateBindingAbi,
+    functionName: "replace",
+    args: [predecessor, b.hashC, b.issuerKey, encodeAgentKey(b.agentKey), b.constraints, termsArg(b.terms)],
+  });
+  return bindingCall(b.principal, data);
+}
+
+export function revokeCall(principal: Address, ref: Hex): MandateCall {
+  return call(principal, encodeFunctionData({ abi: mandateBindingAbi, functionName: "revoke", args: [ref] }), MANDATE_GAS.revoke);
+}
+
+/** A per-payment mandate submitted to `pull` by anyone holding it (the agent's client, a facilitator, the paying PSP as sponsor). */
+export function pullCall(principal: Address, pull: Pull, fields: L3aFields): MandateCall {
+  return call(principal, encodeFunctionData({ abi: mandateBindingAbi, functionName: "pull", args: [pull, fields] }), MANDATE_GAS.pull);
+}

package/src/mandates/chain.ts

@@ -0,0 +1,68 @@
+// Chain reads and the one send the library needs, all through a viem client.
+
+import { type Account, type Address, type Chain, type Hash, type Hex, type PublicClient, type Transport, type WalletClient, isAddressEqual } from "viem";
+import { type AgentKey, type L3aFields, type MandateCall, type Pull, type ReasonName, mandateBindingAbi, reasonName } from "./binding.js";
+
+/** Mandate Binding's `check` on the principal's account at a block: the reason the per-payment mandate would be refused, or `None`. */
+export async function readCheck(client: PublicClient, principal: Address, pull: Pull, fields: L3aFields, blockNumber?: bigint): Promise<ReasonName> {
+  const reason = await client.readContract({
+    address: principal,
+    abi: mandateBindingAbi,
+    functionName: "check",
+    args: [pull, fields],
+    ...(blockNumber === undefined ? {} : { blockNumber }),
+  });
+  return reasonName(reason);
+}
+
+/** A mandate's running state at a block (the latest by default): revoked or not, its spend, its occurrences, and the block it was bound in. */
+export async function readMandateState(client: PublicClient, principal: Address, ref: Hex, blockNumber?: bigint): Promise<{ revoked: boolean; spent: bigint; occurrences: bigint; boundBlock: bigint }> {
+  const at = blockNumber === undefined ? {} : { blockNumber };
+  const mandate = await client.readContract({ address: principal, abi: mandateBindingAbi, functionName: "mandates", args: [ref], ...at });
+  return { revoked: mandate.revoked, spent: mandate.spent, occurrences: mandate.occurrences, boundBlock: mandate.boundBlock };
+}
+
+/** The agent key and its `kid` the mandate `ref` binds on `principal`; undefined when no such mandate is bound. */
+export async function readBoundAgentKey(client: PublicClient, principal: Address, ref: Hex): Promise<{ agentKey: AgentKey; kid: string } | undefined> {
+  const mandate = await client.readContract({ address: principal, abi: mandateBindingAbi, functionName: "mandates", args: [ref] });
+  if (!isAddressEqual(mandate.principal, principal)) return undefined;
+  return { agentKey: { x: mandate.agentX, y: mandate.agentY }, kid: mandate.kid };
+}
+
+/** Sends a call with its fees, the gas an estimate shows it needs, and the nonce and chain id set here, so nothing is left for the node to fill. */
+export async function sendMandateCall(publicClient: PublicClient, walletClient: WalletClient<Transport, Chain, Account>, call: MandateCall): Promise<Hash> {
+  // Estimated first, without fees (Metal refuses a fee-carrying estimate from
+  // a sender holding no gas token): a call that would revert costs nothing and
+  // says why, and the gas sent covers what this call's terms and quorum use,
+  // with a fifth more, never below the limit the call was built with.
+  let estimate: bigint;
+  try {
+    estimate = await publicClient.estimateGas({ account: walletClient.account.address, to: call.to, data: call.data });
+  } catch (error) {
+    throw new Error(`the call to ${call.to} would fail: ${publicMessage(error)}`);
+  }
+  const gas = estimate + estimate / 5n > call.gas ? estimate + estimate / 5n : call.gas;
+  const [nonce, chainId] = await Promise.all([
+    publicClient.getTransactionCount({ address: walletClient.account.address, blockTag: "pending" }),
+    publicClient.getChainId(),
+  ]);
+  return walletClient.sendTransaction({ ...call, gas, nonce, chainId, chain: walletClient.chain, account: walletClient.account });
+}
+
+/**
+ * An error's message with nothing a node or transport added: viem's short
+ * message, which names what failed, never the request, its URL or headers.
+ * An RPC endpoint's URL can carry its credential.
+ */
+export function publicMessage(error: unknown): string {
+  if (error instanceof Error) {
+    const short = (error as { shortMessage?: unknown }).shortMessage;
+    return redactUrls(typeof short === "string" ? short : error.message.split("\n")[0] ?? "");
+  }
+  return redactUrls(String(error));
+}
+
+/** `text` with every URL reduced to its scheme and host, its userinfo, path and query removed. */
+export function redactUrls(text: string): string {
+  return text.replace(/\b([a-z][a-z0-9+.-]*:\/\/)(?:[^\s/@"'<>]*@)?([^\s/?#"'<>]+)([/?#][^\s"'<>]*)?/gi, (_, scheme: string, host: string, rest?: string) => `${scheme}${host}${rest ? "/…" : ""}`);
+}