@myzonerocks/pact 0.1.0

package/src/state.ts

@@ -0,0 +1,76 @@
+// State is a stage in a payment's lifecycle. The unspecified value is
+// intentionally invalid so an uninitialized state never passes for a real one.
+export enum State {
+  Unspecified = 0,
+  Draft,
+  Quoted,
+  Authorized,
+  Submitted,
+  Settled,
+  Failed,
+  Expired,
+  Refunded,
+  // The states below carry a bridged corridor through its escrow middle, where
+  // the pay-in and pay-out are different providers or currencies.
+  Collecting,
+  Held,
+  Disbursing,
+  Refunding,
+}
+
+// stateName maps each state to the lowercase token used in canonical preimages
+// and on the wire. These strings are signed material and must not change for a
+// given wire version.
+export const stateName: Record<State, string> = {
+  [State.Unspecified]: "unspecified",
+  [State.Draft]: "draft",
+  [State.Quoted]: "quoted",
+  [State.Authorized]: "authorized",
+  [State.Submitted]: "submitted",
+  [State.Settled]: "settled",
+  [State.Failed]: "failed",
+  [State.Expired]: "expired",
+  [State.Refunded]: "refunded",
+  [State.Collecting]: "collecting",
+  [State.Held]: "held",
+  [State.Disbursing]: "disbursing",
+  [State.Refunding]: "refunding",
+};
+
+// transitions is the whole state machine expressed as data. A payment may move
+// from a key only to a listed state; every other pairing is illegal. Terminal
+// states map to an empty set. A direct corridor settles in one phase; a bridged
+// one enters the escrow middle at collecting and unwinds through refunding when
+// its pay-out cannot complete.
+const transitions: Record<State, ReadonlySet<State>> = {
+  [State.Unspecified]: new Set([State.Draft]),
+  [State.Draft]: new Set([State.Quoted, State.Expired]),
+  [State.Quoted]: new Set([State.Authorized, State.Expired]),
+  [State.Authorized]: new Set([State.Submitted, State.Collecting, State.Expired]),
+  [State.Submitted]: new Set([State.Settled, State.Failed]),
+  [State.Collecting]: new Set([State.Held, State.Failed, State.Expired]),
+  [State.Held]: new Set([State.Disbursing, State.Refunding, State.Expired]),
+  [State.Disbursing]: new Set([State.Settled, State.Failed, State.Refunding]),
+  [State.Refunding]: new Set([State.Refunded, State.Failed]),
+  [State.Settled]: new Set([State.Refunded]),
+  [State.Failed]: new Set(),
+  [State.Expired]: new Set(),
+  [State.Refunded]: new Set(),
+};
+
+export function canTransition(from: State, to: State): boolean {
+  return transitions[from].has(to);
+}
+
+// isTerminal reports whether a state accepts no further transition. Settled is
+// not terminal because it still admits the single edge to refunded.
+export function isTerminal(state: State): boolean {
+  return transitions[state].size === 0;
+}
+
+export class TransitionError extends Error {
+  constructor(readonly from: State, readonly to: State) {
+    super(`pact: illegal transition ${stateName[from]} -> ${stateName[to]}`);
+    this.name = "TransitionError";
+  }
+}

package/src/wire.ts

