@inco/shield-js 0.0.0-bootstrap.0 → 0.2.0

package/README.md

@@ -4,347 +4,92 @@ TypeScript SDK for interacting with IncoShield contracts from browsers and Node.
 
 ## Installation
 
-> **Note:** This package is not yet published to npm. For now, use it within this monorepo workspace.
-
+```bash
+bun add @inco/shield-js
+```
 
 ## Shield Client
 
-The SDK wraps the shield covalidator's gRPC API with a typed TypeScript client. All protobuf details are hidden — you work with hex strings and bigints.
+The SDK wraps the Shield conductor's gRPC API with a typed TypeScript client. `createShieldClient` accepts the network, contract, transport, signer, serialized TEE public key, and protocol-fee routing configuration. Client creation is asynchronous because it resolves the configured Shield contract's paymaster.
 
-### Connect to the covalidator
+Install a Connect transport for the target environment, such as `@connectrpc/connect-web` for browsers or `@connectrpc/connect-node` for Node.js.
 
-The client accepts a connect-es transport, so it works in any environment:
+### Create a client
 
 ```typescript
-import { createShieldClient } from "@inco/shield-js";
-
-// Browser
 import { createConnectTransport } from "@connectrpc/connect-web";
-const transport = createConnectTransport({ baseUrl: "http://localhost:50051" });
-
-// Node.js
-import { createConnectTransport } from "@connectrpc/connect-node";
-const transport = createConnectTransport({ baseUrl: "http://localhost:50051", httpVersion: "2" });
-
-const shield = createShieldClient(transport);
-```
-
-### Issue a transfer
-
-Submit shielded transfers and receive a spending note to execute on-chain:
-
-```typescript
-const note = await shield.issue({
-  transfer: {
-    sender: "0x2222222222222222222222222222222222222222",
-    receiver: "0x3333333333333333333333333333333333333333",
-    assetId: "0x0000000000000000000000000000000000000000000000000000000000000001",
-    amount: 1000n,
-  },
+import {
+  createShieldClient,
+  type ShieldSignerInput,
+} from "@inco/shield-js";
+import { http } from "viem";
+
+declare const shieldAddress: `0x${string}`;
+declare const signer: ShieldSignerInput;
+declare const teePublicKey: Uint8Array;
+declare const feeAccrualAdapter: `0x${string}`;
+declare const protocolFeeTreasury: `0x${string}`;
+
+const shield = await createShieldClient({
+  grpcTransport: createConnectTransport({
+    baseUrl: "https://conductor.example.com",
+  }),
+  viemTransport: http("https://rpc.example.com"),
+  chainId: 84532n,
+  shieldAddress,
+  signer,
+  teePublicKey,
+  feeAccrualAdapter,
+  protocolFeeTreasury,
 });
-
-// note.spends contains the signed spends to submit on-chain
-// note.signer is the covalidator address
 ```
 
-### Issue a withdrawal
-
-Submit a private-to-public withdrawal intent:
-
-```typescript
-const note = await shield.issueWithdraw({
-  sender: "0x2222222222222222222222222222222222222222",
-  to: "0x4444444444444444444444444444444444444444",
-  assetId: "0x0000000000000000000000000000000000000000000000000000000000000001",
-  amount: 500n,
-  assetMovement: {
-    assetAdapter: erc20AdapterAddress,
-    assetIdentificationArgs: "0x...",
-    movementArgs: "0x...",
-  },
-  sessionKeyHash: "0x0000000000000000000000000000000000000000000000000000000000000001",
-  memo: "0x",
-}, "0x2222222222222222222222222222222222222222");
-
-// note.spends[0].spendType will be "withdraw"
-```
+### Issue a transfer
 
