@inco/shield-js 0.1.0 → 0.2.0

package/dist/shield/convert.d.ts

@@ -1,18 +1,6 @@
 import type { UserOperation } from 'viem/account-abstraction';
 import type { UserOp07 as ProtoUserOp07 } from '../generated/inco/shield/v2/drafting_pb.js';
-import { type GetOwnerGenerationResponse, type GetPermissionDetailsResponse, type GetPermissionsResponse, type PermissionInfo as ProtoPermissionInfo } from '../generated/inco/shield/v2/permission_pb.js';
-import type { GetBalanceResponse } from '../generated/inco/shield/v2/query_pb.js';
-import { Uint256 as ProtoUint256 } from '../generated/inco/shield/v2/types_pb.js';
-import type { Balance, PermissionDetails, PermissionInfo } from './types.js';
+import { type Uint256 as ProtoUint256 } from '../generated/inco/shield/v2/types_pb.js';
 import type { ENTRYPOINT_VERSION } from './userop/types.js';
-export declare function bigintToProtoUint256(value: bigint): ProtoUint256;
-export declare function parseBalance(proto: GetBalanceResponse): Balance;
-export declare function parsePermissionInfo(proto: ProtoPermissionInfo): PermissionInfo;
-export declare function parsePermissions(proto: GetPermissionsResponse): PermissionInfo[];
-export declare function parsePermissionDetails(proto: GetPermissionDetailsResponse): PermissionDetails;
-export declare function parseOwnerGeneration(proto: GetOwnerGenerationResponse): bigint;
-/**
- * Transfer a proto UserOp07 to a viem UserOperation<'0.7'>.
- * This function throws if the proto UserOp07 is malformed.
- */
 export declare function parseUserOp07(proto?: ProtoUserOp07): UserOperation<typeof ENTRYPOINT_VERSION>;
+export declare function bigintToProtoUint256(value: bigint): ProtoUint256;

package/dist/shield/convert.js

@@ -1,120 +1,7 @@
+import { create } from '@bufbuild/protobuf';
 import { bytesToHex } from '../binary.js';
 import { MalformedProto } from '../errors.js';
