@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/server.test.ts

@@ -0,0 +1,223 @@
+import { createServer, type Server } from "node:http";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Hono } from "hono";
+import { paymentMiddleware } from "@x402/hono";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import {
+  decodePaymentRequiredHeader,
+  decodePaymentResponseHeader,
+  encodePaymentSignatureHeader,
+} from "@x402/core/http";
+import type { PaymentPayload, PaymentRequirements } from "@x402/core/types";
+import { USDZ } from "./networks.js";
+import { metalUsd, registerMetalScheme } from "./server.js";
+
+const PAY_TO = "0x000000000000000000000000000000000000b22b";
+const TX = `0x${"ab".repeat(32)}`;
+
+const verified: PaymentPayload[] = [];
+const facilitator = createServer((req, res) => {
+  const chunks: Buffer[] = [];
+  req.on("data", (c: Buffer) => chunks.push(c));
+  req.on("end", () => {
+    const body = (chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : {}) as {
+      paymentPayload?: PaymentPayload & { payload: { authorization?: { from?: string } } };
+    };
+    const payer = body.paymentPayload?.payload.authorization?.from;
+    const reply = (status: number, json: unknown) => {
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(json));
+    };
+    if (req.url === "/supported") {
+      return reply(200, {
+        kinds: [{ x402Version: 2, scheme: "exact", network: "eip155:1337" }],
+        extensions: [],
+        signers: { "eip155:*": ["0x00000000000000000000000000000000000000fa"] },
+      });
+    }
+    if (req.url === "/verify") {
+      if (body.paymentPayload) verified.push(body.paymentPayload);
+      if (payer?.endsWith("dead")) return reply(200, { isValid: false, invalidReason: "insufficient_funds", payer });
+      return reply(200, { isValid: true, payer });
+    }
+    if (req.url === "/settle") {
+      if (payer?.endsWith("f00d")) {
+        return reply(200, {
+          success: false,
+          errorReason: "transaction_failed",
+          errorMessage: "transferWithAuthorization reverted",
+          transaction: TX,
+          network: "eip155:1337",
+          payer,
+        });
+      }
+      return reply(200, { success: true, transaction: TX, network: "eip155:1337", payer });
+    }
+    reply(404, {});
+  });
+});
+
+let app: Hono;
+
+beforeAll(async () => {
+  const facilitatorUrl = await listen(facilitator);
+  const server = registerMetalScheme(
+    new x402ResourceServer(new HTTPFacilitatorClient({ url: facilitatorUrl })),
+    { networks: ["devnet"] },
+  );
+  app = new Hono();
+  app.use(
+    paymentMiddleware(
+      {
+        "GET /quote": {
+          accepts: { scheme: "exact", network: "eip155:1337", payTo: PAY_TO, price: "0.01", maxTimeoutSeconds: 60 },
+          description: "a quote",
+        },
+      },
+      server,
+    ),
+  );
+  app.get("/quote", (c) => c.json({ quote: "hono" }));
+  app.get("/free", (c) => c.json({ free: true }));
+});
+
+afterAll(() => new Promise<void>((resolve) => facilitator.close(() => resolve())));
+
+const fetchQuote = async (headers?: Record<string, string>) => app.request("http://seller.local/quote", { headers });
+
+function paymentFor(requirements: PaymentRequirements, from: string): PaymentPayload {
+  return {
+    x402Version: 2,
+    accepted: requirements,
+    payload: {
+      signature: `0x${"11".repeat(65)}`,
+      authorization: {
+        from,
+        to: requirements.payTo,
+        value: requirements.amount,
+        validAfter: "0",
+        validBefore: "9999999999",
+        nonce: `0x${"22".repeat(32)}`,
+      },
+    },
+  };
+}
+
+async function challenge(): Promise<PaymentRequirements> {
+  const unpaid = await fetchQuote();
+  expect(unpaid.status).toBe(402);
+  const required = decodePaymentRequiredHeader(unpaid.headers.get("payment-required") as string);
+  expect(required.accepts).toHaveLength(1);
+  expect(required.accepts[0]).toMatchObject({
+    scheme: "exact",
+    network: "eip155:1337",
+    asset: USDZ.address,
+    amount: "10000000000000000",
+    payTo: PAY_TO,
+    maxTimeoutSeconds: 60,
+    extra: { name: USDZ.name, version: USDZ.version, primaryType: "TransferWithAuthorization" },
+  });
+  return required.accepts[0] as PaymentRequirements;
+}
+
+describe("registerMetalScheme under @x402/hono", () => {
+  it("leaves free routes alone", async () => {
+    const res = await app.request("http://seller.local/free");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ free: true });
+  });
+
+  it("challenges in *USDZ, then serves and settles a verified payment", async () => {
+    const offer = await challenge();
+    const paid = await fetchQuote({
+      "payment-signature": encodePaymentSignatureHeader(
+        paymentFor(offer, "0x000000000000000000000000000000000000beef"),
+      ),
+    });
+    expect(paid.status).toBe(200);
+    expect(await paid.json()).toEqual({ quote: "hono" });
+    const settlement = decodePaymentResponseHeader(paid.headers.get("payment-response") as string);
+    expect(settlement).toMatchObject({ success: true, transaction: TX, network: "eip155:1337" });
+    expect(verified.at(-1)?.payload).toMatchObject({
+      authorization: { from: "0x000000000000000000000000000000000000beef", to: PAY_TO },
+    });
+  });
+
+  it("returns the facilitator's reason as a 402", async () => {
+    const offer = await challenge();
+    const refused = await fetchQuote({
+      "payment-signature": encodePaymentSignatureHeader(paymentFor(offer, "0x000000000000000000000000000000000000dead")),
+    });
+    expect(refused.status).toBe(402);
+    expect(decodePaymentRequiredHeader(refused.headers.get("payment-required") as string).error).toBe(
+      "insufficient_funds",
+    );
+  });
+
+  it("returns a settle refusal as a 402 whose payment-response header carries the reason", async () => {
+    const offer = await challenge();
+    const refused = await fetchQuote({
+      "payment-signature": encodePaymentSignatureHeader(paymentFor(offer, "0x000000000000000000000000000000000000f00d")),
+    });
+    expect(refused.status).toBe(402);
+    expect(refused.headers.get("payment-required")).toBeNull();
+    expect(await refused.json()).toEqual({});
+    expect(decodePaymentResponseHeader(refused.headers.get("payment-response") as string)).toMatchObject({
+      success: false,
+      errorReason: "transaction_failed",
+      errorMessage: "transferWithAuthorization reverted",
+      transaction: TX,
+      network: "eip155:1337",
+    });
+  });
+
+  it("refuses an unknown network name", () => {
+    expect(() => registerMetalScheme(new x402ResourceServer(), { networks: ["mainnet" as never] })).toThrow(
+      /unknown Metal network/,
+    );
+  });
+});
+
+describe("metalUsd on the stock exact scheme", () => {
+  const scheme = new ExactEvmScheme().registerMoneyParser(metalUsd("eip155:1337"));
+
+  it("prices dollars on its network in *USDZ under USDZ's EIP-712 domain, as a transfer authorization", async () => {
+    expect(await scheme.parsePrice("$0.001", "eip155:1337")).toEqual({
+      amount: (10n ** 15n).toString(),
+      asset: USDZ.address,
+      extra: { name: USDZ.name, version: USDZ.version, primaryType: "TransferWithAuthorization" },
+    });
+    expect(await scheme.parsePrice(1.5, "eip155:1337")).toMatchObject({ amount: (15n * 10n ** 17n).toString() });
+    expect(await scheme.parsePrice(1e-7, "eip155:1337")).toMatchObject({ amount: "100000000000" });
+  });
+
+  it("leaves every other network to the scheme's defaults", async () => {
+    expect(await scheme.parsePrice("$0.01", "eip155:8453")).toMatchObject({
+      amount: "10000",
+      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    });
+  });
+
+  it("prices in another dollar token with its own decimals", async () => {
+    const usdc = { ...USDZ, address: "0x2222222222222222222222222222222222222222", symbol: "USDC", decimals: 6 } as const;
+    const six = new ExactEvmScheme().registerMoneyParser(metalUsd("eip155:1337", usdc));
+    expect(await six.parsePrice("$0.01", "eip155:1337")).toMatchObject({ amount: "10000", asset: usdc.address });
+  });
+
+  it("refuses a price the token cannot carry exactly, and a price of zero", async () => {
+    await expect(scheme.parsePrice(1e-19, "eip155:1337")).rejects.toThrow(/decimals/);
+    await expect(scheme.parsePrice(0, "eip155:1337")).rejects.toThrow("not a price: 0");
+  });
+});
+
+function listen(server: Server): Promise<string> {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") return reject(new Error("no port"));
+      resolve(`http://127.0.0.1:${address.port}`);
+    });
+  });
+}

