kokio-sdk 1.0.0 → 2.0.0

package/dist/esm/logic/constants.js

@@ -2,6 +2,22 @@ import { InvalidClientError, UnconfiguredChainError, UnsupportedChainError, } fr
 import { mainnet, sepolia, optimism, optimismSepolia, arbitrum, arbitrumSepolia, base, baseSepolia } from "viem/chains";
 export const ZERO = BigInt('0');
 export const SIGNATURE_VALIDITY_SECONDS = 180; // 3 minutes validity
+// Gas estimation runs before a passkey signature exists, so the account hands the
+// bundler "0x" as a stub. Account4337 rejects any signature of 39 bytes or fewer
+// before it reaches the P256 verifier, so the bundler measures an early return and
+// prices calldata that is 519 bytes short of the real thing. Both estimates come
+// back too low and an operation sized from them is refused, so both are padded.
+//
+// Measured on Base Sepolia: verification estimated at 33,703 gas against a floor of
+// 76,628, and preVerificationGas 11,536 lower than the same operation carrying a
+// real-length signature.
+// Unused verification gas is refunded in full, unlike callGasLimit, so headroom
+// here only raises the prefund the sponsor has to post and costs nothing when it
+// goes unspent.
+export const STUB_VERIFICATION_GAS_PAD = BigInt(60_000);
+// preVerificationGas is charged whether or not it is used, so this stays close to
+// the measured shortfall.
+export const STUB_PRE_VERIFICATION_GAS_PAD = BigInt(15_000);
 export var CHAIN_ID;
 (function (CHAIN_ID) {
     CHAIN_ID[CHAIN_ID["MAINNET"] = 1] = "MAINNET";
@@ -13,14 +29,17 @@ export var CHAIN_ID;
     CHAIN_ID[CHAIN_ID["ARBITRUM_ONE"] = 42161] = "ARBITRUM_ONE";
     CHAIN_ID[CHAIN_ID["ARBITRUM_SEPOLIA"] = 421614] = "ARBITRUM_SEPOLIA";
 })(CHAIN_ID || (CHAIN_ID = {}));
+// Cleared: the deployment here targets EntryPoint v0.7, which this SDK no longer
+// speaks. Refill only after a redeploy on v0.8.
 export const sepoliaFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0x63005d8214533fC7209678Aa39F7b9b0b51a7bcB',
