@inco/shield-js 0.0.0-bootstrap.0

package/dist/shield/userop/gas-estimation.js

@@ -0,0 +1,284 @@
+/**
+ * Constitution: Creates an intent with gas estimation.
+ *
+ * The flow is:
+ * 1. Create a placeholder UserOp from the user's intent op
+ * 2. Get the gas estimate from the bundler using the placeholder UserOp
+ * 3. Assemble the final intent with the gas estimate
+ */
+import { bytesToHex, concat, encodeAbiParameters, isAddress, isHex, maxUint64, maxUint256, zeroAddress, zeroHash, } from 'viem';
+import { entryPoint07Abi, entryPoint07Address, } from 'viem/account-abstraction';
+import { incoShieldAbi, shieldAbiStubAbi, teeSmartAccountAbi, } from '../../contracts/abi.js';
+import { getAbiFromUnitFunction } from '../../contracts/utils.js';
+import { InvalidContractReturnType } from '../../errors.js';
+import { IntentKind } from '../../generated/inco/shield/v2/drafting_pb.js';
+import { chequeBlobSize } from '../encryption.js';
+import { assembleUserOp, buildUnsignedUserOp } from './userOp.js';
+const ENTRYPOINT_VERSION = '0.7';
+/** Pimlico-style dummy ECDSA sig: EIP-2 canonical `s` keeps OZ's
+ * `ECDSA.tryRecover` on the `ecrecover` path (else verification gas under-quotes). */
+const PLACEHOLDER_ECDSA_SIG = concat([
+    bytesToHex(new Uint8Array(32).fill(0xff)), // r
+    `0x7${'a'.repeat(63)}`, // s (top nibble 0x7 → s < n/2)
+    '0x1c', // v
+]);
+/** Placeholder `abi.encode(bytes[] signers, bytes[] sigs)`. Real signer addresses
+ *  required: OZ's `isSigner` check runs before any `ecrecover`, so zero-address
+ *  signers short-circuit the validation loop and under-quote gas. */
+export function placeholderMultisig(signers) {
+    const sigs = signers.map(() => PLACEHOLDER_ECDSA_SIG);
+    return encodeAbiParameters([{ type: 'bytes[]' }, { type: 'bytes[]' }], [signers, sigs]);
+}
+/**
+ * Given a plaintext encoded as a 0x-prefixed hex string, return the ciphertext size.
+ */
+function ptToCtSize(pt) {
+    // TODO FIXME https://github.com/Inco-fhevm/shield/issues/496
+    // We should use ciphertext size.
+    return chequeBlobSize(pt.length / 2 - 1); // Hex to bytes length
+}
+const TRANSFER_PLAINTEXT = encodeAbiParameters([getAbiFromUnitFunction(shieldAbiStubAbi, 'transferPlaintext')], [
+    {
+        sender: zeroAddress,
+        receiver: zeroAddress,
+        amount: maxUint256,
+        assetId: zeroHash,
+    },
+]);
+const WITHDRAWAL_PLAINTEXT = encodeAbiParameters([getAbiFromUnitFunction(shieldAbiStubAbi, 'withdrawalPlaintext')], [{ sender: zeroAddress }]);
+const SENDER_ESCAPE_PLAINTEXT = encodeAbiParameters([getAbiFromUnitFunction(shieldAbiStubAbi, 'senderEscapePlaintext')], [
+    {
+        sender: zeroAddress,
+        assetId: zeroHash,
+        draftingHandle: zeroHash,
+        spendAmount: maxUint256,
+        balanceSnapshot: maxUint256,
+        chequeNumber: maxUint64,
+        oldestPossiblyOutstanding: maxUint64,
+    },
+]);
+const RECEIVER_ESCAPE_PLAINTEXT = encodeAbiParameters([getAbiFromUnitFunction(shieldAbiStubAbi, 'receiverEscapePlaintext')], [
+    {
+        receiver: zeroAddress,
+        assetId: zeroHash,
+        draftingHandle: zeroHash,
+        receiveAmount: maxUint256,
+        balanceSnapshot: maxUint256,
+        chequeNullifier: zeroHash,
+        senderChequeNumber: maxUint64,
+        oldestPossiblyOutstandingSend: maxUint64,
+    },
+]);
+const INDIVIDUAL_REVOCATION_PLAINTEXT = encodeAbiParameters([getAbiFromUnitFunction(shieldAbiStubAbi, 'individualRevocationPlaintext')], [{ owner: zeroAddress, permissionId: zeroHash }]);
+const USER_WIDE_REVOCATION_PLAINTEXT = encodeAbiParameters([getAbiFromUnitFunction(shieldAbiStubAbi, 'userWideRevocationPlaintext')], [{ owner: zeroAddress }]);
+/** `abi.encode(address)` is one ABI word (32 bytes) regardless of adapter. */
+const ERC20_ASSET_IDENTIFICATION_ARGS_SIZE = 32;
+/** `abi.encode(uint256)` is one ABI word (32 bytes). */
+const ERC20_MOVEMENT_ARGS_SIZE = 32;
+/** Non-zero hex of `byteLength` bytes. Zero bytes cost 4 gas vs 16 for non-zero,
+ *  so `zeroHash`-style placeholders under-quote calldata gas by ~4×. */
+function nonZeroPlaceholder(byteLength) {
+    return bytesToHex(new Uint8Array(byteLength).fill(0xaa));
+}
+/** Build a placeholder {@link SettlementOp} from an `IntentOp`: intent-supplied fields
+ *  (memo, recipient, asset movement, …) are real; enclave-derived fields use
+ *  worst-case-sized placeholders so the estimate never under-quotes. Per-kind
+ *  cases keep TS narrowing intact across the discriminated union.
+ *
+ *  `draftingHandle` must be a handle known on-chain — `IncoShield.transfer` and
+ *  `processWithdrawalCore` revert with `PastShieldHandleNotFound` against an
+ *  unknown handle. Caller reads the live handle via `IncoShield.getHandle()` and
+ *  threads it in, though it need not be the handle the enclave ultimately drafts
+ *  against. `bytes32` slots use a nonzero placeholder so calldata gas (16/byte)
+ *  matches the eventual real values rather than zero bytes (4/byte). */
+function toPlaceholderSettlementOp(intentOp, currentHandle) {
+    switch (intentOp.kind) {
+        case IntentKind.TRANSFER:
+        case IntentKind.DELEGATED_TRANSFER:
+            return {
+                kind: intentOp.kind,
+                op: transferPlaceholder(intentOp.op.memo, currentHandle),
+            };
+        case IntentKind.WITHDRAW:
+        case IntentKind.DELEGATED_WITHDRAW:
+            return {
+                kind: intentOp.kind,
+                op: {
+                    core: withdrawalCorePlaceholder(intentOp.op.core, currentHandle),
+                    memo: intentOp.op.memo,
+                },
+            };
+        case IntentKind.DEFI_INTERACTION:
+        case IntentKind.DELEGATED_DEFI_INTERACTION:
+            return {
+                kind: intentOp.kind,
+                op: {
+                    withdrawal: withdrawalCorePlaceholder(intentOp.op.withdrawal, currentHandle),
+                    defiAdapter: intentOp.op.defiAdapter,
+                    adapterArgs: intentOp.op.adapterArgs,
+                    memo: intentOp.op.memo,
+                },
+            };
+        case IntentKind.INDIVIDUAL_REVOCATION:
+            return {
+                kind: intentOp.kind,
+                op: {
+                    ciphertext: nonZeroPlaceholder(ptToCtSize(INDIVIDUAL_REVOCATION_PLAINTEXT)),
+                    draftingHandle: zeroHash,
+                    draftingTimestamp: maxUint64,
+                },
+            };
+        case IntentKind.USER_WIDE_REVOCATION:
+            return {
+                kind: intentOp.kind,
+                op: {
+                    ciphertext: nonZeroPlaceholder(ptToCtSize(USER_WIDE_REVOCATION_PLAINTEXT)),
+                    draftingHandle: zeroHash,
+                    draftingTimestamp: maxUint64,
+                },
+            };
+    }
+}
+function transferPlaceholder(memo, currentHandle) {
+    return {
+        draftingHandle: currentHandle,
+        draftingTimestamp: maxUint64,
+        nullifier: nonZeroPlaceholder(32),
+        senderEscapeCommitment: nonZeroPlaceholder(32),
+        receiverEscapeCommitment: nonZeroPlaceholder(32),
+        senderEscapeData: nonZeroPlaceholder(ptToCtSize(SENDER_ESCAPE_PLAINTEXT)),
+        receiverEscapeData: nonZeroPlaceholder(ptToCtSize(RECEIVER_ESCAPE_PLAINTEXT)),
+        ciphertext: nonZeroPlaceholder(ptToCtSize(TRANSFER_PLAINTEXT)),
+        memo,
+    };
+}
+function withdrawalCorePlaceholder(core, currentHandle) {
+    return {
+        to: core.to,
+        nullifier: nonZeroPlaceholder(32),
+        amount: maxUint256,
+        draftingHandle: currentHandle,
+        draftingTimestamp: maxUint64,
+        assetMovement: core.assetMovement,
+        ciphertext: nonZeroPlaceholder(ptToCtSize(WITHDRAWAL_PLAINTEXT)),
+        senderEscapeCommitment: nonZeroPlaceholder(32),
+        senderEscapeData: nonZeroPlaceholder(ptToCtSize(SENDER_ESCAPE_PLAINTEXT)),
+    };
+}
+/** Exported for tests that pin the expected placeholder byte counts. */
+export const PLACEHOLDER_SIZES = {
+    transferCiphertext: ptToCtSize(TRANSFER_PLAINTEXT),
+    withdrawalCiphertext: ptToCtSize(WITHDRAWAL_PLAINTEXT),
+    senderEscapeData: ptToCtSize(SENDER_ESCAPE_PLAINTEXT),
+    receiverEscapeData: ptToCtSize(RECEIVER_ESCAPE_PLAINTEXT),
+    erc20AssetIdentificationArgs: ERC20_ASSET_IDENTIFICATION_ARGS_SIZE,
+    erc20MovementArgs: ERC20_MOVEMENT_ARGS_SIZE,
+};
+/**
+ * Build an unsigned UserOp for bundler gas estimation.
+ *
+ * Invariant: every wire-shape field matches the size of what the conductor will
+ * submit. Cheque fields are sized against worst-case plaintexts (over-estimate,
+ * never under); adapter args are ERC-20-sized — new adapters need entries in
+ * `PLACEHOLDER_SIZES`.
+ */
+export async function userOpFromIntentForGasEstimation(intentOp, signer, shieldConfig, publicClient, gas) {
+    const [nonce, signersForPlaceholder, currentHandle, paymasterGasLimits] = await Promise.all([
+        getEntryPointNonce(publicClient, signer.address),
+        getQuorumSignersForPlaceholder(publicClient, signer.address),
+        getCurrentHandle(publicClient, shieldConfig.shieldAddress),
+        getPaymasterGasLimits(),
+    ]);
+    const placeholderGas = {
+        ...gas,
+        callGasLimit: 0n,
+        verificationGasLimit: 0n,
+        preVerificationGas: 0n,
+        paymasterVerificationGasLimit: paymasterGasLimits.paymasterVerificationGasLimit,
+        paymasterPostOpGasLimit: paymasterGasLimits.paymasterPostOpGasLimit,
+        maxAmount: 0n,
+    };
+    const unsigned = buildUnsignedUserOp({
+        settlementOp: toPlaceholderSettlementOp(intentOp, currentHandle),
+        sender: signer.address,
+        nonce,
+        shieldAddress: shieldConfig.shieldAddress,
+        gas: placeholderGas,
+    });
+    return assembleUserOp(unsigned, placeholderMultisig(signersForPlaceholder));
+    /** Read the v0.7 EntryPoint sequential nonce for `sender` under default key 0. */
+    // TODO: implement of parrallelised (2D nonce behaviour) using some random key dont use 0 @chiranjeev13
+    async function getEntryPointNonce(publicClient, sender) {
+        const nonce = await publicClient.readContract({
+            address: entryPoint07Address,
+            abi: entryPoint07Abi,
+            functionName: 'getNonce',
+            args: [sender, 0n],
+        });
+        if (typeof nonce !== 'bigint') {
+            throw new InvalidContractReturnType({
+                message: `EntryPoint.getNonce returned non-bigint: ${typeof nonce}`,
+                functionName: 'EntryPoint.getNonce',
+                expectedType: 'bigint',
+            });
+        }
+        return nonce;
+    }
+    /** Read the TEE quorum signers from `TeeSmartAccount` and slice to threshold T.
+     *  Real addresses let the bundler's `isSigner` loop traverse fully before
+     *  short-circuiting on `DUMMY_ECDSA_SIG`. */
+    async function getQuorumSignersForPlaceholder(publicClient, account) {
+        const [signersRaw, thresholdRaw] = await Promise.all([
+            publicClient.readContract({
+                address: account,
+                abi: teeSmartAccountAbi,
+                functionName: 'getSigners',
+                args: [0n, maxUint64],
+            }),
+            publicClient.readContract({
+                address: account,
+                abi: teeSmartAccountAbi,
+                functionName: 'threshold',
+            }),
+        ]);
+        if (!Array.isArray(signersRaw) ||
+            !signersRaw.every((s) => isAddress(s))) {
+            throw new InvalidContractReturnType({
+                message: 'TeeSmartAccount.getSigners returned a non-address-array result',
+                functionName: 'TeeSmartAccount.getSigners',
+                expectedType: 'readonly Address[]',
+            });
+        }
+        if (typeof thresholdRaw !== 'bigint') {
+            throw new InvalidContractReturnType({
+                message: `TeeSmartAccount.threshold returned non-bigint: ${typeof thresholdRaw}`,
+                functionName: 'TeeSmartAccount.threshold',
+                expectedType: 'bigint',
+            });
+        }
+        return signersRaw.slice(0, Number(thresholdRaw));
+    }
+    async function getCurrentHandle(publicClient, shieldAddress) {
+        const handle = await publicClient.readContract({
+            address: shieldAddress,
+            abi: incoShieldAbi,
+            functionName: 'getHandle',
+        });
+        if (!isHex(handle) || handle.length !== 66) {
+            throw new InvalidContractReturnType({
+                message: `IncoShield.getHandle returned non-bytes32: ${String(handle)}`,
+                functionName: 'IncoShield.getHandle',
+                expectedType: 'Hex (bytes32)',
+            });
+        }
+        return handle;
+    }
+    async function getPaymasterGasLimits() {
+        const defaultPMVerificationGasLimit = 100000n;
+        const defaultPMPostOpGasLimit = 300000n;
+        return {
+            paymasterVerificationGasLimit: defaultPMVerificationGasLimit,
+            paymasterPostOpGasLimit: defaultPMPostOpGasLimit,
+        };
+    }
+}

