@obbyx/x402-obyte 0.2.0 → 0.2.2

package/src/batch/client.ts

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 import type {
   PaymentPayloadResult,
   PaymentRequirements,
+  SchemeClientHooks,
   SchemeNetworkClient,
   SettleResponse,
 } from '@x402/core/types';
@@ -18,8 +19,13 @@ import obyte from 'obyte';
 import type { ReservingComposer } from '../coins/index.js';
 import { hubCall } from '../hub/hub-call.js';
 import { parseStateVars } from '../hub/schemas.js';
-import type { ClientChannelStore, PendingVoucher } from './client-store.js';
-import { BATCH_REASONS, BATCH_SCHEME, parseBatchRequirements } from './requirements.js';
+import type { ClientChannel, ClientChannelStore, PendingVoucher } from './client-store.js';
+import {
+  BATCH_REASONS,
+  BATCH_SCHEME,
+  type ParsedBatchRequirements,
+  parseBatchRequirements,
+} from './requirements.js';
 
 /**
  * Buyer side of `batch-settlement` on Obyte (party B of an AA channel).
@@ -159,6 +165,16 @@ export function confirmClose(
 
 export class BatchObyteClient implements SchemeNetworkClient {
   readonly scheme = BATCH_SCHEME;
+  /**
+   * The official x402 clients (`@x402/fetch`, `@x402/axios`) report the
+   * seller's PAYMENT-RESPONSE here, so the voucher is confirmed or released
+   * exactly as with `payingFetch`.
+   */
+  readonly schemeHooks: SchemeClientHooks = {
+    onPaymentResponse: async (ctx) => {
+      this.onSettled(ctx.requirements, ctx.settleResponse);
+    },
+  };
   private readonly log: Logger;
 
   constructor(private readonly options: BatchClientOptions) {
@@ -183,8 +199,33 @@ export class BatchObyteClient implements SchemeNetworkClient {
     if (cap !== undefined && req.amount > cap) {
       throw new ObbyxError('amount_over_limit', `Price ${req.amount} exceeds the limit ${cap}`);
     }
-    const store = this.options.store;
-    const channel = store.find(req.network.caip2, req.payTo, req.asset);
+    const channel = this.channelFor(req);
+
+    // Same operation retried: resend the same voucher (never sign a second one).
+    if (channel.pending !== null) {
+      if (channel.pending.binding === req.extra.binding)
+        return { x402Version: 2, payload: { signedPackage: channel.pending.signedPackage } };
+      throw new ObbyxError(
+        'payment_pending',
+        `A previous voucher on channel ${channel.aa} has an unknown outcome; retry that request first`,
+      );
+    }
+
+    const { period, balance } = await this.ledgerState(channel);
+    const committed = period > channel.period ? 0n : channel.committed;
+    const amountSpent = committed + req.amount;
+    if (amountSpent > balance) {
+      throw new ObbyxError(
+        'channel_exhausted',
+        `Channel balance ${balance} is not enough; deposit more with: obbyx channel deposit ${channel.aa}`,
+      );
+    }
+    return this.signVoucher(channel.aa, period, amountSpent, req);
+  }
+
+  /** Our open channel to this seller, with a dispute window the seller accepts. */
+  private channelFor(req: ParsedBatchRequirements): ClientChannel {
+    const channel = this.options.store.find(req.network.caip2, req.payTo, req.asset);
     if (channel === undefined) {
       throw new ObbyxError(
         'no_channel',
@@ -197,17 +238,14 @@ export class BatchObyteClient implements SchemeNetworkClient {
         `The seller requires a channel timeout ≥ ${req.extra.minTimeout} s`,
       );
     }
+    return channel;
+  }
 
-    // Same operation retried: resend the same voucher (never sign a second one).
-    if (channel.pending !== null) {
-      if (channel.pending.binding === req.extra.binding)
-        return { x402Version: 2, payload: { signedPackage: channel.pending.signedPackage } };
-      throw new ObbyxError(
-        'payment_pending',
-        `A previous voucher on channel ${channel.aa} has an unknown outcome; retry that request first`,
-      );
-    }
-
+  /**
+   * The channel's current period and confirmed deposit, from the AA state.
+   * A new period (the channel was closed and reopened) resets our local amount.
+   */
+  private async ledgerState(channel: ClientChannel): Promise<{ period: number; balance: bigint }> {
     const vars = await hubCall(
       () => this.options.client.api.getAaStateVars({ address: channel.aa }),
       this.options.hubTimeoutMs ?? 15_000,
@@ -225,19 +263,20 @@ export class BatchObyteClient implements SchemeNetworkClient {
       );
     if (state['close_initiated_by'] !== undefined)
       throw new ObbyxError('channel_closing', 'The channel is being closed');
-    if (period > channel.period) store.newPeriod(channel.aa, period);
-    const committed = period > channel.period ? 0n : channel.committed;
-    const amountSpent = committed + req.amount;
+    if (period > channel.period) this.options.store.newPeriod(channel.aa, period);
     const balance = BigInt(typeof state['balanceB'] === 'number' ? state['balanceB'] : 0);
-    if (amountSpent > balance) {
-      throw new ObbyxError(
-        'channel_exhausted',
-        `Channel balance ${balance} is not enough; deposit more with: obbyx channel deposit ${channel.aa}`,
-      );
-    }
+    return { period, balance };
+  }
 
+  /** Signs the voucher and records it as THE pending one of the channel (one at a time). */
+  private signVoucher(
+    aa: string,
+    period: number,
+    amountSpent: bigint,
+    req: ParsedBatchRequirements,
+  ): PaymentPayloadResult {
     const message = {
-      aa_address: channel.aa,
+      aa_address: aa,
       period,
       amount_spent: toSafeNumber(amountSpent),
       payment_amount: toSafeNumber(req.amount),
@@ -253,11 +292,11 @@ export class BatchObyteClient implements SchemeNetworkClient {
       amountSpent: amountSpent.toString(),
       signedPackage,
     };
-    if (!store.setPending(channel.aa, pending)) {
+    if (!this.options.store.setPending(aa, pending)) {
       throw new ObbyxError('payment_pending', 'Another voucher on this channel is in flight');
     }
     this.log.info(
-      { aa: channel.aa, period, amountSpent: amountSpent.toString(), binding: req.extra.binding },
+      { aa, period, amountSpent: amountSpent.toString(), binding: req.extra.binding },
       'voucher signed',
     );
     return { x402Version: 2, payload: { signedPackage } };
@@ -287,23 +326,7 @@ export class BatchObyteClient implements SchemeNetworkClient {
       typeof charged === 'string' &&
       /^\d+$/.test(charged)
     ) {
-      // PAYMENT-RESPONSE is NOT authenticated: never raise our committed amount
-      // to an arbitrary value (a malicious seller could make us sign a voucher
-      // for the whole deposit). Accept only:
-      //  - exactly the amount of the voucher WE signed (it was committed earlier), or
-      //  - a lower amount (signing less than before cannot hurt us).
-      const claimed = BigInt(charged);
-      if (claimed === BigInt(pending.amountSpent)) {
-        this.options.store.confirm(channel.aa, pending.period, claimed);
-      } else if (pending.period === channel.period && claimed <= channel.committed) {
-        this.options.store.dropPending(channel.aa, { period: pending.period, committed: claimed });
-      } else {
-        this.options.store.dropPending(channel.aa);
-        this.log.error(
-          { aa: channel.aa, claimed: charged, local: channel.committed.toString() },
-          'seller claimed a committed amount we never signed; refusing to resync',
-        );
-      }
+      this.resync(channel, pending, BigInt(charged));
     } else if (
       reason !== undefined &&
       reason !== 'settlement_pending' &&
@@ -314,4 +337,25 @@ export class BatchObyteClient implements SchemeNetworkClient {
     }
     // settlement_pending / busy / no answer: keep the voucher pending; retry the same operation.
   }
+
+  /**
+   * The seller says our committed amount differs. PAYMENT-RESPONSE is NOT
+   * authenticated: never raise our committed amount to an arbitrary value (a
+   * malicious seller could make us sign a voucher for the whole deposit).
+   * Accept only exactly the voucher WE signed (it was committed earlier), or a
+   * lower amount (signing less than before cannot hurt us).
+   */
+  private resync(channel: ClientChannel, pending: PendingVoucher, claimed: bigint): void {
+    if (claimed === BigInt(pending.amountSpent)) {
+      this.options.store.confirm(channel.aa, pending.period, claimed);
+    } else if (pending.period === channel.period && claimed <= channel.committed) {
+      this.options.store.dropPending(channel.aa, { period: pending.period, committed: claimed });
+    } else {
+      this.options.store.dropPending(channel.aa);
+      this.log.error(
+        { aa: channel.aa, claimed: claimed.toString(), local: channel.committed.toString() },
+        'seller claimed a committed amount we never signed; refusing to resync',
+      );
+    }
+  }
 }

package/src/batch/facilitator.ts

@@ -186,8 +186,7 @@ export class BatchObyteFacilitator implements SchemeNetworkFacilitator {
     channelKey: string,
     network: Network,
   ): Promise<SettleResponse> {
-    const store = this.options.store;
-    let commitment = await store.commitmentByHash(c.packageHash);
+    let commitment = await this.options.store.commitmentByHash(c.packageHash);
     if (commitment !== undefined && commitment.binding !== c.voucher.binding) {
       return failure(
         network,
@@ -196,96 +195,123 @@ export class BatchObyteFacilitator implements SchemeNetworkFacilitator {
       );
     }
     if (commitment === undefined) {
-      const appended = await store.appendPending({
-        channelKey,
-        network: c.req.network.caip2,
-        aa: c.voucher.aa_address,
-        payTo: c.req.payTo,
-        payer: c.payer,
-        asset: c.req.asset,
-        period: c.voucher.period,
-        amountSpent: BigInt(c.voucher.amount_spent),
-        paymentAmount: BigInt(c.voucher.payment_amount),
-        binding: c.voucher.binding,
-        packageHash: c.packageHash,
-        packageJson: c.packageJson,
-      });
-      if (!appended.ok) {
-        const reason =
-          appended.reason === 'channel_busy'
-            ? R.busy
-            : appended.reason === 'period_mismatch'
-              ? R.period
-              : R.cumulative;
-        await this.emit({
-          key: channelKey,
-          kind: 'voucher_refused',
-          data: {
-            reason,
-            amountSpent: c.voucher.amount_spent,
-            committed: appended.committed.toString(),
-          },
-        });
-        return {
-          ...failure(network, reason, `Voucher rejected: ${appended.reason}`),
-          extra: { chargedCumulativeAmount: appended.committed.toString() },
-        };
-      }
-      commitment = appended.commitment;
-      await this.emit({
-        key: channelKey,
-        kind: 'voucher_pending',
-        data: {
-          seq: commitment.seq,
-          period: commitment.period,
-          amountSpent: commitment.amountSpent.toString(),
-        },
-      });
-      this.log.info(
-        { seq: commitment.seq, amountSpent: commitment.amountSpent.toString() },
-        'voucher pending',
-      );
+      const appended = await this.append(c, channelKey, network);
+      if ('success' in appended) return appended;
+      commitment = appended;
     }
-
     if (commitment.state === 'pending') {
-      const delivered = await this.options.gateway.deliver(commitment, this.ackTimeoutMs);
-      if (delivered !== 'acked') {
-        // Stored here but not yet confirmed by the seller's watcher: the outcome
-        // is unknown to the client → settlement_pending (x402: non-empty
-        // transaction), retried with the SAME voucher. Distinct from the
-        // definite refusal `…_watcher_unavailable` at verification.
-        this.log.warn(
-          { seq: commitment.seq },
-          'watcher did not ack in time; voucher stays pending',
-        );
-        await this.emit({ key: channelKey, kind: 'ack_timeout', data: { seq: commitment.seq } });
-        return {
-          success: false,
-          errorReason: 'settlement_pending',
-          errorMessage:
-            "Waiting for the seller's watcher to store this voucher; retry with the same voucher",
-          transaction: commitmentIdOf(network, commitment),
-          network,
-          payer: c.payer,
-        };
-      }
-      commitment =
-        (await store.commit(commitment.seq, {
-          payTo: commitment.payTo,
-          network: commitment.network,
-        })) ?? commitment;
-      this.log.info({ seq: commitment.seq }, 'voucher committed (watcher ack)');
+      const committed = await this.handToWatcher(c, commitment, channelKey, network);
+      if ('success' in committed) return committed;
+      commitment = committed;
+    }
+    return this.success(network, c, commitment);
+  }
+
+  /**
+   * Appends the voucher to the channel journal as pending. The store enforces
+   * committed + price, the period and one voucher in flight per channel; a
+   * refusal reports the committed amount so an honest client can resync.
+   */
+  private async append(
+    c: Authenticated,
+    channelKey: string,
+    network: Network,
+  ): Promise<CommitmentRow | SettleResponse> {
+    const appended = await this.options.store.appendPending({
+      channelKey,
+      network: c.req.network.caip2,
+      aa: c.voucher.aa_address,
+      payTo: c.req.payTo,
+      payer: c.payer,
+      asset: c.req.asset,
+      period: c.voucher.period,
+      amountSpent: BigInt(c.voucher.amount_spent),
+      paymentAmount: BigInt(c.voucher.payment_amount),
+      binding: c.voucher.binding,
+      packageHash: c.packageHash,
+      packageJson: c.packageJson,
+    });
+    if (!appended.ok) {
+      const reason =
+        appended.reason === 'channel_busy'
+          ? R.busy
+          : appended.reason === 'period_mismatch'
+            ? R.period
+            : R.cumulative;
       await this.emit({
         key: channelKey,
-        kind: 'voucher_committed',
+        kind: 'voucher_refused',
         data: {
-          seq: commitment.seq,
-          period: commitment.period,
-          amountSpent: commitment.amountSpent.toString(),
+          reason,
+          amountSpent: c.voucher.amount_spent,
+          committed: appended.committed.toString(),
         },
       });
+      return {
+        ...failure(network, reason, `Voucher rejected: ${appended.reason}`),
+        extra: { chargedCumulativeAmount: appended.committed.toString() },
+      };
     }
-    return this.success(network, c, commitment);
+    const commitment = appended.commitment;
+    await this.emit({
+      key: channelKey,
+      kind: 'voucher_pending',
+      data: {
+        seq: commitment.seq,
+        period: commitment.period,
+        amountSpent: commitment.amountSpent.toString(),
+      },
+    });
+    this.log.info(
+      { seq: commitment.seq, amountSpent: commitment.amountSpent.toString() },
+      'voucher pending',
+    );
+    return commitment;
+  }
+
+  /**
+   * Delivers a pending voucher to the seller's watcher and commits it on its
+   * ack. Without the ack the voucher is stored here but not confirmed by the
+   * watcher: the outcome is unknown to the client → settlement_pending (x402:
+   * non-empty transaction), retried with the SAME voucher. Distinct from the
+   * definite refusal `…_watcher_unavailable` at verification.
+   */
+  private async handToWatcher(
+    c: Authenticated,
+    pending: CommitmentRow,
+    channelKey: string,
+    network: Network,
+  ): Promise<CommitmentRow | SettleResponse> {
+    const delivered = await this.options.gateway.deliver(pending, this.ackTimeoutMs);
+    if (delivered !== 'acked') {
+      this.log.warn({ seq: pending.seq }, 'watcher did not ack in time; voucher stays pending');
+      await this.emit({ key: channelKey, kind: 'ack_timeout', data: { seq: pending.seq } });
+      return {
+        success: false,
+        errorReason: 'settlement_pending',
+        errorMessage:
+          "Waiting for the seller's watcher to store this voucher; retry with the same voucher",
+        transaction: commitmentIdOf(network, pending),
+        network,
+        payer: c.payer,
+      };
+    }
+    const commitment =
+      (await this.options.store.commit(pending.seq, {
+        payTo: pending.payTo,
+        network: pending.network,
+      })) ?? pending;
+    this.log.info({ seq: commitment.seq }, 'voucher committed (watcher ack)');
+    await this.emit({
+      key: channelKey,
+      kind: 'voucher_committed',
+      data: {
+        seq: commitment.seq,
+        period: commitment.period,
+        amountSpent: commitment.amountSpent.toString(),
+      },
+    });
+    return commitment;
   }
 
   private success(

package/src/exact/client.ts

@@ -9,7 +9,11 @@ import { type Logger, moduleLogger } from '@obbyx/obyte/logger';
 import type obyte from 'obyte';
 import type { ReservingComposer } from '../coins/index.js';
 import { type PaymentRequirementsV1, requirementsV1ToV2 } from './facilitator-v1.js';
-import { EXACT_SCHEME, parseExactRequirements } from './requirements.js';
+import {
+  EXACT_SCHEME,
+  type ParsedExactRequirements,
+  parseExactRequirements,
+} from './requirements.js';
 
 /**
  * Client side of `exact` on Obyte: composes and signs (but does NOT
@@ -55,6 +59,36 @@ export class ExactObyteClient implements SchemeNetworkClient {
     requirements: PaymentRequirements,
     context?: PaymentPayloadContext,
   ): Promise<PaymentPayloadResult> {
+    const req = this.acceptable(x402Version, requirements, context);
+    const unit = await this.signUnit(req);
+    this.log.info(
+      {
+        proofId: unit['unit'],
+        payTo: req.payTo,
+        asset: req.asset,
+        amount: req.amount.toString(),
+        binding: req.extra.binding,
+      },
+      'payment unit signed (not broadcast)',
+    );
+    // v1: the mechanism returns the complete payload (core passes it through as-is).
+    if (x402Version === 1) {
+      return {
+        x402Version: 1,
+        scheme: EXACT_SCHEME,
+        network: requirements.network,
+        payload: { unit },
+      } as unknown as PaymentPayloadResult;
+    }
+    return { x402Version, payload: { unit } };
+  }
+
+  /** The requirements, if this client may pay them (network, limits, offer still valid). */
+  private acceptable(
+    x402Version: number,
+    requirements: PaymentRequirements,
+    context: PaymentPayloadContext | undefined,
+  ): ParsedExactRequirements {
     if (x402Version !== 1 && x402Version !== 2) {
       throw new ObbyxError('invalid_x402_version', 'Only x402 v1 and v2 are supported');
     }
@@ -85,7 +119,14 @@ export class ExactObyteClient implements SchemeNetworkClient {
     if (req.extra.validUntil < Math.floor(Date.now() / 1000)) {
       throw new ObbyxError('quote_expired', 'The payment offer has expired');
     }
+    return req;
+  }
 
+  /**
+   * Composes and signs (never broadcasts) the unit: one output to payTo and the
+   * binding in a data message. Refuses it when the network fee is above the limit.
+   */
+  private async signUnit(req: ParsedExactRequirements): Promise<Record<string, unknown>> {
     const output = { address: req.payTo, amount: toSafeNumber(req.amount) };
     const payment =
       req.asset === 'base'
@@ -95,7 +136,6 @@ export class ExactObyteClient implements SchemeNetworkClient {
       app: 'data',
       payload: { x402: { binding: req.extra.binding, quoteId: req.extra.quoteId } },
     };
-
     const compose = () =>
       this.options.client.compose.message('multi', [payment, data] as never, {
         privateKey: this.options.privateKey,
@@ -120,25 +160,6 @@ export class ExactObyteClient implements SchemeNetworkClient {
         `Network fee ${fee} exceeds the limit ${this.options.maxFee} bytes`,
       );
     }
-    this.log.info(
-      {
-        proofId: unit['unit'],
-        payTo: req.payTo,
-        asset: req.asset,
-        amount: req.amount.toString(),
-        binding: req.extra.binding,
-      },
-      'payment unit signed (not broadcast)',
-    );
-    // v1: the mechanism returns the complete payload (core passes it through as-is).
-    if (x402Version === 1) {
-      return {
-        x402Version: 1,
-        scheme: EXACT_SCHEME,
-        network: requirements.network,
-        payload: { unit },
-      } as unknown as PaymentPayloadResult;
-    }
-    return { x402Version, payload: { unit } };
+    return unit;
   }
 }

package/src/exact/facilitator.ts

@@ -90,6 +90,8 @@ export class ExactObyteFacilitator implements SchemeNetworkFacilitator {
   private readonly now: () => number;
   /** Serializes settle/resume per settlement key inside this process. */
   private readonly inFlight = new Map<string, Promise<SettleResponse>>();
+  /** Known plain (non-AA) recipients; an address can never turn into an AA. */
+  private readonly plainRecipients = new Set<string>();
 
   constructor(private readonly options: ExactObyteFacilitatorOptions) {
     this.log = moduleLogger(options.logger, 'x402.exact', { scheme: EXACT_SCHEME });
@@ -264,7 +266,6 @@ export class ExactObyteFacilitator implements SchemeNetworkFacilitator {
         now: this.now,
       },
       client,
-      req,
       facts,
       unit as Record<string, unknown>,
     );
@@ -272,9 +273,6 @@ export class ExactObyteFacilitator implements SchemeNetworkFacilitator {
     return { ok: true, value: { facts, req } };
   }
 
-  /** Known plain (non-AA) recipients; an address can never turn into an AA. */
-  private readonly plainRecipients = new Set<string>();
-
   private async recipientIsNotAa(client: obyte.Client, payTo: string): Promise<Check<null>> {
     if (this.plainRecipients.has(payTo)) return { ok: true, value: null };
     const res = await hubCall(() => client.api.getDefinition(payTo), this.hubTimeoutMs);

package/src/exact/ledger-checks.ts

@@ -3,7 +3,6 @@ import type { ExactUnitFacts } from '@obbyx/obyte';
 import { hubCall } from '../hub/hub-call.js';
 import { type LedgerUnit, parseHistory, parseLedgerUnit } from '../hub/schemas.js';
 import { type Check, EXACT_SETTLE_REASONS, fail } from './reasons.js';
-import type { ParsedExactRequirements } from './requirements.js';
 
 export interface LedgerCheckContext {
   readonly hubTimeoutMs: number;
@@ -18,12 +17,25 @@ export interface LedgerCheckContext {
 export async function checkLedger(
   ctx: LedgerCheckContext,
   client: obyte.Client,
-  req: ParsedExactRequirements,
   facts: ExactUnitFacts,
   unit: Record<string, unknown>,
 ): Promise<Check<null>> {
-  const t = ctx.hubTimeoutMs;
-  const lastBall = await hubCall(() => client.api.getJoint(facts.lastBallUnit), t);
+  const recent = await lastBallIsRecent(ctx, client, facts);
+  if (!recent.ok) return recent;
+  const totals = await inputTotals(ctx, client, facts);
+  if (!totals.ok) return totals;
+  const balanced = inputsBalance(totals.value, facts, unit);
+  if (!balanced.ok) return balanced;
+  return inputsUnspent(ctx, client, facts);
+}
+
+/** The unit's last ball exists and is not older than the configured limit. */
+async function lastBallIsRecent(
+  ctx: LedgerCheckContext,
+  client: obyte.Client,
+  facts: ExactUnitFacts,
+): Promise<Check<null>> {
+  const lastBall = await hubCall(() => client.api.getJoint(facts.lastBallUnit), ctx.hubTimeoutMs);
   if (lastBall.kind !== 'ok')
     return fail(EXACT_SETTLE_REASONS.ledger, `last ball: ${lastBall.error}`);
   const lastBallTs = lastBall.value.joint?.unit.timestamp;
@@ -36,14 +48,21 @@ export async function checkLedger(
       `Last ball is ${lastBallAge} s old; the limit is ${ctx.maxLastBallAgeSeconds} s (MAX_LAST_BALL_AGE_SECONDS)`,
     );
   }
+  return { ok: true, value: null };
+}
 
-  // Inputs: each referenced output exists, belongs to the payer, has the right asset.
+/** Each input refers to an existing output of the payer in its asset; sums per asset. */
+async function inputTotals(
+  ctx: LedgerCheckContext,
+  client: obyte.Client,
+  facts: ExactUnitFacts,
+): Promise<Check<Map<string, bigint>>> {
   const totals = new Map<string, bigint>();
   const sources = new Map<string, LedgerUnit>();
   for (const input of facts.inputs) {
     let source = sources.get(input.unit);
     if (source === undefined) {
-      const res = await hubCall(() => client.api.getJoint(input.unit), t);
+      const res = await hubCall(() => client.api.getJoint(input.unit), ctx.hubTimeoutMs);
       if (res.kind !== 'ok') return fail(EXACT_SETTLE_REASONS.ledger, `input source: ${res.error}`);
       if (res.value.joint === undefined)
         return fail(EXACT_SETTLE_REASONS.inputs, 'Input source unit not found');
@@ -71,6 +90,15 @@ export async function checkLedger(
     }
     totals.set(asset, (totals.get(asset) ?? 0n) + BigInt(output.amount));
   }
+  return { ok: true, value: totals };
+}
+
+/** Inputs equal outputs per asset; bytes also cover every fee of the unit. */
+function inputsBalance(
+  totals: ReadonlyMap<string, bigint>,
+  facts: ExactUnitFacts,
+  unit: Record<string, unknown>,
+): Check<null> {
   const fees =
     BigInt(facts.commissions.headers + facts.commissions.payload) +
     BigInt((unit['tps_fee'] as number | undefined) ?? 0) +
@@ -81,9 +109,18 @@ export async function checkLedger(
       return fail(EXACT_SETTLE_REASONS.inputs, `Inputs and outputs do not balance in ${asset}`);
     }
   }
+  return { ok: true, value: null };
+}
 
-  // Unspent: no other unit of the payer spends these inputs (best effort
-  // until stability; the network decides double-spends definitively).
+/**
+ * No other unit of the payer spends these inputs (best effort until
+ * stability; the network decides double spends definitively).
+ */
+async function inputsUnspent(
+  ctx: LedgerCheckContext,
+  client: obyte.Client,
+  facts: ExactUnitFacts,
+): Promise<Check<null>> {
   const history = await hubCall(
     () =>
       client.api
@@ -91,7 +128,7 @@ export async function checkLedger(
         .then((witnesses) =>
           client.api.getHistory({ witnesses, addresses: [facts.payer] } as never),
         ),
-    t,
+    ctx.hubTimeoutMs,
   );
   if (history.kind !== 'ok') return fail(EXACT_SETTLE_REASONS.ledger, `history: ${history.error}`);
   const parsedHistory = parseHistory(history.value);

package/src/hub/schemas.ts

@@ -87,3 +87,32 @@ export function parseStateVars(raw: unknown): Record<string, unknown> | undefine
   const parsed = z.record(z.string(), z.unknown()).safeParse(raw);
   return parsed.success ? parsed.data : undefined;
 }
+
+/** Balance of one asset: confirmed (stable) and not yet confirmed (pending), atomic units. */
+export interface AssetBalance {
+  readonly stable: bigint;
+  readonly pending: bigint;
+}
+
+const balancesSchema = z.record(
+  z.string(),
+  z.record(z.string(), z.object({ stable: safeAmount, pending: safeAmount }).loose()),
+);
+
+/**
+ * `light/get_balances` for one address: balances by asset ('base' = bytes);
+ * an address without funds has none. Undefined when the answer is malformed.
+ */
+export function parseBalances(
+  raw: unknown,
+  address: string,
+): Record<string, AssetBalance> | undefined {
+  const parsed = balancesSchema.safeParse(raw);
+  if (!parsed.success) return undefined;
+  return Object.fromEntries(
+    Object.entries(parsed.data[address] ?? {}).map(([asset, b]) => [
+      asset,
+      { stable: BigInt(b.stable), pending: BigInt(b.pending) },
+    ]),
+  );
+}