@dvmkit/sdk 0.0.0 → 0.1.0-rc.2

package/dist/chunk-5GFED3GJ.js

@@ -0,0 +1,955 @@
+// src/sdk/server/mpp-setup.ts
+import { randomUUID } from "crypto";
+import { Errors as MppxErrors, PaymentRequest } from "mppx";
+import { Mppx, tempo } from "mppx/server";
+import { Session as TempoSession } from "mppx/tempo";
+
+// src/sdk/server/tempo-settlement-readiness.ts
+import { BaseError, InsufficientFundsError } from "viem";
+var TEMPO_SETTLEMENT_DEFAULT_LOW_BALANCE_MICRO = 10000n;
+var TEMPO_SETTLEMENT_BALANCE_INTERVAL_MS = 5 * 60 * 1e3;
+var TempoSettlementReadiness = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.lowBalanceMicro = opts.lowBalanceMicro ?? TEMPO_SETTLEMENT_DEFAULT_LOW_BALANCE_MICRO;
+    this.intervalMs = opts.balanceCheckIntervalMs ?? TEMPO_SETTLEMENT_BALANCE_INTERVAL_MS;
+    this.now = opts.now ?? Date.now;
+    this.failureStateKnown = !opts.stateStore;
+    if (this.lowBalanceMicro <= 0n) {
+      throw new Error("Tempo settlement lowBalanceMicro must be positive");
+    }
+    if (!Number.isFinite(this.intervalMs) || this.intervalMs <= 0) {
+      throw new Error("Tempo settlement balanceCheckIntervalMs must be positive");
+    }
+  }
+  opts;
+  lowBalanceMicro;
+  intervalMs;
+  now;
+  listeners = /* @__PURE__ */ new Set();
+  timer;
+  inFlight;
+  lastBalanceMicro;
+  failureBalanceMicro;
+  failureVersion;
+  failureLatched = false;
+  failureStateKnown;
+  localFailureGeneration = 0;
+  pendingFailureGeneration = 0;
+  failurePersistence;
+  /** Whether new Tempo session channels may be offered at this instant. */
+  available() {
+    return !this.failureLatched && this.failureStateKnown && this.lastBalanceMicro !== void 0 && this.lastBalanceMicro >= this.lowBalanceMicro;
+  }
+  /** Refresh shared failure state and hold the first balance read before gating. */
+  async ensureFresh() {
+    if (this.lastBalanceMicro === void 0) {
+      await this.checkBalance().catch(() => void 0);
+      return;
+    }
+    const state = await this.refreshFailureState().catch((error) => {
+      logStateFailure(error);
+      return void 0;
+    });
+    if (state?.latched && state.balanceMicro === void 0) {
+      await this.checkBalance().catch(() => void 0);
+    }
+  }
+  /** Add a reporting listener; the disposer removes only that listener. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /** Start the boot reading and in-process cadence. Idempotent. */
+  start() {
+    if (this.timer) return;
+    void this.checkBalance().catch(logBalanceFailure);
+    this.timer = setInterval(
+      () => void this.checkBalance().catch(logBalanceFailure),
+      this.intervalMs
+    );
+    this.timer.unref();
+  }
+  /** Stop the cadence without affecting any in-flight reading. */
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+  /** Read and report the configured fee-token balance now. */
+  async checkBalance(opts) {
+    if (this.inFlight) {
+      const current = await this.inFlight;
+      if (!opts?.successfulTransaction) return current;
+    }
+    const check = this.checkBalanceOnce(opts).finally(() => {
+      if (this.inFlight === check) this.inFlight = void 0;
+    });
+    this.inFlight = check;
+    return check;
+  }
+  /** Latch fleet-wide and report every redacted fee-funding rejection. */
+  async recordInsufficientFunds(failure) {
+    this.failureLatched = true;
+    this.failureStateKnown = true;
+    this.failureBalanceMicro = void 0;
+    this.failureVersion = void 0;
+    let sharedLatchWritten = false;
+    if (this.opts.stateStore) {
+      this.localFailureGeneration += 1;
+      this.pendingFailureGeneration = this.localFailureGeneration;
+      try {
+        await this.persistPendingFailure();
+        sharedLatchWritten = this.pendingFailureGeneration === 0;
+      } catch (error) {
+        logStateFailure(error);
+      }
+    } else {
+      this.failureBalanceMicro ??= this.lastBalanceMicro;
+    }
+    const observation = {
+      address: this.opts.address,
+      network: this.opts.network,
+      token: this.opts.token,
+      operation: failure.operation,
+      errorClass: "InsufficientFundsError",
+      checkedAt: this.now(),
+      ...this.lastBalanceMicro !== void 0 ? { balanceMicro: this.lastBalanceMicro } : {},
+      ...failure.channelId ? { channelId: failure.channelId } : {},
+      ...failure.creditId ? { creditId: failure.creditId } : {},
+      ...failure.drainId ? { drainId: failure.drainId } : {}
+    };
+    console.warn(
+      JSON.stringify({
+        level: "warn",
+        event: "tempo_settlement_insufficient_funds",
+        address: observation.address,
+        network: observation.network,
+        token: observation.token,
+        operation: observation.operation,
+        error_class: observation.errorClass,
+        ...observation.channelId ? { channel_id: observation.channelId } : {},
+        ...observation.creditId ? { credit_id: observation.creditId } : {},
+        ...observation.drainId ? { drain_id: observation.drainId } : {}
+      })
+    );
+    await this.notify((listener) => listener.onFailure?.(observation));
+    if (sharedLatchWritten && this.failureBalanceMicro === void 0) {
+      await this.captureFailureBalance().catch(logBalanceFailure);
+    }
+  }
+  /** Snapshot the failure version an operator-funded transaction may recover. */
+  async captureRecoveryVersion() {
+    const state = await this.refreshFailureState().catch((error) => {
+      logStateFailure(error);
+      return void 0;
+    });
+    return state?.latched ? state.version : void 0;
+  }
+  /** Re-check after a landed transaction and recover only its preflight version. */
+  async recordSuccessfulTransaction(recoveryVersion) {
+    await this.checkBalance({
+      successfulTransaction: true,
+      ...recoveryVersion ? { recoveryVersion } : {}
+    }).catch(logBalanceFailure);
+  }
+  /** Exposed for timer-lifecycle assertions without reaching into Node internals. */
+  timerHasRef() {
+    return this.timer?.hasRef();
+  }
+  async checkBalanceOnce(opts) {
+    const state = await this.refreshFailureState().catch((error) => {
+      logStateFailure(error);
+      return this.currentFailureState();
+    });
+    const balanceMicro = await this.opts.readBalance();
+    if (this.opts.stateStore && state?.latched && state.version) {
+      if (opts?.successfulTransaction && opts.recoveryVersion && balanceMicro >= this.lowBalanceMicro) {
+        await this.opts.stateStore.clearFailureAfterSuccessfulTransaction(opts.recoveryVersion);
+      }
+      if (state.balanceMicro === void 0) {
+        await this.opts.stateStore.captureFailureBalance(state.version, balanceMicro);
+      } else {
+        await this.opts.stateStore.clearFailureIfRefilled(
+          state.version,
+          balanceMicro,
+          this.lowBalanceMicro
+        );
+      }
+      await this.refreshFailureState().catch(logStateFailure);
+    } else if (!this.opts.stateStore) {
+      const refilled = this.failureLatched && this.failureBalanceMicro !== void 0 && balanceMicro > this.failureBalanceMicro;
+      if (this.failureLatched && balanceMicro >= this.lowBalanceMicro && (opts?.successfulTransaction || refilled)) {
+        this.failureLatched = false;
+        this.failureBalanceMicro = void 0;
+      }
+    }
+    this.lastBalanceMicro = balanceMicro;
+    return this.reportBalance(balanceMicro);
+  }
+  async captureFailureBalance() {
+    if (!this.opts.stateStore || !this.failureVersion) return;
+    const version = this.failureVersion;
+    const balanceMicro = await this.opts.readBalance();
+    await this.opts.stateStore.captureFailureBalance(version, balanceMicro);
+    await this.refreshFailureState();
+    this.lastBalanceMicro = balanceMicro;
+    await this.reportBalance(balanceMicro);
+  }
+  async refreshFailureState() {
+    if (!this.opts.stateStore) return void 0;
+    try {
+      await this.persistPendingFailure();
+      const generation = this.localFailureGeneration;
+      const state = await this.opts.stateStore.readFailure();
+      if (generation !== this.localFailureGeneration || this.pendingFailureGeneration !== 0) {
+        return this.currentFailureState();
+      }
+      this.applyFailureState(state);
+      return state;
+    } catch (error) {
+      if (this.pendingFailureGeneration !== 0) {
+        this.failureLatched = true;
+        this.failureStateKnown = true;
+      } else {
+        this.failureStateKnown = false;
+      }
+      throw error;
+    }
+  }
+  async persistPendingFailure() {
+    if (!this.opts.stateStore) return;
+    while (this.pendingFailureGeneration !== 0) {
+      if (this.failurePersistence) {
+        await this.failurePersistence;
+        continue;
+      }
+      const generation = this.pendingFailureGeneration;
+      const persistence = this.opts.stateStore.latchFailure().then((state) => {
+        if (this.pendingFailureGeneration !== generation) return;
+        this.pendingFailureGeneration = 0;
+        this.applyFailureState(state);
+      });
+      this.failurePersistence = persistence;
+      try {
+        await persistence;
+      } finally {
+        if (this.failurePersistence === persistence) this.failurePersistence = void 0;
+      }
+    }
+  }
+  applyFailureState(state) {
+    this.failureLatched = state.latched;
+    this.failureVersion = state.latched ? state.version : void 0;
+    this.failureBalanceMicro = state.latched ? state.balanceMicro : void 0;
+    this.failureStateKnown = true;
+  }
+  currentFailureState() {
+    return {
+      latched: this.failureLatched,
+      ...this.failureVersion ? { version: this.failureVersion } : {},
+      ...this.failureBalanceMicro !== void 0 ? { balanceMicro: this.failureBalanceMicro } : {}
+    };
+  }
+  async reportBalance(balanceMicro) {
+    const observation = {
+      address: this.opts.address,
+      network: this.opts.network,
+      token: this.opts.token,
+      balanceMicro,
+      lowBalanceMicro: this.lowBalanceMicro,
+      checkedAt: this.now(),
+      ready: this.available()
+    };
+    console.info(
+      JSON.stringify({
+        level: "info",
+        event: "tempo_settlement_fee_balance",
+        address: observation.address,
+        network: observation.network,
+        token: observation.token,
+        balance_micro: observation.balanceMicro.toString(),
+        low_balance_micro: observation.lowBalanceMicro.toString(),
+        ready: observation.ready
+      })
+    );
+    await this.notify((listener) => listener.onBalance?.(observation));
+    return observation;
+  }
+  async notify(invoke) {
+    await Promise.all(
+      [...this.listeners].map(
+        (listener) => Promise.resolve(invoke(listener)).catch(() => void 0)
+      )
+    );
+  }
+};
+function isTempoInsufficientFundsError(error) {
+  if (error instanceof InsufficientFundsError) return true;
+  return error instanceof BaseError && error.walk((cause) => cause instanceof InsufficientFundsError) !== null;
+}
+function logBalanceFailure(error) {
+  console.warn(
+    JSON.stringify({
+      level: "warn",
+      event: "tempo_settlement_fee_balance_failed",
+      error_name: error instanceof Error ? error.name : "unknown"
+    })
+  );
+}
+function logStateFailure(error) {
+  console.warn(
+    JSON.stringify({
+      level: "warn",
+      event: "tempo_settlement_readiness_state_failed",
+      error_name: error instanceof Error ? error.name : "unknown"
+    })
+  );
+}
+
+// src/sdk/server/mpp-setup.ts
+var MPPX_HMAC_MISMATCH_REASON = "challenge was not issued by this server";
+var TEMPO_SETTLEMENT_LEASE_FIELD = "settlementLeaseUntil";
+var TEMPO_SETTLEMENT_LEASE_OWNER_FIELD = "settlementLeaseOwner";
+var TEMPO_SETTLEMENT_LEASE_MS = 3e5;
+var TEMPO_SETTLEMENT_IN_FLIGHT = "settlement already in flight";
+var TEMPO_USDC_MAINNET = "0x20C000000000000000000000b9537d11c60E8b50";
+var HEX_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+function challengeMeta(challenge) {
+  if (challenge.opaque) {
+    try {
+      return PaymentRequest.deserialize(challenge.opaque);
+    } catch {
+      return void 0;
+    }
+  }
+  return challenge.meta;
+}
+function createMppFromOpts(opts = {}, env = process.env) {
+  const built = buildMppMethods(opts, env);
+  if (!built) return void 0;
+  const secretKey = env.DVMKIT_TEMPO_SECRET_KEY;
+  if (!secretKey) {
+    throw new Error(
+      "Tempo requires DVMKIT_TEMPO_SECRET_KEY env var. Generate one with 'openssl rand -hex 32'."
+    );
+  }
+  return Object.assign(
+    attachTempoSessionRuntime(
+      wrapMppx(
+        Mppx.create({
+          methods: built.methods,
+          secretKey,
+          ...opts.realm && { realm: opts.realm }
+        })
+      ),
+      opts.tempoSession
+    ),
+    { tempoConfiguration: built.tempoConfiguration }
+  );
+}
+function createDualKeyMppxFromOpts(opts, env, stateLoader) {
+  const built = buildMppMethods(opts, env);
+  if (!built) return void 0;
+  const activeSecret = env.DVMKIT_TEMPO_SECRET_KEY;
+  if (!activeSecret) {
+    throw new Error(
+      "Tempo requires DVMKIT_TEMPO_SECRET_KEY env var. Generate one with 'openssl rand -hex 32'."
+    );
+  }
+  const activeMppx = Object.assign(
+    attachTempoSessionRuntime(
+      wrapMppx(
+        Mppx.create({
+          methods: built.methods,
+          secretKey: activeSecret,
+          ...opts.realm && { realm: opts.realm }
+        })
+      ),
+      opts.tempoSession
+    ),
+    { tempoConfiguration: built.tempoConfiguration }
+  );
+  const activeVerify = activeMppx.broadcastCredential.bind(activeMppx);
+  const verifyWithDualKey = async (credential, verifyOpts) => {
+    try {
+      return await activeVerify(credential, verifyOpts);
+    } catch (err) {
+      if (!isHmacMismatch(err)) throw err;
+      const state = await stateLoader();
+      const previous = state?.previous;
+      if (!previous) {
+        if (state?.rapidRotationAtMs != null) {
+          throw decorateRapidRotation(err, state.rapidRotationAtMs);
+        }
+        throw err;
+      }
+      const previousMppx = wrapMppx(
+        Mppx.create({
+          methods: built.methods,
+          secretKey: previous.secret,
+          ...opts.realm && { realm: opts.realm }
+        })
+      );
+      try {
+        return await previousMppx.broadcastCredential(credential, verifyOpts);
+      } catch (retryErr) {
+        if (state.rapidRotationAtMs != null) {
+          throw decorateRapidRotation(retryErr, state.rapidRotationAtMs);
+        }
+        throw retryErr;
+      }
+    }
+  };
+  return Object.assign(activeMppx, {
+    broadcastCredential: verifyWithDualKey,
+    verifyCredential: verifyWithDualKey
+  });
+}
+function buildMppMethods(opts, env) {
+  if (!opts.tempoRecipient) return void 0;
+  const allowlist = opts.methodsAllowlist;
+  const isAllowed = (name) => !allowlist || allowlist.length === 0 || allowlist.includes(name);
+  const methods = [];
+  let tempoConfiguration;
+  if (isAllowed("tempo")) {
+    if (!HEX_ADDRESS_RE.test(opts.tempoRecipient)) {
+      throw new Error(
+        `DVMKIT_TEMPO_RECIPIENT must be a 0x-prefixed 40-char hex address; got '${opts.tempoRecipient}'.`
+      );
+    }
+    const tempoCurrency = env.DVMKIT_TEMPO_CURRENCY ?? TEMPO_USDC_MAINNET;
+    if (!HEX_ADDRESS_RE.test(tempoCurrency)) {
+      throw new Error(
+        `DVMKIT_TEMPO_CURRENCY must be a 0x-prefixed 40-char hex address; got '${tempoCurrency}'.`
+      );
+    }
+    tempoConfiguration = {
+      recipient: opts.tempoRecipient,
+      paymentToken: tempoCurrency,
+      ...opts.tempoSession && {
+        operator: opts.tempoSession.account.address,
+        feeToken: tempoCurrency
+      }
+    };
+    methods.push(
+      tempo.charge({
+        recipient: opts.tempoRecipient,
+        currency: tempoCurrency,
+        decimals: 6,
+        // Without this mppx installs `Store.memory()`, so the consumed-hash
+        // guard is per-process and a credential replayed onto a sibling machine
+        // (or after a restart) reaches a broadcast the chain then rejects
+        // instead of a cheap refusal (internal-review).
+        ...opts.tempoCharge && { store: opts.tempoCharge.store }
+      })
+    );
+    if (opts.tempoSession) {
+      methods.push(
+        tempo.session({
+          recipient: opts.tempoRecipient,
+          account: opts.tempoSession.account,
+          operator: opts.tempoSession.account.address,
+          currency: tempoCurrency,
+          // A server-driven settle/close must spend fees from the same TIP-20
+          // token the channel carries. Leaving this implicit lets an account's
+          // stale fee preference win even when that token has too little left
+          // to broadcast, while the channel token is funded (internal-review).
+          feeToken: tempoCurrency,
+          decimals: 6,
+          unitType: "request",
+          store: opts.tempoSession.store,
+          channelStateTtl: 5e3,
+          // dvmkit's watcher owns scheduled settlement because it gates on
+          // terminal ledger consumption. mppx's in-request scheduler settles
+          // the full accepted voucher and can capture caller-owned balance.
+          ...opts.tempoSession.chainId !== void 0 && {
+            chainId: opts.tempoSession.chainId
+          },
+          ...opts.tempoSession.getClient && { getClient: opts.tempoSession.getClient },
+          ...opts.tempoSession.onSessionSettlement && {
+            onSessionSettlement: opts.tempoSession.onSessionSettlement
+          }
+        })
+      );
+    }
+  }
+  if (methods.length === 0 || !tempoConfiguration) return void 0;
+  return { methods, tempoConfiguration };
+}
+function isHmacMismatch(err) {
+  if (!(err instanceof MppxErrors.InvalidChallengeError)) return false;
+  return typeof err.message === "string" && err.message.includes(MPPX_HMAC_MISMATCH_REASON);
+}
+function decorateRapidRotation(original, rapidRotationAtMs) {
+  const base = original instanceof Error ? original : new Error(String(original));
+  const decorated = new Error(
+    `${base.message} (rapid_rotation=true; last_rotation_at_ms=${rapidRotationAtMs})`
+  );
+  decorated.name = base.name;
+  decorated.stack = base.stack;
+  return decorated;
+}
+function wrapMppx(mppx) {
+  const dispatcher = mppx.challenge;
+  const issueChallenge = (method, intent, o) => {
+    const handler = dispatcher[method][intent];
+    if (!handler) {
+      throw new Error(`Mppx: no challenge handler registered for ${method}/${intent}`);
+    }
+    return handler(o);
+  };
+  return Object.assign(mppx, { issueChallenge });
+}
+var DEFAULT_TEMPO_SESSION_CHAIN_OPS = {
+  getChannelStatesBatch: TempoSession.Precompile.Chain.getChannelStatesBatch,
+  settle: TempoSession.Server.settle,
+  readChannelClose: async (client, channelId, txHash) => TempoSession.Precompile.Chain.readChannelClosedReceiptFields(
+    TempoSession.Precompile.Chain.getChannelEvent(
+      await TempoSession.Precompile.Chain.waitForSuccessfulReceipt(client, txHash),
+      "ChannelClosed",
+      channelId
+    )
+  )
+};
+function attachTempoSessionRuntime(mppx, config, chainOpOverrides = {}) {
+  let creditLedger;
+  Object.assign(mppx, {
+    useTempoCreditLedger: (ledger) => {
+      creditLedger = ledger;
+    }
+  });
+  const chainOps = {
+    ...DEFAULT_TEMPO_SESSION_CHAIN_OPS,
+    ...chainOpOverrides
+  };
+  const store = config?.store;
+  if (store?.withVoucherAcceptance) {
+    Object.assign(mppx, {
+      withTempoSessionAcceptance: store.withVoucherAcceptance.bind(store)
+    });
+  }
+  if (store) {
+    Object.assign(mppx, {
+      getTempoSessionSpent: async (channelId) => {
+        const state = readTempoSessionState(await store.get(channelId.toLowerCase()));
+        if (!state) throw new Error(`Tempo session channel ${channelId} not found`);
+        return state.spent;
+      }
+    });
+  }
+  const getClient = config?.getClient;
+  const listActive = store?.listActive;
+  if (!config || !getClient || !store) return mppx;
+  const terminalizeLostBacking = async (channel, chainState) => {
+    if (chainState.deposit !== 0n) return;
+    if (!creditLedger) return;
+    const ledger = creditLedger;
+    const retire = async (lifecycle, tx) => {
+      const settledOnChain = maxBigInt(lifecycle.settledOnChain, chainState.settled);
+      if (lifecycle.highestVoucherAmount <= settledOnChain) return;
+      await ledger.terminalizeTempoCredits(
+        {
+          channelId: channel.channelId,
+          settledOnChainNative: settledOnChain,
+          highestVoucherNative: lifecycle.highestVoucherAmount,
+          consumedNative: lifecycle.spent
+        },
+        tx
+      );
+    };
+    if (store.withFinalizedCreditLoss) {
+      await store.withFinalizedCreditLoss(
+        channel.channelId,
+        (tx, lifecycle) => retire(lifecycle, tx)
+      );
+      return;
+    }
+    await retire(channel);
+  };
+  const getTempoSessionDrainState = async (channelId) => {
+    const normalized = channelId.toLowerCase();
+    const current = readTempoSessionState(await store.get(normalized));
+    if (!current) throw new Error(`Tempo session channel ${channelId} not found`);
+    const client = await getClient({ chainId: current.chainId });
+    const [chainState] = await chainOps.getChannelStatesBatch(
+      client,
+      [current.channelId],
+      current.escrowContract
+    );
+    await terminalizeLostBacking(current, chainState);
+    const chainFinalized = chainState.deposit === 0n;
+    await store.update(normalized, (value) => {
+      const active = readTempoSessionState(value);
+      if (!active) return { op: "noop", result: void 0 };
+      return {
+        op: "set",
+        value: {
+          ...value,
+          finalized: active.finalized || chainFinalized,
+          closeRequestedAt: chainFinalized ? 0n : BigInt(chainState.closeRequestedAt),
+          deposit: chainFinalized ? 0n : maxBigInt(active.deposit, chainState.deposit),
+          settledOnChain: maxBigInt(active.settledOnChain, chainState.settled)
+        },
+        result: void 0
+      };
+    });
+    const reconciled = readTempoSessionState(await store.get(normalized));
+    if (!reconciled) throw new Error(`Tempo session channel ${channelId} disappeared`);
+    return {
+      spent: reconciled.spent,
+      settledOnChain: reconciled.settledOnChain,
+      closeRequestedAt: reconciled.closeRequestedAt,
+      deposit: reconciled.deposit,
+      finalized: reconciled.finalized
+    };
+  };
+  Object.assign(mppx, { getTempoSessionDrainState });
+  const writeBackChainState = async (channel, chainState) => {
+    const chainFinalized = chainState.deposit === 0n;
+    await store.update(channel.channelId, (current) => {
+      const active = readTempoSessionState(current);
+      if (!active) return { op: "noop", result: void 0 };
+      return {
+        op: "set",
+        value: {
+          ...current,
+          finalized: active.finalized || chainFinalized,
+          closeRequestedAt: chainFinalized ? 0n : BigInt(chainState.closeRequestedAt),
+          deposit: chainFinalized ? 0n : maxBigInt(active.deposit, chainState.deposit),
+          settledOnChain: maxBigInt(active.settledOnChain, chainState.settled)
+        },
+        result: void 0
+      };
+    });
+    return chainFinalized;
+  };
+  const settlingHere = /* @__PURE__ */ new Set();
+  const leaseMs = config.settlementSchedule?.leaseMs ?? TEMPO_SETTLEMENT_LEASE_MS;
+  const claimSettlement = async (channelId) => {
+    if (settlingHere.has(channelId)) return false;
+    settlingHere.add(channelId);
+    const leaseOwner = randomUUID();
+    const leaseUntil = Date.now() + leaseMs;
+    try {
+      const claimed = await store.update(channelId, (current) => {
+        if (!isStateRecord(current)) return { op: "noop", result: false };
+        const until = current[TEMPO_SETTLEMENT_LEASE_FIELD];
+        const owner = current[TEMPO_SETTLEMENT_LEASE_OWNER_FIELD];
+        if (typeof until === "number" && until > Date.now() && owner !== leaseOwner) {
+          return { op: "noop", result: false };
+        }
+        return {
+          op: "set",
+          value: {
+            ...current,
+            [TEMPO_SETTLEMENT_LEASE_FIELD]: leaseUntil,
+            [TEMPO_SETTLEMENT_LEASE_OWNER_FIELD]: leaseOwner
+          },
+          result: true
+        };
+      });
+      if (!claimed) settlingHere.delete(channelId);
+      return claimed;
+    } catch (err) {
+      settlingHere.delete(channelId);
+      throw err;
+    }
+  };
+  const releaseSettlement = async (channelId) => {
+    try {
+      await store.update(channelId, (current) => {
+        if (!isStateRecord(current)) return { op: "noop", result: void 0 };
+        const next = Object.fromEntries(
+          Object.entries(current).filter(
+            ([field]) => field !== TEMPO_SETTLEMENT_LEASE_FIELD && field !== TEMPO_SETTLEMENT_LEASE_OWNER_FIELD
+          )
+        );
+        return { op: "set", value: next, result: void 0 };
+      });
+    } catch {
+    } finally {
+      settlingHere.delete(channelId);
+    }
+  };
+  const settleChannel = async (channel, client) => {
+    if (!await claimSettlement(channel.channelId)) return false;
+    try {
+      const recoveryVersion = await config.beforeSessionSettlement?.();
+      await chainOps.settle(store, client, channel.channelId, {
+        account: config.account,
+        escrowContract: channel.escrowContract,
+        // The session method pins the channel token for credential-driven
+        // cooperative closes. This explicit observer/sweep path calls mppx's
+        // public settle helper directly, so it must carry the same fee-token
+        // choice itself. Leaving it implicit makes Tempo prepare the operator
+        // transaction without a spendable fee token and fail before broadcast.
+        feeToken: channel.token,
+        ...config.onSessionSettlement && {
+          onSessionSettlement: (context) => config.onSessionSettlement?.({
+            ...context,
+            ...recoveryVersion ? { recoveryVersion } : {}
+          })
+        }
+      });
+    } catch (err) {
+      settlingHere.delete(channel.channelId);
+      if (isTempoInsufficientFundsError(err)) {
+        await config.onInsufficientFunds?.({
+          operation: "settle",
+          channelId: channel.channelId
+        });
+      }
+      throw err;
+    }
+    await releaseSettlement(channel.channelId);
+    return true;
+  };
+  const settleTempoSessionChannel = async (channelId) => {
+    const normalized = channelId.toLowerCase();
+    const channel = readTempoSessionState(await store.get(normalized));
+    if (!channel) return { outcome: "unknown_channel", channelId: normalized };
+    try {
+      const client = await getClient({ chainId: channel.chainId });
+      const [chainState] = await chainOps.getChannelStatesBatch(
+        client,
+        [channel.channelId],
+        channel.escrowContract
+      );
+      await terminalizeLostBacking(channel, chainState);
+      const chainFinalized = await writeBackChainState(channel, chainState);
+      const settledOnChain = maxBigInt(channel.settledOnChain, chainState.settled);
+      if (chainFinalized) {
+        const owed = channel.highestVoucherAmount - settledOnChain;
+        return owed > 0n ? {
+          outcome: "finalized_before_protection",
+          channelId: normalized,
+          owed,
+          settledOnChain
+        } : { outcome: "already_safe", channelId: normalized, settledOnChain };
+      }
+      const forcedClose = BigInt(chainState.closeRequestedAt) !== 0n;
+      if (!forcedClose) {
+        return {
+          outcome: "retryable_failure",
+          channelId: normalized,
+          error: "chain reports no close request yet"
+        };
+      }
+      if (!tempoSettlementDue({
+        channel,
+        chainSettled: chainState.settled,
+        forcedClose,
+        intervalMs: config.settlementSchedule?.intervalMs
+      })) {
+        return { outcome: "already_safe", channelId: normalized, settledOnChain };
+      }
+      if (!await settleChannel(channel, client)) {
+        return {
+          outcome: "retryable_failure",
+          channelId: normalized,
+          error: TEMPO_SETTLEMENT_IN_FLIGHT
+        };
+      }
+      return {
+        outcome: "settled",
+        channelId: normalized,
+        settledAmount: channel.highestVoucherAmount
+      };
+    } catch (err) {
+      return {
+        outcome: "retryable_failure",
+        channelId: normalized,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  };
+  const getTempoSessionBinding = async (channelId) => {
+    const stored = await store.get(channelId.toLowerCase());
+    const channel = readTempoSessionState(stored);
+    if (!channel) return null;
+    const payee = stored?.payee;
+    return {
+      chainId: channel.chainId,
+      escrowContract: channel.escrowContract,
+      ...typeof payee === "string" && { payee }
+    };
+  };
+  const getTempoReceipt = async ({
+    chainId,
+    txHash
+  }) => {
+    const { getTransactionReceipt } = await import("viem/actions");
+    const client = await getClient({ chainId });
+    return getTransactionReceipt(client, { hash: txHash });
+  };
+  const getTempoSessionCloseAmounts = async ({ channelId, txHash }) => {
+    const current = readTempoSessionState(await store.get(channelId.toLowerCase()));
+    if (!current) return null;
+    const client = await getClient({ chainId: current.chainId });
+    return chainOps.readChannelClose(client, current.channelId, txHash);
+  };
+  Object.assign(mppx, {
+    settleTempoSessionChannel,
+    getTempoSessionBinding,
+    getTempoReceipt,
+    getTempoSessionCloseAmounts
+  });
+  if (!listActive) return mppx;
+  const sweepTempoSessions = async () => {
+    const rows = [];
+    let cursor;
+    do {
+      const page = await listActive.call(store, 100, cursor);
+      rows.push(...page);
+      const last = page.at(-1);
+      cursor = last ? { updatedAt: last.updatedAt, key: last.key } : void 0;
+      if (page.length < 100) break;
+    } while (cursor);
+    let closeRequested = 0;
+    let settled = 0;
+    let inFlight = 0;
+    const groups = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      const state = readTempoSessionState(row.state);
+      if (!state) continue;
+      const groupKey = `${state.chainId}:${state.escrowContract.toLowerCase()}`;
+      const group = groups.get(groupKey) ?? [];
+      group.push(state);
+      groups.set(groupKey, group);
+    }
+    for (const groupedChannels of groups.values()) {
+      for (let offset = 0; offset < groupedChannels.length; offset += 100) {
+        const channels = groupedChannels.slice(offset, offset + 100);
+        const first = channels[0];
+        const client = await getClient({ chainId: first.chainId });
+        const chainStates = await chainOps.getChannelStatesBatch(
+          client,
+          channels.map((channel) => channel.channelId),
+          first.escrowContract
+        );
+        for (const [index, channel] of channels.entries()) {
+          const chainState = chainStates[index];
+          await terminalizeLostBacking(channel, chainState);
+          const chainFinalized = await writeBackChainState(channel, chainState);
+          const forcedClose = !chainFinalized && BigInt(chainState.closeRequestedAt) !== 0n;
+          if (forcedClose) closeRequested += 1;
+          if (!tempoSettlementDue({
+            channel,
+            chainSettled: chainState.settled,
+            forcedClose,
+            intervalMs: config.settlementSchedule?.intervalMs
+          })) {
+            continue;
+          }
+          if (await settleChannel(channel, client)) settled += 1;
+          else inFlight += 1;
+        }
+      }
+    }
+    return { scanned: rows.length, closeRequested, settled, inFlight };
+  };
+  const recoverTempoSessionClose = async (channelId, drainId) => {
+    if (!store.getClose || !store.confirmClose) return null;
+    const intent = await store.getClose(channelId);
+    if (intent?.drainId !== drainId) return null;
+    if (intent.reference) return intent.reference;
+    const current = readTempoSessionState(await store.get(channelId));
+    if (!current) throw new Error(`Tempo session channel ${channelId} not found`);
+    let finalized = current.finalized;
+    if (!finalized) {
+      const client = await getClient({ chainId: current.chainId });
+      const [chainState] = await chainOps.getChannelStatesBatch(
+        client,
+        [current.channelId],
+        current.escrowContract
+      );
+      await terminalizeLostBacking(current, chainState);
+      finalized = chainState.deposit === 0n;
+    }
+    if (!finalized) return null;
+    const recovered = await store.confirmClose(channelId, drainId, `channel:${channelId}`);
+    return recovered.reference;
+  };
+  const getClose = store.getClose?.bind(store) ?? (() => Promise.resolve(null));
+  const beginClose = store.beginClose?.bind(store);
+  const withCloseIntent = store.withCloseIntent?.bind(store);
+  const resolveCloseForecast = store.resolveCloseForecast?.bind(store);
+  const releaseCloseIntent = store.releaseCloseIntent?.bind(store);
+  const confirmClose = store.confirmClose?.bind(store);
+  return Object.assign(mppx, {
+    sweepTempoSessions,
+    ...beginClose && {
+      beginTempoSessionClose: async (channelId, drainId) => {
+        await beginClose(channelId, drainId);
+      }
+    },
+    ...withCloseIntent && { withTempoSessionCloseIntent: withCloseIntent },
+    ...resolveCloseForecast && {
+      resolveTempoSessionCloseForecast: resolveCloseForecast
+    },
+    ...releaseCloseIntent && { releaseTempoSessionCloseIntent: releaseCloseIntent },
+    ...confirmClose && {
+      confirmTempoSessionClose: async (channelId, drainId, reference) => (await confirmClose(channelId, drainId, reference)).reference ?? reference
+    },
+    ...store.getClose && store.confirmClose && { recoverTempoSessionClose },
+    ...store.getClose && {
+      getTempoSessionCloseIntent: (channelId) => getClose(channelId.toLowerCase())
+    }
+  });
+}
+function readTempoSessionState(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const state = value;
+  if (typeof state.channelId !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(state.channelId) || typeof state.chainId !== "number" || typeof state.escrowContract !== "string" || typeof state.token !== "string" || !HEX_ADDRESS_RE.test(state.token) || typeof state.closeRequestedAt !== "bigint" || typeof state.deposit !== "bigint" || typeof state.highestVoucherAmount !== "bigint" || typeof state.spent !== "bigint" || typeof state.settledOnChain !== "bigint") {
+    return void 0;
+  }
+  return state;
+}
+function maxBigInt(left, right) {
+  return left > right ? left : right;
+}
+function isStateRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function tempoSettlementDue(args) {
+  const { channel, chainSettled, forcedClose, intervalMs } = args;
+  const settlementBoundary = Date.parse(channel.lastSettlementAt ?? channel.createdAt ?? "");
+  const scheduled = intervalMs !== void 0 && Number.isFinite(settlementBoundary) && Date.now() - settlementBoundary >= intervalMs;
+  if (!forcedClose && !scheduled) return false;
+  if (channel.highestVoucherAmount <= chainSettled) return false;
+  if (!forcedClose && channel.highestVoucherAmount !== channel.spent) return false;
+  return true;
+}
+function parseMppMethodsAllowlist(raw) {
+  if (!raw) return void 0;
+  const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : void 0;
+}
+function advertisedMethods(mppx) {
+  return mppx.methods.map((m) => {
+    const method = m;
+    return { method: method.name, intent: method.intent };
+  });
+}
+var _testing = {
+  attachTempoSessionRuntime
+};
+
+export {
+  TEMPO_SETTLEMENT_DEFAULT_LOW_BALANCE_MICRO,
+  TempoSettlementReadiness,
+  isTempoInsufficientFundsError,
+  MPPX_HMAC_MISMATCH_REASON,
+  TEMPO_SETTLEMENT_LEASE_FIELD,
+  TEMPO_SETTLEMENT_LEASE_OWNER_FIELD,
+  TEMPO_SETTLEMENT_LEASE_MS,
+  TEMPO_SETTLEMENT_IN_FLIGHT,
+  TEMPO_USDC_MAINNET,
+  challengeMeta,
+  createMppFromOpts,
+  createDualKeyMppxFromOpts,
+  wrapMppx,
+  parseMppMethodsAllowlist,
+  advertisedMethods,
+  _testing
+};