package/src/server.ts

@@ -0,0 +1,77 @@
+import type { x402ResourceServer } from "@x402/core/server";
+import type { AssetAmount, MoneyParser, Network } from "@x402/core/types";
+import { numberToDecimalString } from "@x402/core/utils";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+import {
+  METAL_NETWORKS,
+  USDZ,
+  baseUnits,
+  resolveNetwork,
+  type DollarToken,
+  type MetalNetwork,
+  type MetalNetworkName,
+} from "./networks.js";
+
+/**
+ * A dollar price (`"$0.01"`, `"0.01"`, `0.01`) in base units of `token`.
+ * Refuses a price the token cannot carry exactly, and one of zero.
+ */
+export function dollarBaseUnits(price: string | number, token: DollarToken): string {
+  const units = baseUnits(typeof price === "number" ? numberToDecimalString(price) : price, token);
+  if (BigInt(units) === 0n) throw new Error(`not a price: ${String(price)}`);
+  return units;
+}
+
+/**
+ * A money parser that prices dollar amounts on `network` in `token`, and
+ * leaves every other network to the scheme's own defaults. The stock seller
+ * scheme looks dollar prices up in a table of networks it ships, and Metal is
+ * not in it; this is the hook the scheme provides for that:
+ *
+ *     new ExactEvmScheme().registerMoneyParser(metalUsd("eip155:<chain id>"))
+ */
+export function metalUsd(network: Network, token: DollarToken = USDZ): MoneyParser {
+  return async (amount, on): Promise<AssetAmount | null> =>
+    on === network
+      ? {
+          amount: dollarBaseUnits(amount, token),
+          asset: token.address,
+          // `primaryType` names the ERC-3009 message the payer signs, so a
+          // client need not probe the token for which one it supports.
+          extra: { name: token.name, version: token.version, primaryType: "TransferWithAuthorization" },
+        }
+      : null;
+}
+
+/**
+ * The `createAuthHeaders` option of the stock `HTTPFacilitatorClient`, for
+ * the token Metal's facilitator issued to this seller.
+ */
+export function sellerToken(token: string) {
+  return async () => {
+    const headers = { Authorization: `Bearer ${token}` };
+    return { verify: headers, settle: headers };
+  };
+}
+
+export interface RegisterMetalSchemeConfig {
+  /** Which Metal networks to price offers on; both by default. */
+  networks?: readonly (MetalNetworkName | MetalNetwork)[];
+}
+
+/**
+ * Register the stock `exact` scheme on Metal's devnet and testnet (or the
+ * named ones) with a resource server, pricing dollar amounts in `*USDZ`, so
+ * the official middleware issues Metal offers and settles through the
+ * server's facilitator client.
+ */
+export function registerMetalScheme(
+  server: x402ResourceServer,
+  { networks }: RegisterMetalSchemeConfig = {},
+): x402ResourceServer {
+  for (const entry of networks ?? Object.values(METAL_NETWORKS)) {
+    const { network } = resolveNetwork(entry);
+    server.register(network, new ExactEvmScheme().registerMoneyParser(metalUsd(network)));
+  }
+  return server;
+}