package/dist/shield/userop/index.d.ts

@@ -0,0 +1 @@
+export { ENTRYPOINT_VERSION } from './types.js';

package/dist/shield/userop/index.js

@@ -0,0 +1 @@
+export { ENTRYPOINT_VERSION } from './types.js';

package/dist/shield/userop/token-exchange.d.ts

@@ -0,0 +1,54 @@
+import { type Address, type Hex, type PublicClient } from 'viem';
+export type AggregatorRate = {
+    readonly answer: bigint;
+    readonly decimals: number;
+    readonly updatedAt: bigint;
+    readonly description: string;
+};
+/**
+ * Fetch the latest price from a single Chainlink aggregator contract.
+ *
+ * The aggregator's `description` (e.g. "ETH / USD") encodes the pair —
+ * there is no on-chain way to enforce that callers passed the right address.
+ */
+export declare function getAggregatorRate(publicClient: PublicClient, aggregator: Address): Promise<AggregatorRate>;
+declare const UnknownAssetFeed_base: new <Fields extends Record<string, unknown>>(fields: Fields) => Error & {
+    readonly _tag: "UnknownAssetFeed";
+} & Readonly<Fields>;
+export declare class UnknownAssetFeed extends UnknownAssetFeed_base<{
+    readonly assetId: Hex;
+}> {
+}
+/**
+ * Resolve the Chainlink aggregator for a Shield `assetId` (= ERC-20 token
+ * address padded to bytes32) and return its latest rate.
+ */
+export declare function getAssetRate(publicClient: PublicClient, assetId: Hex): Promise<AggregatorRate>;
+/** RAY = 1e27, the fixed-point scale used by the Shield paymaster. */
+export declare const RAY: bigint;
+/**
+ * Compute the RAY-precision exchange rate (ETH priced in token units)
+ * that the Shield paymaster consumes. Mirrors the on-chain convention
+ * from SHIELD_PAYMASTER.md:
+ *
+ *     tokenAmount = ceil(gasCostWei * exchangeRate / 1e27)
+ *
+ * Worked example: if 1 ETH = 2000 USDC and USDC has 6 decimals,
+ *     exchangeRate = 2000 * 1e6 * 1e27 / 1e18 = 2e18
+ *
+ * Derivation here uses two Chainlink USD feeds:
+ *     ethInToken (real) = ethUsd / tokenUsd
+ *     rate (RAY)        = ethInToken * 10^tokenDec * 1e27 / 1e18
+ *                       = ethUsd * 10^tokenDec * 10^tokenFeedDec * RAY
+ *                         / (tokenUsd * 10^ethFeedDec * 1e18)
+ */
+export declare function getEthExchangeRateRay(publicClient: PublicClient, assetId: Hex): Promise<bigint>;
+/** `ceil(ethWei * exchangeRate / RAY)` — matches the paymaster's rounding. */
+export declare function applyExchangeRateRayCeil(ethWei: bigint, exchangeRateRay: bigint): bigint;
+/**
+ * Convenience: fetch the RAY rate for `assetId` and apply it to `ethWei`.
+ * Use `getEthExchangeRateRay` directly when the caller also needs to
+ * forward the rate to the paymaster signer.
+ */
+export declare function convertEthWeiToTokenUnits(publicClient: PublicClient, assetId: Hex, ethWei: bigint): Promise<bigint>;
+export {};

