@openzeppelin/guardian-evm-client 0.14.5

package/dist/proposals.js

@@ -0,0 +1,111 @@
+import { normalizeBytes32, normalizeEvmAddress, normalizeSignature, normalizeUint256String, } from './encoding.js';
+export function evmAccountId(chainId, smartAccountAddress) {
+    assertSafeChainId(chainId);
+    return `evm:${chainId}:${normalizeEvmAddress(smartAccountAddress)}`;
+}
+export function toServerRegisterAccountRequest(request) {
+    assertSafeChainId(request.chainId);
+    return {
+        chain_id: request.chainId,
+        account_address: normalizeEvmAddress(request.smartAccountAddress),
+        multisig_validator_address: normalizeEvmAddress(request.multisigValidatorAddress),
+    };
+}
+export function fromServerAccountRegistration(server) {
+    return {
+        accountId: stringField(server.account_id, 'account_id'),
+        chainId: numberField(server.chain_id, 'chain_id'),
+        accountAddress: normalizeEvmAddress(server.account_address),
+        multisigValidatorAddress: normalizeEvmAddress(server.multisig_validator_address),
+        signers: arrayField(server.signers, 'signers').map(normalizeEvmAddress),
+        threshold: numberField(server.threshold, 'threshold'),
+    };
+}
+export function toServerCreateProposalRequest(request) {
+    assertSafeChainId(request.chainId);
+    assertPositiveSeconds(request.ttlSeconds, 'ttlSeconds');
+    const accountId = request.accountId ?? evmAccountId(request.chainId, request.smartAccountAddress);
+    return {
+        account_id: accountId,
+        user_op_hash: normalizeBytes32(request.userOpHash, 'userOpHash'),
+        payload: request.payload,
+        nonce: normalizeUint256String(request.nonce),
+        ttl_seconds: request.ttlSeconds,
+        signature: normalizeSignature(request.signature),
+    };
+}
+export function toServerApproveRequest(accountId, request) {
+    return {
+        account_id: accountId,
+        signature: normalizeSignature(request.signature),
+    };
+}
+export function toServerCancelRequest(accountId) {
+    return { account_id: accountId };
+}
+export function fromServerProposal(server) {
+    return {
+        proposalId: normalizeBytes32(server.proposal_id, 'proposal_id'),
+        accountId: stringField(server.account_id, 'account_id'),
+        chainId: numberField(server.chain_id, 'chain_id'),
+        smartAccountAddress: normalizeEvmAddress(server.smart_account_address),
+        validatorAddress: normalizeEvmAddress(server.validator_address),
+        userOpHash: normalizeBytes32(server.user_op_hash, 'user_op_hash'),
+        payload: stringField(server.payload, 'payload'),
+        nonce: stringField(server.nonce, 'nonce'),
+        nonceKey: stringField(server.nonce_key, 'nonce_key'),
+        proposer: normalizeEvmAddress(server.proposer),
+        signerSnapshot: arrayField(server.signer_snapshot, 'signer_snapshot').map(normalizeEvmAddress),
+        threshold: numberField(server.threshold, 'threshold'),
+        signatures: arrayField(server.signatures, 'signatures').map(fromServerSignature),
+        createdAt: numberField(server.created_at, 'created_at'),
+        expiresAt: numberField(server.expires_at, 'expires_at'),
+    };
+}
+export function fromServerExecutable(server) {
+    return {
+        hash: normalizeBytes32(server.hash, 'hash'),
+        payload: stringField(server.payload, 'payload'),
+        signatures: arrayField(server.signatures, 'signatures').map(normalizeSignature),
+        signers: arrayField(server.signers, 'signers').map(normalizeEvmAddress),
+    };
+}
+export function accountProposalParams(accountId) {
+    return new URLSearchParams({ account_id: accountId });
+}
+function fromServerSignature(server) {
+    return {
+        signer: normalizeEvmAddress(server.signer),
+        signature: normalizeSignature(server.signature),
+        signedAt: numberField(server.signed_at, 'signed_at'),
+    };
+}
+function assertSafeChainId(chainId) {
+    if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+        throw new Error('chainId must be a positive safe integer');
+    }
+}
+function assertPositiveSeconds(value, field) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${field} must be a positive safe integer`);
+    }
+}
+function stringField(value, field) {
+    if (typeof value !== 'string') {
+        throw new Error(`${field} must be a string`);
+    }
+    return value;
+}
+function numberField(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+        throw new Error(`${field} must be a safe integer`);
+    }
+    return value;
+}
+function arrayField(value, field) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${field} must be an array`);
+    }
+    return value;
+}
+//# sourceMappingURL=proposals.js.map