@@ -0,0 +1,248 @@
+import { Money } from "./money.js";
+import { State } from "./state.js";
+import { CanonicalWriter } from "./canonical.js";
+import type { Intent, Quote, Authorization, Settlement } from "./message.js";
+
+// The wire codec serializes messages for transport. It is distinct from the
+// canonical signing preimage: signing binds a fixed subset of fields under a
+// domain tag, while the wire form carries every field so a peer can reconstruct
+// the message. Both use the same length-delimited primitives; a message's wire
+// bytes are never signed and its signing preimage is never sent.
+
+export enum WireKind {
+  Intent = 1,
+  Quote = 2,
+  Authorization = 3,
+  Settlement = 4,
+}
+
+const decoder = new TextDecoder();
+
+export function encodeIntent(i: Intent): Uint8Array {
+  return new CanonicalWriter()
+    .str(i.id)
+    .str(i.senderRef)
+    .str(i.recipientRef)
+    .money(i.amount)
+    .str(i.memo)
+    .u64(i.expiresAt)
+    .list(i.allowedRails)
+    .stringMap(i.metadata)
+    .preimage();
+}
+
+export function encodeQuote(q: Quote): Uint8Array {
+  return new CanonicalWriter()
+    .str(q.id)
+    .str(q.intentId)
+    .str(q.payInAdapterId)
+    .str(q.payInRail)
+    .str(q.payOutAdapterId)
+    .str(q.payOutRail)
+    .str(q.bridgeId)
+    .money(q.srcAmount)
+    .money(q.dstAmount)
+    .money(q.fees)
+    .str(q.fxRate)
+    .u64(q.expiresAt)
+    .str(q.providerQuoteRef)
+    .u64(q.latencyEstimateMs)
+    .preimage();
+}
+
+export function encodeAuthorization(a: Authorization): Uint8Array {
+  return new CanonicalWriter()
+    .str(a.intentId)
+    .str(a.quoteId)
+    .str(a.signerIdentity)
+    .u64(a.signedAt)
+    .bytes(a.signature)
+    .preimage();
+}
+
+export function encodeSettlement(s: Settlement): Uint8Array {
+  return new CanonicalWriter()
+    .str(s.intentId)
+    .u64(s.state)
+    .str(s.adapterId)
+    .str(s.providerTxRef)
+    .str(s.onchainTxHash)
+    .bytes(s.receiptHash)
+    .str(s.reason)
+    .u64(s.settledAt)
+    .preimage();
+}
+
+// frame prefixes a kind tag onto an encoding so a receiver can dispatch without
+// knowing the type in advance. This is what a host carries inside its envelope.
+export type WireMessage =
+  | { kind: WireKind.Intent; message: Intent }
+  | { kind: WireKind.Quote; message: Quote }
+  | { kind: WireKind.Authorization; message: Authorization }
+  | { kind: WireKind.Settlement; message: Settlement };
+
+export function encodeMessage(msg: WireMessage): Uint8Array {
+  const payload =
+    msg.kind === WireKind.Intent
+      ? encodeIntent(msg.message)
+      : msg.kind === WireKind.Quote
+        ? encodeQuote(msg.message)
+        : msg.kind === WireKind.Authorization
+          ? encodeAuthorization(msg.message)
+          : encodeSettlement(msg.message);
+  const out = new Uint8Array(payload.length + 1);
+  out[0] = msg.kind;
+  out.set(payload, 1);
+  return out;
+}
+
+export function decodeMessage(frame: Uint8Array): WireMessage {
+  if (frame.length === 0) {
+    throw new Error("pact: wire frame ended mid-field");
+  }
+  const kind = frame[0] as WireKind;
+  const body = frame.subarray(1);
+  switch (kind) {
+    case WireKind.Intent:
+      return { kind, message: decodeIntent(body) };
+    case WireKind.Quote:
+      return { kind, message: decodeQuote(body) };
+    case WireKind.Authorization:
+      return { kind, message: decodeAuthorization(body) };
+    case WireKind.Settlement:
+      return { kind, message: decodeSettlement(body) };
+    default:
+      throw new Error(`pact: unknown wire kind ${kind}`);
+  }
+}
+
+// WireReader consumes the length-delimited primitives in order.
+class WireReader {
+  private pos = 0;
+  constructor(private readonly buf: Uint8Array) {}
+
+  bytes(): Uint8Array {
+    if (this.pos + 4 > this.buf.length) {
+      throw new Error("pact: wire frame ended mid-field");
+    }
+    const view = new DataView(this.buf.buffer, this.buf.byteOffset + this.pos, 4);
+    const length = view.getUint32(0, false);
+    this.pos += 4;
+    if (this.pos + length > this.buf.length) {
+      throw new Error("pact: wire frame ended mid-field");
+    }
+    const out = this.buf.subarray(this.pos, this.pos + length);
+    this.pos += length;
+    return out;
+  }
+
+  str(): string {
+    return decoder.decode(this.bytes());
+  }
+
+  u64(): number {
+    if (this.pos + 8 > this.buf.length) {
+      throw new Error("pact: wire frame ended mid-field");
+    }
+    const view = new DataView(this.buf.buffer, this.buf.byteOffset + this.pos, 8);
+    this.pos += 8;
+    return Number(view.getBigUint64(0, false));
+  }
+
+  money(): Money {
+    const minor = this.str();
+    const currency = this.str();
+    const exponent = this.u64();
+    return Money.parse(currency, exponent, minor);
+  }
+
+  list(): string[] {
+    const count = this.u64();
+    const out: string[] = [];
+    for (let i = 0; i < count; i++) out.push(this.str());
+    return out;
+  }
+
+  stringMap(): Record<string, string> {
+    const count = this.u64();
+    const out: Record<string, string> = {};
+    for (let i = 0; i < count; i++) {
+      const key = this.str();
+      out[key] = this.str();
+    }
+    return out;
+  }
+
+  requireDone(): void {
+    if (this.pos !== this.buf.length) {
+      throw new Error("pact: trailing bytes after wire frame");
+    }
+  }
+}
+
+export function decodeIntent(b: Uint8Array): Intent {
+  const r = new WireReader(b);
+  const intent: Intent = {
+    id: r.str(),
+    senderRef: r.str(),
+    recipientRef: r.str(),
+    amount: r.money(),
+    memo: r.str(),
+    expiresAt: r.u64(),
+    allowedRails: r.list(),
+    metadata: r.stringMap(),
+  };
+  r.requireDone();
+  return intent;
+}
+
+export function decodeQuote(b: Uint8Array): Quote {
+  const r = new WireReader(b);
+  const quote: Quote = {
+    id: r.str(),
+    intentId: r.str(),
+    payInAdapterId: r.str(),
+    payInRail: r.str(),
+    payOutAdapterId: r.str(),
+    payOutRail: r.str(),
+    bridgeId: r.str(),
+    srcAmount: r.money(),
+    dstAmount: r.money(),
+    fees: r.money(),
+    fxRate: r.str(),
+    expiresAt: r.u64(),
+    providerQuoteRef: r.str(),
+    latencyEstimateMs: r.u64(),
+  };
+  r.requireDone();
+  return quote;
+}
+
+export function decodeAuthorization(b: Uint8Array): Authorization {
+  const r = new WireReader(b);
+  const auth: Authorization = {
+    intentId: r.str(),
+    quoteId: r.str(),
+    signerIdentity: r.str(),
+    signedAt: r.u64(),
+    signature: r.bytes().slice(),
+  };
+  r.requireDone();
+  return auth;
+}
+
+export function decodeSettlement(b: Uint8Array): Settlement {
+  const r = new WireReader(b);
+  const settlement: Settlement = {
+    intentId: r.str(),
+    state: r.u64() as State,
+    adapterId: r.str(),
+    providerTxRef: r.str(),
+    onchainTxHash: r.str(),
+    receiptHash: r.bytes().slice(),
+    reason: r.str(),
+    settledAt: r.u64(),
+  };
+  r.requireDone();
+  return settlement;
+}