@primuslabs/fhetransform-sdk 0.4.0

package/README.md

@@ -0,0 +1,198 @@
+# fhetransform-sdk
+
+TypeScript SDK for FHETransform. It provides helpers for:
+
+- Connecting to the FHETransform blockchain contracts
+- Encrypting and decrypting values through the Jazz service
+- Interacting with confidential token contracts
+- Running shield / unshield flows for converter contracts
+
+## Install
+
+```bash
+npm install fhetransform-sdk
+```
+
+Requirements:
+
+- Node.js `>= 20` for server-side usage
+- ESM-aware tooling
+- A blockchain provider and signer for write operations
+
+### Environment variables
+
+If you do not pass a provider or signer directly, the SDK can fall back to environment configuration in Node.js:
+
+- `RPC_URL` or `FHE_RPC_URL` for the JSON-RPC endpoint
+- `PRIVATE_KEY` for a signer
+- `JAZZ_URL` for the Jazz API endpoint when the default is not suitable
+
+## Quick Start
+
+### Node.js
+
+```ts
+import { FheTransformSDK } from "fhetransform-sdk";
+import { ethers } from "ethers";
+
+const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
+const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+
+const sdk = new FheTransformSDK({
+  provider,
+  signer,
+  // Optional:
+  // jazzUrl: process.env.JAZZ_URL,
+  // mock: false,
+  onEvent: (event) => {
+    console.log("SDK event:", event.type);
+  },
+});
+
+const token = sdk.createToken("0x0000000000000000000000000000000000000000");
+
+console.log("Name:", await token.name());
+console.log("Decimals:", await token.decimals());
+console.log("Balance:", await token.balanceOf(await signer.getAddress()));
+```
+
+### Confidential transfer
+
+```ts
+const result = await token.confidentialTransfer(
+  "0x0000000000000000000000000000000000000001",
+  100n
+);
+
+console.log(result.txHash);
+console.log(result.transferred);
+```
+
+Transfer methods also accept transaction options and lifecycle callbacks:
+
+```ts
+await token.confidentialTransfer(
+  "0x0000000000000000000000000000000000000001",
+  100n,
+  { gasLimit: 500_000n },
+  {
+    onEncryptComplete: () => console.log("Amount encrypted"),
+    onTransferSubmitted: (txHash) => console.log("Submitted:", txHash),
+    onTransferConfirmed: (receipt) => console.log("Confirmed:", receipt.hash),
+    onError: (error) => console.error("Transfer failed:", error),
+  }
+);
+```
+
+### Converter flow
+
+```ts
+const convert = sdk.createConvertToken("0x0000000000000000000000000000000000000002");
+
+const shield = await convert.shield(1000n);
+console.log(shield.roundedAmount);
+
+const unshield = await convert.unshieldAndFinalize(1000n);
+console.log(unshield.cleartext);
+```
+
+### Browser
+
+In browsers, the SDK will attempt to use MetaMask when a signer is not supplied. Pass a provider and signer explicitly if you want to control the connection flow yourself.
+
+```ts
+import { FheTransformSDK } from "fhetransform-sdk";
+
+const sdk = new FheTransformSDK({
+  onEvent: (event) => console.log(event.type),
+});
+```
+
+## Events
+
+The SDK emits structured events for encryption, decryption, and transaction lifecycles. Subscribe by passing an `onEvent` listener in the config:
+
+```ts
+import { FheTransformSDK, FheTransformSDKEvents } from "fhetransform-sdk";
+
+const sdk = new FheTransformSDK({
+  provider,
+  signer,
+  onEvent: (event) => {
+    switch (event.type) {
+      case FheTransformSDKEvents.EncryptStart:
+        console.log("Encryption started", event.dappAddress);
+        break;
+      case FheTransformSDKEvents.EncryptEnd:
+        console.log(`Encryption finished in ${event.durationMs}ms`);
+        break;
+      case FheTransformSDKEvents.DecryptEnd:
+        console.log("Decrypted values:", event.plaintexts);
+        break;
+      case FheTransformSDKEvents.TransactionError:
+        console.error("Transaction failed:", event.error);
+        break;
+      case FheTransformSDKEvents.ShieldSubmitted:
+        console.log("Shield transaction submitted:", event.txHash);
+        break;
+    }
+  },
+});
+```
+
+Every event carries a `type` and a `timestamp`. Events tied to a contract —
+encryption operations and events from the `Token` / `ConvertToken` wrappers —
+also include `dappAddress`, the relevant contract address. Use the exported
+`FheTransformSDKEvents` constants and the `FheTransformSDKEvent` type instead
+of hardcoding event strings.
+
+### Event types
+
+| Event type | Payload |
+| --- | --- |
+| `encrypt:start` | — |
+| `encrypt:end` | `durationMs` |
+| `encrypt:error` | `durationMs`, `error` |
+| `decrypt:start` | `encryptedValues` |
+| `decrypt:end` | `durationMs`, `encryptedValues`, `plaintexts` |
+| `decrypt:error` | `encryptedValues`, `error`, `durationMs` |
+| `transaction:end` | `functionName`, `txHash`, `durationMs` |
+| `transaction:error` | `functionName`, `error`, `durationMs` |
+| `shield:submitted` / `shield:confirmed` / `shield:end` | `txHash`, `elapsedMs` or `durationMs` |
+| `unshield:submitted` / `unshield:confirmed` / `unshield:end` | `txHash`, `elapsedMs` or `durationMs` |
+| `finalizeUnshield:submitted` / `finalizeUnshield:confirmed` / `finalizeUnshield:end` | `txHash`, `elapsedMs` or `durationMs` |
+
+Notes:
+
+- Listener exceptions are caught and logged; a misbehaving subscriber never breaks SDK operations.
+- Decrypt events carry decrypted plaintext values — treat them as sensitive data.
+- `transfer:submitted`, `transferFrom:submitted`, and `setOperator:submitted` are reserved event types and are not emitted yet.
+- The encryption/decryption pipelines also emit low-level progress events such as
+  `encryptWithZk:end` and `fetchInputProof:start`; see the
+  [API reference](docs/API.md#internal-pipeline-events) for the full list.
+
+## Build
+
+```bash
+npm run build
+```
+
+This compiles the TypeScript sources into `dist/`, copies the native assets used by the SDK, and prepares the package for publication or local consumption.
+
+Useful companion commands:
+
+- `npm test` - run the test suite
+- `npm run lint` - lint the source tree
+- `npm run format` - format the TypeScript sources
+
+## API
+
+See [docs/API.md](docs/API.md) for the class reference.
+
+Besides the SDK classes, the package exports helpers and types for events
+(`FheTransformSDKEvents`, `FheTransformSDKEvent`), addresses
+(`toChecksumAddress`, `isZeroAddress`, …), chain and fee utilities
+(`getChainKey`, `estimateFheFee`, …), contract operation types, and the unified
+error system (`FheError`, `FheErrorCode`, `toFheError`, …). See the
+[Supporting exports](docs/API.md#supporting-exports) section of the API
+reference for the full list.

package/dist/abis/acl.abi.d.ts

@@ -0,0 +1,379 @@
+export declare const aclAbi: readonly [{
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "target";
+        readonly type: "address";
+    }];
+    readonly name: "AddressEmptyCode";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "EnforcedPause";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "ExpectedPause";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "FailedCall";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "HandlesListIsEmpty";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidInitialization";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "NotInitializing";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly name: "OwnableInvalidOwner";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "OwnableUnauthorizedAccount";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "sender";
+        readonly type: "address";
+    }];
+    readonly name: "SenderNotAllowed";
+    readonly type: "error";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "caller";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }];
+    readonly name: "Allowed";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "caller";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "bytes32[]";
+        readonly name: "handlesList";
+        readonly type: "bytes32[]";
+    }];
+    readonly name: "AllowedForDecryption";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: false;
+        readonly internalType: "uint64";
+        readonly name: "version";
+        readonly type: "uint64";
+    }];
+    readonly name: "Initialized";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "previousOwner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "newOwner";
+        readonly type: "address";
+    }];
+    readonly name: "OwnershipTransferred";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: false;
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "Paused";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: false;
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "Unpaused";
+    readonly type: "event";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly internalType: "enum PermissionType";
+        readonly name: "pt";
+        readonly type: "uint8";
+    }];
+    readonly name: "accessPolicy";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "accessPolicy";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "allow";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32[]";
+        readonly name: "handlesList";
+        readonly type: "bytes32[]";
+    }];
+    readonly name: "allowForDecryption";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "allowTransient";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "allowedTransient";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "cleanTransientStorage";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "getVersion";
+    readonly outputs: readonly [{
+        readonly internalType: "string";
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "pure";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly name: "initialize";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "isAllowed";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }];
+    readonly name: "isAllowedForDecryption";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "isAllowedForDecryption";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes[]";
+        readonly name: "data";
+        readonly type: "bytes[]";
+    }];
+    readonly name: "multicall";
+    readonly outputs: readonly [{
+        readonly internalType: "bytes[]";
+        readonly name: "results";
+        readonly type: "bytes[]";
+    }];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "owner";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "paused";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "bytes32";
+        readonly name: "handle";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly name: "persistAllowed";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "renounceOwnership";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "addr";
+        readonly type: "address";
+    }];
+    readonly name: "setFheExecutorAddress";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "newOwner";
+        readonly type: "address";
+    }];
+    readonly name: "transferOwnership";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}];