package/dist/proposals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposals.js","sourceRoot":"","sources":["../src/proposals.ts"],"names":[],"mappings":"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"}

package/dist/typed-data.d.ts

@@ -0,0 +1,45 @@
+import type { Hex } from 'viem';
+export type TypedDataField = {
+    name: string;
+    type: string;
+};
+export type GuardianTypedData = {
+    domain: {
+        name: string;
+        version: string;
+    };
+    types: {
+        EIP712Domain: TypedDataField[];
+        GuardianEvmSession: TypedDataField[];
+    };
+    primaryType: 'GuardianEvmSession';
+    message: {
+        wallet: `0x${string}`;
+        nonce: Hex;
+        issued_at: number;
+        expires_at: number;
+    };
+};
+export interface EvmSessionChallenge {
+    address: `0x${string}`;
+    nonce: Hex;
+    issuedAt: number;
+    expiresAt: number;
+    typedData: GuardianTypedData;
+}
+export declare function buildEvmSessionTypedData(input: {
+    address: string;
+    nonce: string;
+    issuedAt: number;
+    expiresAt: number;
+}): GuardianTypedData;
+export declare function fromServerChallenge(server: ServerChallengeResponse): EvmSessionChallenge;
+interface ServerChallengeResponse {
+    address: string;
+    nonce: string;
+    issued_at: number;
+    expires_at: number;
+    typed_data?: unknown;
+}
+export {};
+//# sourceMappingURL=typed-data.d.ts.map

package/dist/typed-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-data.d.ts","sourceRoot":"","sources":["../src/typed-data.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAGhC,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,KAAK,EAAE;QACL,YAAY,EAAE,cAAc,EAAE,CAAC;QAC/B,kBAAkB,EAAE,cAAc,EAAE,CAAC;KACtC,CAAC;IACF,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,EAAE;QACP,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;QACtB,KAAK,EAAE,GAAG,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,GAAG,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,iBAAiB,CA0BpB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,uBAAuB,GAAG,mBAAmB,CAWxF;AAED,UAAU,uBAAuB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/dist/typed-data.js