-### Query a balance
+Draft a shielded transfer as an ERC-4337 user operation, then submit it through the client's configured bundler:
 
 ```typescript
-const balance = await shield.getBalance({
-  address: "0x2222222222222222222222222222222222222222",
+const { userOp } = await shield.issueTransfer({
+  receiver: "0x3333333333333333333333333333333333333333",
   assetId: "0x0000000000000000000000000000000000000000000000000000000000000001",
-});
-
-console.log(balance.confirmed, balance.pending, balance.available);
-```
-
-## Contract Interactions
-
-The `contracts` module provides typed helpers for all IncoShield on-chain operations.
-
-```typescript
-import { contracts } from "@inco/shield-js";
-```
-
-### Deposit
-
-```typescript
-// 1. Request the TEE attestation. The enclave returns toCiphertext (the
-//    AEAD-sealed recipient address) and the TEE signature over the deposit.
-const attestation = await shield.requestDepositAttestation({
-  recipient: account.address,
-  assetAdapter: erc20AdapterAddress,
-  assetIdentificationArgs: encodedTokenAddress,
+  amount: 1000n,
   memo: "0x",
-  escapeHatch: "0x",
 });
 
-// 2. Submit on-chain with the TEE-issued ciphertext + signature.
-const { txHash } = await contracts.deposit(
-  walletClient,
-  publicClient,
-  shieldAddress,
-  {
-    toCiphertext: attestation.toCiphertext,
-    from: account.address,
-    assetMovement: {
-      assetAdapter: erc20AdapterAddress,
-      assetIdentificationArgs: encodedTokenAddress,
-      movementArgs: encodedAmount,
-    },
-    amount: 1000n,
-    memo: "0x",
-    escapeHatch: "0x",
-  },
-  attestation.teeSignature,
-);
-```
-
-### Transfer, Withdraw, DeFi Interaction
-
-```typescript
-// Transfer (with TEE signature)
-await contracts.transfer(walletClient, publicClient, shieldAddress, transferData, signature);
-
-// Withdraw (with TEE signature)
-await contracts.withdraw(walletClient, publicClient, shieldAddress, withdrawData, signature);
-
-// DeFi interaction (with TEE signature)
-await contracts.performDefiInteraction(walletClient, publicClient, shieldAddress, interaction, signature);
+const { receipt } = await shield.submitUserOp(userOp);
 ```
 
-### Proxy Account Operations
-
-```typescript
-// Execute operations via protocol-managed proxy account
-await contracts.performProxyAccountOperation(walletClient, publicClient, shieldAddress, {
-  account: proxyAddress, // or address(0) to deploy new
-  nonce: await contracts.getProxyAccountOperationNonce(publicClient, shieldAddress, proxyAddress),
-  batch: [{ target: tokenAddress, value: 0n, data: calldata }],
-  escapeHatchData: "0x",
-}, signature);
-
-// Query proxy accounts
-const proxies = await contracts.getDeployedProxyAccounts(publicClient, shieldAddress);
-const isOwned = await contracts.isProxyAccountOwnedByProtocol(publicClient, shieldAddress, proxyAddress);
-```
-
-### Digests and State
-
-```typescript
-// Get current handle
-const handle = await contracts.getHandle(publicClient, shieldAddress);
-
-// Compute operation digests (for TEE signing)
-const digest = await contracts.getTransferDigest(publicClient, shieldAddress, transferData);
-const digest = await contracts.getWithdrawDigest(publicClient, shieldAddress, withdrawData);
-const digest = await contracts.getProxyAccountOperationDigest(publicClient, shieldAddress, operation);
-```
-
-### Watch Settlement Events
-
-```typescript
-const unwatch = contracts.watchSettlementEvents(publicClient, shieldAddress, {
-  onTransferSettled: (event, log) => {
-    console.log("Transfer settled:", event.newShieldHandle);
-  },
-  onDepositSettled: (event, log) => {
-    console.log("Deposit:", event.deposit.from, event.assetId, event.deposit.amount);
-  },
-  onWithdrawSettled: (event, log) => {
-    console.log("Withdraw:", event.withdraw.to, event.assetId, event.withdraw.amount);
-  },
-  onProxyAccountOperationSettled: (event, log) => {
-    console.log("Proxy op:", event.proxyAccount);
-  },
-});
-
-// Stop watching
-unwatch();
-```
-
-### Parse individual event logs
-
-```typescript
-import { contracts } from "@inco/shield-js";
-
-const transferEvent = contracts.parseTransferSettledLog(log);
-const depositEvent = contracts.parseDepositSettledLog(log);
-const withdrawEvent = contracts.parseWithdrawSettledLog(log);
-const proxyOpEvent = contracts.parseProxyAccountOperationSettledLog(log);
-```
-
-## Uniswap Adapter
+### Query a balance
 
-### Setup Clients
+Balance, portfolio, and history queries are authorized by a signed viewing session. Sign one once and reuse it for every query until it expires:
 
 ```typescript
-import { createPublicClient, createWalletClient, http } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
-import { sepolia } from "viem/chains";
-
-const account = privateKeyToAccount("0x...");
-
-const publicClient = createPublicClient({
-  chain: sepolia,
-  transport: http("https://rpc.sepolia.org"),
-});
-
-const walletClient = createWalletClient({
-  account,
-  chain: sepolia,
-  transport: http("https://rpc.sepolia.org"),
+const viewing = await shield.createViewingSession({
+  expiresAt: BigInt(Math.floor(Date.now() / 1000) + 3600),
 });
-```
-
-### Authorize a DeFi Adapter
 
