@verify-network/contracts 0.0.0-stage → 0.1.1

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/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @verify-network/contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What a consumer of the Verify Network router builds against. It holds the Solidity interfaces a consumer imports, the viem-ready ABIs of the router's facets, and the creation bytecode and diamond cut helpers for deploying the router yourself.
+
+## Install
+
+```sh
+npm install @verify-network/contracts viem
+```
+
+`viem` (`^2.56.3`) is a peer dependency. Node 22 or later.
+
+## Solidity interfaces
+
+| Import                                                         | Contents                                                            |
+| -------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `@verify-network/contracts/contracts/IVerifyNetworkRouter.sol` | The router functions a consumer calls: the requests and the balance |
+| `@verify-network/contracts/contracts/IVrfReceiver.sol`         | The callback a consumer implements to receive randomness            |
+| `@verify-network/contracts/contracts/IDirectVrfReceiver.sol`   | The callback a consumer implements to receive direct requests       |
+
+Hardhat 3 resolves these paths from `node_modules` as they are. Foundry needs one remapping:
+
+```
+@verify-network/contracts/=node_modules/@verify-network/contracts/
+```
+
+A minimal consumer:
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.30;
+
+import {IVerifyNetworkRouter} from "@verify-network/contracts/contracts/IVerifyNetworkRouter.sol";
+import {IVrfReceiver} from "@verify-network/contracts/contracts/IVrfReceiver.sol";
+
+contract Lottery is IVrfReceiver {
+    IVerifyNetworkRouter public immutable router;
+    address public immutable owner;
+
+    error OnlyRouter(address caller);
+
+    constructor(IVerifyNetworkRouter router_) {
+        router = router_;
+        owner = msg.sender;
+    }
+
+    /// Requests from this contract's balance on the router. The round travels as callback data.
+    function draw(uint256 round) external returns (bytes32 requestId) {
+        requestId = router.requestRandomness(abi.encode(round), 200_000);
+    }
+
+    /// The router calls this with exactly the callback gas limit of the request.
+    function onRandomnessFulfilled(bytes32, bytes32 randomness, bytes calldata callbackData) external {
+        if (msg.sender != address(router)) revert OnlyRouter(msg.sender);
+        uint256 round = abi.decode(callbackData, (uint256));
+        // settle `round` with `randomness`
+    }
+
+    /// Refunds of stale requests land on this contract's balance on the router.
+    function withdrawBalance(address recipient, uint256 amount) external {
+        require(msg.sender == owner);
+        router.withdraw(recipient, amount);
+    }
+}
+```
+
+Fund it once with `router.deposit(address(lottery))`. It pays for each request from that balance. Two rules apply to every consumer:
+
+- Only the router may call the callback. Nothing else authenticates the randomness.
+- Give the consumer a way to withdraw. A stale request's refund goes to the consumer's balance on the router, even when the request was paid with `msg.value`.
+
+The router stores only the request id. Your callback data is hashed into it and returned to your callback verbatim, so a consumer may keep its whole pending state there, up to 16 KiB.
+
+## ABIs
+
+Each ABI is the default export of `@verify-network/contracts/abi/<Contract>`, typed `as const` for viem:
+
+| ABI                    | Use                                                                        |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `VrfFacet`             | Requests, fulfillments, stale reports, challenges, and the router's events |
+| `BalancesFacet`        | `deposit`, `withdraw`, `balanceOf`                                         |
+| `ConfigFacet`          | `pricing()`, the stake, and the admin's settings                           |
+| `NodesFacet`           | The active set, node keys (`publicKeyOf`), and endpoints (`endpointOf`)    |
+| `IVerifyNetworkRouter` | The consumer's subset of the router                                        |
+| `IVrfReceiver`         | The on-chain request callback                                              |
+| `IDirectVrfReceiver`   | The direct request callback                                                |
+
+The router is an EIP-2535 diamond, so every facet lives at the router's address.
+
+```ts
+import BalancesFacet from "@verify-network/contracts/abi/BalancesFacet";
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+
+const publicClient = createPublicClient({ chain: base, transport: http() });
+const balance = await publicClient.readContract({
+  address: "0x…", // the router
+  abi: BalancesFacet,
+  functionName: "balanceOf",
+  args: ["0x…"], // the consumer
+});
+console.log(balance);
+```
+
+## Deploy the router yourself
+
+`@verify-network/contracts/artifacts` holds the ABI and creation bytecode of every contract a router deployment needs: `Router`, `RouterInit`, `ECVRFVerifier`, `TrustedNodeEnclaveKeyVerifier`, and the facets in `FACETS`. Each one is in the shape viem's `deployContract` takes.
+
+`@verify-network/contracts/diamond` holds the EIP-2535 helpers. `DIAMOND_ACTIONS` and `facetSelectors` build the first `diamondCut`. `planFacetCut` and `facetCuts` plan an in-place upgrade of one facet from the diamond loupe. They refuse a selector that another facet already serves.
+
+To test a consumer against a local router, use `@verify-network/local`. It deploys these artifacts and runs a node that fulfills requests.
+
+## License
+
+MIT

package/contracts/IDirectVrfReceiver.sol

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.0;
+
+/// @notice What a consumer implements to receive a direct request's randomness (ADR 0026). A
+/// different selector from `IVrfReceiver.onRandomnessFulfilled`, so a consumer that never opted
+/// in cannot mistake a direct fulfillment for a request it made itself. `signer` is who signed
+/// the authorization and paid for it; what that signer may do here is the consumer's to decide.
+/// `callbackData` is what the signer committed to in the authorization, authenticated by the
+/// request id, so a bet the randomness resolves belongs in it, never after.
+interface IDirectVrfReceiver {
+    function onDirectRandomness(
+        bytes32 requestId,
+        address signer,
+        bytes32 randomness,
+        bytes calldata callbackData
+    ) external;
+}

package/contracts/IVerifyNetworkRouter.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.0;
+
+/// @notice The part of the router a consumer calls: the request overloads of `VrfFacet` and the
+/// balance functions of `BalancesFacet`. The router is one address for every facet (an EIP-2535
+/// diamond), so this is the router's address on the target chain.
+///
+/// The router stores only the id of an open request: `callbackData` is hashed into the request
+/// id, echoed back by the fulfiller, and checked by the router before it reaches
+/// `IVrfReceiver.onRandomnessFulfilled`, so a consumer may keep its whole pending state in it. At
+/// most 16 KiB (`CallbackDataTooLong` above).
+///
+/// The fee is reserved when the request is made, from the callback gas limit, the callback data's
+/// length, the gas price, and the router's premium (`ConfigFacet.pricing()`). It is taken from
+/// `msg.value` when one is sent, the excess credited to the caller's balance, and from the
+/// caller's balance on the router otherwise. The fulfillment charges the gas it took, at the gas
+/// price the request locked, and the rest of the reservation goes back to the caller's balance.
+interface IVerifyNetworkRouter {
+    /// @notice Requests randomness with the router's default callback gas limit.
+    /// @return requestId The id the callback and `RandomnessFulfilled` carry.
+    function requestRandomness(
+        bytes calldata callbackData
+    ) external payable returns (bytes32 requestId);
+
+    /// @notice Requests randomness with a chosen callback gas limit, at most the router's max.
+    /// @return requestId The id the callback and `RandomnessFulfilled` carry.
+    function requestRandomness(
+        bytes calldata callbackData,
+        uint32 callbackGasLimit
+    ) external payable returns (bytes32 requestId);
+
+    /// @notice Credits `msg.value` to `account`'s balance on the router. Anyone may fund anyone.
+    function deposit(address account) external payable;
+
+    /// @notice Pays `amount` of the caller's own balance to `recipient`.
+    function withdraw(address recipient, uint256 amount) external;
+
+    /// @notice What `account` holds on the router to pay for its requests.
+    function balanceOf(address account) external view returns (uint256);
+}

package/contracts/IVrfReceiver.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.0;
+
+/// @notice What a consumer implements to receive randomness. `callbackData` is exactly what the
+/// consumer passed to `requestRandomness`; the router authenticated it through the request id, so
+/// the consumer may treat it as its own state. The selector is the baseline's, so existing
+/// consumers keep working.
+interface IVrfReceiver {
+    function onRandomnessFulfilled(
+        bytes32 requestId,
+        bytes32 randomness,
+        bytes calldata callbackData
+    ) external;
+}

package/dist/abi/Balances.d.ts

@@ -0,0 +1,32 @@
+//#region abi/Balances.d.ts
+declare const _default: readonly [{
+  readonly inputs: readonly [{
+    readonly internalType: "address";
+    readonly name: "account";
+    readonly type: "address";
+  }, {
+    readonly internalType: "uint256";
+    readonly name: "balance";
+    readonly type: "uint256";
+  }, {
+    readonly internalType: "uint256";
+    readonly name: "needed";
+    readonly type: "uint256";
+  }];
+  readonly name: "InsufficientBalance";
+  readonly type: "error";
+}, {
+  readonly inputs: readonly [{
+    readonly internalType: "address";
+    readonly name: "recipient";
+    readonly type: "address";
+  }, {
+    readonly internalType: "uint256";
+    readonly name: "amount";
+    readonly type: "uint256";
+  }];
+  readonly name: "TransferFailed";
+  readonly type: "error";
+}];
+//#endregion
+export { _default as default };

package/dist/abi/Balances.js

@@ -0,0 +1,36 @@
+//#region abi/Balances.ts
+var Balances_default = [{
+	"inputs": [
+		{
+			"internalType": "address",
+			"name": "account",
+			"type": "address"
+		},
+		{
+			"internalType": "uint256",
+			"name": "balance",
+			"type": "uint256"
+		},
+		{
+			"internalType": "uint256",
+			"name": "needed",
+			"type": "uint256"
+		}
+	],
+	"name": "InsufficientBalance",
+	"type": "error"
+}, {
+	"inputs": [{
+		"internalType": "address",
+		"name": "recipient",
+		"type": "address"
+	}, {
+		"internalType": "uint256",
+		"name": "amount",
+		"type": "uint256"
+	}],
+	"name": "TransferFailed",
+	"type": "error"
+}];
+//#endregion
+export { Balances_default as default };

package/dist/abi/BalancesFacet.d.ts

@@ -0,0 +1,110 @@
+//#region abi/BalancesFacet.d.ts
+declare const _default: readonly [{
+  readonly inputs: readonly [{
+    readonly internalType: "address";
+    readonly name: "account";
+    readonly type: "address";
+  }, {
+    readonly internalType: "uint256";
+    readonly name: "balance";
+    readonly type: "uint256";
+  }, {
+    readonly internalType: "uint256";
+    readonly name: "needed";
+    readonly type: "uint256";
+  }];
+  readonly name: "InsufficientBalance";
+  readonly type: "error";
+}, {
+  readonly inputs: readonly [{
+    readonly internalType: "address";
+    readonly name: "recipient";
+    readonly type: "address";
+  }, {
+    readonly internalType: "uint256";
+    readonly name: "amount";
+    readonly type: "uint256";
+  }];
+  readonly name: "TransferFailed";
+  readonly type: "error";
+}, {
+  readonly anonymous: false;
+  readonly inputs: readonly [{
+    readonly indexed: true;
+    readonly internalType: "address";
+    readonly name: "account";
+    readonly type: "address";
+  }, {
+    readonly indexed: true;
+    readonly internalType: "address";
+    readonly name: "from";
+    readonly type: "address";
+  }, {
+    readonly indexed: false;
+    readonly internalType: "uint256";
+    readonly name: "amount";
+    readonly type: "uint256";
+  }];
+  readonly name: "Deposited";
+  readonly type: "event";
+}, {
+  readonly anonymous: false;
+  readonly inputs: readonly [{
+    readonly indexed: true;
+    readonly internalType: "address";
+    readonly name: "account";
+    readonly type: "address";
+  }, {
+    readonly indexed: true;
+    readonly internalType: "address";
+    readonly name: "recipient";
+    readonly type: "address";
+  }, {
+    readonly indexed: false;
+    readonly internalType: "uint256";
+    readonly name: "amount";
+    readonly type: "uint256";
+  }];
+  readonly name: "Withdrawn";
+  readonly type: "event";
+}, {
+  readonly inputs: readonly [{
+    readonly internalType: "address";
+    readonly name: "account";
+    readonly type: "address";
+  }];
+  readonly name: "balanceOf";
+  readonly outputs: readonly [{
+    readonly internalType: "uint256";
+    readonly name: "";
+    readonly type: "uint256";
+  }];
+  readonly stateMutability: "view";
+  readonly type: "function";
+}, {
+  readonly inputs: readonly [{
+    readonly internalType: "address";
+    readonly name: "account";
+    readonly type: "address";
+  }];
+  readonly name: "deposit";
+  readonly outputs: readonly [];
+  readonly stateMutability: "payable";
+  readonly type: "function";
+}, {
+  readonly inputs: readonly [{
+    readonly internalType: "address";
+    readonly name: "recipient";
+    readonly type: "address";
+  }, {
+    readonly internalType: "uint256";
+    readonly name: "amount";
+    readonly type: "uint256";
+  }];
+  readonly name: "withdraw";
+  readonly outputs: readonly [];
+  readonly stateMutability: "nonpayable";
+  readonly type: "function";
+}];
+//#endregion
+export { _default as default };

package/dist/abi/BalancesFacet.js

@@ -0,0 +1,130 @@
+//#region abi/BalancesFacet.ts
+var BalancesFacet_default = [
+	{
+		"inputs": [
+			{
+				"internalType": "address",
+				"name": "account",
+				"type": "address"
+			},
+			{
+				"internalType": "uint256",
+				"name": "balance",
+				"type": "uint256"
+			},
+			{
+				"internalType": "uint256",
+				"name": "needed",
+				"type": "uint256"
+			}
+		],
+		"name": "InsufficientBalance",
+		"type": "error"
+	},
+	{
+		"inputs": [{
+			"internalType": "address",
+			"name": "recipient",
+			"type": "address"
+		}, {
+			"internalType": "uint256",
+			"name": "amount",
+			"type": "uint256"
+		}],
+		"name": "TransferFailed",
+		"type": "error"
+	},
+	{
+		"anonymous": false,
+		"inputs": [
+			{
+				"indexed": true,
+				"internalType": "address",
+				"name": "account",
+				"type": "address"
+			},
+			{
+				"indexed": true,
+				"internalType": "address",
+				"name": "from",
+				"type": "address"
+			},
+			{
+				"indexed": false,
+				"internalType": "uint256",
+				"name": "amount",
+				"type": "uint256"
+			}
+		],
+		"name": "Deposited",
+		"type": "event"
+	},
+	{
+		"anonymous": false,
+		"inputs": [
+			{
+				"indexed": true,
+				"internalType": "address",
+				"name": "account",
+				"type": "address"
+			},
+			{
+				"indexed": true,
+				"internalType": "address",
+				"name": "recipient",
+				"type": "address"
+			},
+			{
+				"indexed": false,
+				"internalType": "uint256",
+				"name": "amount",
+				"type": "uint256"
+			}
+		],
+		"name": "Withdrawn",
+		"type": "event"
+	},
+	{
+		"inputs": [{
+			"internalType": "address",
+			"name": "account",
+			"type": "address"
+		}],
+		"name": "balanceOf",
+		"outputs": [{
+			"internalType": "uint256",
+			"name": "",
+			"type": "uint256"
+		}],
+		"stateMutability": "view",
+		"type": "function"
+	},
+	{
+		"inputs": [{
+			"internalType": "address",
+			"name": "account",
+			"type": "address"
+		}],
+		"name": "deposit",
+		"outputs": [],
+		"stateMutability": "payable",
+		"type": "function"
+	},
+	{
+		"inputs": [{
+			"internalType": "address",
+			"name": "recipient",
+			"type": "address"
+		}, {
+			"internalType": "uint256",
+			"name": "amount",
+			"type": "uint256"
+		}],
+		"name": "withdraw",
+		"outputs": [],
+		"stateMutability": "nonpayable",
+		"type": "function"
+	}
+];
+//#endregion
+export { BalancesFacet_default as default };

package/dist/abi/Config.d.ts

@@ -0,0 +1,12 @@
+//#region abi/Config.d.ts
+declare const _default: readonly [{
+  readonly inputs: readonly [{
+    readonly internalType: "address";
+    readonly name: "verifier";
+    readonly type: "address";
+  }];
+  readonly name: "VerifierWithoutCode";
+  readonly type: "error";
+}];
+//#endregion
+export { _default as default };

package/dist/abi/Config.js

@@ -0,0 +1,12 @@
+//#region abi/Config.ts
+var Config_default = [{
+	"inputs": [{
+		"internalType": "address",
+		"name": "verifier",
+		"type": "address"
+	}],
+	"name": "VerifierWithoutCode",
+	"type": "error"
+}];
+//#endregion
+export { Config_default as default };