@verify-network/protocol 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verify Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/domain-CXJsoNRU.d.ts

@@ -0,0 +1,9 @@
+import { Address } from "viem";
+//#region src/domain.d.ts
+/** One router deployment: what request ids and fulfillment digests are bound to. */
+type RouterDomain = {
+  readonly chainId: bigint | number;
+  readonly router: Address;
+};
+//#endregion
+export { RouterDomain as t };

package/dist/ecvrf.d.ts

@@ -0,0 +1,69 @@
+import { Hex } from "viem";
+//#region src/ecvrf.d.ts
+/**
+ * ECVRF-SECP256K1-SHA256-TAI, the RFC 9381 cipher suite the router's `ECVRFVerifier` checks,
+ * on `@noble/curves` and `@noble/hashes`. Hash-to-curve, the challenge, the proof encoding,
+ * and the randomness derivation mirror `VRF.sol` so the enclave and the router agree byte for
+ * byte; the nonce is RFC 6979, as RFC 9381 prescribes for the suite. Every function is pure and
+ * synchronous, so it runs unchanged on a `node:worker_threads` worker, under Node and Bun.
+ */
+/** A proof as the router takes it: `[gammaX, gammaY, c, s]`. */
+export type Proof = readonly [gammaX: bigint, gammaY: bigint, c: bigint, s: bigint];
+/** An enclave key as the router stores it: the uncompressed point's `[x, y]`. */
+export type PublicKey = readonly [x: bigint, y: bigint];
+/**
+ * `VRF.HASH_TO_CURVE_MAX_ITERATIONS`: the try-and-increment attempts the on-chain verifier makes
+ * before declaring an alpha unfulfillable (probability 2^-50 per request).
+ */
+export declare const HASH_TO_CURVE_MAX_ITERATIONS = 50;
+/** What a fulfiller submits for an alpha that fails the hash-to-curve check. */
+export declare const SENTINEL_PROOF: Proof;
+/** The router recognises the sentinel by its gamma alone. */
+export declare const isSentinel: ([gammaX, gammaY]: Proof) => boolean;
+/**
+ * The `[x, y]` point the router stores, from the key viem derives (`0x04 || x || y`). Throws
+ * when the key is not on the curve.
+ */
+export declare const publicKeyPoint: (publicKey: Hex) => PublicKey;
+/**
+ * Proves `alpha` (the request id) under the enclave key. Deterministic: RFC 6979 fixes the nonce.
+ * Throws when `alpha` has no curve point within the on-chain cap; the fulfiller submits the
+ * sentinel for such a request (see `isFulfillable`).
+ */
+export declare const prove: ({ privateKey, alpha }: {
+  privateKey: Hex;
+  alpha: Hex;
+}) => Proof;
+/**
+ * Whether `proof` proves `alpha` under `publicKey`, as `ECVRFVerifier.verify` decides: gamma must
+ * be a curve point with the `y` as submitted (the router multiplies it as given), `c` must fit 16
+ * bytes, `s` must be below the group order, and `alpha` must hash to a point within the cap.
+ */
+export declare const verify: ({ publicKey, proof, alpha }: {
+  publicKey: PublicKey;
+  proof: Proof;
+  alpha: Hex;
+}) => boolean;
+/**
+ * The 81-byte RFC 9381 proof string: compressed gamma, `c` in 16 bytes, `s` in 32. Throws when
+ * a scalar does not fit.
+ */
+export declare const encodeProof: ([gammaX, gammaY, c, s]: Proof) => Hex;
+/** The router's four limbs from an RFC 9381 proof string. Throws when the string is malformed. */
+export declare const decodeProof: (encoded: Hex) => Proof;
+/**
+ * The randomness a proof yields, as `VRF.gammaToHash` derives it: sha256 of the suite byte,
+ * `0x03`, the compressed gamma, and a zero byte. Zero for the sentinel, as the router emits it.
+ */
+export declare const deriveRandomness: (proof: Proof) => Hex;
+/** What the enclave signs over: `keccak256(abi.encode(proof))` in the router. */
+export declare const proofCommitment: (proof: Proof) => Hex;
+/**
+ * The try-and-increment attempts `VRF.tryHashToPoint` needs to hash `alpha` to a point for
+ * `publicKey`, or `null` when none is found within `maxIterations`: such a request cannot be
+ * proven and is closed with the sentinel.
+ */
+export declare const hashToCurveIterations: (publicKey: PublicKey, alpha: Hex, maxIterations?: number) => number | null;
+/** Whether the on-chain verifier can hash `alpha` to a point for `publicKey`. */
+export declare const isFulfillable: (publicKey: PublicKey, alpha: Hex, maxIterations?: number) => boolean;
+//#endregion

