@verify-network/protocol 0.0.0-stage → 0.1.1

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

package/dist/fee.js

@@ -0,0 +1,142 @@
+import { remainingDelay } from "./request.js";
+import { parseGwei, size } from "viem";
+//#region src/fee.ts
+/** The fees a node's sender never goes below unless configured otherwise; tuned for Base. */
+const DEFAULT_FEE_FLOOR = {
+	maxFeePerGas: parseGwei("0.005"),
+	maxPriorityFeePerGas: parseGwei("0.001")
+};
+/** Headroom over the base fee so a send stays mineable while the base fee climbs between refreshes. */
+const BASE_FEE_MULTIPLIER = 2n;
+/**
+* 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.
+*/
+const computeFees = (baseFeePerGas, floor = DEFAULT_FEE_FLOOR) => {
+	const headroom = baseFeePerGas * BASE_FEE_MULTIPLIER + floor.maxPriorityFeePerGas;
+	return {
+		maxFeePerGas: headroom > floor.maxFeePerGas ? headroom : floor.maxFeePerGas,
+		maxPriorityFeePerGas: floor.maxPriorityFeePerGas
+	};
+};
+/**
+* `Config.CALLDATA_GAS_PER_BYTE`: EIP-7623's calldata floor for a non-zero byte, charged for every
+* echoed byte (ADR 0023).
+*/
+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.
+*/
+const lockedGasPrice = ({ gasPrice, baseFeePerGas }) => gasPrice > baseFeePerGas ? gasPrice : baseFeePerGas;
+/**
+* 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.
+*/
+const fee = ({ callbackGasLimit, fulfillmentOverheadGas, callbackDataLength, gasPrice, baseFeePerGas, premiumPercent }) => (BigInt(callbackGasLimit) + BigInt(fulfillmentOverheadGas) + CALLDATA_GAS_PER_BYTE * BigInt(callbackDataLength)) * lockedGasPrice({
+	gasPrice,
+	baseFeePerGas
+}) * (100n + BigInt(premiumPercent)) / 100n;
+/**
+* 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.
+*/
+const ceiling = ({ callbackGasLimit, fulfillmentOverheadGas, callbackDataLength, maxGasPrice, premiumPercent }) => fee({
+	callbackGasLimit,
+	fulfillmentOverheadGas,
+	callbackDataLength,
+	gasPrice: maxGasPrice,
+	baseFeePerGas: 0n,
+	premiumPercent
+});
+/**
+* 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.
+*/
+const settlement = ({ gasUsed, requestGasPrice, premiumPercent, fee: reserved, assignedAt, settledAt }) => settlementAtShare({
+	gasUsed,
+	requestGasPrice,
+	premiumPercent,
+	fee: reserved,
+	share: premiumShare({
+		assignedAt,
+		settledAt
+	})
+});
+/** The whole premium: what the assignment's block pays, and a direct request whenever it lands. */
+const WHOLE_PREMIUM = {
+	remaining: BigInt(30),
+	delay: BigInt(30)
+};
+/**
+* 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.
+*/
+const premiumShare = ({ assignedAt, settledAt }) => ({
+	remaining: remainingDelay({
+		assignedAt,
+		at: settledAt
+	}),
+	delay: BigInt(30)
+});
+/**
+* `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.
+*/
+const settlementAtShare = ({ gasUsed, requestGasPrice, premiumPercent, fee: reserved, share: { remaining, delay } }) => {
+	const amount = BigInt(gasUsed) * requestGasPrice * (100n * delay + BigInt(premiumPercent) * remaining) / (100n * delay);
+	return amount > reserved ? reserved : amount;
+};
+/**
+* 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.
+*/
+const chargedGas = ({ charged, requestGasPrice, premiumPercent, share: { remaining, delay } }) => {
+	const perGas = requestGasPrice * (100n * delay + BigInt(premiumPercent) * remaining);
+	return perGas === 0n ? 0n : (charged * 100n * delay + perGas - 1n) / perGas;
+};
+/** Transaction intrinsic gas. */
+const INTRINSIC_GAS = 21000n;
+/**
+* What the router spends around the callback: the diamond dispatch, recomputing the request
+* id, recovering the enclave signature, closing the request, and crediting the operator before
+* it, the event after it. Measured under 60k besides the callback (`GasBudget.test.ts`); the
+* margin covers cold storage slots, and in a batch the array encoding around each item.
+*/
+const FULFILLMENT_OVERHEAD_GAS = 150000n;
+/** `Config.FULFILLMENT_POST_CALLBACK_GAS`: what the router keeps back for after the callback. */
+const FULFILLMENT_POST_CALLBACK_GAS = 80000n;
+/**
+* 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.
+*/
+const fulfillmentItemGas = ({ callbackGasLimit, data }) => CALLDATA_GAS_PER_BYTE * BigInt(size(data)) + FULFILLMENT_OVERHEAD_GAS + BigInt(callbackGasLimit) * 64n / 63n + FULFILLMENT_POST_CALLBACK_GAS;
+//#endregion
+export { CALLDATA_GAS_PER_BYTE, DEFAULT_FEE_FLOOR, INTRINSIC_GAS, WHOLE_PREMIUM, ceiling, chargedGas, computeFees, fee, fulfillmentItemGas, lockedGasPrice, premiumShare, settlement, settlementAtShare };

