kokio-sdk 1.0.0 → 2.0.0

package/README.md

@@ -1,8 +1,8 @@
 # Kokio SDK
 
 A TypeScript SDK for interacting with the Koki'o eSIM smart contracts. It wraps
-[viem](https://viem.sh) and [`@aa-sdk/core`](https://www.npmjs.com/package/@aa-sdk/core)
-so that two very different callers can use the same contracts:
+[viem](https://viem.sh), including its account abstraction module, so that two
+very different callers can use the same contracts:
 
 - the **mobile app** (Expo / React Native), which acts on behalf of a user through
   an ERC-4337 device-wallet smart account signed by an on-device passkey, and
@@ -16,6 +16,10 @@ actually needs.
 | `Kokio` | `kokio-sdk` | Passkey (WebAuthn P-256) via user operations | Mobile app |
 | `KokioAdmin` | `kokio-sdk/admin` | Admin / owner EOA via direct transactions | Backend server |
 
+This README covers setup and the common flows. For every method on every
+surface, with a code example and return type, see the
+[full SDK reference](docs/README.md).
+
 ## Installation
 
 ```sh
@@ -23,8 +27,8 @@ npm install kokio-sdk
 ```
 
 The package ships as ES modules and requires Node 18 or newer (or a React Native
-runtime). `viem` and `@aa-sdk/core` are bundled as dependencies, so you do not
-need to install them separately.
+runtime). `viem` is bundled as a dependency, so you do not need to install it
+separately.
 
 ## Mobile client (Expo / React Native)
 
@@ -37,8 +41,7 @@ You will need:
 
 - a viem `WalletClient` connected to the target chain,
 - the passkey `credentialId` and `rpId` registered for the device,
-- your `organizationId`, a Pimlico API key, and a gas policy id (used by the
-  bundler and paymaster).
+- a Pimlico API key and a gas policy id (used by the bundler and paymaster).
 
 ```ts
 import { Kokio } from "kokio-sdk";
@@ -51,7 +54,6 @@ const kokio = new Kokio(
   walletClient,
   credentialId,        // passkey credential id on the device
   rpId,                // relying party id (your app domain)
-  organizationId,
   pimlicoAPIKey,
   gasPolicyId,
 );
@@ -70,7 +72,6 @@ const session = new Kokio(
   walletClient,
   credentialId,
   rpId,
-  organizationId,
   pimlicoAPIKey,
   gasPolicyId,
   smartAccountClient,
@@ -79,16 +80,31 @@ const session = new Kokio(
 );
 
 // 4. Send a user operation. The passkey signs it on the device.
-const { hash } = await session.deviceWallet!.toggleAccessToETH(eSIMWalletAddress, true);
+const hash = await session.deviceWallet!.toggleAccessToETH(eSIMWalletAddress, true);
 await smartAccountClient.waitForUserOperationTransaction({ hash });
 ```
 
 The contract surfaces (`deviceWallet`, `eSIMWallet`, `deviceWalletFactory`,
-`eSIMWalletFactory`, `lazyWalletRegistry`, `P256Verifier`) are only present once a
+`eSIMWalletFactory`, `registry`, `P256Verifier`) are only present once a
 `smartAccountClient` is supplied, which is why the example constructs `Kokio`
 twice. Instance surfaces (`deviceWallet`, `eSIMWallet`) also need their contract
 address. They stay `undefined` until you pass it.
 