-    ESIM_WALLET_FACTORY: '0xB4473979ff8cE4e09161B08f74EEb66BD7718076',
-    LAZY_WALLET_REGISTRY: '0x8a1E53b903efcc6b252CE4bD3b255202318505Ef',
-    REGISTRY: '0xCa447f5C75C57f6C59027304A5Fb5A09F0E005c9',
-    ENTRY_POINT: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
-    SENDER_CREATOR: '0xefc2c1444ebcc4db75e7613d20c6a62ff67a167c',
-    P256VERIFIER: '0xF04f3b3935aD461D17d4a8a78E7ea21d4a61AEb1'
+    DEVICE_WALLET_FACTORY: '0x',
+    ESIM_WALLET_FACTORY: '0x',
+    LAZY_WALLET_REGISTRY: '0x',
+    REGISTRY: '0x',
+    ENTRY_POINT: '0x',
+    SENDER_CREATOR: '0x',
+    P256VERIFIER: '0x',
+    PROTOCOL_ADMIN: '0x'
 };
 export const mainnetFactoryAddresses = {
     DEVICE_WALLET_FACTORY: '0x',
@@ -29,7 +48,8 @@ export const mainnetFactoryAddresses = {
     REGISTRY: '0x',
     ENTRY_POINT: '0x',
     SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x'
+    P256VERIFIER: '0x',
+    PROTOCOL_ADMIN: '0x'
 };
 export const optimismMainnetFactoryAddresses = {
     DEVICE_WALLET_FACTORY: '0x',
@@ -38,16 +58,19 @@ export const optimismMainnetFactoryAddresses = {
     REGISTRY: '0x',
     ENTRY_POINT: '0x',
     SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x'
+    P256VERIFIER: '0x',
+    PROTOCOL_ADMIN: '0x'
 };
+// Cleared for the same reason as Sepolia: a v0.7 deployment this SDK cannot use.
 export const optimismSepoliaFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0x243cCdE6a56b0Ba740E067f39896772748E20fFD',
-    ESIM_WALLET_FACTORY: '0x8444bF9C39F01e4B092e42DC11695C61f8B93957',
-    LAZY_WALLET_REGISTRY: '0x3F14D060074B174B0784056bDe5e0f8970D25ff1',
-    REGISTRY: '0x96dA9cE92D2C09f7b3ADE01260608e9079f16d12',
-    ENTRY_POINT: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
-    SENDER_CREATOR: '0xefc2c1444ebcc4db75e7613d20c6a62ff67a167c',
-    P256VERIFIER: '0x3c15a78046838481788613A9F111F972B562623C'
+    DEVICE_WALLET_FACTORY: '0x',
+    ESIM_WALLET_FACTORY: '0x',
+    LAZY_WALLET_REGISTRY: '0x',
+    REGISTRY: '0x',
+    ENTRY_POINT: '0x',
+    SENDER_CREATOR: '0x',
+    P256VERIFIER: '0x',
+    PROTOCOL_ADMIN: '0x'
 };
 export const baseMainnetFactoryAddresses = {
     DEVICE_WALLET_FACTORY: '0x',
@@ -56,16 +79,18 @@ export const baseMainnetFactoryAddresses = {
     REGISTRY: '0x',
     ENTRY_POINT: '0x',
     SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x'
+    P256VERIFIER: '0x',
+    PROTOCOL_ADMIN: '0x'
 };
 export const baseSepoliaFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0xB4473979ff8cE4e09161B08f74EEb66BD7718076',
-    ESIM_WALLET_FACTORY: '0x63005d8214533fC7209678Aa39F7b9b0b51a7bcB',
-    LAZY_WALLET_REGISTRY: '0x8a1E53b903efcc6b252CE4bD3b255202318505Ef',
-    REGISTRY: '0xCa447f5C75C57f6C59027304A5Fb5A09F0E005c9',
-    ENTRY_POINT: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
-    SENDER_CREATOR: '0xefc2c1444ebcc4db75e7613d20c6a62ff67a167c',
-    P256VERIFIER: '0xF04f3b3935aD461D17d4a8a78E7ea21d4a61AEb1'
+    DEVICE_WALLET_FACTORY: '0xB006c7066C89a5d7Bfc229e9fb0bADf96c8F979f',
+    ESIM_WALLET_FACTORY: '0x13998C0bb7433c51cE5101922B12EE69F459699A',
+    LAZY_WALLET_REGISTRY: '0x394177c5cc4762b897c37de1820259B75993e033',
+    REGISTRY: '0x89e386E3251692F21a2E9048A46518AdC2A5Cb4A',
+    ENTRY_POINT: '0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108',
+    SENDER_CREATOR: '0x449ED7C3e6Fee6a97311d4b55475DF59C44AdD33',
+    P256VERIFIER: '0x625561429bD99d647956ccBCA4eBf762aaA142c5',
+    PROTOCOL_ADMIN: '0x77A1D6f27462c34BF038832d9Cff6b3E94a9Fe6F'
 };
 export const arbitrumOneFactoryAddresses = {
     DEVICE_WALLET_FACTORY: '0x',
@@ -74,7 +99,8 @@ export const arbitrumOneFactoryAddresses = {
     REGISTRY: '0x',
     ENTRY_POINT: '0x',
     SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x'
+    P256VERIFIER: '0x',
+    PROTOCOL_ADMIN: '0x'
 };
 export const arbitrumSepoliaFactoryAddresses = {
     DEVICE_WALLET_FACTORY: '0x',
@@ -83,7 +109,8 @@ export const arbitrumSepoliaFactoryAddresses = {
     REGISTRY: '0x',
     ENTRY_POINT: '0x',
     SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x'
+    P256VERIFIER: '0x',
+    PROTOCOL_ADMIN: '0x'
 };
 export const customErrors = {
     NULL_OR_UNDEFINED_VALUE: "Error: Null or undefined value provided",

package/dist/esm/logic/deviceWallet.js

@@ -4,59 +4,159 @@ import { MissingSmartWalletError } from "./errors.js";
 // A userOp from a device wallet runs through `execute`, so at the target contract
 // msg.sender is the device-wallet account itself. That constrains which DeviceWallet
 // functions this surface can expose:
-//   - deployESIMWallet / setESIMUniqueIdentifierForAnESIMWallet are `onlyESIMWalletAdmin`
-//     / `onlyESIMWalletAdminOrRegistry` - only the admin EOA (or registry) may call, so a
-//     device-wallet userOp always reverts. They are exposed on `KokioAdmin.deviceWallet`.
-//   - payETHForDataBundles / pullETH are `onlyAssociatedESIMWallets` - callable only by an
-//     associated eSIM wallet contract, never by the device wallet or an EOA.
+//   - deployESIMWallet is `onlyESIMWalletAdmin` - only the admin EOA may call, so a
+//     device-wallet userOp always reverts. It is exposed on `KokioAdmin.deviceWallet`.
+//   - pullETH is `onlyAssociatedESIMWallets` - callable only by an associated eSIM
+//     wallet contract, never by the device wallet or an EOA. An eSIM wallet reaches it
+//     on its own during `buyDataBundle`.
+//   - execute and executeBatch are what a userOp runs through, so the smart account
+//     client already uses them; calling one directly would nest a userOp inside a userOp.
+//     `_sendUserOperation` below is the generic entry point instead: it hands the smart
+//     account client raw calls, and the account's own `encodeCalls` is what turns those
+//     into `execute` or `executeBatch`, never this file.
+//   - init runs at deploy, and validateUserOp is `onlyEntryPoint`.
 // The functions below are self-callable (target = the device wallet's own address, so
 // msg.sender == self), so they succeed via a userOp.
+/**
+ * Send one or more calls from this device wallet as a single user operation.
+ * The only escape hatch on this surface for anything not named below: sending
+ * ETH to any address, calling another contract, moving tokens, interacting
+ * with a DeFi protocol. A lone call encodes to `execute`, several batch
+ * atomically through `executeBatch`.
+ */
+export const _sendUserOperation = async (client, calls) => {
+    if (!client.account)
+        throw new MissingSmartWalletError();
+    return client.sendUserOperation({
+        account: client.account,
+        calls
+    });
+};
 export const _toggleAccessToETH = async (client, address, eSIMWalletAddress, hasAccessToETH) => {
     if (!client.account)
         throw new MissingSmartWalletError();
     // UserOp - `onlySelf`; the device wallet toggles ETH access for an eSIM wallet it owns.
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: DeviceWallet,
-                functionName: "toggleAccessToETH",
-                args: [eSIMWalletAddress, hasAccessToETH]
-            })
-        }
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: DeviceWallet,
+                    functionName: "toggleAccessToETH",
+                    args: [eSIMWalletAddress, hasAccessToETH]
+                })
+            }]
     });
 };