package/dist/fulfillment.d.ts

@@ -0,0 +1,32 @@
+import { t as RouterDomain } from "./domain-CXJsoNRU.js";
+import { Hex } from "viem";
+//#region src/fulfillment.d.ts
+/** The typed data an enclave signs to deliver a fulfillment, as viem's `signTypedData` takes it. */
+export declare const fulfillmentTypedData: ({ chainId, router, requestId, proofCommitment }: RouterDomain & {
+  readonly requestId: Hex;
+  readonly proofCommitment: Hex;
+}) => {
+  readonly domain: {
+    readonly name: "VerifyNetworkVRF";
+    readonly version: "2";
+    readonly chainId: number | bigint;
+    readonly verifyingContract: `0x${string}`;
+  };
+  readonly types: {
+    readonly Fulfillment: readonly [{
+      readonly name: "requestId";
+      readonly type: "bytes32";
+    }, {
+      readonly name: "proofCommitment";
+      readonly type: "bytes32";
+    }];
+  };
+  readonly primaryType: "Fulfillment";
+  readonly message: {
+    readonly requestId: `0x${string}`;
+    readonly proofCommitment: `0x${string}`;
+  };
+};
+/** Mirrors `Signatures.fulfillmentDigest` in the router: the hash the enclave signature is recovered against. */
+export declare const fulfillmentDigest: (fulfillment: Parameters<typeof fulfillmentTypedData>[0]) => Hex;
+//#endregion

package/dist/fulfillment.js

@@ -0,0 +1,28 @@
+import { hashTypedData } from "viem";
+//#region src/fulfillment.ts
+const fulfillmentTypes = { Fulfillment: [{
+	name: "requestId",
+	type: "bytes32"
+}, {
+	name: "proofCommitment",
+	type: "bytes32"
+}] };
+/** The typed data an enclave signs to deliver a fulfillment, as viem's `signTypedData` takes it. */
+const fulfillmentTypedData = ({ chainId, router, requestId, proofCommitment }) => ({
+	domain: {
+		name: "VerifyNetworkVRF",
+		version: "2",
+		chainId,
+		verifyingContract: router
+	},
+	types: fulfillmentTypes,
+	primaryType: "Fulfillment",
+	message: {
+		requestId,
+		proofCommitment
+	}
+});
+/** Mirrors `Signatures.fulfillmentDigest` in the router: the hash the enclave signature is recovered against. */
+const fulfillmentDigest = (fulfillment) => hashTypedData(fulfillmentTypedData(fulfillment));
+//#endregion
+export { fulfillmentDigest, fulfillmentTypedData };