package/dist/ecvrf.js

@@ -0,0 +1,174 @@
+import { bytesToHex, encodeAbiParameters, hexToBytes, keccak256, zeroHash } from "viem";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { bytesToNumberBE, concatBytes, createHmacDrbg, numberToBytesBE } from "@noble/curves/utils.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+//#region src/ecvrf.ts
+/**
+* `VRF.HASH_TO_CURVE_MAX_ITERATIONS`: the try-and-increment attempts the on-chain verifier makes
+* before declaring an alpha unfulfillable (probability 2^-50 per request).
+*/
+const HASH_TO_CURVE_MAX_ITERATIONS = 50;
+/** What a fulfiller submits for an alpha that fails the hash-to-curve check. */
+const SENTINEL_PROOF = [
+	0n,
+	0n,
+	0n,
+	0n
+];
+/** The router recognises the sentinel by its gamma alone. */
+const isSentinel = ([gammaX, gammaY]) => gammaX === 0n && gammaY === 0n;
+const { Point } = secp256k1;
+const G = Point.BASE;
+/** The group order, RFC 9381's `q`. */
+const Q = Point.Fn.ORDER;
+/** The suite string; the byte after it separates the three hashes the suite takes. */
+const SUITE = 254;
+/** RFC 9381 sizes for the suite: the challenge `c` is 16 bytes, the proof string 33 + 16 + 32. */
+const C_BYTES = 16;
+const C_LIMIT = 1n << 128n;
+const PROOF_BYTES = 81;
+/** The curve point at `[x, y]`. Throws when there is none, including for the sentinel. */
+const point = ([x, y]) => {
+	const p = Point.fromAffine({
+		x,
+		y
+	});
+	p.assertValidity();
+	return p;
+};
+const limbs = (p) => {
+	const { x, y } = p.toAffine();
+	return [x, y];
+};
+/** `VRF.encodePoint`: SEC 1 compressed, the parity prefix then `x`, over the limbs as given. */
+const encodePoint = (x, y) => concatBytes(Uint8Array.of(y % 2n === 0n ? 2 : 3), numberToBytesBE(x, 32));
+const compressed = (p) => encodePoint(...limbs(p));
+/**
+* The `[x, y]` point the router stores, from the key viem derives (`0x04 || x || y`). Throws
+* when the key is not on the curve.
+*/
+const publicKeyPoint = (publicKey) => limbs(Point.fromBytes(hexToBytes(publicKey)));
+/**
+* `VRF.tryHashToPoint`: try-and-increment over
+* `sha256(0xfe || 0x01 || compressed key || alpha || counter || 0x00)`, reading each digest as
+* the `x` of an even-`y` point; a digest of zero or at least the field prime yields none, as
+* `EllipticCurve.isOnCurve` decides. The point and the attempts it took, or `null` past the cap.
+*/
+const hashToCurve = (publicKey, alpha, maxIterations) => {
+	const prefix = concatBytes(Uint8Array.of(SUITE, 1), encodePoint(...publicKey), alpha);
+	for (let counter = 0; counter < maxIterations; counter++) {
+		const digest = sha256(concatBytes(prefix, Uint8Array.of(counter, 0)));
+		try {
+			return {
+				point: Point.fromBytes(concatBytes(Uint8Array.of(2), digest)),
+				iterations: counter + 1
+			};
+		} catch {}
+	}
+	return null;
+};
+/**
+* `VRF.hashPoints`: the first 16 bytes of `sha256(0xfe || 0x02 || H || Gamma || U || V || 0x00)`,
+* the points compressed.
+*/
+const challenge = (points) => bytesToNumberBE(sha256(concatBytes(Uint8Array.of(SUITE, 2), ...points.map(compressed), Uint8Array.of(0))).subarray(0, C_BYTES));
+const drbg = createHmacDrbg(32, 32, (key, message) => hmac(sha256, key, message));
+/**
+* RFC 9381 §5.4.2.1: the nonce RFC 6979 §3.2 derives from the secret scalar and `sha256` of the
+* compressed `H`, so a proof is a function of the key and alpha alone.
+*/
+const nonce = (x, h) => {
+	const h1 = bytesToNumberBE(sha256(compressed(h))) % Q;
+	return drbg(concatBytes(numberToBytesBE(x, 32), numberToBytesBE(h1, 32)), (candidate) => {
+		const k = bytesToNumberBE(candidate);
+		return k > 0n && k < Q ? k : void 0;
+	});
+};
+/**
+* Proves `alpha` (the request id) under the enclave key. Deterministic: RFC 6979 fixes the nonce.
+* Throws when `alpha` has no curve point within the on-chain cap; the fulfiller submits the
+* sentinel for such a request (see `isFulfillable`).
+*/
+const prove = ({ privateKey, alpha }) => {
+	const x = bytesToNumberBE(hexToBytes(privateKey));
+	const publicKey = G.multiply(x);
+	const hashed = hashToCurve(limbs(publicKey), hexToBytes(alpha), 50);
+	if (hashed === null) throw new Error("ECVRF alpha has no curve point within the on-chain cap");
+	const h = hashed.point;
+	const gamma = h.multiply(x);
+	const k = nonce(x, h);
+	const c = challenge([
+		h,
+		gamma,
+		G.multiply(k),
+		h.multiply(k)
+	]);
+	return [
+		...limbs(gamma),
+		c,
+		(k + c * x) % Q
+	];
+};
+/**
+* Whether `proof` proves `alpha` under `publicKey`, as `ECVRFVerifier.verify` decides: gamma must
+* be a curve point with the `y` as submitted (the router multiplies it as given), `c` must fit 16
+* bytes, `s` must be below the group order, and `alpha` must hash to a point within the cap.
+*/
+const verify = ({ publicKey, proof, alpha }) => {
+	const [gammaX, gammaY, c, s] = proof;
+	if (c >= C_LIMIT || s >= Q) return false;
+	try {
+		const y = point(publicKey);
+		const gamma = point([gammaX, gammaY]);
+		const hashed = hashToCurve(publicKey, hexToBytes(alpha), 50);
+		if (hashed === null) return false;
+		const h = hashed.point;
+		const u = G.mulAddUnsafe(s, y.negate(), c);
+		const v = h.mulAddUnsafe(s, gamma.negate(), c);
+		return challenge([
+			h,
+			gamma,
+			u,
+			v
+		]) === c;
+	} catch {
+		return false;
+	}
+};
+/**
+* The 81-byte RFC 9381 proof string: compressed gamma, `c` in 16 bytes, `s` in 32. Throws when
+* a scalar does not fit.
+*/
+const encodeProof = ([gammaX, gammaY, c, s]) => bytesToHex(concatBytes(encodePoint(gammaX, gammaY), numberToBytesBE(c, C_BYTES), numberToBytesBE(s, 32)));
+/** The router's four limbs from an RFC 9381 proof string. Throws when the string is malformed. */
+const decodeProof = (encoded) => {
+	const proof = hexToBytes(encoded);
+	if (proof.length !== PROOF_BYTES) throw new Error("ECVRF proof must be 81 bytes");
+	const gamma = Point.fromBytes(proof.subarray(0, 33));
+	const c = bytesToNumberBE(proof.subarray(33, 49));
+	const s = bytesToNumberBE(proof.subarray(49));
+	if (s >= Q) throw new Error("ECVRF proof scalar s must be below the group order");
+	return [
+		...limbs(gamma),
+		c,
+		s
+	];
+};
+/**
+* The randomness a proof yields, as `VRF.gammaToHash` derives it: sha256 of the suite byte,
+* `0x03`, the compressed gamma, and a zero byte. Zero for the sentinel, as the router emits it.
+*/
+const deriveRandomness = (proof) => isSentinel(proof) ? zeroHash : bytesToHex(sha256(concatBytes(Uint8Array.of(SUITE, 3), encodePoint(proof[0], proof[1]), Uint8Array.of(0))));
+/** What the enclave signs over: `keccak256(abi.encode(proof))` in the router. */
+const proofCommitment = (proof) => keccak256(encodeAbiParameters([{ type: "uint256[4]" }], [proof]));
+/**
+* The try-and-increment attempts `VRF.tryHashToPoint` needs to hash `alpha` to a point for
+* `publicKey`, or `null` when none is found within `maxIterations`: such a request cannot be
+* proven and is closed with the sentinel.
+*/
+const hashToCurveIterations = (publicKey, alpha, maxIterations = 50) => hashToCurve(publicKey, hexToBytes(alpha), maxIterations)?.iterations ?? null;
+/** Whether the on-chain verifier can hash `alpha` to a point for `publicKey`. */
+const isFulfillable = (publicKey, alpha, maxIterations = 50) => hashToCurveIterations(publicKey, alpha, maxIterations) !== null;
+//#endregion
+export { HASH_TO_CURVE_MAX_ITERATIONS, SENTINEL_PROOF, decodeProof, deriveRandomness, encodeProof, hashToCurveIterations, isFulfillable, isSentinel, proofCommitment, prove, publicKeyPoint, verify };