-export const _addESIMWallet = async (client, address, eSIMWalletAddress, hasAccessToETH) => {
+/**
+ * Bind an eSIM wallet this device wallet already owns.
+ *
+ * A bind never carries ETH access: the contract reverts on a `true` rather than
+ * downgrading it quietly, so the SDK passes `false` and there is nothing to
+ * choose. `toggleAccessToETH` is the only way to grant it, which is what stops a
+ * bind from undoing the owner's revocation.
+ */
+export const _addESIMWallet = async (client, address, eSIMWalletAddress) => {
     if (!client.account)
         throw new MissingSmartWalletError();
     // UserOp - `onlyRegistryOrDeviceWalletFactoryOrOwner`; self is permitted.
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: DeviceWallet,
-                functionName: "addESIMWallet",
-                args: [eSIMWalletAddress, hasAccessToETH]
-            })
-        }
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: DeviceWallet,
+                    functionName: "addESIMWallet",
+                    args: [eSIMWalletAddress, false]
+                })
+            }]
     });
 };
-export const _removeESIMWallet = async (client, address, eSIMWalletAddress, hasAccessToETH) => {
+/**
+ * Release an eSIM wallet and put it on standby for a transfer.
+ *
+ * `callBackETH` sweeps whatever ETH the eSIM wallet still holds back here. It
+ * runs after the release, so a wallet whose handler misbehaves has already lost
+ * its ETH access and its registry association. A failed sweep is swallowed by
+ * the contract, so a `true` is not a promise that anything arrived.
+ */
+export const _removeESIMWallet = async (client, address, eSIMWalletAddress, callBackETH) => {
     if (!client.account)
         throw new MissingSmartWalletError();
     // UserOp - `onlySelfOrAssociatedESIMWallet`; self is permitted.
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: DeviceWallet,
-                functionName: "removeESIMWallet",
-                args: [eSIMWalletAddress, hasAccessToETH]
-            })
-        }
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: DeviceWallet,
+                    functionName: "removeESIMWallet",
+                    args: [eSIMWalletAddress, callBackETH]
+                })
+            }]
+    });
+};
+/**
+ * Rotate the P256 key that owns this wallet. The registry is told in the same
+ * call, so its record of the owner cannot drift from the wallet's.
+ *
+ * A key that cannot produce a verifiable signature bricks the wallet: this is
+ * reachable only through a signed userOp, so there is no rotating back and no
+ * reaching the balance afterwards. The contract rejects a key it can tell is
+ * unusable, but check the new key can sign before calling.
+ */
+export const _transferOwnership = async (client, address, newOwner) => {
+    if (!client.account)
+        throw new MissingSmartWalletError();
+    // UserOp - `onlySelf`.
+    return client.sendUserOperation({
+        account: client.account,
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: DeviceWallet,
+                    functionName: "transferOwnership",
+                    args: [newOwner]
+                })
+            }]
+    });
+};
+/**
+ * Top up the gas deposit the EntryPoint holds for this wallet, from the wallet's
+ * own balance. Anyone may pay into any account's deposit, so an EOA can do this
+ * with a plain transfer too and not spend a userOp on it.
+ */
+export const _addDeposit = async (client, address, amount) => {
+    if (!client.account)
+        throw new MissingSmartWalletError();
+    return client.sendUserOperation({
+        account: client.account,
+        calls: [{
+                to: address,
+                value: amount,
+                data: encodeFunctionData({
+                    abi: DeviceWallet,
+                    functionName: "addDeposit",
+                    args: []
+                })
+            }]
+    });
+};
+/** Pull part of the EntryPoint gas deposit back out to any address. */
+export const _withdrawDepositTo = async (client, address, withdrawAddress, amount) => {
+    if (!client.account)
+        throw new MissingSmartWalletError();
+    // UserOp - `onlySelf`.
+    return client.sendUserOperation({
+        account: client.account,
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: DeviceWallet,
+                    functionName: "withdrawDepositTo",
+                    args: [withdrawAddress, amount]
+                })
+            }]
     });
 };
 // `getVaultAddress` is a `view` - read it directly instead of spending a userOp.