package/dist/clearing.d.ts

@@ -1,204 +0,0 @@
-import { type Address, type Hex, type TypedDataDomain } from "viem";
-/** A Debit as it travels in a payment: uint values as decimal strings. */
-export interface DebitWire {
-    payer: Address;
-    recipient: Address;
-    epoch: string;
-    index: string;
-    cumulativeDebit: string;
-    ref: Hex;
-}
-/** The x402 scheme name of Metal's clearing lane. */
-export declare const CLEARING_DEBIT = "clearing-debit";
-export declare const CLEARING_DOMAIN_NAME = "MetalClearing";
-export declare const DEBIT_TYPES: {
-    readonly Debit: readonly [{
-        readonly name: "payer";
-        readonly type: "address";
-    }, {
-        readonly name: "recipient";
-        readonly type: "address";
-    }, {
-        readonly name: "epoch";
-        readonly type: "uint64";
-    }, {
-        readonly name: "index";
-        readonly type: "uint64";
-    }, {
-        readonly name: "cumulativeDebit";
-        readonly type: "uint256";
-    }, {
-        readonly name: "ref";
-        readonly type: "bytes32";
-    }];
-};
-export declare const RECEIPT_TYPES: {
-    readonly Receipt: readonly [{
-        readonly name: "recipient";
-        readonly type: "address";
-    }, {
-        readonly name: "epoch";
-        readonly type: "uint64";
-    }, {
-        readonly name: "shard";
-        readonly type: "uint64";
-    }, {
-        readonly name: "index";
-        readonly type: "uint64";
-    }, {
-        readonly name: "cumulativeCredit";
-        readonly type: "uint256";
-    }, {
-        readonly name: "prevReceiptDigest";
-        readonly type: "bytes32";
-    }, {
-        readonly name: "debitDigest";
-        readonly type: "bytes32";
-    }];
-};
-/** The payer's cumulative outgoing authorization for one epoch. */
-export interface Debit {
-    payer: Address;
-    recipient: Address;
-    epoch: bigint;
-    index: bigint;
-    cumulativeDebit: bigint;
-    ref: Hex;
-}
-/** The operator's acknowledgment crediting a recipient's receive shard. */
-export interface Receipt {
-    recipient: Address;
-    epoch: bigint;
-    shard: bigint;
-    index: bigint;
-    cumulativeCredit: bigint;
-    prevReceiptDigest: Hex;
-    debitDigest: Hex;
-}
-export declare function clearingDomain(chainId: number, contract: Address): TypedDataDomain;
-export declare function debitFromWire(wire: DebitWire): Debit;
-export declare function debitTypedData(domain: TypedDataDomain, debit: Debit): {
-    readonly domain: TypedDataDomain;
-    readonly types: {
-        readonly Debit: readonly [{
-            readonly name: "payer";
-            readonly type: "address";
-        }, {
-            readonly name: "recipient";
-            readonly type: "address";
-        }, {
-            readonly name: "epoch";
-            readonly type: "uint64";
-        }, {
-            readonly name: "index";
-            readonly type: "uint64";
-        }, {
-            readonly name: "cumulativeDebit";
-            readonly type: "uint256";
-        }, {
-            readonly name: "ref";
-            readonly type: "bytes32";
-        }];
-    };
-    readonly primaryType: "Debit";
-    readonly message: Debit;
-};
-export declare function receiptTypedData(domain: TypedDataDomain, receipt: Receipt): {
-    readonly domain: TypedDataDomain;
-    readonly types: {
-        readonly Receipt: readonly [{
-            readonly name: "recipient";
-            readonly type: "address";
-        }, {
-            readonly name: "epoch";
-            readonly type: "uint64";
-        }, {
-            readonly name: "shard";
-            readonly type: "uint64";
-        }, {
-            readonly name: "index";
-            readonly type: "uint64";
-        }, {
-            readonly name: "cumulativeCredit";
-            readonly type: "uint256";
-        }, {
-            readonly name: "prevReceiptDigest";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "debitDigest";
-            readonly type: "bytes32";
-        }];
-    };
-    readonly primaryType: "Receipt";
-    readonly message: Receipt;
-};
-export declare function debitDigest(domain: TypedDataDomain, debit: Debit): Hex;
-export declare function receiptDigest(domain: TypedDataDomain, receipt: Receipt): Hex;
-/** An account's request to take funds out of clearing custody. Only the
- * account can sign it, and it names where the funds go. */
-export declare const EXIT_TYPES: {
-    readonly Exit: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }, {
-        readonly name: "destination";
-        readonly type: "address";
-    }, {
-        readonly name: "amount";
-        readonly type: "uint256";
-    }, {
-        readonly name: "deadline";
-        readonly type: "uint64";
-    }];
-};
-export interface Exit {
-    account: Address;
-    destination: Address;
-    amount: bigint;
-    deadline: bigint;
-}
-export declare function exitTypedData(domain: TypedDataDomain, exit: Exit): {
-    readonly domain: TypedDataDomain;
-    readonly types: {
-        readonly Exit: readonly [{
-            readonly name: "account";
-            readonly type: "address";
-        }, {
-            readonly name: "destination";
-            readonly type: "address";
-        }, {
-            readonly name: "amount";
-            readonly type: "uint256";
-        }, {
-            readonly name: "deadline";
-            readonly type: "uint64";
-        }];
-    };
-    readonly primaryType: "Exit";
-    readonly message: Exit;
-};
-export declare function exitDigest(domain: TypedDataDomain, exit: Exit): Hex;
-export declare function recoverExitSigner(domain: TypedDataDomain, exit: Exit, signature: Hex): Promise<Address | null>;
-/** An account asking the facilitator about itself: where its next Debit
- * starts, or what it can withdraw. Signed under the clearing domain so that
- * only the account can read its own position; the deadline keeps a request
- * someone else has seen from being used for long. Never sent on chain. */
-export declare const ACCOUNT_REQUEST_TYPES: {
-    readonly AccountRequest: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }, {
-        readonly name: "deadline";
-        readonly type: "uint64";
-    }];
-};
-export declare function recoverAccountRequestSigner(domain: TypedDataDomain, request: {
-    account: Address;
-    deadline: bigint;
-}, signature: Hex): Promise<Address | null>;
-export declare function recoverDebitSigner(domain: TypedDataDomain, debit: Debit, signature: Hex): Promise<Address | null>;
-/** Receive shards spread a hot recipient over parallel credit lanes. The
- * shard is a pure function of `ref`, so a replayed debit lands on the same
- * one. Same formula as the café's. */
-export declare const REVENUE_SHARDS = 8n;
-export declare function shardFor(ref: Hex): bigint;