package/dist/event.d.ts

@@ -0,0 +1,101 @@
+import { Proof } from "./ecvrf.js";
+import { Request } from "./request.js";
+import { Hex, Log } from "viem";
+//#region src/event.d.ts
+/**
+ * `VrfFacet.RandomnessRequested`: the id, consumer, and fulfiller indexed for filtering, the
+ * whole request as data so anyone can recompute the id and the fulfiller can echo it. Spelled
+ * out here because the protocol package does not depend on the contracts package; the
+ * contracts package's `test/Vrf.test.ts` decodes a real log through it and catches drift.
+ */
+export declare const randomnessRequestedEvent: {
+  readonly name: "RandomnessRequested";
+  readonly type: 'event';
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "requestId";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "consumer";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "fulfiller";
+    readonly indexed: true;
+  }, {
+    readonly type: 'tuple';
+    readonly components: readonly [{
+      readonly type: "address";
+      readonly name: "consumer";
+    }, {
+      readonly type: "uint64";
+      readonly name: "sequence";
+    }, {
+      readonly type: "address";
+      readonly name: "fulfiller";
+    }, {
+      readonly type: "uint40";
+      readonly name: "assignedAt";
+    }, {
+      readonly type: "uint96";
+      readonly name: "fee";
+    }, {
+      readonly type: "uint96";
+      readonly name: "gasPrice";
+    }, {
+      readonly type: "uint32";
+      readonly name: "callbackGasLimit";
+    }, {
+      readonly type: "bytes";
+      readonly name: "callbackData";
+    }];
+    readonly name: "request";
+  }];
+};
+/**
+ * `VrfFacet.RandomnessFulfilled`: the id indexed, the randomness and the evidence (the proof and
+ * the enclave signature, which a challenge takes) as data. Spelled out here for the same reason
+ * as the request event, and held to the real log by the same test.
+ */
+export declare const randomnessFulfilledEvent: {
+  readonly name: "RandomnessFulfilled";
+  readonly type: 'event';
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "requestId";
+    readonly indexed: true;
+  }, {
+    readonly type: "bytes32";
+    readonly name: "randomness";
+  }, {
+    readonly type: "uint256[4]";
+    readonly name: "proof";
+  }, {
+    readonly type: "bytes";
+    readonly name: "enclaveSignature";
+  }];
+};
+/** The part of a log the decoder reads, as every viem client returns it. */
+export type EventLog = Pick<Log, "data" | "topics">;
+/**
+ * Decodes a `RandomnessRequested` log into its id and a `Request` in the schema's shape, so
+ * the decoded request passes to `requestId` or a typed router call unchanged. Throws on a log
+ * of another event.
+ */
+export declare const decodeRandomnessRequested: (log: EventLog) => {
+  readonly requestId: Hex;
+  readonly request: Request;
+};
+/**
+ * Decodes a `RandomnessFulfilled` log into the id it closed, the randomness delivered, and the
+ * evidence (the proof and the enclave signature) a challenge or a verifier takes. Throws on a
+ * log of another event.
+ */
+export declare const decodeRandomnessFulfilled: (log: EventLog) => {
+  readonly requestId: Hex;
+  readonly randomness: Hex;
+  readonly proof: Proof;
+  readonly enclaveSignature: Hex;
+};
+//#endregion