package/dist/shield/userop/token-exchange.js

@@ -0,0 +1,165 @@
+import { parseAbi } from 'viem';
+import { InvalidContractReturnType, TaggedError } from '../../errors.js';
+const aggregatorAbi = parseAbi([
+    'function latestRoundData() view returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)',
+    'function decimals() view returns (uint8)',
+    'function description() view returns (string)',
+]);
+const erc20DecimalsAbi = parseAbi(['function decimals() view returns (uint8)']);
+/** ETH / USD aggregator on Base Sepolia. */
+const BASE_SEPOLIA_ETH_USD_FEED = '0x4aDC67696bA383F43DD60A9e78F2C97Fbbfc7cb1';
+/**
+ * Fetch the latest price from a single Chainlink aggregator contract.
+ *
+ * The aggregator's `description` (e.g. "ETH / USD") encodes the pair —
+ * there is no on-chain way to enforce that callers passed the right address.
+ */
+export async function getAggregatorRate(publicClient, aggregator) {
+    const [roundDataRaw, decimalsRaw, descriptionRaw] = await Promise.all([
+        publicClient.readContract({
+            address: aggregator,
+            abi: aggregatorAbi,
+            functionName: 'latestRoundData',
+        }),
+        publicClient.readContract({
+            address: aggregator,
+            abi: aggregatorAbi,
+            functionName: 'decimals',
+        }),
+        publicClient.readContract({
+            address: aggregator,
+            abi: aggregatorAbi,
+            functionName: 'description',
+        }),
+    ]);
+    const { answer, updatedAt } = parseLatestRoundData(roundDataRaw);
+    const decimals = parseDecimals(decimalsRaw);
+    if (typeof descriptionRaw !== 'string') {
+        throw new InvalidContractReturnType({
+            message: `Aggregator.description returned non-string: ${typeof descriptionRaw}`,
+            functionName: 'Aggregator.description',
+            expectedType: 'string',
+        });
+    }
+    if (answer <= 0n) {
+        throw new InvalidContractReturnType({
+            message: `Aggregator ${aggregator} returned non-positive answer (${answer})`,
+            functionName: 'Aggregator.latestRoundData',
+            expectedType: 'positive int256',
+        });
+    }
+    return { answer, decimals, updatedAt, description: descriptionRaw };
+}
+function parseLatestRoundData(value) {
+    if (!Array.isArray(value) ||
+        value.length < 5 ||
+        typeof value[1] !== 'bigint' ||
+        typeof value[3] !== 'bigint') {
+        throw new InvalidContractReturnType({
+            message: 'Aggregator.latestRoundData returned an unexpected shape',
+            functionName: 'Aggregator.latestRoundData',
+            expectedType: '[uint80, int256, uint256, uint256, uint80]',
+        });
+    }
+    return { answer: value[1], updatedAt: value[3] };
+}
+/**
+ * Chainlink aggregators for fee-payment assets on Base Sepolia, keyed by
+ * the ERC-20 token address (Shield's `assetId` is just the token address
+ * left-padded to bytes32). Each feed is **TOKEN / USD** — direction matters
+ * when converting gas cost from ETH to token units downstream.
+ */
+const BASE_SEPOLIA_TOKEN_FEEDS = {
+    // Circle native USDC on Base Sepolia → USDC/USD aggregator
+    '0x036CbD53842c5426634e7929541eC2318f3dCF7e': '0xd30e2101a97dcbAeBCBC04F14C3f624E67A35165',
+};
+export class UnknownAssetFeed extends TaggedError('UnknownAssetFeed') {
+}
+/**
+ * Resolve the Chainlink aggregator for a Shield `assetId` (= ERC-20 token
+ * address padded to bytes32) and return its latest rate.
+ */
+export async function getAssetRate(publicClient, assetId) {
+    const tokenAddress = tokenAddressFromAssetId(assetId);
+    const aggregator = lookupFeed(tokenAddress);
+    if (aggregator === undefined) {
+        throw new UnknownAssetFeed({ assetId });
+    }
+    return getAggregatorRate(publicClient, aggregator);
+}
+/** Extract the trailing 20-byte ERC-20 address from a bytes32 assetId. */
+function tokenAddressFromAssetId(assetId) {
+    // bytes32 hex = "0x" + 64 chars; last 40 are the address.
+    const hex = assetId.startsWith('0x') ? assetId.slice(2) : assetId;
+    return `0x${hex.slice(-40)}`;
+}
+/** Case-insensitive lookup against the feed registry. */
+function lookupFeed(token) {
+    const target = token.toLowerCase();
+    for (const [key, aggregator] of Object.entries(BASE_SEPOLIA_TOKEN_FEEDS)) {
+        if (key.toLowerCase() === target)
+            return aggregator;
+    }
+    return undefined;
+}
+/** RAY = 1e27, the fixed-point scale used by the Shield paymaster. */
+export const RAY = 10n ** 27n;
+/**
+ * Compute the RAY-precision exchange rate (ETH priced in token units)
+ * that the Shield paymaster consumes. Mirrors the on-chain convention
+ * from SHIELD_PAYMASTER.md:
+ *
+ *     tokenAmount = ceil(gasCostWei * exchangeRate / 1e27)
+ *
+ * Worked example: if 1 ETH = 2000 USDC and USDC has 6 decimals,
+ *     exchangeRate = 2000 * 1e6 * 1e27 / 1e18 = 2e18
+ *
+ * Derivation here uses two Chainlink USD feeds:
+ *     ethInToken (real) = ethUsd / tokenUsd
+ *     rate (RAY)        = ethInToken * 10^tokenDec * 1e27 / 1e18
+ *                       = ethUsd * 10^tokenDec * 10^tokenFeedDec * RAY
+ *                         / (tokenUsd * 10^ethFeedDec * 1e18)
+ */
+export async function getEthExchangeRateRay(publicClient, assetId) {
+    const tokenAddress = tokenAddressFromAssetId(assetId);
+    const [tokenRate, ethRate, tokenDecimalsRaw] = await Promise.all([
+        getAssetRate(publicClient, assetId),
+        getAggregatorRate(publicClient, BASE_SEPOLIA_ETH_USD_FEED),
+        publicClient.readContract({
+            address: tokenAddress,
+            abi: erc20DecimalsAbi,
+            functionName: 'decimals',
+        }),
+    ]);
+    const tokenDecimals = parseDecimals(tokenDecimalsRaw);
+    const numerator = ethRate.answer *
+        10n ** BigInt(tokenDecimals) *
+        10n ** BigInt(tokenRate.decimals) *
+        RAY;
+    const denominator = tokenRate.answer * 10n ** BigInt(ethRate.decimals) * 10n ** 18n;
+    return numerator / denominator;
+}
+/** `ceil(ethWei * exchangeRate / RAY)` — matches the paymaster's rounding. */
+export function applyExchangeRateRayCeil(ethWei, exchangeRateRay) {
+    const product = ethWei * exchangeRateRay;
+    return (product + RAY - 1n) / RAY;
+}
+/**
+ * Convenience: fetch the RAY rate for `assetId` and apply it to `ethWei`.
+ * Use `getEthExchangeRateRay` directly when the caller also needs to
+ * forward the rate to the paymaster signer.
+ */
+export async function convertEthWeiToTokenUnits(publicClient, assetId, ethWei) {
+    const rate = await getEthExchangeRateRay(publicClient, assetId);
+    return applyExchangeRateRayCeil(ethWei, rate);
+}
+function parseDecimals(value) {
+    if (typeof value !== 'number') {
+        throw new InvalidContractReturnType({
+            message: `Aggregator.decimals returned non-number: ${typeof value}`,
+            functionName: 'Aggregator.decimals',
+            expectedType: 'uint8',
+        });
+    }
+    return value;
+}