@@ -68,6 +168,99 @@ export const _getVaultAddress = async (client, address) => {
         args: []
     });
 };
+/** Gas this wallet has on deposit at the EntryPoint. */
+export const _getDeposit = async (client, address) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "getDeposit",
+        args: []
+    });
+};
+/** The device identifier this wallet was deployed for. Set once, at deploy. */
+export const _deviceUniqueIdentifier = async (client, address) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "deviceUniqueIdentifier",
+        args: []
+    });
+};
+/** Whether this wallet currently holds the given eSIM wallet. */
+export const _isValidESIMWallet = async (client, address, eSIMWalletAddress) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "isValidESIMWallet",
+        args: [eSIMWalletAddress]
+    });
+};
+/**
+ * Whether an eSIM wallet may pull ETH from this one. Binding a wallet never
+ * grants it, so this stays false until `toggleAccessToETH` says otherwise.
+ */
+export const _canPullETH = async (client, address, eSIMWalletAddress) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "canPullETH",
+        args: [eSIMWalletAddress]
+    });
+};
+/**
+ * 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 not `messageHash` itself but
+ * an EIP-191 digest over version, validUntil, chain id, this wallet's address and
+ * `messageHash`, so a signature cannot be replayed on another chain or against
+ * the same owner key's wallet at a different salt.
+ */
+export const _isValidSignature = async (client, address, messageHash, signature) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "isValidSignature",
+        args: [messageHash, signature]
+    });
+};
+/** The registry this wallet reports its ownership changes to. */
+export const _registry = async (client, address) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "registry",
+        args: []
+    });
+};
+/** The factory that deploys this wallet's eSIM wallets. */
+export const _eSIMWalletFactory = async (client, address) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "eSIMWalletFactory",
+        args: []
+    });
+};
+/** The ERC-4337 EntryPoint this wallet answers to. Immutable. */
+export const _entryPoint = async (client, address) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "entryPoint",
+        args: []
+    });
+};
+/** The P256 verifier used when the RIP-7212 precompile is unavailable. */
+export const _verifier = async (client, address) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "verifier",
+        args: []
+    });
+};
 export const _getOwner = async (client, address) => {
     const contract = getContract({
         abi: DeviceWallet,

package/dist/esm/logic/deviceWalletFactory.js

@@ -45,3 +45,92 @@ export const _getCurrentDeviceWalletImplementation = async (client) => {
         args: []
     });
 };
+/**
+ * Check an identifier and owner key before deploying. Answers the zero address
+ * when both are free, or the wallet already holding one of them.
+ *
+ * Call this first. `createAccount` runs inside EntryPoint validation, where the
+ * 4337 rules bar it from reading the registry, so it cannot see that an
+ * identifier or a key is taken: it deploys a second wallet at a fresh address
+ * and the `postCreateAccount` that would register it fails afterwards.
+ *
+ * Reverts on an empty identifier or a key that is not a point on the P256 curve.
+ */
+export const _preCreateAccountValidation = async (client, deviceUniqueIdentifier, deviceWalletOwnerKey) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "preCreateAccountValidation",
+        args: [deviceUniqueIdentifier, deviceWalletOwnerKey]
+    });
+};
+/**
+ * Whether the factory has recorded this wallet. Set by `postCreateAccount`, not
+ * by the deploy, so a wallet the app just created reads false until the backend
+ * registers it.
+ */
+export const _deviceWalletInfoAdded = async (client, deviceWallet) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "deviceWalletInfoAdded",
+        args: [deviceWallet]
+    });
+};
+/**
+ * The beacon every device wallet reads its implementation from. One update moves
+ * all of them and no wallet can decline it.
+ */
+export const _beacon = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "beacon",
+        args: []
+    });
+};
+/** The registry the factory writes new wallets into. */
+export const _registry = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "registry",
+        args: []
+    });
+};
+/** The EntryPoint baked into every device wallet this factory deploys. */
+export const _entryPoint = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "entryPoint",
+        args: []
+    });
+};
+/** The contract new device wallets verify WebAuthn assertions through. */
+export const _verifier = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "verifier",
+        args: []
+    });
+};