@@ -0,0 +1,60 @@
+import { normalizeBytes32, normalizeEvmAddress } from './encoding.js';
+export function buildEvmSessionTypedData(input) {
+    return {
+        domain: {
+            name: 'Guardian EVM Session',
+            version: '1',
+        },
+        types: {
+            EIP712Domain: [
+                { name: 'name', type: 'string' },
+                { name: 'version', type: 'string' },
+            ],
+            GuardianEvmSession: [
+                { name: 'wallet', type: 'address' },
+                { name: 'nonce', type: 'bytes32' },
+                { name: 'issued_at', type: 'uint64' },
+                { name: 'expires_at', type: 'uint64' },
+            ],
+        },
+        primaryType: 'GuardianEvmSession',
+        message: {
+            wallet: normalizeEvmAddress(input.address),
+            nonce: normalizeBytes32(input.nonce, 'nonce'),
+            issued_at: input.issuedAt,
+            expires_at: input.expiresAt,
+        },
+    };
+}
+export function fromServerChallenge(server) {
+    const issuedAt = numberField(server.issued_at, 'issued_at');
+    const expiresAt = numberField(server.expires_at, 'expires_at');
+    const typedData = parseTypedData(server.typed_data, server.address, server.nonce, issuedAt, expiresAt);
+    return {
+        address: normalizeEvmAddress(server.address),
+        nonce: normalizeBytes32(server.nonce, 'nonce'),
+        issuedAt,
+        expiresAt,
+        typedData,
+    };
+}
+function parseTypedData(value, address, nonce, issuedAt, expiresAt) {
+    if (!isRecord(value)) {
+        return buildEvmSessionTypedData({ address, nonce, issuedAt, expiresAt });
+    }
+    const primaryType = value.primaryType;
+    if (primaryType !== 'GuardianEvmSession') {
+        return buildEvmSessionTypedData({ address, nonce, issuedAt, expiresAt });
+    }
+    return buildEvmSessionTypedData({ address, nonce, issuedAt, expiresAt });
+}
+function numberField(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+        throw new Error(`${field} must be a safe integer`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//# sourceMappingURL=typed-data.js.map

package/dist/typed-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-data.js","sourceRoot":"","sources":["../src/typed-data.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AA8BtE,MAAM,UAAU,wBAAwB,CAAC,KAKxC;IACC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,GAAG;SACb;QACD,KAAK,EAAE;YACL,YAAY,EAAE;gBACZ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAChC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE;aACpC;YACD,kBAAkB,EAAE;gBAClB,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;gBACnC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;gBAClC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACrC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE;aACvC;SACF;QACD,WAAW,EAAE,oBAAoB;QACjC,OAAO,EAAE;YACP,MAAM,EAAE,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAC;YAC1C,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC;YAC7C,SAAS,EAAE,KAAK,CAAC,QAAQ;YACzB,UAAU,EAAE,KAAK,CAAC,SAAS;SAC5B;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAA+B;IACjE,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvG,OAAO;QACL,OAAO,EAAE,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC;QAC5C,KAAK,EAAE,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;QAC9C,QAAQ;QACR,SAAS;QACT,SAAS;KACV,CAAC;AACJ,CAAC;AAUD,SAAS,cAAc,CACrB,KAAc,EACd,OAAe,EACf,KAAa,EACb,QAAgB,EAChB,SAAiB;IAEjB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,wBAAwB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IACtC,IAAI,WAAW,KAAK,oBAAoB,EAAE,CAAC;QACzC,OAAO,wBAAwB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,wBAAwB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,KAAa;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,yBAAyB,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@openzeppelin/guardian-evm-client",
+  "version": "0.14.5",
+  "description": "TypeScript EVM client for Guardian server proposal workflows",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "viem": "^2.47.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/auth.ts

@@ -0,0 +1,47 @@
+import type { GuardianTypedData } from './typed-data.js';
+import { normalizeBytes32, normalizeEvmAddress, normalizeSignature } from './encoding.js';
+
+export interface Eip1193Provider {
+  request(args: { method: string; params?: unknown[] }): Promise<unknown>;
+}
+
+export async function requestWalletAddress(provider: Eip1193Provider): Promise<`0x${string}`> {
+  const accounts = await provider.request({ method: 'eth_requestAccounts' });
+  if (!Array.isArray(accounts) || typeof accounts[0] !== 'string') {
+    throw new Error('Wallet did not return an account');
+  }
+  return normalizeEvmAddress(accounts[0]);
+}
+
+export async function signTypedData(
+  provider: Eip1193Provider,
+  signerAddress: string,
+  typedData: GuardianTypedData
+): Promise<`0x${string}`> {
+  const signer = normalizeEvmAddress(signerAddress);
+  const signature = await provider.request({
+    method: 'eth_signTypedData_v4',
+    params: [signer, JSON.stringify(typedData)],
+  });
+  if (typeof signature !== 'string') {
+    throw new Error('Wallet returned a non-string EIP-712 signature');
+  }
+  return normalizeSignature(signature);
+}
+
+export async function signProposalHash(
+  provider: Eip1193Provider,
+  signerAddress: string,
+  hash: string
+): Promise<`0x${string}`> {
+  const signer = normalizeEvmAddress(signerAddress);
+  const normalizedHash = normalizeBytes32(hash, 'hash');
+  const signature = await provider.request({
+    method: 'eth_sign',
+    params: [signer, normalizedHash],
+  });
+  if (typeof signature !== 'string') {
+    throw new Error('Wallet returned a non-string hash signature');
+  }
+  return normalizeSignature(signature);
+}

package/src/client.ts

@@ -0,0 +1,190 @@
+import { requestWalletAddress, signTypedData, type Eip1193Provider } from './auth.js';
+import { normalizeEvmAddress } from './encoding.js';
+import { GuardianEvmHttpError } from './errors.js';
+import {
+  fromServerAccountRegistration,
+  accountProposalParams,
+  evmAccountId,
+  fromServerExecutable,
+  fromServerProposal,
+  toServerApproveRequest,
+  toServerCancelRequest,
+  toServerCreateProposalRequest,
+  toServerRegisterAccountRequest,
+  type AccountRegistration,
+  type ApproveRequest,
+  type ConfigureRequest,
+  type ExecutableProposal,
+  type Proposal,
+  type ProposeRequest,
+  type ServerExecutableProposal,
+  type ServerListProposalsResponse,
+  type ServerProposal,
+  type ServerRegisterAccountResponse,
+} from './proposals.js';
+import { fromServerChallenge, type EvmSessionChallenge } from './typed-data.js';
+
+export interface GuardianEvmClientOptions {
+  guardianUrl: string;
+  provider?: Eip1193Provider;
+  signerAddress?: string;
+}
+
+export interface EvmSession {
+  address: `0x${string}`;
+  expiresAt: number;
+}
+
+interface ServerVerifyResponse {
+  address: string;
+  expires_at: number;
+}
+
+export class GuardianEvmClient {
+  readonly guardianUrl: string;
+  readonly provider?: Eip1193Provider;
+  readonly signerAddress?: `0x${string}`;
+  private cookieHeader?: string;
+
+  constructor(options: GuardianEvmClientOptions) {
+    this.guardianUrl = options.guardianUrl.replace(/\/$/, '');
+    this.provider = options.provider;
+    this.signerAddress = options.signerAddress
+      ? normalizeEvmAddress(options.signerAddress)
+      : undefined;
+  }
+
+  accountId(chainId: number, smartAccountAddress: string): string {
+    return evmAccountId(chainId, smartAccountAddress);
+  }
+
+  async challenge(address?: string): Promise<EvmSessionChallenge> {
+    const signer = await this.resolveSigner(address);
+    const params = new URLSearchParams({ address: signer });
+    const response = await this.fetch(`/evm/auth/challenge?${params}`, { method: 'GET' });
+    return fromServerChallenge(await response.json());
+  }
+
+  async login(address?: string): Promise<EvmSession> {
+    const challenge = await this.challenge(address);
+    const provider = this.requireProvider();
+    const signature = await signTypedData(provider, challenge.address, challenge.typedData);
+    const response = await this.fetch('/evm/auth/verify', {
+      method: 'POST',
+      body: JSON.stringify({
+        address: challenge.address,
+        nonce: challenge.nonce,
+        signature,
+      }),
+    });
+    const server = (await response.json()) as ServerVerifyResponse;
+    return {
+      address: normalizeEvmAddress(server.address),
+      expiresAt: server.expires_at,
+    };
+  }
+
+  async logout(): Promise<void> {
+    await this.fetch('/evm/auth/logout', { method: 'POST' });
+  }
+
+  async configure(request: ConfigureRequest): Promise<AccountRegistration> {
+    const response = await this.fetch('/evm/accounts', {
+      method: 'POST',
+      body: JSON.stringify(toServerRegisterAccountRequest(request)),
+    });
+    return fromServerAccountRegistration((await response.json()) as ServerRegisterAccountResponse);
+  }
+
+  async createProposal(request: ProposeRequest): Promise<Proposal> {
+    const response = await this.fetch('/evm/proposals', {
+      method: 'POST',
+      body: JSON.stringify(toServerCreateProposalRequest(request)),
+    });
+    return fromServerProposal((await response.json()) as ServerProposal);
+  }
+
+  async listProposals(accountId: string): Promise<Proposal[]> {
+    const params = accountProposalParams(accountId);
+    const response = await this.fetch(`/evm/proposals?${params}`, { method: 'GET' });
+    const server = (await response.json()) as ServerListProposalsResponse;
+    return server.proposals.map(fromServerProposal);
+  }
+
+  async getProposal(accountId: string, proposalId: string): Promise<Proposal> {
+    const params = accountProposalParams(accountId);
+    const response = await this.fetch(`/evm/proposals/${proposalId}?${params}`, { method: 'GET' });
+    return fromServerProposal((await response.json()) as ServerProposal);
+  }
+
+  async approveProposal(
+    accountId: string,
+    proposalId: string,
+    request: ApproveRequest
+  ): Promise<Proposal> {
+    const response = await this.fetch(`/evm/proposals/${proposalId}/approve`, {
+      method: 'POST',
+      body: JSON.stringify(toServerApproveRequest(accountId, request)),
+    });
+    return fromServerProposal((await response.json()) as ServerProposal);
+  }
+
+  async getExecutableProposal(
+    accountId: string,
+    proposalId: string
+  ): Promise<ExecutableProposal> {
+    const params = accountProposalParams(accountId);
+    const response = await this.fetch(`/evm/proposals/${proposalId}/executable?${params}`, {
+      method: 'GET',
+    });
+    return fromServerExecutable((await response.json()) as ServerExecutableProposal);
+  }
+
+  async cancelProposal(accountId: string, proposalId: string): Promise<void> {
+    await this.fetch(`/evm/proposals/${proposalId}/cancel`, {
+      method: 'POST',
+      body: JSON.stringify(toServerCancelRequest(accountId)),
+    });
+  }
+
+  private async resolveSigner(address?: string): Promise<`0x${string}`> {
+    if (address) {
+      return normalizeEvmAddress(address);
+    }
+    if (this.signerAddress) {
+      return this.signerAddress;
+    }
+    return requestWalletAddress(this.requireProvider());
+  }
+
+  private requireProvider(): Eip1193Provider {
+    if (!this.provider) {
+      throw new Error('GuardianEvmClient requires a provider for wallet signing');
+    }
+    return this.provider;
+  }
+
+  private async fetch(path: string, init: RequestInit): Promise<Response> {
+    const response = await fetch(`${this.guardianUrl}${path}`, {
+      ...init,
+      credentials: 'include',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.cookieHeader ? { Cookie: this.cookieHeader } : {}),
+        ...init.headers,
+      },
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new GuardianEvmHttpError(response.status, response.statusText, body);
+    }
+
+    const setCookie = response.headers.get('set-cookie');
+    if (setCookie) {
+      this.cookieHeader = setCookie.split(';')[0];
+    }
+
+    return response;
+  }
+}

package/src/encoding.ts

@@ -0,0 +1,33 @@
+import { getAddress, isHex, type Hex } from 'viem';
+
+export function normalizeEvmAddress(address: string): `0x${string}` {
+  return getAddress(address).toLowerCase() as `0x${string}`;
+}
+
+export function normalizeBytes32(value: string, field: string): Hex {
+  if (!isHex(value) || value.length !== 66) {
+    throw new Error(`${field} must be a 32-byte 0x-prefixed hex string`);
+  }
+  return value.toLowerCase() as Hex;
+}
+
+export function normalizeSignature(value: string): Hex {
+  if (!isHex(value) || value.length !== 132) {
+    throw new Error('signature must be a 65-byte 0x-prefixed hex string');
+  }
+  return value.toLowerCase() as Hex;
+}
+
+export function normalizeUint256String(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('0x')) {
+    if (!isHex(trimmed) || trimmed.length > 66) {
+      throw new Error('nonce must be a uint256 decimal string or 0x-prefixed hex string');
+    }
+    return trimmed.toLowerCase();
+  }
+  if (!/^[0-9]+$/.test(trimmed)) {
+    throw new Error('nonce must be a uint256 decimal string or 0x-prefixed hex string');
+  }
+  return trimmed;
+}

package/src/errors.ts

@@ -0,0 +1,22 @@
+export class GuardianEvmHttpError extends Error {
+  public readonly code?: string;
+
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly body: string
+  ) {
+    super(`Guardian EVM HTTP error ${status}: ${statusText} - ${body}`);
+    this.name = 'GuardianEvmHttpError';
+    this.code = parseErrorCode(body);
+  }
+}
+
+function parseErrorCode(body: string): string | undefined {
+  try {
+    const parsed = JSON.parse(body) as { code?: unknown };
+    return typeof parsed.code === 'string' ? parsed.code : undefined;
+  } catch {
+    return undefined;
+  }
+}