-```typescript
-import { authorizeAdapter } from "@inco/shield-js";
-
-const result = await authorizeAdapter({
-  publicClient,
-  walletClient,
-  incoShieldAddress: "0x...",
-  adapterAddress: "0x...",
+const balance = await shield.getBalance(viewing, {
+  assetId: "0x0000000000000000000000000000000000000000000000000000000000000001",
 });
-```
-
-### Find Uniswap V4 Pools
-
-```typescript
-import { findPoolsWithLiquidity, UNISWAP_V4_SEPOLIA } from "@inco/shield-js";
 
-const pools = await findPoolsWithLiquidity(
-  publicClient,
-  UNISWAP_V4_SEPOLIA.STATE_VIEW,
-  [
-    {
-      name: "ETH/USDC 0.3%",
-      currency0: "0x0000000000000000000000000000000000000000",
-      currency1: "0x...",
-      fee: 3000,
-      tickSpacing: 60,
-      hooks: "0x0000000000000000000000000000000000000000",
-    },
-  ],
+console.log(
+  balance.bankBalance,
+  balance.outstandingBalance,
+  balance.bookBalance,
 );
 ```
 
-### Execute a Swap
-
-```typescript
-import {
-  approveToken,
-  buildEncodedV4Actions,
-  encodeSwapArgs,
-  buildDefiInteraction,
-  depositToShield,
-  executeDefiInteraction,
-  generateNullifier,
-  getDefiInteractionDigest,
-  signDefiInteraction,
-  DEPLOYED_CONTRACTS,
-  SEPOLIA_TOKENS,
-  POOL_CONFIG,
-} from "@inco/shield-js";
-
-const {
-  incoShield: incoShieldAddress,
-  erc20Adapter: erc20AdapterAddress,
-  uniswapV4Adapter: uniswapAdapterAddress,
-} = DEPLOYED_CONTRACTS;
+## Contract Exports
 
-const amount = parseUnits("0.1", 18);
+The `contracts` namespace exports the generated contract ABIs and the ERC-20 asset ID helper. Use the ABIs with a viem client for direct contract interactions.
 
-// 1. Approve and deposit tokens to shield
-await approveToken(walletClient, publicClient, SEPOLIA_TOKENS.WETH, incoShieldAddress, amount);
-
-const { stateAfterDeposit } = await depositToShield(
-  walletClient,
-  publicClient,
-  incoShieldAddress,
-  {
-    toCiphertext: "0x01",
-    from: account.address,
-    assetAdapter: erc20AdapterAddress,
-    tokenAddress: SEPOLIA_TOKENS.WETH,
-    amount,
-  },
-);
-
-// 2. Build swap args
-const poolKey = {
-  currency0: SEPOLIA_TOKENS.NATIVE_ETH,
-  currency1: SEPOLIA_TOKENS.USDC,
-  fee: POOL_CONFIG.FEE,
-  tickSpacing: POOL_CONFIG.TICK_SPACING,
-  hooks: POOL_CONFIG.HOOKS,
-};
-
-const encodedV4Actions = buildEncodedV4Actions({
-  poolKey,
-  zeroForOne: true,
-  amountIn: amount,
-  amountOutMinimum: 1n,
-});
-
-const swapArgs = encodeSwapArgs({
-  encodedV4Actions,
-  tokenIn: SEPOLIA_TOKENS.WETH,
-  tokenOut: SEPOLIA_TOKENS.USDC,
-  amountOutMinimum: 1n,
-  toCiphertext: "0x01",
-  deadline: BigInt(Math.floor(Date.now() / 1000) + 1800),
-  unwrapWeth: true,
-});
-
-// 3. Build and sign defi interaction
-const defiInteraction = buildDefiInteraction({
-  to: uniswapAdapterAddress,
-  nullifier: generateNullifier(account.address),
-  pastShieldHandle: stateAfterDeposit,
-  assetAdapter: erc20AdapterAddress,
-  tokenAddress: SEPOLIA_TOKENS.WETH,
-  amount,
-  defiAdapter: uniswapAdapterAddress,
-  adapterArgs: swapArgs,
-});
-
-const digest = await getDefiInteractionDigest(publicClient, incoShieldAddress, defiInteraction);
-const signature = await signDefiInteraction(account, digest);
+```typescript
+import { computeErc20AssetId, contracts } from "@inco/shield-js";
 
-// 4. Execute
-const { txHash, blockNumber } = await executeDefiInteraction(
-  walletClient,
-  publicClient,
-  incoShieldAddress,
-  defiInteraction,
-  signature,
-  { gas: 1_000_000n },
+const assetId = computeErc20AssetId(
+  "0x1111111111111111111111111111111111111111",
 );
+const { erc20AdapterAbi, incoShieldAbi } = contracts;
 ```
 
 ## Development
@@ -355,5 +100,4 @@ bun run generate    # Generate proto types + ABIs
 bun run build       # Generate + compile TypeScript
 bun run test        # Run tests
 bun run typecheck   # Type-check only
-bun run uniswap     # Run example swap script
 ```