package/dist/event.js

@@ -0,0 +1,53 @@
+import { decodeEventLog, parseAbiItem } from "viem";
+//#region src/event.ts
+/**
+* `VrfFacet.RandomnessRequested`: the id, consumer, and fulfiller indexed for filtering, the
+* whole request as data so anyone can recompute the id and the fulfiller can echo it. Spelled
+* out here because the protocol package does not depend on the contracts package; the
+* contracts package's `test/Vrf.test.ts` decodes a real log through it and catches drift.
+*/
+const randomnessRequestedEvent = parseAbiItem("event RandomnessRequested(bytes32 indexed requestId, address indexed consumer, address indexed fulfiller, (address consumer, uint64 sequence, address fulfiller, uint40 assignedAt, uint96 fee, uint96 gasPrice, uint32 callbackGasLimit, bytes callbackData) request)");
+/**
+* `VrfFacet.RandomnessFulfilled`: the id indexed, the randomness and the evidence (the proof and
+* the enclave signature, which a challenge takes) as data. Spelled out here for the same reason
+* as the request event, and held to the real log by the same test.
+*/
+const randomnessFulfilledEvent = parseAbiItem("event RandomnessFulfilled(bytes32 indexed requestId, bytes32 randomness, uint256[4] proof, bytes enclaveSignature)");
+/**
+* Decodes a `RandomnessRequested` log into its id and a `Request` in the schema's shape, so
+* the decoded request passes to `requestId` or a typed router call unchanged. Throws on a log
+* of another event.
+*/
+const decodeRandomnessRequested = (log) => {
+	const { args } = decodeEventLog({
+		abi: [randomnessRequestedEvent],
+		eventName: "RandomnessRequested",
+		data: log.data,
+		topics: log.topics
+	});
+	return {
+		requestId: args.requestId,
+		request: args.request
+	};
+};
+/**
+* Decodes a `RandomnessFulfilled` log into the id it closed, the randomness delivered, and the
+* evidence (the proof and the enclave signature) a challenge or a verifier takes. Throws on a
+* log of another event.
+*/
+const decodeRandomnessFulfilled = (log) => {
+	const { args } = decodeEventLog({
+		abi: [randomnessFulfilledEvent],
+		eventName: "RandomnessFulfilled",
+		data: log.data,
+		topics: log.topics
+	});
+	return {
+		requestId: args.requestId,
+		randomness: args.randomness,
+		proof: args.proof,
+		enclaveSignature: args.enclaveSignature
+	};
+};
+//#endregion
+export { decodeRandomnessFulfilled, decodeRandomnessRequested, randomnessFulfilledEvent, randomnessRequestedEvent };