package/dist/clearing.js

@@ -1,151 +0,0 @@
-// Metal clearing's signed messages: the EIP-712 types and digests that a
-// payer, a seller, the facilitator and the clearing operator must agree on
-// field for field. They mirror contracts/src/clearing/ClearingTypes.sol and
-// the operator's local API (apps/clearing-operator).
-//
-// - A Debit is a payer's signed running total, naming who it pays.
-// - A Receipt is the operator's signature crediting a recipient's shard.
-// - An Exit is an account's signed withdrawal, naming where funds go.
-// - An AccountRequest is an account asking the facilitator about itself.
-//
-// All are signed under the Clearing contract's domain ("MetalClearing", "1",
-// chainId, contract). Pure: no I/O.
-import { hashTypedData, recoverTypedDataAddress, } from "viem";
-/** The x402 scheme name of Metal's clearing lane. */
-export const CLEARING_DEBIT = "clearing-debit";
-export const CLEARING_DOMAIN_NAME = "MetalClearing";
-export const DEBIT_TYPES = {
-    Debit: [
-        { name: "payer", type: "address" },
-        { name: "recipient", type: "address" },
-        { name: "epoch", type: "uint64" },
-        { name: "index", type: "uint64" },
-        { name: "cumulativeDebit", type: "uint256" },
-        { name: "ref", type: "bytes32" },
-    ],
-};
-export const RECEIPT_TYPES = {
-    Receipt: [
-        { name: "recipient", type: "address" },
-        { name: "epoch", type: "uint64" },
-        { name: "shard", type: "uint64" },
-        { name: "index", type: "uint64" },
-        { name: "cumulativeCredit", type: "uint256" },
-        { name: "prevReceiptDigest", type: "bytes32" },
-        { name: "debitDigest", type: "bytes32" },
-    ],
-};
-export function clearingDomain(chainId, contract) {
-    return {
-        name: CLEARING_DOMAIN_NAME,
-        version: "1",
-        chainId,
-        verifyingContract: contract,
-    };
-}
-export function debitFromWire(wire) {
-    return {
-        payer: wire.payer,
-        recipient: wire.recipient,
-        epoch: BigInt(wire.epoch),
-        index: BigInt(wire.index),
-        cumulativeDebit: BigInt(wire.cumulativeDebit),
-        ref: wire.ref,
-    };
-}
-export function debitTypedData(domain, debit) {
-    return {
-        domain,
-        types: DEBIT_TYPES,
-        primaryType: "Debit",
-        message: debit,
-    };
-}
-export function receiptTypedData(domain, receipt) {
-    return {
-        domain,
-        types: RECEIPT_TYPES,
-        primaryType: "Receipt",
-        message: receipt,
-    };
-}
-export function debitDigest(domain, debit) {
-    return hashTypedData(debitTypedData(domain, debit));
-}
-export function receiptDigest(domain, receipt) {
-    return hashTypedData(receiptTypedData(domain, receipt));
-}
-/** An account's request to take funds out of clearing custody. Only the
- * account can sign it, and it names where the funds go. */
-export const EXIT_TYPES = {
-    Exit: [
-        { name: "account", type: "address" },
-        { name: "destination", type: "address" },
-        { name: "amount", type: "uint256" },
-        { name: "deadline", type: "uint64" },
-    ],
-};
-export function exitTypedData(domain, exit) {
-    return {
-        domain,
-        types: EXIT_TYPES,
-        primaryType: "Exit",
-        message: exit,
-    };
-}
-export function exitDigest(domain, exit) {
-    return hashTypedData(exitTypedData(domain, exit));
-}
-export async function recoverExitSigner(domain, exit, signature) {
-    try {
-        return await recoverTypedDataAddress({
-            ...exitTypedData(domain, exit),
-            signature,
-        });
-    }
-    catch {
-        return null;
-    }
-}
-/** An account asking the facilitator about itself: where its next Debit
- * starts, or what it can withdraw. Signed under the clearing domain so that
- * only the account can read its own position; the deadline keeps a request
- * someone else has seen from being used for long. Never sent on chain. */
-export const ACCOUNT_REQUEST_TYPES = {
-    AccountRequest: [
-        { name: "account", type: "address" },
-        { name: "deadline", type: "uint64" },
-    ],
-};
-export async function recoverAccountRequestSigner(domain, request, signature) {
-    try {
-        return await recoverTypedDataAddress({
-            domain,
-            types: ACCOUNT_REQUEST_TYPES,
-            primaryType: "AccountRequest",
-            message: request,
-            signature,
-        });
-    }
-    catch {
-        return null;
-    }
-}
-export async function recoverDebitSigner(domain, debit, signature) {
-    try {
-        return await recoverTypedDataAddress({
-            ...debitTypedData(domain, debit),
-            signature,
-        });
-    }
-    catch {
-        return null;
-    }
-}
-/** Receive shards spread a hot recipient over parallel credit lanes. The
- * shard is a pure function of `ref`, so a replayed debit lands on the same
- * one. Same formula as the café's. */
-export const REVENUE_SHARDS = 8n;
-export function shardFor(ref) {
-    return BigInt(`0x${ref.slice(-2)}`) % REVENUE_SHARDS;
-}

