@inco/js 0.8.0-devnet-11 → 0.8.0-devnet-13

package/README.md

@@ -1,100 +1,594 @@
 # @inco/js
 
-The @inco/js package contains the TypeScript SDK for creating dapps built on Inco.
+TypeScript SDK for building privacy-preserving dapps on [Inco Lightning](https://docs.inco.org). Encrypt values client-side, post ciphertexts to smart contracts for confidential computation, and retrieve attested decryptions — all with post-quantum hybrid encryption (X-Wing KEM).
 
 ## Current Status: Active Development
 
-The SDK is currently going through active development, to support all new features that Inco offers. As such, do expect breaking changes in subsequent releases, which will be documented in the [CHANGELOG](./CHANGELOG.md).
+The SDK is under active development. Expect breaking changes in subsequent releases, documented in the [CHANGELOG](./CHANGELOG.md).
 
-## Install
-
-Choose your favorite package manager:
+## Installation
 
 ```bash
 npm install @inco/js
 # or
-bun install @inco/js
-# or
 yarn add @inco/js
+# or
+bun add @inco/js
 ```
 
-## Usage
+**Peer dependency:** [viem](https://viem.sh) `^2.39.3` is used for Ethereum interactions.
 
-A typical usage of `@inco/js` includes 3 steps:
+> **Note:** The library has currently only been tested with Webpack and Next.js. If you encounter issues with Rollup or Vite, please open an issue.
 
-1. Encrypting a value.
-2. Posting the ciphertext to the contract, which will perform confidential computes on it.
-3. Requesting an attested decryption of the result of the computation.
+## Quick Start
 
-### 1. Encrypt a value
+A typical workflow has three steps:
+
+1. **Encrypt** a value client-side
+2. **Submit** the ciphertext to a smart contract for confidential computation
+3. **Decrypt** the result via attested decryption
 
 ```ts
-import { getViemChain, supportedChains } from '@inco/js';
+import { getViemChain, supportedChains, handleTypes } from '@inco/js';
 import { Lightning } from '@inco/js/lite';
 import { createWalletClient } from 'viem';
 
-// Setup: do it once at initialization
+// 1. Setup
 const chainId = supportedChains.baseSepolia;
-const zap = Lightning.latest('testnet', chainId); // Connect to Inco's latest public testnet
+const zap = await Lightning.latest('testnet', chainId);
 const walletClient = createWalletClient({
   chain: getViemChain(chainId),
-  account: /* Choose your account, e.g. from window.ethereum */,
-  transport: /* Choose your transport, e.g. from Alchemy */,
+  account: /* your account */,
+  transport: /* your transport */,
 });
-const dappAddress = '0x00000000000000000000000000000000deadbeef'; // Put your contract address here
+const dappAddress = '0x...'; // Your contract address
 
-// Encrypt the plaintext value
-const plaintext = 42;
-const ciphertext = await zap.encrypt(plaintext, {
+// 2. Encrypt
+const ciphertext = await zap.encrypt(42n, {
   accountAddress: walletClient.account.address,
   dappAddress,
+  handleType: handleTypes.euint256,
 });
 
-console.log(ciphertext); // A long hex string representing the encrypted value
+// 3. Submit ciphertext to contract via viem writeContract (not SDK-specific)
+
+// 4. Decrypt the result
+const resultHandle = '0x...'; // Retrieved from the contract
+const [attestation] = await zap.attestedDecrypt(walletClient, [resultHandle]);
+console.log(attestation.plaintext.value);
 ```
 
-### 2. Post the ciphertext to the contract
+---
+
+## Package Exports
+
+| Import Path             | Description                                                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------- |
+| `@inco/js`              | Core utilities: binary helpers, chain definitions, handle types, viem integration              |
+| `@inco/js/lite`         | Main SDK: `Lightning` class, encryption, attested decrypt/compute, X-Wing crypto, session keys |
+| `@inco/js/encryption`   | Encryption types, plaintext/ciphertext conversions, scheme constants                           |
+| `@inco/js/reencryption` | Reencryption types, EIP-712 payload creation                                                   |
+| `@inco/js/abis`         | Generated smart contract ABIs (Lightning, Verifier)                                            |
+| `@inco/js/local`        | Local node environment parsing for development                                                 |
+
+---
+
+## API Reference
+
+### `Lightning` Class
+
+**Import:** `import { Lightning } from '@inco/js/lite'`
 
-This step does not require any specific `@inco/js` functionality. We recommend using [viem](https://viem.sh) to interact with the blockchain. Specifically, use the [`writeContract`](https://viem.sh/docs/contract/writeContract) method to submit transactions. Pass the `ciphertext` from the previous encryption step as the input ciphertext parameter of type `bytes`.
+The primary entry point for all SDK operations. Binds to a specific Inco Lightning deployment and provides encryption, attested decryption, attested compute, and session key management.
 
-### 3. Request a reencryption
+#### Factory Methods
 
-Following transaction submission, the Inco covalidator processes the computation request. The contract stores the computation result as a handle on-chain. This handle, referenced below as `resultHandle`, is a hexadecimal string of type `Handle` that serves as a reference to the encrypted computation output.
+The constructor is private. Use one of the static factory methods:
 
 ```ts
-import { Hex } from "viem";
+// Connect to the latest deployment for a given pepper and chain
+const zap = await Lightning.latest("testnet", supportedChains.baseSepolia);
+// Connect with custom configuration
+const zap = await Lightning.custom({
+  executorAddress: "0x...",
+  chainId: 84532,
+  covalidatorUrls: ["https://..."],
+});
+
+// Connect to a local development node
+const zap = await Lightning.localNode(); // default testnet pepper
+const zap = await Lightning.localNodeFromEnv(".env"); // from env file
+```
+
+| Method                                        | Returns              | Description                                     |
+| --------------------------------------------- | -------------------- | ----------------------------------------------- |
+| `Lightning.baseSepoliaTestnet()`              | `Promise<Lightning>` | Latest testnet deployment on Base Sepolia       |
+| `Lightning.latest(pepper, chainId)`           | `Promise<Lightning>` | Latest deployment for a given pepper and chain  |
+| `Lightning.latestDeployment(pepper, chainId)` | `Deployment`         | Synchronous deployment lookup (no network call) |
+| `Lightning.at(id)`                            | `Promise<Lightning>` | Deployment by name or executor address          |
+| `Lightning.custom(config)`                    | `Promise<Lightning>` | Custom deployment configuration                 |
+| `Lightning.localNode(env?)`                   | `Promise<Lightning>` | Local development node                          |
+| `Lightning.localNodeFromEnv(source?)`         | `Promise<Lightning>` | Local node from dotenv file or buffer           |
+
+#### Properties
+
+| Property          | Type      | Description                                  |
+| ----------------- | --------- | -------------------------------------------- |
+| `executorAddress` | `Address` | The executor contract address                |
+| `chainId`         | `bigint`  | The host chain ID                            |
+| `deployment`      | `T`       | Shallow copy of the deployment configuration |
 
-// Request a re-encryption of the result ciphertext
-const resultHandle = "0x..." as Hex; // Retrieve the handle from the contract, e.g. using viem
-// Use same walletClient as previous step
-const resultPlaintext = await zap.attestedDecrypt(walletClient, [resultHandle]);
+#### `encrypt(value, context)`
 
-console.log(resultPlaintext[0].plaintext.value); // The decrypted value
+Encrypts a plaintext value using the network's public key.
+
+```ts
+async encrypt<T extends boolean | bigint | number>(
+  value: T,
+  context: {
+    accountAddress: string;  // EOA interacting with the dapp
+    dappAddress: string;     // Contract address
+    handleType?: FheType;    // Optional, defaults based on value type
+  }
+): Promise<HexString>
 ```
 
-Handles are processed asynchronously so you may need to wait for our covalidators to catch and compute the value. If you request an attested decryption before it has been processed you will get an error. To help ameliorate this the `attestedDecrypt` has built-in retries, you can further customise by passing a `BackoffConfig` as an extra argument:
+**Supported types and default handle mappings:**
+
+| Value Type          | Default Handle Type    | Example                                                                   |
+| ------------------- | ---------------------- | ------------------------------------------------------------------------- |
+| `boolean`           | `handleTypes.ebool`    | `zap.encrypt(true, ctx)`                                                  |
+| `bigint` / `number` | `handleTypes.euint256` | `zap.encrypt(42n, ctx)`                                                   |
+| `bigint` (address)  | `handleTypes.euint160` | `zap.encrypt(BigInt(addr), { ...ctx, handleType: handleTypes.euint160 })` |
+
+Returns a hex string ciphertext to pass to your contract as `bytes`.
+
+#### `attestedDecrypt(walletClient, handles, ...)`
+
+Requests attested decryption of one or more handles. Only handles approved via `e.allow()` can be decrypted.
+
+**Three calling modes:**
 
 ```ts
-type BackoffConfig = {
-  maxRetries: number;
-  baseDelayInMs: number;
-  backoffFactor: number;
-};
+// Mode 1: Plaintext result (auto-generates ephemeral keypair internally)
+const attestations = await zap.attestedDecrypt(walletClient, [handle]);
+attestations[0].plaintext.value; // The decrypted value
+
+// Mode 2: Reencrypt for a delegate (returns encrypted result)
+const encrypted = await zap.attestedDecrypt(
+  walletClient,
+  [handle],
+  delegatePubKey,
+);
+encrypted[0].encryptedPlaintext.ciphertext.value;
+
+// Mode 3: Reencrypt and decrypt locally
+const decrypted = await zap.attestedDecrypt(
+  walletClient,
+  [handle],
+  keypair.encodePublicKey(),
+  keypair,
+);
+decrypted[0].plaintext.value;
+```
 
-const resultHandle = "0x..." as Hex;
-// Default backoff config shown for reference
-const backoffConfig: BackoffConfig = {
+All modes accept an optional `BackoffConfig` as the last argument for retry tuning:
+
+```ts
+const attestations = await zap.attestedDecrypt(walletClient, [handle], {
   maxRetries: 10,
   baseDelayInMs: 1000,
   backoffFactor: 1.5,
-};
-const resultPlaintext = await zap.attestedDecrypt(
+});
+```
+
+**Return types:**
+
+| Mode                      | Return Type                                                                                                       |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Plaintext                 | `DecryptionAttestation[]` — `{ handle, plaintext, covalidatorSignatures }`                                        |
+| Reencrypt                 | `EncryptedDecryptionAttestation[]` — `{ handle, encryptedPlaintext, encryptedSignatures, covalidatorSignatures }` |
+| Reencrypt + local decrypt | `DecryptionAttestation[]`                                                                                         |
+
+#### `attestedReveal(handles, backoffConfig?)`
+
+Decrypts publicly revealed handles (those marked with `e.reveal()`). Does not require a wallet — anyone can call this.
+
+```ts
+const attestations = await zap.attestedReveal([handle]);
+attestations[0].plaintext.value;
+```
+
+> **Warning:** Once `e.reveal()` is called on-chain, the ciphertext is considered public and can be accessed by anyone. This cannot be undone.
+
+#### `attestedCompute(walletClient, lhsHandle, op, rhsPlaintext, ...)`
+
+Performs an off-chain comparison operation on an encrypted handle against a plaintext scalar, returning an attested result.
+
+```ts
+import { AttestedComputeSupportedOps } from "@inco/js/lite";
+
+// Plaintext result
+const result = await zap.attestedCompute(
   walletClient,
-  [resultHandle],
-  backoffConfig,
+  handle,
+  AttestedComputeSupportedOps.Ge,
+  700n,
+);
+console.log(result.plaintext.value); // true or false
+```
+
+**Supported operations:**
+
+| Operation                        | Description           |
+| -------------------------------- | --------------------- |
+| `AttestedComputeSupportedOps.Eq` | Equal                 |
+| `AttestedComputeSupportedOps.Ne` | Not equal             |
+| `AttestedComputeSupportedOps.Ge` | Greater than or equal |
+| `AttestedComputeSupportedOps.Gt` | Greater than          |
+| `AttestedComputeSupportedOps.Le` | Less than or equal    |
+| `AttestedComputeSupportedOps.Lt` | Less than             |
+
+Supports the same three calling modes as `attestedDecrypt` (plaintext, reencrypt, reencrypt + local decrypt).
+
+#### Session Key Methods
+
+Session keys (allowance vouchers) enable delegated decryption without requiring the data owner's wallet signature for each request.
+
+```ts
+// Owner grants a session key to a delegate
+const voucher = await zap.grantSessionKeyAllowanceVoucher(
+  walletClient, // Owner's wallet
+  granteeAddress, // Delegate's address
+  expiresAt, // Expiration Date
+  sessionVerifierAddr, // Session verifier contract
+);
+
+// Delegate decrypts using the voucher
+const attestations = await zap.attestedDecryptWithVoucher(
+  ephemeralAccount,
+  voucher,
+  ethClient,
+  [handle],
+);
+
+// Delegate computes using the voucher
+const result = await zap.attestedComputeWithVoucher(
+  ephemeralAccount,
+  voucher,
+  ethClient,
+  handle,
+  AttestedComputeSupportedOps.Eq,
+  42n,
 );
+
+// Owner revokes all active vouchers
+const txHash = await zap.updateActiveVouchersSessionNonce(walletClient);
 ```
 
+| Method                                                                         | Description                          |
+| ------------------------------------------------------------------------------ | ------------------------------------ |
+| `grantSessionKeyAllowanceVoucher(walletClient, grantee, expiresAt, verifier)`  | Grant a time-limited session key     |
+| `grantCustomSessionKeyAllowanceVoucher(walletClient, verifier, sharerArgData)` | Grant with custom verifier arguments |
+| `attestedDecryptWithVoucher(account, voucher, client, handles, ...)`           | Decrypt using a session key          |
+| `attestedComputeWithVoucher(account, voucher, client, handle, op, rhs, ...)`   | Compute using a session key          |
+| `updateActiveVouchersSessionNonce(walletClient)`                               | Revoke all active vouchers           |
+
+#### Static Helpers
+
+```ts
+// Read network public key from on-chain verifier
+const pubkey = await Lightning.getNetworkPubkey(publicClient, executorAddress);
+
+// Get the IncoVerifier contract instance
+const verifier = await Lightning.getIncoVerifierContract(
+  publicClient,
+  executorAddress,
+);
+
+// Get covalidator URLs for a deployment
+const urls = Lightning.getCovalidatorUrls(deployment, threshold);
+```
+
+---
+
+### Core Utilities (`@inco/js`)
+
+#### Chain Support
+
+```ts
+import { supportedChains, getSupportedChain, getViemChain } from "@inco/js";
+
+// Supported chains
+supportedChains.baseSepolia; // 84532
+supportedChains.sepolia; // 11155111
+supportedChains.monadTestnet; // 10143
+supportedChains.plasmaTestnet; // 9746
+supportedChains.worldchainSepolia; // 4801
+supportedChains.anvil; // 31337
+
+// Resolve chain from ID, name, or object
+const chain = getSupportedChain(84532);
+const chain = getSupportedChain("baseSepolia");
+const chain = getSupportedChain({ id: 84532 });
+
+// Get viem Chain object
+const viemChain = getViemChain(84532);
+```
+
+#### Handle Types
+
+```ts
+import {
+  handleTypes,
+  isFheType,
+  validateHandle,
+  getHandleType,
+} from "@inco/js";
+
+// FHE type identifiers
+handleTypes.ebool; // 0
+handleTypes.euint4; // 1
+handleTypes.euint8; // 2
+handleTypes.euint16; // 3
+handleTypes.euint32; // 4
+handleTypes.euint64; // 5
+handleTypes.euint128; // 6
+handleTypes.euint160; // 7
+handleTypes.euint256; // 8
+handleTypes.ebytes64; // 9
+handleTypes.ebytes128; // 10
+handleTypes.ebytes256; // 11
+
+// Validate and inspect handles
+validateHandle("0x..."); // throws if malformed
+const fheType = getHandleType("0x..."); // extracts FheType from handle
+isFheType(5); // true (euint64)
+```
+
+#### Binary Utilities
+
+```ts
+import {
+  bytesToBigInt,
+  bigintToBytes,
+  bigintToBytes32,
+  bytes32ToBigint,
+  bytesFromHexString,
+  bytesToHex,
+  mustBeHex,
+  normaliseToHex,
+  padLeft,
+  asBytes32,
+  parseAddress,
+  parseHex,
+} from "@inco/js";
+
+// Conversions
+bytesToBigInt(new Uint8Array([1, 0])); // 256n
+bigintToBytes(42n); // 32-byte Buffer
+bigintToBytes32(42n); // '0x000...002a' (Bytes32)
+
+// Hex helpers
+mustBeHex("0xdead"); // returns typed Hex, throws if invalid
+normaliseToHex("dead"); // '0xdead'
+bytesToHex(new Uint8Array()); // '0x'
+
+// Parsing with validation
+parseAddress("0x1234...5678"); // validated Address (20 bytes)
+parseHex("0xabcd"); // validated HexString
+asBytes32("0x00...00"); // validated Bytes32 (32 bytes)
+```
+
+#### Handle Computation
+
+````ts
+import { computePrehandle, computeHandle, hashInputContext, HANDLE_VERSION } from '@inco/js';
+
+const prehandle = computePrehandle({
+  ciphertext: new Uint8Array([...]),
+  indexHandle: 0,
+  handleType: handleTypes.euint256,
+  handleVersion: HANDLE_VERSION,
+});
+
+const handle = computeHandle({ prehandle, context: inputContext });
+const contextHash = hashInputContext(inputContext);
+
+---
+
+### Encryption Module (`@inco/js/encryption`)
+
+Types and conversion utilities for plaintexts and ciphertexts.
+
+```ts
+import {
+  // Constants
+  encryptionSchemes,       // { xwing: 2 }
+  supportedFheTypes,       // { euint64: 5, euint160: 7, euint256: 8, ebool: 0 }
+
+  // Conversions
+  bigintToPlaintext,       // (scheme, type, bigint) => Plaintext
+  plaintextToBigint,       // (plaintext) => bigint
+  plaintextToBytes32,      // (plaintext) => Bytes32
+  plaintextToBytes,        // (plaintext) => Buffer
+  bytes32ToPlaintext,      // (bytes32, scheme, type) => Plaintext
+  bytesToPlaintext,        // (bytes, scheme, type) => Plaintext
+
+  // Ciphertext input encoding (for on-chain format)
+  encodeCiphertextInput,   // (version, handle, ciphertext) => Hex
+  decodeCiphertextInput,   // (input) => { version, handle, ciphertext }
+
+  // Helpers
+  getEncryptionSchemeName, // (scheme) => 'X-Wing'
+} from '@inco/js/encryption';
+````
+
+**Key types:**
+
+| Type               | Description                                                                            |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| `Plaintext`        | `{ scheme, type, value }` — value is `bigint` for integer types, `boolean` for `ebool` |
+| `Ciphertext`       | `{ scheme, type, value }` — value is a hex string                                      |
+| `EncryptResult`    | `{ ciphertext, context, prehandle, handle }`                                           |
+| `EncryptionScheme` | Currently only `2` (X-Wing)                                                            |
+| `SupportedFheType` | `0`, `5`, `7`, `8` (ebool, euint64, euint160, euint256)                                |
+| `Encryptor<S>`     | `(plaintext) => Promise<EncryptResult>`                                                |
+| `Decryptor<S>`     | `(ciphertext) => Promise<Plaintext>`                                                   |
+
+---
+
+### X-Wing Cryptography (`@inco/js/lite`)
+
+Post-quantum hybrid encryption using X-Wing KEM (ML-KEM-768 + X25519).
+
+```ts
+import {
+  generateXwingKeypair,
+  deriveXwingKeypairFromSeed,
+  decodeXwingPublicKey,
+  decodeXwingPrivateKey,
+  encodeXwingPublicKey,
+  getXwingEncryptor,
+  getXwingDecryptor,
+  encrypt,
+  decrypt,
+  XWING_PUBLIC_KEY_SIZE, // 1216 bytes
+} from "@inco/js/lite";
+
+// Generate a random keypair
+const keypair = await generateXwingKeypair();
+const pubKeyBytes = keypair.encodePublicKey(); // Uint8Array (1216 bytes)
+
+// Deterministic keypair from a 32-byte seed
+const keypair = await deriveXwingKeypairFromSeed(seed);
+
+// Create encryptor/decryptor functions
+const encryptor = getXwingEncryptor({ pubKeyA: keypair.publicKey });
+const decryptor = getXwingDecryptor({ privKeyA: keypair });
+
+// Low-level HPKE encrypt/decrypt
+const encrypted = await encrypt(publicKey, message);
+const decrypted = await decrypt(keypair, encrypted);
+```
+
+---
+
+### Deployment Utilities (`@inco/js/lite`)
+
+```ts
+import {
+  getActiveLightningDeployment,
+  getLightningDeployments,
+} from "@inco/js/lite";
+
+// Get the latest active deployment for a chain
+const deployment = getActiveLightningDeployment("baseSepolia");
+
+// Get all deployments for a chain
+const deployments = getLightningDeployments(84532);
+```
+
+---
+
+### Reencryption Module (`@inco/js/reencryption`)
+
+EIP-712 typed data utilities for signing reencryption requests.
+
+```ts
+import { createEIP712Payload } from "@inco/js/reencryption";
+
+const payload = createEIP712Payload({
+  chainId: 84532n,
+  primaryType: "Reencrypt",
+  primaryTypeFields: [{ name: "publicKey", type: "bytes" }],
+  message: { publicKey: "0x..." },
+  domainName: "IncoLite",
+  domainVersion: "1",
+  verifyingContract: "0x...",
+});
+```
+
+**Key types:**
+
+| Type              | Description                                    |
+| ----------------- | ---------------------------------------------- |
+| `Reencryptor<S>`  | `(args, backoffConfig?) => Promise<Plaintext>` |
+| `PubKeyEncodable` | `{ encodePublicKey(): Uint8Array }`            |
+| `EIP712<Message>` | Full EIP-712 typed data payload                |
+
+---
+
+### Local Development (`@inco/js/local`)
+
+Tools for connecting to a local Anvil + Covalidator development node.
+
+```ts
+import { parseLocalEnv } from "@inco/js/local";
+
+// Parse from dotenv string/buffer
+const env = parseLocalEnv(fs.readFileSync(".env"));
+
+// Parse from process.env
+const env = parseLocalEnv();
+
+// Use with Lightning
+const zap = await Lightning.localNode(env);
+```
+
+Docker images for local development:
+
+- `inconetwork/local-node-anvil`
+- `inconetwork/local-node-covalidator`
+
+---
+
+### ABIs (`@inco/js/abis`)
+
+Generated contract ABIs for direct contract interaction with viem.
+
+```ts
+import { incoLightningAbi } from "@inco/js/abis/lightning";
+import { incoVerifierAbi } from "@inco/js/abis/verifier";
+```
+
+---
+
+## Supported Chains
+
+| Chain          | Chain ID | Name            |
+| -------------- | -------- | --------------- |
+| Base Sepolia   | `84532`  | `baseSepolia`   |
+| Plasma Testnet | `9746`   | `plasmaTestnet` |
+
+---
+
+## BackoffConfig
+
+All attested decrypt/compute methods support optional retry configuration:
+
+```ts
+type BackoffConfig = {
+  maxRetries: number; // Default: 5
+  baseDelayInMs: number; // Default: 1000
+  backoffFactor: number; // Default: 1.5
+  errHandler?: (error: Error, attempt: number) => "stop" | "continue";
+};
+```
+
+Only transient errors (timeouts, connection issues, 503s) are retried. Security-critical errors (auth failures, invalid signatures) fail immediately.
+
+---
+
+## Further Reading
+
+- [Inco Documentation](https://docs.inco.org)
+- [Encryption Guide](https://docs.inco.org/js-sdk/encryption)
+- [Attested Decrypt](https://docs.inco.org/js-sdk/attestations/attested-decrypt)
+- [Attested Compute](https://docs.inco.org/js-sdk/attestations/attested-compute)
+- [Attested Reveal](https://docs.inco.org/js-sdk/attestations/attested-reveal)
+- [Allowance Vouchers](https://docs.inco.org/js-sdk/voucher/allowance-voucher)
+
 ## License
 
-See the [LICENSE](./LICENSE) file.
+[Apache-2.0](./LICENSE)