package/dist/fee.d.ts

@@ -0,0 +1,142 @@
+import { Hex } from "viem";
+//#region src/fee.d.ts
+/** EIP-1559 fees for one broadcast. */
+export type GasFees = {
+  readonly maxFeePerGas: bigint;
+  readonly maxPriorityFeePerGas: bigint;
+};
+/** The fees a node's sender never goes below unless configured otherwise; tuned for Base. */
+export declare const DEFAULT_FEE_FLOOR: GasFees;
+/**
+ * The fees a node's sender bids given the latest base fee: twice the base fee plus the tip, never
+ * under the floor. Here because a signer mirrors it: the enclave refuses an authorization whose
+ * maximum gas price is under this bid (ADR 0028), so a client sizes its maximum from it.
+ */
+export declare const computeFees: (baseFeePerGas: bigint, floor?: GasFees) => GasFees;
+/**
+ * `Config.CALLDATA_GAS_PER_BYTE`: EIP-7623's calldata floor for a non-zero byte, charged for every
+ * echoed byte (ADR 0023).
+ */
+export declare const CALLDATA_GAS_PER_BYTE = 40n;
+/**
+ * The gas price a request locks, mirroring the router's: the request transaction's gas price, never
+ * below the base fee of the block it lands in (ADR 0019). An OP-stack L1→L2 deposit transaction
+ * runs at a zero gas price; priced at that, its request would reserve nothing and its fulfillment
+ * charge nothing.
+ */
+export declare const lockedGasPrice: ({ gasPrice, baseFeePerGas }: {
+  readonly gasPrice: bigint;
+  readonly baseFeePerGas: bigint;
+}) => bigint;
+/**
+ * The fee a request locks at request time (ADR 0013, 0019, 0023):
+ * `(callbackGasLimit + fulfillmentOverheadGas + 40 × callbackDataLength) × lockedGasPrice × (100% + premium)`,
+ * rounded down to the wei, where the locked gas price is `gasPrice` floored at `baseFeePerGas`
+ * (`lockedGasPrice`). Mirrors the router's fee, so the router must multiply before it divides by
+ * 100 too. Gas amounts and the premium are accepted as `number` so a decoded request can be priced
+ * without conversion.
+ */
+export declare const fee: ({ callbackGasLimit, fulfillmentOverheadGas, callbackDataLength, gasPrice, baseFeePerGas, premiumPercent }: {
+  readonly callbackGasLimit: bigint | number;
+  readonly fulfillmentOverheadGas: bigint | number;
+  readonly callbackDataLength: bigint | number;
+  /** The gas price the request transaction is sent at. */
+  readonly gasPrice: bigint;
+  /** The base fee of the block the request lands in: the floor of the locked gas price. */
+  readonly baseFeePerGas: bigint;
+  readonly premiumPercent: bigint | number;
+}) => bigint;
+/**
+ * The most a direct request can ever charge (ADR 0028): the reservation formula at the maximum
+ * gas price the authorization names, with the same overhead and premium as an on-chain request.
+ * Mirrors the router's ceiling, which debits it from the signer's balance before the callback and
+ * credits back what the settlement does not take.
+ */
+export declare const ceiling: ({ callbackGasLimit, fulfillmentOverheadGas, callbackDataLength, maxGasPrice, premiumPercent }: {
+  readonly callbackGasLimit: bigint | number;
+  readonly fulfillmentOverheadGas: bigint | number;
+  readonly callbackDataLength: bigint | number;
+  /** The most the signer agreed to pay per gas: `DirectRequest.maxGasPrice`. */
+  readonly maxGasPrice: bigint;
+  readonly premiumPercent: bigint | number;
+}) => bigint;
+/**
+ * What a fulfillment is owed for the gas it took, mirroring the router's settlement: that gas at
+ * the price the request locked, plus the premium, and never more than the request reserved. The
+ * submitting transaction's gas price does not change it (ADR 0019). The premium decays in a
+ * straight line with the time since the assignment (ADR 0029): whole when `settledAt`, the
+ * router's `block.timestamp`, is `assignedAt`, and nothing once the request is late (ADR 0025),
+ * so the same timing decides the quote here and on the router:
+ * `gasUsed × lockedGasPrice × (100 × D + premiumPercent × remaining) / (100 × D)`, with `D` the
+ * stale delay and `remaining` the seconds left of it (`remainingDelay`). Everything is multiplied
+ * before the one division, as on the router, so both round down to the same wei. The rest of the
+ * reservation goes back to the consumer.
+ */
+export declare const settlement: ({ gasUsed, requestGasPrice, premiumPercent, fee: reserved, assignedAt, settledAt }: {
+  readonly gasUsed: bigint | number;
+  readonly requestGasPrice: bigint;
+  readonly premiumPercent: bigint | number;
+  readonly fee: bigint;
+  readonly assignedAt: bigint | number;
+  readonly settledAt: bigint | number;
+}) => bigint;
+/**
+ * The share of the premium a settlement pays (ADR 0029), exact: `remaining` seconds of the stale
+ * delay's `delay`. A fraction and not a percentage, so a charge is reproduced from it to the wei.
+ */
+export type PremiumShare = {
+  readonly remaining: bigint;
+  readonly delay: bigint;
+};
+/** The whole premium: what the assignment's block pays, and a direct request whenever it lands. */
+export declare const WHOLE_PREMIUM: PremiumShare;
+/**
+ * The share of the premium a fulfillment settled at `settledAt`, the router's `block.timestamp`,
+ * was paid for a request assigned at `assignedAt`. `RequestSettled` does not carry it, so a reader
+ * of a settlement works it out from the two times, by the same `remainingDelay` the charge uses.
+ */
+export declare const premiumShare: ({ assignedAt, settledAt }: {
+  readonly assignedAt: bigint | number;
+  readonly settledAt: bigint | number;
+}) => PremiumShare;
+/**
+ * `settlement` at a share of the premium already worked out, as the router's own takes the
+ * seconds left: `gasUsed × lockedGasPrice × (100 × delay + premiumPercent × remaining) / (100 × delay)`,
+ * capped by the reservation.
+ */
+export declare const settlementAtShare: ({ gasUsed, requestGasPrice, premiumPercent, fee: reserved, share: { remaining, delay } }: {
+  readonly gasUsed: bigint | number;
+  readonly requestGasPrice: bigint;
+  readonly premiumPercent: bigint | number;
+  readonly fee: bigint;
+  readonly share: PremiumShare;
+}) => bigint;
+/**
+ * The gas a charge was computed from, which `RequestSettled` does not carry: the charge divided
+ * back by the locked price and the premium's share, rounded up, since the charge was rounded down
+ * by less than one gas's worth. `settlementAtShare` on it reproduces the charge to the wei. A
+ * charge the reservation capped says only that the gas was at least this; a gas price of nothing
+ * says nothing of the gas.
+ */
+export declare const chargedGas: ({ charged, requestGasPrice, premiumPercent, share: { remaining, delay } }: {
+  readonly charged: bigint;
+  readonly requestGasPrice: bigint;
+  readonly premiumPercent: bigint | number;
+  readonly share: PremiumShare;
+}) => bigint;
+/** Transaction intrinsic gas. */
+export declare const INTRINSIC_GAS = 21000n;
+/**
+ * The gas one fulfillment adds to a transaction, given the calldata that carries it, every byte
+ * at EIP-7623's non-zero floor (`CALLDATA_GAS_PER_BYTE`), below which the chain refuses a
+ * transaction whose execution is small beside its calldata (ADR 0023). The router
+ * reverts `InsufficientFulfillmentGas` unless `gasleft()` at the callback covers the callback gas
+ * limit scaled by 64/63 (EIP-150 keeps a 64th back from a call) plus what it needs afterwards, so
+ * the item needs that requirement plus everything spent before the callback. A batch's limit is
+ * the intrinsic gas plus every item's share.
+ */
+export declare const fulfillmentItemGas: ({ callbackGasLimit, data }: {
+  readonly callbackGasLimit: number;
+  readonly data: Hex;
+}) => bigint;
+//#endregion