package/dist/file-storage.d.ts

@@ -1,39 +0,0 @@
-import { type ClearingPositionStorage, type StoredClearingPosition } from "./clearing-client.js";
-export interface FileClearingPositionStorageOptions {
-    /** How long a writer waits for the lock before giving up. Default 5s. */
-    lockWaitMs?: number;
-    /** A lock this old was left by a writer that died or hung. Default 30s;
-     * a write holds the lock for milliseconds. */
-    lockStaleMs?: number;
-}
-export declare class FileClearingPositionStorage implements ClearingPositionStorage {
-    private readonly path;
-    private readonly lockPath;
-    private readonly takeoverPath;
-    private readonly lockWaitMs;
-    private readonly lockStaleMs;
-    constructor(path: string, options?: FileClearingPositionStorageOptions);
-    private read;
-    /** Hold the lock file while `job` runs. The whole file is read, changed
-     * and rewritten, so two writers (two instances, or two processes) must
-     * not overlap or one would drop the other's record.
-     *
-     * The lock is a file created exclusively, holding a token unique to its
-     * holder. A lock left by a writer that died is taken over, and that is
-     * the delicate part: two waiters must not both conclude it is abandoned
-     * and both remove it, or the second would delete the first one's fresh
-     * lock. So removal itself is guarded (see `takeOver`), and a writer whose
-     * lock was taken over finds out before it writes (`stillHeld`). */
-    private locked;
-    private inspect;
-    /** Remove `path` only while it still holds `token`. */
-    private removeIfHolds;
-    /** Remove an abandoned lock, at most one waiter at a time. The takeover
-     * file is itself created exclusively, so only one waiter is ever inside;
-     * it removes the lock only if it is still the abandoned one it saw. A
-     * waiter that arrives later finds either no lock or a fresh one from a
-     * new holder, and leaves it alone. */
-    private takeOver;
-    get(key: string): Promise<StoredClearingPosition | undefined>;
-    set(key: string, position: StoredClearingPosition): Promise<void>;
-}