kokio-sdk 1.0.0 → 2.0.0

package/dist/esm/logic/admin/protocolAdmin.eoa.js

@@ -0,0 +1,524 @@
+import { encodeFunctionData, publicActions } from "viem";
+import { _getChainSpecificConstants } from "../constants.js";
+import { MissingEOAWalletError } from "../errors.js";
+import { ProtocolAdmin, Registry } from "../../abis/index.js";
+// Admin-EOA logic for `ProtocolAdmin`, the timelock that owns `Registry`,
+// `LazyWalletRegistry`, `DeviceWalletFactory` and `ESIMWalletFactory`.
+//
+// Anything `onlyOwner` on those four contracts goes one way: a proposer schedules
+// it, the delay elapses, and anyone executes it. Only `schedule` and `cancel` need
+// a privileged EOA. Execution is open, so the `client` for `_execute` can be any
+// funded account.
+//
+// The guardian calls and `_acceptOwnershipBatch` are the exceptions: they land
+// straight away with no delay.
+const ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+const _resolve = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    return _getChainSpecificConstants(chainID, rpcURL);
+};
+// Turns an `OwnerCall` into the (target, value, payload) triple the timelock stores.
+const _encode = (call) => ({
+    target: call.address,
+    value: call.value ?? 0n,
+    payload: encodeFunctionData({
+        abi: call.abi,
+        functionName: call.functionName,
+        args: call.args,
+    }),
+});
+// ---------------------------------------------------------------------------
+// Operation ids
+// ---------------------------------------------------------------------------
+/**
+ * The id the timelock will file this call under. Computed on chain so the SDK
+ * and the contract cannot disagree about it.
+ */
+export const _operationId = async (client, call, opts = {}) => {
+    const values = await _resolve(client);
+    const { target, value, payload } = _encode(call);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "hashOperation",
+        args: [target, value, payload, opts.predecessor ?? ZERO_BYTES32, opts.salt ?? ZERO_BYTES32]
+    });
+};
+/** The id for a batch. Hashes differently from the same calls scheduled one by one. */
+export const _operationIdBatch = async (client, calls, opts = {}) => {
+    const values = await _resolve(client);
+    const encoded = calls.map(_encode);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "hashOperationBatch",
+        args: [
+            encoded.map((e) => e.target),
+            encoded.map((e) => e.value),
+            encoded.map((e) => e.payload),
+            opts.predecessor ?? ZERO_BYTES32,
+            opts.salt ?? ZERO_BYTES32
+        ]
+    });
+};
+/**
+ * The id for a payload built outside this SDK. `_scheduleRaw` hands back only a
+ * transaction hash, so this is the only way to get the id that `cancel`,
+ * `getTimestamp` and the `isOperation*` reads need.
+ */
+export const _operationIdRaw = async (client, target, value, payload, predecessor, salt) => {
+    const values = await _resolve(client);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "hashOperation",
+        args: [target, value, payload, predecessor, salt]
+    });
+};
+/** The id for a raw batch. Same reason as `_operationIdRaw`. */
+export const _operationIdBatchRaw = async (client, targets, callValues, payloads, predecessor, salt) => {
+    const values = await _resolve(client);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "hashOperationBatch",
+        args: [targets, callValues, payloads, predecessor, salt]
+    });
+};
+// ---------------------------------------------------------------------------
+// Scheduling - PROPOSER_ROLE
+// ---------------------------------------------------------------------------
+/**
+ * Announce an owner call. `PROPOSER_ROLE`.
+ *
+ * `delay` defaults to `getMinDelay()`. Keep the returned object: `execute` rebuilds
+ * the id from it, and without it the arguments have to be recovered from the
+ * `CallScheduled` event.
+ */
+export const _schedule = async (client, call, opts = {}, delay) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    const { target, value, payload } = _encode(call);
+    const predecessor = opts.predecessor ?? ZERO_BYTES32;
+    const salt = opts.salt ?? ZERO_BYTES32;
+    const publicClient = client.extend(publicActions);
+    const resolvedDelay = delay ?? await publicClient.readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "getMinDelay",
+        args: []
+    });
+    const id = await publicClient.readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "hashOperation",
+        args: [target, value, payload, predecessor, salt]
+    });
+    const hash = await client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'schedule',
+        args: [target, value, payload, predecessor, salt, resolvedDelay]
+    });
+    return { hash, id, target, value, payload, predecessor, salt, delay: resolvedDelay };
+};
+/**
+ * Announce several owner calls as one operation. `PROPOSER_ROLE`.
+ *
+ * Use this where the calls only make sense together, such as evicting a guardian,
+ * which needs both its guardian and its executor role revoked before it can act
+ * again.
+ */
+export const _scheduleBatch = async (client, calls, opts = {}, delay) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    const encoded = calls.map(_encode);
+    const targets = encoded.map((e) => e.target);
+    const callValues = encoded.map((e) => e.value);
+    const payloads = encoded.map((e) => e.payload);
+    const predecessor = opts.predecessor ?? ZERO_BYTES32;
+    const salt = opts.salt ?? ZERO_BYTES32;
+    const publicClient = client.extend(publicActions);
+    const resolvedDelay = delay ?? await publicClient.readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "getMinDelay",
+        args: []
+    });
+    const id = await publicClient.readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "hashOperationBatch",
+        args: [targets, callValues, payloads, predecessor, salt]
+    });
+    const hash = await client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'scheduleBatch',
+        args: [targets, callValues, payloads, predecessor, salt, resolvedDelay]
+    });
+    return { hash, id, targets, values: callValues, payloads, predecessor, salt, delay: resolvedDelay };
+};
+/**
+ * Schedule a payload built elsewhere. `PROPOSER_ROLE`. For calldata that did not
+ * come from an ABI in this SDK.
+ *
+ * Returns what `_schedule` returns, so the id needed to cancel or inspect the
+ * operation comes back with it.
+ */
+export const _scheduleRaw = async (client, target, value, payload, predecessor, salt, delay) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    const id = await client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: "hashOperation",
+        args: [target, value, payload, predecessor, salt]
+    });
+    const hash = await client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'schedule',
+        args: [target, value, payload, predecessor, salt, delay]
+    });
+    return { hash, id, target, value, payload, predecessor, salt, delay };
+};
+// ---------------------------------------------------------------------------
+// Execution - open to anyone
+// ---------------------------------------------------------------------------
+/**
+ * Run a scheduled operation once its delay has elapsed. Permissionless, so any
+ * funded EOA works.
+ *
+ * Pass back the object `schedule` returned. The timelock recomputes the id from
+ * these fields, so an altered value looks up an operation that was never
+ * scheduled and reverts.
+ */
+export const _execute = async (client, operation) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'execute',
+        args: [operation.target, operation.value, operation.payload, operation.predecessor, operation.salt],
+        value: operation.value
+    });
+};
+/** Run a scheduled batch. Permissionless, same rules as `_execute`. */
+export const _executeBatch = async (client, operation) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'executeBatch',
+        args: [operation.targets, operation.values, operation.payloads, operation.predecessor, operation.salt],
+        value: operation.values.reduce((sum, v) => sum + v, 0n)
+    });
+};
+/** Execute a payload scheduled through `_scheduleRaw`. Permissionless. */
+export const _executeRaw = async (client, target, value, payload, predecessor, salt) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'execute',
+        args: [target, value, payload, predecessor, salt],
+        value
+    });
+};
+// ---------------------------------------------------------------------------
+// Cancelling - CANCELLER_ROLE
+// ---------------------------------------------------------------------------
+/**
+ * Drop a scheduled operation before it runs. `CANCELLER_ROLE`, which every
+ * proposer also holds.
+ */
+export const _cancel = async (client, id) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'cancel',
+        args: [id]
+    });
+};
+// ---------------------------------------------------------------------------
+// Guardian powers - GUARDIAN_ROLE, no delay
+// ---------------------------------------------------------------------------
+/**
+ * Release a pause on a protocol contract straight away. `GUARDIAN_ROLE`.
+ *
+ * The selector is fixed in the contract, so this cannot be pointed at anything
+ * else on the target.
+ */
+export const _unpauseInstantly = async (client, target) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'unpauseInstantly',
+        args: [target]
+    });
+};
+/**
+ * Strip the cancel power from accounts straight away. `GUARDIAN_ROLE`.
+ *
+ * All or nothing: an account that does not hold the role reverts the whole batch
+ * rather than being skipped, so a guardian acting on a list is never left
+ * believing a veto is gone while it is still there.
+ */
+export const _revokeCancellersInstantly = async (client, accounts) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'revokeCancellersInstantly',
+        args: [accounts]
+    });
+};
+/**
+ * Suspend a protocol contract's admin key straight away. `GUARDIAN_ROLE`.
+ *
+ * Takes the power away and hands none out. Reinstating the key or naming a
+ * replacement is an owner action and waits out the delay.
+ *
+ * `target` defaults to the registry, the one contract that keeps the admin
+ * address. Everything else reads it from there, so suspending it there closes
+ * every gate in the protocol.
+ */
+export const _disableAdminInstantly = async (client, target) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'disableAdminInstantly',
+        args: [target ?? values.factoryAddresses.REGISTRY]
+    });
+};
+// ---------------------------------------------------------------------------
+// Ownership handover and role exit - permissionless / self
+// ---------------------------------------------------------------------------
+/**
+ * Finish taking ownership of contracts that have already offered it.
+ * Permissionless, and reverts `OwnershipNotOffered` for any target whose
+ * `pendingOwner` is not the timelock.
+ */
+export const _acceptOwnershipBatch = async (client, targets) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'acceptOwnershipBatch',
+        args: [targets]
+    });
+};
+/**
+ * Give up one of your own roles. The chain requires `account` to be the caller,
+ * so this is the one role change that does not wait.
+ */
+export const _renounceRole = async (client, role, account) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ProtocolAdmin,
+        functionName: 'renounceRole',
+        args: [role, account]
+    });
+};
+// ---------------------------------------------------------------------------
+// Self-call payloads - only reachable through schedule
+// ---------------------------------------------------------------------------
+// These four are `msg.sender == address(this)` on chain, so they exist only as
+// something to schedule. Each builds the `OwnerCall` to hand to `schedule`, which
+// is why they return a call rather than sending one.
+/** Grant a role. Pass the result to `schedule`. */
+export const _grantRoleCall = async (client, role, account) => {
+    const values = await _resolve(client);
+    return {
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: 'grantRole',
+        args: [role, account],
+    };
+};
+/**
+ * Revoke a role. Pass the result to `schedule`.
+ *
+ * Evicting a guardian takes two of these in one `scheduleBatch`, its guardian
+ * role and its executor role, because the grant paired them but the revoke
+ * cannot tell that pairing from an independent grant.
+ */
+export const _revokeRoleCall = async (client, role, account) => {
+    const values = await _resolve(client);
+    return {
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: 'revokeRole',
+        args: [role, account],
+    };
+};
+/**
+ * Change the delay. Pass the result to `schedule`. `minDelayFloor` still clamps
+ * whatever this writes, so it cannot take the timelock below the floor.
+ */
+export const _updateDelayCall = async (client, newDelay) => {
+    const values = await _resolve(client);
+    return {
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: 'updateDelay',
+        args: [newDelay],
+    };
+};
+/**
+ * Suspend a protocol contract's admin and nominate its replacement in one step.
+ * Pass the result to `schedule`.
+ *
+ * The nominee still has to accept, and the role stays dormant until it does.
+ */
+export const _disableAndNominateCall = async (client, target, newAdmin) => {
+    const values = await _resolve(client);
+    return {
+        address: values.factoryAddresses.PROTOCOL_ADMIN,
+        abi: ProtocolAdmin,
+        functionName: 'disableAndNominate',
+        args: [target, newAdmin],
+    };
+};
+// ---------------------------------------------------------------------------
+// Pause and price ceiling payloads - aimed at the registry
+// ---------------------------------------------------------------------------
+/**
+ * Release the protocol pause on the owner's route. Pass the result to `schedule`.
+ *
+ * There is no matching `pauseCall`. Tripping the pause is `onlyESIMWalletAdmin`,
+ * so the timelock cannot do it at all; the admin key calls `registry.pause`
+ * directly.
+ *
+ * A guardian can skip the delay with `_unpauseInstantly`. Use this form when no
+ * guardian key is to hand, or when the release is planned rather than urgent.
+ *
+ * `target` defaults to the registry.
+ */
+export const _unpauseCall = async (client, target) => {
+    const values = await _resolve(client);
+    return {
+        address: target ?? values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: 'unpause',
+        args: [],
+    };
+};
+/**
+ * Set the fallback data bundle price ceiling. Pass the result to `schedule`.
+ *
+ * Zero reverts on execution, not on scheduling, so a zero here costs the whole
+ * delay before it fails.
+ *
+ * `target` defaults to the registry.
+ */
+export const _setDefaultDataBundlePriceCapCall = async (client, cap, target) => {
+    const values = await _resolve(client);
+    return {
+        address: target ?? values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: 'setDefaultDataBundlePriceCap',
+        args: [cap],
+    };
+};
+// ---------------------------------------------------------------------------
+// Admin suspension payloads - the owner's route, aimed at the target contract
+// ---------------------------------------------------------------------------
+// Unlike the four above, these are aimed at the registry rather than the
+// timelock. The timelock owns it, so both are `onlyOwner` calls it can only make
+// through `schedule`.
+//
+// There is no instant form of either. A guardian can suspend an admin without
+// waiting through `_disableAdminInstantly`, and nothing lifts a suspension
+// without the delay. That asymmetry is what stops a compromised key from undoing
+// its own suspension.
+/**
+ * Suspend a contract's admin key on the owner's route. Pass the result to
+ * `schedule`.
+ *
+ * Prefer `_disableAdminInstantly` during an incident: it does the same thing
+ * with no wait. This form is for a planned suspension, and for an owner holding
+ * no guardian key.
+ *
+ * `target` defaults to the registry, the one contract that keeps the admin
+ * address.
+ */
+export const _disableAdminCall = async (client, target) => {
+    const values = await _resolve(client);
+    return {
+        address: target ?? values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: 'disableAdmin',
+        args: [],
+    };
+};
+/**
+ * Give a suspended admin its powers back. Pass the result to `schedule`.
+ *
+ * The only route there is, and it waits out the delay however the key is held.
+ * Leaves an outstanding nomination alone, so an incumbent stripped by one is
+ * still powerless afterwards; withdraw that by naming the incumbent in
+ * `requestAdminUpdate`.
+ *
+ * `target` defaults to the registry.
+ */
+export const _enableAdminCall = async (client, target) => {
+    const values = await _resolve(client);
+    return {
+        address: target ?? values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: 'enableAdmin',
+        args: [],
+    };
+};