+A device wallet often holds more than one eSIM wallet, and the app needs to
+switch which one it is acting on without resolving the smart account again.
+Bind a new instance address with a setter and keep using the same `Kokio`
+reference:
+
+```ts
+session.setESIMWalletAddress(anotherESIMWalletAddress);
+const hash = await session.eSIMWallet!.buyDataBundle({ dataBundleID, dataBundlePrice });
+```
+
+`setDeviceWalletAddress` and `setESIMWalletAddress` each mutate the instance
+and return `this`, so they can be chained. Both need a `smartAccountClient`
+already on the instance; without one the corresponding surface stays
+`undefined`, same as when no address is passed to the constructor.
+
 The passkey signing path depends on
 [`react-native-passkey`](https://github.com/f-23/react-native-passkey) and runs
 only on a device or simulator that supports WebAuthn. It is not available in a
@@ -132,7 +148,7 @@ with a setter and keep using the same `KokioAdmin` reference:
 
 ```ts
 admin.setDeviceWalletAddress(deviceWalletAddress);
-await admin.deviceWallet!.deployESIMWallet(true, salt);
+await admin.deviceWallet!.deployESIMWallet(salt);
 
 admin.setESIMWalletAddress(eSIMWalletAddress);
 await admin.eSIMWallet!.buyDataBundle({ dataBundleID, dataBundlePrice });
@@ -143,9 +159,27 @@ the instance and return `this`, so they can be chained. Admin methods send ordin
 transactions and resolve to a transaction hash.
 
 The chain-wide surfaces (`deviceWalletFactory`, `eSIMWalletFactory`, `registry`,
-`lazyWalletRegistry`) are available as soon as the instance exists. The
-instance-scoped surfaces (`deviceWallet`, `eSIMWallet`) become available once their
-address is set.
+`lazyWalletRegistry`, `protocolAdmin`) are available as soon as the instance
+exists. The instance-scoped surfaces (`deviceWallet`, `eSIMWallet`) become
+available once their address is set.
+
+`protocolAdmin` wraps the timelock that owns `registry`, `lazyWalletRegistry`,
+`deviceWalletFactory`, and `eSIMWalletFactory` on chain. It schedules, executes,
+and cancels privileged calls behind a delay, split across four role-scoped
+surfaces: `proposer` schedules a call, `executor` runs one once its delay has
+passed, `canceller` cancels a pending one, and `guardian` bypasses the delay for
+emergency actions such as unpausing or disabling a compromised admin.
+
+## Types and ABIs
+
+Two more subpaths support the entry points above:
+
+- `kokio-sdk/types` re-exports the shared types (`P256Key`, `WebAuthnSignature`,
+  `DataBundleDetails`, `KokioSmartAccountClient`, `OwnerCall`, and others) so you
+  can type your own code without reaching into internal paths.
+- `kokio-sdk/abis` re-exports the typed contract ABIs (`DeviceWallet`,
+  `ESIMWallet`, `Registry`, `ProtocolAdmin`, and others), useful if you need to
+  decode logs or call a contract directly with viem.
 
 ## Errors
 
@@ -156,7 +190,7 @@ on-chain reverts without reaching into internal module paths:
 import { KokioError, ContractRevertError } from "kokio-sdk";        // or "kokio-sdk/admin"
 
 try {
-  await admin.deviceWalletFactory.requestAdminUpdate(newAdmin);
+  await admin.registry.requestAdminUpdate(newAdmin);
 } catch (err) {
   if (err instanceof ContractRevertError) {
     console.error("reverted:", err.message);
@@ -169,11 +203,26 @@ try {
 `CounterfactualMismatchError`, and `ContractRevertError`. `decodeContractRevert`
 turns raw revert data into a readable reason.
 
-## Supported chains
+The paginated `lazyWalletRegistry` calls on `KokioAdmin` can also throw a few
+narrower `KokioError` subclasses that are not exported by name (for example
+`BatchSizeOutOfRangeError`). Catch them with `instanceof KokioError` and read
+`.code` instead of importing the specific class.
+
+## Constants and supported chains
+
+Both entry points expose an async `constants` getter with the resolved factory
+addresses, chain, RPC URL, and custom-error selectors for the wallet client's
+connected chain:
+
+```ts
+const { factoryAddresses, chain, rpcURL } = await kokio.constants;
+```
 
-The SDK resolves the contract addresses from the wallet client's connected chain
-id, so you do not pass them yourself. Base Sepolia (chain id `84532`) is the
-deployment used in development. Sepolia and other testnets are also configured.
+The SDK resolves these from the wallet client's connected chain id, so you do not
+pass addresses yourself. Base Sepolia (chain id `84532`) is the only chain with a
+live deployment today. Ethereum, Optimism, and Arbitrum (mainnet and their
+testnets) are wired into the chain-resolution logic but not yet deployed;
+connecting to one of them throws `UnconfiguredChainError` until it is.
 
 ## Testing
 

package/dist/esm/abis/BeaconProxy.js

@@ -1,79 +1,63 @@
 const BeaconProxy = [
     {
+        "type": "fallback",
+        "stateMutability": "payable"
+    },
+    {
+        "type": "event",
+        "name": "BeaconUpgraded",
         "inputs": [
             {
-                "internalType": "address",
                 "name": "beacon",
-                "type": "address"
-            },
-            {
-                "internalType": "bytes",
-                "name": "data",
-                "type": "bytes"
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
             }
         ],
-        "stateMutability": "payable",
-        "type": "constructor"
+        "anonymous": false
     },
     {
+        "type": "error",
+        "name": "AddressEmptyCode",
         "inputs": [
             {
-                "internalType": "address",
                 "name": "target",
-                "type": "address"
+                "type": "address",
+                "internalType": "address"
             }
-        ],
-        "name": "AddressEmptyCode",
-        "type": "error"
+        ]
     },
     {
+        "type": "error",
+        "name": "ERC1967InvalidBeacon",
         "inputs": [
             {
-                "internalType": "address",
                 "name": "beacon",
-                "type": "address"
+                "type": "address",
+                "internalType": "address"
             }
-        ],
-        "name": "ERC1967InvalidBeacon",
-        "type": "error"
+        ]
     },
     {
+        "type": "error",
+        "name": "ERC1967InvalidImplementation",
         "inputs": [
             {
-                "internalType": "address",
                 "name": "implementation",
-                "type": "address"
+                "type": "address",
+                "internalType": "address"
             }
-        ],
-        "name": "ERC1967InvalidImplementation",
-        "type": "error"
+        ]
     },
     {
-        "inputs": [],
+        "type": "error",
         "name": "ERC1967NonPayable",
-        "type": "error"
-    },
-    {
-        "inputs": [],
-        "name": "FailedInnerCall",
-        "type": "error"
-    },
-    {
-        "anonymous": false,
-        "inputs": [
-            {
-                "indexed": true,
-                "internalType": "address",
-                "name": "beacon",
-                "type": "address"
-            }
-        ],
-        "name": "BeaconUpgraded",
-        "type": "event"
+        "inputs": []
     },
     {
-        "stateMutability": "payable",
-        "type": "fallback"
+        "type": "error",
+        "name": "FailedCall",
+        "inputs": []
     }
 ];
 export default BeaconProxy;