package/dist/shield/userop/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Type-only surface for the UserOp builder. Runtime code lives in `userOp.ts`.
+ */
+import type { Address } from 'viem';
+import type { UserOperation } from 'viem/account-abstraction';
+import type { IntentKind } from '../../generated/inco/shield/v2/drafting_pb.js';
+import type * as abi from '../shield.eip712.gen.js';
+import type { DefiInteraction, IndividualRevocation, Transfer, UserWideRevocation, Withdrawal } from '../shield.eip712.gen.js';
+export declare const ENTRYPOINT_VERSION: "0.7";
+/**
+ * A drafted op — the full on-chain settlement struct the enclave produces from
+ * an intent via `draft()`, tagged by {@link IntentKind}. This is the "cheque":
+ * an intent is what the user signs *before* `draft()`; the cheque is what comes
+ * *after*, and is exactly what `IncoShield.{transfer,withdraw,...}` settles.
+ *
+ * Delegated kinds settle through the same on-chain function — and thus the same
+ * struct — as their non-delegated counterparts; the delegation context rides
+ * inside the intent, not in a separate selector.
+ */
+export type SettlementOp = {
+    kind: IntentKind.TRANSFER;
+    op: Transfer;
+} | {
+    kind: IntentKind.DELEGATED_TRANSFER;
+    op: Transfer;
+} | {
+    kind: IntentKind.WITHDRAW;
+    op: Withdrawal;
+} | {
+    kind: IntentKind.DELEGATED_WITHDRAW;
+    op: Withdrawal;
+} | {
+    kind: IntentKind.DEFI_INTERACTION;
+    op: DefiInteraction;
+} | {
+    kind: IntentKind.DELEGATED_DEFI_INTERACTION;
+    op: DefiInteraction;
+} | {
+    kind: IntentKind.INDIVIDUAL_REVOCATION;
+    op: IndividualRevocation;
+} | {
+    kind: IntentKind.USER_WIDE_REVOCATION;
+    op: UserWideRevocation;
+};
+/**
+ * Domain Intent: a signed EIP-712 intent struct tagged by its {@link IntentKind}
+ * discriminant. This is what the user signs *before* `draft()` — the enclave
+ * processes an `Intent` and produces the {@link Cheque}. Each variant is the
+ * generated `abi.{*}Intent` struct plus a `kind` tag; delegated kinds wrap
+ * their non-delegated inner intent inside the generated `Delegated*Intent` shape.
+ */
+export type Intent = TransferIntent | WithdrawalIntent | DefiInteractionIntent | IndividualRevocationIntent | UserWideRevocationIntent | DelegatedTransferIntent | DelegatedWithdrawalIntent | DelegatedDefiInteractionIntent;
+export type TransferIntent = {
+    readonly kind: IntentKind.TRANSFER;
+} & abi.TransferIntent;
+export type WithdrawalIntent = {
+    readonly kind: IntentKind.WITHDRAW;
+} & abi.WithdrawalIntent;
+export type DefiInteractionIntent = {
+    readonly kind: IntentKind.DEFI_INTERACTION;
+} & abi.DefiInteractionIntent;
+export type IndividualRevocationIntent = {
+    readonly kind: IntentKind.INDIVIDUAL_REVOCATION;
+} & abi.IndividualRevocationIntent;
+export type UserWideRevocationIntent = {
+    readonly kind: IntentKind.USER_WIDE_REVOCATION;
+} & abi.UserWideRevocationIntent;
+export type DelegatedTransferIntent = {
+    readonly kind: IntentKind.DELEGATED_TRANSFER;
+} & abi.DelegatedTransferIntent;
+export type DelegatedWithdrawalIntent = {
+    readonly kind: IntentKind.DELEGATED_WITHDRAW;
+} & abi.DelegatedWithdrawalIntent;
+export type DelegatedDefiInteractionIntent = {
+    readonly kind: IntentKind.DELEGATED_DEFI_INTERACTION;
+} & abi.DelegatedDefiInteractionIntent;
+/**
+ * A v0.7 UserOperation before the quorum signature is attached. Quorum signing
+ * happens enclave-side over {@link userOpHash}; the SDK only builds and assembles.
+ */
+export type UnsignedUserOperation = Omit<UserOperation<typeof ENTRYPOINT_VERSION>, 'signature'>;
+export type BuildUnsignedUserOpParams = {
+    /** The drafted on-chain struct to settle, tagged by intent kind. */
+    settlementOp: SettlementOp;
+    /** AA account submitting the op — the TeeSmartAccount (sole TEE_ROLE holder). */
+    sender: Address;
+    nonce: bigint;
+    shieldAddress: Address;
+    /** Bundler-estimated limits — everything except the signed fee fields. */
+    gas: abi.Gas;
+};