package/dist/esm/logic/admin/reads/deviceWallet.reads.js

@@ -1,12 +1,10 @@
 import { publicActions } from "viem";
 import { DeviceWallet } from "../../../abis/index.js";
-/**
- * Read-only admin logic targeting a specific `DeviceWallet` instance (its address
- * is passed in). Surfaces the instance's public storage getters + `getVaultAddress`
- * view for the backend. Each read extends the `WalletClient` with `publicActions`;
- * no EOA account is required, and the target is the instance address (not a
- * factory address, so no chain-constants lookup is needed).
- */
+// Read-only admin logic targeting a specific `DeviceWallet` instance (its address
+// is passed in). Surfaces the instance's public storage getters + `getVaultAddress`
+// view for the backend. Each read extends the `WalletClient` with `publicActions`;
+// no EOA account is required, and the target is the instance address (not a
+// factory address, so no chain-constants lookup is needed).
 /** The device's unique identifier string. */
 export const _deviceUniqueIdentifier = async (client, deviceWalletAddress) => {
     return client.extend(publicActions).readContract({
@@ -43,3 +41,80 @@ export const _getVaultAddress = async (client, deviceWalletAddress) => {
         args: []
     });
 };
+/**
+ * The P256 key that owns this wallet, as its X and Y co-ordinates. Two reads,
+ * because the contract stores the pair as an array and Solidity gives an indexed
+ * getter rather than one returning both.
+ */
+export const _getOwner = async (client, deviceWalletAddress) => {
+    const publicClient = client.extend(publicActions);
+    const read = (index) => publicClient.readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "owner",
+        args: [index]
+    });
+    return Promise.all([read(0n), read(1n)]);
+};
+/** Gas this wallet has on deposit at the EntryPoint. */
+export const _getDeposit = async (client, deviceWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "getDeposit",
+        args: []
+    });
+};
+/**
+ * Check a signature over an arbitrary message, per ERC-1271. Returns `0x1626ba7e`
+ * when the signature is valid and unexpired, `0xffffffff` otherwise.
+ *
+ * The signature is a version byte, then six bytes of `validUntil`, then the
+ * ABI-encoded WebAuthn assertion. What was signed is an EIP-191 digest over
+ * version, validUntil, chain id, the wallet address and `messageHash`, not
+ * `messageHash` on its own.
+ */
+export const _isValidSignature = async (client, deviceWalletAddress, messageHash, signature) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "isValidSignature",
+        args: [messageHash, signature]
+    });
+};
+/** The registry this wallet reports its ownership changes to. */
+export const _registry = async (client, deviceWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "registry",
+        args: []
+    });
+};
+/** The factory that deploys this wallet's eSIM wallets. */
+export const _eSIMWalletFactory = async (client, deviceWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "eSIMWalletFactory",
+        args: []
+    });
+};
+/** The ERC-4337 EntryPoint this wallet answers to. Immutable. */
+export const _entryPoint = async (client, deviceWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "entryPoint",
+        args: []
+    });
+};
+/** The P256 verifier used when the RIP-7212 precompile is unavailable. */
+export const _verifier = async (client, deviceWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "verifier",
+        args: []
+    });
+};