-import { PermissionStatus as ProtoPermissionStatus, } from '../generated/inco/shield/v2/permission_pb.js';
-import { Uint256 as ProtoUint256 } from '../generated/inco/shield/v2/types_pb.js';
-// ---------------------------------------------------------------------------
-// Utilities
-// ---------------------------------------------------------------------------
-function requireField(value, name) {
-    if (value === undefined || value === null) {
-        throw new MalformedProto({
-            message: `Missing required proto field: ${name}`,
-            field: name,
-        });
-    }
-    return value;
-}
-function requireFixedBytes(bytes, name, expected) {
-    if (!bytes)
-        throw new Error(`Missing required proto field: ${name}`);
-    if (bytes.length !== expected) {
-        throw new Error(`Malformed proto field ${name}: expected ${expected} bytes, got ${bytes.length}`);
-    }
-    return bytes;
-}
-// ---------------------------------------------------------------------------
-// Uint256 codec — 32-byte big-endian unsigned. Wire shape is a `Uint256`
-// message wrapping exactly 32 bytes; matches Solidity's `uint256` ABI
-// encoding.
-// ---------------------------------------------------------------------------
-const UINT256_BYTES = 32;
-const UINT256_MAX = 1n << 256n;
-function bigintToUint256BEBytes(value) {
-    if (value < 0n || value >= UINT256_MAX) {
-        throw new Error(`Value out of uint256 range: ${value}`);
-    }
-    const buf = new Uint8Array(UINT256_BYTES);
-    let remaining = value;
-    for (let i = UINT256_BYTES - 1; i >= 0; i--) {
-        buf[i] = Number(remaining & 0xffn);
-        remaining >>= 8n;
-    }
-    return buf;
-}
-function uint256BEBytesToBigint(bytes) {
-    let result = 0n;
-    for (const byte of bytes) {
-        result = (result << 8n) | BigInt(byte);
-    }
-    return result;
-}
-export function bigintToProtoUint256(value) {
-    return new ProtoUint256({
-        value: new Uint8Array(bigintToUint256BEBytes(value)),
-    });
-}
-function requireUint256(proto, name) {
-    const bytes = requireFixedBytes(proto?.value, name, UINT256_BYTES);
-    return uint256BEBytesToBigint(bytes);
-}
-// ---------------------------------------------------------------------------
-// Parsers (proto → SDK types)
-// ---------------------------------------------------------------------------
-export function parseBalance(proto) {
-    return {
-        confirmed: requireUint256(proto.confirmedBalance, 'GetBalanceResponse.confirmed_balance'),
-        pending: requireUint256(proto.pendingBalance, 'GetBalanceResponse.pending_balance'),
-        available: requireUint256(proto.availableBalance, 'GetBalanceResponse.available_balance'),
-    };
-}
-function parseProtoPermissionStatus(proto) {
-    switch (proto) {
-        case ProtoPermissionStatus.ACTIVE:
-            return 'active';
-        case ProtoPermissionStatus.NOT_YET_ACTIVE:
-            return 'not_yet_active';
-        case ProtoPermissionStatus.EXPIRED:
-            return 'expired';
-        case ProtoPermissionStatus.REVOKED:
-            return 'revoked';
-        case ProtoPermissionStatus.GENERATION_REVOKED:
-            return 'generation_revoked';
-        default:
-            return 'unspecified';
-    }
-}
-export function parsePermissionInfo(proto) {
-    return {
-        permissionId: bytesToHex(requireFixedBytes(proto.permissionId?.value, 'permission.permission_id', 32)),
-        owner: bytesToHex(requireFixedBytes(proto.owner?.value, 'permission.owner', 20)),
-        spender: bytesToHex(requireFixedBytes(proto.spender?.value, 'permission.spender', 20)),
-        assetId: bytesToHex(requireFixedBytes(proto.assetId?.value, 'permission.asset_id', 32)),
-        allowance: requireUint256(proto.allowance, 'permission.allowance'),
-        start: BigInt(proto.start),
-        end: BigInt(proto.end),
-        period: BigInt(proto.period),
-        agreementHash: bytesToHex(requireFixedBytes(proto.agreementHash?.value, 'permission.agreement_hash', 32)),
-        spentInCurrentPeriod: requireUint256(proto.spentInCurrentPeriod, 'permission.spent_in_current_period'),
-        availableAllowance: requireUint256(proto.availableAllowance, 'permission.available_allowance'),
-        status: parseProtoPermissionStatus(proto.status),
-    };
-}
-export function parsePermissions(proto) {
-    return proto.permissions.map(parsePermissionInfo);
-}
-export function parsePermissionDetails(proto) {
-    return {
-        permission: parsePermissionInfo(requireField(proto.permission, 'GetPermissionDetailsResponse.permission')),
-        found: proto.found,
-    };
-}
-export function parseOwnerGeneration(proto) {
-    return BigInt(proto.generation);
-}
-/**
- * Transfer a proto UserOp07 to a viem UserOperation<'0.7'>.
- * This function throws if the proto UserOp07 is malformed.
- */
+import { Uint256Schema as ProtoUint256Desc, } from '../generated/inco/shield/v2/types_pb.js';
 export function parseUserOp07(proto) {
     if (!proto) {
         throw new MalformedProto({
@@ -150,3 +37,40 @@ export function parseUserOp07(proto) {
             : undefined,
     };
 }
+const UINT256_BYTES = 32;
+const UINT256_MAX = 1n << 256n;
+export function bigintToProtoUint256(value) {
+    return create(ProtoUint256Desc, {
+        value: new Uint8Array(bigintToUint256BEBytes(value)),
+    });
+}
+function bigintToUint256BEBytes(value) {
+    if (value < 0n || value >= UINT256_MAX) {
+        throw new Error(`Value out of uint256 range: ${value}`);
+    }
+    const buf = new Uint8Array(UINT256_BYTES);
+    let remaining = value;
+    for (let i = UINT256_BYTES - 1; i >= 0; i--) {
+        buf[i] = Number(remaining & 0xffn);
+        remaining >>= 8n;
+    }
+    return buf;
+}
+function uint256BEBytesToBigint(bytes) {
+    let result = 0n;
+    for (const byte of bytes) {
+        result = (result << 8n) | BigInt(byte);
+    }
+    return result;
+}
+function requireUint256(proto, name) {
+    return uint256BEBytesToBigint(requireFixedBytes(proto?.value, name, UINT256_BYTES));
+}
+function requireFixedBytes(bytes, name, expected) {
+    if (!bytes)
+        throw new Error(`Missing required proto field: ${name}`);
+    if (bytes.length !== expected) {
+        throw new Error(`Malformed proto field ${name}: expected ${expected} bytes, got ${bytes.length}`);
+    }
+    return bytes;
+}

package/dist/shield/encryption.d.ts

@@ -1,86 +1,19 @@
-/**
- * Encryption primitives for the Shield SDK:
- *  - HPKE envelope sealing/opening (X-Wing KEM + ChaCha20Poly1305) for messages to the TEE.
- *  - Standalone symmetric AEAD (AES-GCM-SIV) seal/open for keys negotiated
- *    out-of-band (e.g. `response_key` from authenticated queries) or for
- *    deterministic, quorum-shared encryption derived from a trace hash.
- *
- * HPKE wire format: [encappedKey || ciphertext (ChaCha20Poly1305)]
- */
-/** AEAD key size in bytes, sourced from the cipher suite. */
 export declare const AEAD_KEY_SIZE: number;
-/** AEAD nonce size in bytes, sourced from the cipher suite. */
 export declare const AEAD_NONCE_SIZE: number;
-/** AEAD authentication tag size in bytes (appended to ciphertext). */
 export declare const AEAD_TAG_SIZE: number;
-/**
- * Wire size of an `encryptCheque` blob: `[nonce || aead(plaintext)]`,
- * where `aead` appends an authentication tag.
- */
 export declare function chequeBlobSize(plaintextByteLength: number): number;
-/** Raw byte representation of a keypair for persistence or transport. */
 export interface SerializedKeyPair {
     publicKey: Uint8Array;
     privateKey: Uint8Array;
 }
-/** Generate a fresh X-Wing keypair. */
 export declare function generateKeyPair(): Promise<CryptoKeyPair>;
-/** X-Wing IKM size in bytes — required input length for {@link deriveKeyPair}. */
 export declare const HPKE_IKM_SIZE = 32;
-/**
- * Derive an X-Wing keypair deterministically from a 32-byte IKM. Used by
- * the enclave to derive its long-lived HPKE keypair from
- * `sharedEnclaveSecretSeed` so all quorum members agree on the recipient
- * public key.
- *
- * Throws {@link HpkeKeyPairDerivationFailure} on wrong-length IKM or
- * underlying KEM failure. IKM length is validated up front (matching the
- * length guards in {@link sealAead} / {@link openAead}) so the diagnostic
- * doesn't depend on the upstream library's exception shape.
- */
 export declare function deriveKeyPair(ikm: Uint8Array): Promise<CryptoKeyPair>;
-/** Serialize a {@link CryptoKeyPair} to raw bytes. */
 export declare function serializeKeyPair(kp: CryptoKeyPair): Promise<SerializedKeyPair>;
-/** Deserialize raw bytes back into a {@link CryptoKeyPair}. */
 export declare function deserializeKeyPair(serialized: SerializedKeyPair): Promise<CryptoKeyPair>;
-/** Serialize a public key to raw bytes. */
 export declare function serializePublicKey(key: CryptoKey): Promise<Uint8Array>;
-/** Deserialize a public key from raw bytes. */
 export declare function deserializePublicKey(bytes: Uint8Array): Promise<CryptoKey>;
-/**
- * Encrypt plaintext to the recipient's public key using HPKE.
- *
- * @returns A single buffer in wire format: `[encappedKey || ciphertext]`.
- */
 export declare function sealEnvelope(recipientPublicKey: CryptoKey, plaintext: Uint8Array): Promise<Uint8Array>;
-/**
- * Decrypt an envelope using the recipient's private key.
- *
- * @param envelope - Wire format `[encappedKey || ciphertext]` as returned by {@link sealEnvelope}.
- * @throws If the envelope is too short or decryption fails.
- */
 export declare function openEnvelope(recipientPrivateKey: CryptoKey, envelope: Uint8Array): Promise<Uint8Array>;
-/**
- * Encrypt plaintext with a 32-byte symmetric key using AES-GCM-SIV.
- *
- * The nonce is caller-provided and required. Callers that need
- * deterministic ciphertext (e.g. cheque-internal encryption that must match
- * across TEEs in a quorum) derive the nonce deterministically from the
- * relevant context (trace hash + slot label). Callers that don't (e.g. the
- * TEE→client response path) generate a fresh random nonce.
- *
- * AES-GCM-SIV is misuse-resistant: nonce reuse with the same plaintext
- * leaks plaintext equality but does not catastrophically break the cipher.
- *
- * @param key - 32-byte symmetric key.
- * @param nonce - 12-byte nonce.
- * @param plaintext - Bytes to encrypt.
- * @returns ciphertext (with appended GCM authentication tag).
- */
 export declare function sealAead(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
-/**
- * Decrypt ciphertext with a 32-byte symmetric key using AES-GCM-SIV.
- *
- * @throws If authentication fails or key/nonce sizes are wrong.
- */
 export declare function openAead(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;

package/dist/shield/encryption.js

@@ -1,12 +1,3 @@
-/**
- * Encryption primitives for the Shield SDK:
- *  - HPKE envelope sealing/opening (X-Wing KEM + ChaCha20Poly1305) for messages to the TEE.
- *  - Standalone symmetric AEAD (AES-GCM-SIV) seal/open for keys negotiated
- *    out-of-band (e.g. `response_key` from authenticated queries) or for
- *    deterministic, quorum-shared encryption derived from a trace hash.
- *
- * HPKE wire format: [encappedKey || ciphertext (ChaCha20Poly1305)]
- */
 import { Chacha20Poly1305 } from '@hpke/chacha20poly1305';
 import { CipherSuite, HkdfSha256 } from '@hpke/core';
 import { XWing } from '@hpke/hybridkem-x-wing';
@@ -19,38 +10,17 @@ const suite = new CipherSuite({
     kdf: new HkdfSha256(),
     aead: chachaPoly,
 });
-/** X-Wing KEM encapsulated key size in bytes. */
 const ENCAPPED_KEY_SIZE = kem.encSize;
-/** AEAD key size in bytes, sourced from the cipher suite. */
 export const AEAD_KEY_SIZE = chachaPoly.keySize;
-/** AEAD nonce size in bytes, sourced from the cipher suite. */
 export const AEAD_NONCE_SIZE = chachaPoly.nonceSize;
-/** AEAD authentication tag size in bytes (appended to ciphertext). */
 export const AEAD_TAG_SIZE = chachaPoly.tagSize;
-/**
- * Wire size of an `encryptCheque` blob: `[nonce || aead(plaintext)]`,
- * where `aead` appends an authentication tag.
- */
 export function chequeBlobSize(plaintextByteLength) {
     return AEAD_NONCE_SIZE + plaintextByteLength + AEAD_TAG_SIZE;
 }
-/** Generate a fresh X-Wing keypair. */
 export async function generateKeyPair() {
     return suite.kem.generateKeyPair();
 }
-/** X-Wing IKM size in bytes — required input length for {@link deriveKeyPair}. */
 export const HPKE_IKM_SIZE = 32;
-/**
- * Derive an X-Wing keypair deterministically from a 32-byte IKM. Used by
- * the enclave to derive its long-lived HPKE keypair from
- * `sharedEnclaveSecretSeed` so all quorum members agree on the recipient
- * public key.
- *
- * Throws {@link HpkeKeyPairDerivationFailure} on wrong-length IKM or
- * underlying KEM failure. IKM length is validated up front (matching the
- * length guards in {@link sealAead} / {@link openAead}) so the diagnostic
- * doesn't depend on the upstream library's exception shape.
- */
 export async function deriveKeyPair(ikm) {
     if (ikm.byteLength !== HPKE_IKM_SIZE) {
         throw new HpkeKeyPairDerivationFailure({
@@ -66,7 +36,6 @@ export async function deriveKeyPair(ikm) {
         });
     }
 }
-/** Serialize a {@link CryptoKeyPair} to raw bytes. */
 export async function serializeKeyPair(kp) {
     const [pub, priv] = await Promise.all([
         suite.kem.serializePublicKey(kp.publicKey),
@@ -77,7 +46,6 @@ export async function serializeKeyPair(kp) {
         privateKey: new Uint8Array(priv),
     };
 }
-/** Deserialize raw bytes back into a {@link CryptoKeyPair}. */
 export async function deserializeKeyPair(serialized) {
     const [publicKey, privateKey] = await Promise.all([
         suite.kem.deserializePublicKey(serialized.publicKey),
@@ -85,19 +53,12 @@ export async function deserializeKeyPair(serialized) {
     ]);
     return { publicKey, privateKey };
 }
-/** Serialize a public key to raw bytes. */
 export async function serializePublicKey(key) {
     return new Uint8Array(await suite.kem.serializePublicKey(key));
 }
-/** Deserialize a public key from raw bytes. */
 export async function deserializePublicKey(bytes) {
     return suite.kem.deserializePublicKey(bytes);
 }
-/**
- * Encrypt plaintext to the recipient's public key using HPKE.
- *
- * @returns A single buffer in wire format: `[encappedKey || ciphertext]`.
- */
 export async function sealEnvelope(recipientPublicKey, plaintext) {
     const sender = await suite.createSenderContext({ recipientPublicKey });
     const ciphertext = await sender.seal(plaintext);
@@ -107,12 +68,6 @@ export async function sealEnvelope(recipientPublicKey, plaintext) {
     result.set(ct, sender.enc.byteLength);
     return result;
 }
-/**
- * Decrypt an envelope using the recipient's private key.
- *
- * @param envelope - Wire format `[encappedKey || ciphertext]` as returned by {@link sealEnvelope}.
- * @throws If the envelope is too short or decryption fails.
- */
 export async function openEnvelope(recipientPrivateKey, envelope) {
     if (envelope.byteLength <= ENCAPPED_KEY_SIZE) {
         throw new EncryptionError({
@@ -128,23 +83,6 @@ export async function openEnvelope(recipientPrivateKey, envelope) {
     const plaintext = await recipient.open(ciphertext);
     return new Uint8Array(plaintext);
 }
-/**
- * Encrypt plaintext with a 32-byte symmetric key using AES-GCM-SIV.
- *
- * The nonce is caller-provided and required. Callers that need
- * deterministic ciphertext (e.g. cheque-internal encryption that must match
- * across TEEs in a quorum) derive the nonce deterministically from the
- * relevant context (trace hash + slot label). Callers that don't (e.g. the
- * TEE→client response path) generate a fresh random nonce.
- *
- * AES-GCM-SIV is misuse-resistant: nonce reuse with the same plaintext
- * leaks plaintext equality but does not catastrophically break the cipher.
- *
- * @param key - 32-byte symmetric key.
- * @param nonce - 12-byte nonce.
- * @param plaintext - Bytes to encrypt.
- * @returns ciphertext (with appended GCM authentication tag).
- */
 export async function sealAead(key, nonce, plaintext) {
     if (key.byteLength !== AEAD_KEY_SIZE) {
         throw new EncryptionError({
@@ -159,11 +97,6 @@ export async function sealAead(key, nonce, plaintext) {
     const cipher = gcmsiv(key, nonce);
     return cipher.encrypt(plaintext);
 }
-/**
- * Decrypt ciphertext with a 32-byte symmetric key using AES-GCM-SIV.
- *
- * @throws If authentication fails or key/nonce sizes are wrong.
- */
 export async function openAead(key, nonce, ciphertext) {
     if (key.byteLength !== AEAD_KEY_SIZE) {
         throw new EncryptionError({

package/dist/shield/envelope.d.ts

@@ -1,14 +1,13 @@
 import { type Hex } from 'viem';
-import { EncryptedEnvelope, type EncryptedResponse } from '../generated/inco/shield/v2/types_pb.js';
-/** HPKE-encrypt a serialized Authenticated* proto into an EncryptedEnvelope. */
-export declare function makeEnvelope(teePublicKey: CryptoKey, inner: {
-    toBinary(): Uint8Array<ArrayBufferLike>;
-}): Promise<EncryptedEnvelope>;
-/** Generate a random 32-byte AEAD response key. */
+import { type EncryptedResponse } from '../generated/inco/shield/v2/types_pb.js';
+export type RequestAuthInput = {
+    eip712Signature?: Uint8Array;
+    responseKey: Uint8Array;
+};
+export declare function makeEnvelope(teePublicKey: CryptoKey, auth: RequestAuthInput, body: Uint8Array): Promise<import("../generated/inco/shield/v2/types_pb.js").EncryptedEnvelope>;
 export declare function generateResponseKey(): Uint8Array<ArrayBuffer>;
-/** Generate a fresh 32-byte replay-protection salt using the platform CSPRNG. */
 export declare function generateRandomSalt(): Hex;
-/** AEAD-decrypt an EncryptedResponse using the response key, then decode as a typed proto. */
-export declare function decryptResponse<T>(resp: EncryptedResponse, responseKey: Uint8Array, Type: {
-    fromBinary(bytes: Uint8Array): T;
-}): Promise<T>;
+export declare function openSignedResponse(resp: EncryptedResponse, responseKey: Uint8Array): Promise<{
+    body: Uint8Array;
+    teeSignature: Uint8Array;
+}>;

package/dist/shield/envelope.js

@@ -1,29 +1,30 @@
+import { create, fromBinary, toBinary } from '@bufbuild/protobuf';
 import { toHex } from 'viem';
-import { EncryptedEnvelope, } from '../generated/inco/shield/v2/types_pb.js';
+import { EncryptedEnvelopeSchema, RequestAuthSchema, SignedRequestSchema, SignedResponseSchema, } from '../generated/inco/shield/v2/types_pb.js';
 import { AEAD_KEY_SIZE, openAead, sealEnvelope } from './encryption.js';
-// ---------------------------------------------------------------------------
-// Envelope helpers
-// ---------------------------------------------------------------------------
-/** HPKE-encrypt a serialized Authenticated* proto into an EncryptedEnvelope. */
-export async function makeEnvelope(teePublicKey, inner) {
-    const bytes = inner.toBinary();
-    const sealed = await sealEnvelope(teePublicKey, bytes);
-    return new EncryptedEnvelope({ payload: new Uint8Array(sealed) });
+export async function makeEnvelope(teePublicKey, auth, body) {
+    const signedRequest = create(SignedRequestSchema, {
+        auth: create(RequestAuthSchema, {
+            eip712Signature: auth.eip712Signature,
+            responseKey: auth.responseKey,
+        }),
+        body,
+    });
+    const sealed = await sealEnvelope(teePublicKey, toBinary(SignedRequestSchema, signedRequest));
+    return create(EncryptedEnvelopeSchema, { payload: new Uint8Array(sealed) });
 }
-/** Generate a random 32-byte AEAD response key. */
 export function generateResponseKey() {
     const key = new Uint8Array(AEAD_KEY_SIZE);
     crypto.getRandomValues(key);
     return key;
 }
-/** Generate a fresh 32-byte replay-protection salt using the platform CSPRNG. */
 export function generateRandomSalt() {
     const bytes = new Uint8Array(32);
     crypto.getRandomValues(bytes);
     return toHex(bytes);
 }
-/** AEAD-decrypt an EncryptedResponse using the response key, then decode as a typed proto. */
-export async function decryptResponse(resp, responseKey, Type) {
+export async function openSignedResponse(resp, responseKey) {
     const plaintext = await openAead(responseKey, resp.nonce, resp.ciphertext);
-    return Type.fromBinary(plaintext);
+    const signed = fromBinary(SignedResponseSchema, plaintext);
+    return { body: signed.body, teeSignature: signed.teeSignature };
 }

package/dist/shield/fee.d.ts

@@ -0,0 +1,24 @@
+import { type Hex } from 'viem';
+import type { AssetMovement, WithdrawalIntentOp } from './shield.eip712.gen.js';
+export declare const WITHDRAW_FEE_BPS = 25n;
+export declare function protocolFee(amount: bigint): bigint;
+export type FeeContext = {
+    readonly adapter: Hex;
+    readonly treasury: Hex;
+};
+export type DeliveryQuote = {
+    readonly feeBps: bigint;
+    readonly fee: bigint;
+    readonly debit: bigint;
+};
+export declare function quoteByDelivery(delivered: bigint): DeliveryQuote;
+export type DebitQuote = {
+    readonly feeBps: bigint;
+    readonly fee: bigint;
+    readonly delivered: bigint;
+};
+export declare function quoteByDebit(debit: bigint): DebitQuote;
+export declare function encodeMovementAmount(amount: bigint): Hex;
+export declare function decodeMovementAmount(movementArgs: Hex): bigint;
+export declare function checkProtocolFeeSplit(movements: readonly AssetMovement[], feeContext: FeeContext): string | null;
+export declare function withProtocolFeeLeg(intentOp: WithdrawalIntentOp, feeContext: FeeContext): WithdrawalIntentOp;

package/dist/shield/fee.js

@@ -0,0 +1,151 @@
+import { decodeAbiParameters, encodeAbiParameters } from 'viem';
+import { InvalidWithdrawalIntentOp } from '../errors.js';
+export const WITHDRAW_FEE_BPS = 25n;
+const BPS_DENOMINATOR = 10000n;
+export function protocolFee(amount) {
+    return (amount * WITHDRAW_FEE_BPS) / BPS_DENOMINATOR;
+}
+export function quoteByDelivery(delivered) {
+    const fee = protocolFee(delivered);
+    return { feeBps: WITHDRAW_FEE_BPS, fee, debit: delivered + fee };
+}
+export function quoteByDebit(debit) {
+    const delivered = (BPS_DENOMINATOR * (debit + 1n) - 1n) /
+        (BPS_DENOMINATOR + WITHDRAW_FEE_BPS);
+    return { feeBps: WITHDRAW_FEE_BPS, fee: protocolFee(delivered), delivered };
+}
+const MOVEMENT_AMOUNT_ABI = [{ type: 'uint256' }];
+export function encodeMovementAmount(amount) {
+    return encodeAbiParameters(MOVEMENT_AMOUNT_ABI, [amount]);
+}
+export function decodeMovementAmount(movementArgs) {
+    return decodeAbiParameters(MOVEMENT_AMOUNT_ABI, movementArgs)[0];
+}
+export function checkProtocolFeeSplit(movements, feeContext) {
+    const violation = checkOnTopProtocolFeeSplit(movements, feeContext);
+    return violation !== null &&
+        matchesLegacyProtocolFeeSplit(movements, feeContext)
+        ? null
+        : violation;
+}
+export function withProtocolFeeLeg(intentOp, feeContext) {
+    const recipients = intentOp.core.assetMovements;
+    if (recipients.length === 0) {
+        throw new InvalidWithdrawalIntentOp({
+            message: 'withdrawal intent op must carry at least one recipient movement',
+        });
+    }
+    let recipientTotal = 0n;
+    for (const recipient of recipients) {
+        if (addressEq(recipient.account, feeContext.treasury) ||
+            addressEq(recipient.assetAdapter, feeContext.adapter)) {
+            throw new InvalidWithdrawalIntentOp({
+                message: 'recipient movement must not target the protocol treasury or route through the fee adapter',
+            });
+        }
+        const amount = tryDecodeAmount(recipient.movementArgs);
+        if (amount === null) {
+            throw new InvalidWithdrawalIntentOp({
+                message: `recipient movementArgs must be abi.encode(uint256): ${recipient.movementArgs}`,
+            });
+        }
+        recipientTotal += amount;
+    }
+    const fee = protocolFee(recipientTotal);
+    if (fee === 0n) {
+        return intentOp;
+    }
+    const feeLeg = {
+        account: feeContext.treasury,
+        assetAdapter: feeContext.adapter,
+        movementArgs: encodeMovementAmount(fee),
+    };
+    return {
+        ...intentOp,
+        core: {
+            ...intentOp.core,
+            assetMovements: [...recipients, feeLeg],
+        },
+    };
+}
+function checkOnTopProtocolFeeSplit(movements, feeContext) {
+    if (movements.length === 0) {
+        return 'withdrawal must carry at least one movement';
+    }
+    const feeLegs = movements.filter((m) => addressEq(m.account, feeContext.treasury));
+    const recipients = movements.filter((m) => !addressEq(m.account, feeContext.treasury));
+    if (recipients.length === 0) {
+        return 'withdrawal must carry at least one recipient movement';
+    }
+    let recipientTotal = 0n;
+    for (const recipient of recipients) {
+        if (addressEq(recipient.assetAdapter, feeContext.adapter)) {
+            return 'recipient movement must not route through the fee-accrual adapter';
+        }
+        const amount = tryDecodeAmount(recipient.movementArgs);
+        if (amount === null) {
+            return `recipient movementArgs must be abi.encode(uint256): ${recipient.movementArgs}`;
+        }
+        recipientTotal += amount;
+    }
+    const expected = protocolFee(recipientTotal);
+    if (feeLegs.length === 0) {
+        return expected === 0n
+            ? null
+            : 'fee-bearing withdrawal must carry exactly one fee leg, got 0';
+    }
+    if (feeLegs.length !== 1) {
+        return `fee-bearing withdrawal must carry exactly one fee leg, got ${feeLegs.length}`;
+    }
+    const feeLeg = feeLegs[0];
+    if (movements.at(-1) !== feeLeg) {
+        return 'protocol fee leg must be the final movement';
+    }
+    if (!addressEq(feeLeg.assetAdapter, feeContext.adapter)) {
+        return `fee leg must route through the canonical fee-accrual adapter ${feeContext.adapter}, got ${feeLeg.assetAdapter}`;
+    }
+    const feeAmount = tryDecodeAmount(feeLeg.movementArgs);
+    if (feeAmount === null) {
+        return `fee leg movementArgs must be abi.encode(uint256): ${feeLeg.movementArgs}`;
+    }
+    return feeAmount === expected && expected > 0n
+        ? null
+        : expected === 0n
+            ? 'dust withdrawal must not carry a fee leg'
+            : `fee leg carries ${feeAmount}, expected ${expected} for delivered ${recipientTotal}`;
+}
+function matchesLegacyProtocolFeeSplit(movements, feeContext) {
+    let gross = 0n;
+    for (const movement of movements) {
+        const amount = tryDecodeAmount(movement.movementArgs);
+        if (amount === null) {
+            return false;
+        }
+        gross += amount;
+    }
+    const expected = protocolFee(gross);
+    if (expected === 0n) {
+        return movements.length === 1;
+    }
+    if (movements.length !== 2) {
+        return false;
+    }
+    const [recipient, feeLeg] = movements;
+    if (addressEq(recipient.assetAdapter, feeContext.adapter) ||
+        !addressEq(feeLeg.assetAdapter, feeContext.adapter) ||
+        !addressEq(feeLeg.account, feeContext.treasury)) {
+        return false;
+    }
+    return tryDecodeAmount(feeLeg.movementArgs) === expected;
+}
+function addressEq(a, b) {
+    return a.toLowerCase() === b.toLowerCase();
+}
+function tryDecodeAmount(movementArgs) {
+    try {
+        return decodeMovementAmount(movementArgs);
+    }
+    catch {
+        return null;
+    }
+}