package/dist/shield/userop/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type-only surface for the UserOp builder. Runtime code lives in `userOp.ts`.
+ */
+export const ENTRYPOINT_VERSION = '0.7';

package/dist/shield/userop/userOp.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Constitution: builds a v0.7 UserOperation from a drafted cheque in three pure
+ * stages — (1) assemble the unsigned op, (2) compute the hash the quorum signs,
+ * (3) attach a signature. Every stage is deterministic: identical inputs produce
+ * identical bytes across all quorum members. That is the property the on-chain
+ * TEE smart account relies on when it verifies that every quorum signature is
+ * over the same userOpHash. Quorum signing itself is enclave-side and
+ * intentionally absent here — the SDK builds and assembles, it does not sign.
+ */
+import { type Address, type Hex } from 'viem';
+import { type UserOperation } from 'viem/account-abstraction';
+import { type BuildUnsignedUserOpParams, ENTRYPOINT_VERSION, type SettlementOp, type UnsignedUserOperation } from './types.js';
+export declare function buildUnsignedUserOp(params: BuildUnsignedUserOpParams): UnsignedUserOperation;
+export declare function userOpHash(unsignedUserOp: UnsignedUserOperation, chainId: number, entryPointAddress?: Address): Hex;
+export declare function assembleUserOp(unsigned: UnsignedUserOperation, signature: Hex): UserOperation<typeof ENTRYPOINT_VERSION>;
+/**
+ * Encode the shield settlement call for a drafted {@link OnchainCheque}: the
+ * `kind` selects the on-chain function and `op` is its sole argument. This is
+ * the inner call wrapped by {@link buildUnsignedUserOp} inside `execute`, and is
+ * exported so the enclave can reuse the canonical encoding when it assembles
+ * the cheque calldata itself.
+ *
+ * TODO(#639): the enclave OnChainOp path ABI-encodes only the struct while this
+ * emits selector + struct. Harmonize so both produce identical calldata.
+ */
+export declare function encodeSettlementOpCall(settlementOp: SettlementOp): Hex;