@towns-labs/relayer 2.0.12

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@towns-labs/relayer",
+  "version": "2.0.12",
+  "main": "dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./rpc/schema/*": "./src/rpc/schema/*.ts"
+  },
+  "files": [
+    "dist",
+    "src/rpc/schema"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && wrangler build",
+    "deploy": "wrangler deploy",
+    "deploy:prod": "wrangler deploy --env prod",
+    "deploy:stage": "wrangler deploy --env stage",
+    "dev": "./scripts/dev.sh --crosschain",
+    "dev:prod": "wrangler dev --env prod",
+    "dev:stage": "wrangler dev --env stage",
+    "dev:wrangler": "wrangler dev",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "oxlint --deny-warnings",
+    "lint:fix": "oxlint --fix",
+    "logs:prod": "wrangler tail --env prod",
+    "logs:stage": "wrangler tail --env stage",
+    "telemetry:summary": "bun run scripts/telemetry-summary.ts",
+    "telemetry:summary:stage": "wrangler tail --env stage --format json | bun run scripts/telemetry-summary.ts",
+    "telemetry:summary:prod": "wrangler tail --env prod --format json | bun run scripts/telemetry-summary.ts",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "@hono/zod-validator": "0.7.6",
+    "@scure/bip32": "2.0.1",
+    "@scure/bip39": "2.0.1",
+    "@towns-labs/contracts": "^2.0.12",
+    "hono": "^4.11.7",
+    "oxlint": "^1.41.0",
+    "pino": "10.2.0",
+    "viem": "2.45.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.8.38",
+    "@cloudflare/workers-types": "^4.20250618.0",
+    "typescript": "~5.8.3",
+    "vitest": "^3.2.3",
+    "wrangler": "^4.61.0"
+  }
+}

package/src/rpc/schema/getCallsStatus.ts

@@ -0,0 +1,21 @@
+import type { Hex } from 'viem'
+
+/**
+ * Result of wallet_getCallsStatus
+ */
+export interface GetCallsStatusResult {
+    id: string
+    status: number // 100=Pending, 200=Confirmed, 201=PreConfirmed, 300=Failed, 400=Reverted, 500=Partially Reverted
+    receipts: Array<{
+        chain_id: string
+        transaction_hash: Hex
+        status: boolean // Transaction success
+        block_hash?: string
+        block_number?: string
+        gas_used: string
+        logs: unknown[]
+        /** Intent execution error (bytes4 selector, e.g., 0x9054c912 for ExceededSpendLimit) */
+        intent_error?: Hex
+    }>
+    capabilities?: Record<string, unknown>
+}

package/src/rpc/schema/getCapabilities.ts

@@ -0,0 +1,91 @@
+import type { Address } from 'viem'
+
+/**
+ * Parameters for wallet_getCapabilities
+ */
+export interface GetCapabilitiesParams {
+    /** Hex-encoded chain IDs to filter (e.g., ["0x1", "0xa"]) */
+    chains?: string[]
+}
+
+/**
+ * Versioned contract addresses (spec-compliant)
+ */
+export interface VersionedContracts {
+    orchestrator: Address
+    delegation: Address
+    simulator: Address
+}
+
+/**
+ * Quote configuration for fee estimation
+ */
+export interface QuoteConfig {
+    /** Default quote TTL in seconds */
+    ttlSeconds?: number
+}
+
+/**
+ * Fee token configuration
+ */
+export interface ChainFeeToken {
+    /** Asset unique identifier (e.g., "usdc") */
+    uid: string
+    /** Token address */
+    address: Address
+    /** Token decimals */
+    decimals: number
+    /** Whether this token can be used for fees */
+    feeToken: boolean
+    /** Token symbol */
+    symbol?: string
+    /** Rate of 1 token against native token (hex) */
+    nativeRate?: string
+}
+
+/**
+ * Fees configuration (spec-compliant)
+ */
+export interface ChainFees {
+    recipient: Address
+    quoteConfig: QuoteConfig
+    tokens: ChainFeeToken[]
+}
+
+/**
+ * Individual signer information
+ */
+export interface SignerInfo {
+    index: number
+    address: string | null
+    balance: string | null
+    balanceEth: string | null
+    capacity: number
+    pending: number
+    paused: boolean
+}
+
+/**
+ * Pool status information
+ */
+export interface PoolInfo {
+    signerCount: number
+    totalCapacity: number
+    totalPending: number
+    availableCapacity: number
+    signers: SignerInfo[]
+}
+
+/**
+ * Capabilities for a single chain (spec-compliant)
+ */
+export interface ChainCapabilities {
+    contracts: VersionedContracts
+    fees: ChainFees
+    pool: PoolInfo
+}
+
+/**
+ * Result type for wallet_getCapabilities
+ */
+export type GetCapabilitiesResult = Record<string, ChainCapabilities>

package/src/rpc/schema/getKeys.ts

@@ -0,0 +1,40 @@
+import type { Address, Hex } from 'viem'
+import type { CallPermission, KeyType, SpendPermission } from './upgradeAccount'
+
+/**
+ * Spend permission response - extends SpendPermission with current spent amount
+ */
+export interface SpendPermissionResponse extends Omit<SpendPermission, 'limit'> {
+    limit: Hex
+    spent: Hex
+}
+
+/**
+ * Permission types returned by getKeys
+ */
+export type PermissionResponse = CallPermission | SpendPermissionResponse
+
+/**
+ * Authorized key response with permissions
+ */
+export interface AuthorizedKeyResponse {
+    hash: Hex
+    expiry: Hex
+    type: KeyType
+    role: 'admin' | 'normal'
+    publicKey: Hex
+    permissions: PermissionResponse[]
+}
+
+/**
+ * Parameters for wallet_getKeys
+ */
+export interface GetKeysParams {
+    address: Address
+    chainIds?: string[]
+}
+
+/**
+ * Result type for wallet_getKeys - keyed by hex chain ID
+ */
+export type GetKeysResult = Record<string, AuthorizedKeyResponse[]>

package/src/rpc/schema/prepareCalls.ts

@@ -0,0 +1,173 @@
+import type { Address, Hex } from 'viem'
+
+/**
+ * Call object in JSON-RPC format
+ */
+export interface RpcCall {
+    to: Address
+    data?: Hex
+    value?: string // hex
+}
+
+/**
+ * Key type for signing
+ */
+export type KeyType = 'secp256k1'
+
+/**
+ * Call key for signing
+ */
+export interface CallKey {
+    type: KeyType
+    publicKey: Hex
+    prehash: boolean
+}
+
+/**
+ * Parameters for wallet_prepareCalls
+ */
+export interface PrepareCallsParams {
+    from?: Address
+    chain_id: string // hex
+    calls: RpcCall[]
+    key?: {
+        type: string
+        public_key: Hex
+        prehash?: boolean
+    }
+    capabilities?: {
+        meta?: {
+            fee_payer?: Address
+            fee_token?: Address
+            fee_max_amount?: string
+            nonce?: string
+            seq_key?: string
+            settler?: Address
+            settler_context?: Hex
+        }
+    }
+}
+
+/**
+ * Intent structure within a Quote
+ */
+export interface QuoteIntent {
+    eoa: Address
+    calls: { to: Address; value: string; data: Hex }[]
+    nonce: string
+    combinedGas: string
+    expiry: string
+    encodedPreCalls?: Hex[]
+    funder?: Address
+    encodedFundTransfers?: Hex[]
+    settler?: Address
+    settlerContext?: Hex
+    payer?: Address
+    paymentToken?: Address
+    paymentMaxAmount?: string
+    /** Payment signature for third-party sponsorship (when payer != eoa) */
+    paymentSignature?: Hex
+}
+
+/**
+ * Quote for a prepared call bundle
+ */
+export interface Quote {
+    chainId: string
+    intent: QuoteIntent
+    extraPayment: string
+    ethPrice: string
+    paymentTokenDecimals: number
+    txGas: number
+    nativeFeeEstimate: {
+        maxFeePerGas: number
+        maxPriorityFeePerGas: number
+    }
+    /** Calculated payment amount in fee token units (set by relayer) */
+    paymentAmount: string
+    orchestrator: Address
+    feeTokenDeficit: string
+    assetDeficits: Array<{
+        address?: Address
+        metadata: { name?: string; symbol?: string; decimals?: number }
+        required: string
+        deficit: string
+    }>
+    telemetry?: {
+        simulationGas?: string
+        combinedGas?: string
+        txGas?: string
+        paymentEnabled?: boolean
+    }
+}
+
+/**
+ * Signed quotes with relay signature
+ */
+export interface SignedQuotes {
+    quotes: Quote[]
+    signature: Hex
+    ttl: number
+}
+
+/**
+ * Asset metadata
+ */
+export interface AssetMetadata {
+    name?: string
+    symbol?: string
+    decimals?: number
+}
+
+/**
+ * Asset price
+ */
+export interface AssetPrice {
+    currency: string
+    value: number
+}
+
+/**
+ * Asset diff for tracking balance changes
+ */
+export interface AssetDiff {
+    address?: Address
+    tokenKind?: 'native' | 'erc20' | 'erc721'
+    metadata: AssetMetadata
+    value: string
+    direction: 'incoming' | 'outgoing'
+    fiat?: AssetPrice
+    recipients: Address[]
+}
+
+/**
+ * Context returned by prepareCalls, used in sendPreparedCalls (spec-compliant)
+ */
+export type PrepareCallsContext = { quote: SignedQuotes }
+
+/**
+ * Capabilities in the prepareCalls response
+ */
+export interface PrepareCallsCapabilities {
+    authorizeKeys: unknown[]
+    revokeKeys: unknown[]
+    feeTotals: Record<string, AssetPrice>
+    assetDiffs: Record<string, Array<[Address, AssetDiff[]]>>
+}
+
+/**
+ * Result of wallet_prepareCalls (spec-compliant)
+ */
+export interface PrepareCallsResult {
+    context: PrepareCallsContext
+    digest: Hex
+    typedData: {
+        domain: Record<string, unknown>
+        types: Record<string, unknown>
+        primaryType: string
+        message: Record<string, unknown>
+    }
+    capabilities: PrepareCallsCapabilities
+    key?: CallKey
+    signature: Hex
+}

package/src/rpc/schema/sendPreparedCalls.ts

@@ -0,0 +1,23 @@
+import type { Hex } from 'viem'
+import type { CallKey, PrepareCallsContext } from './prepareCalls'
+
+/**
+ * Parameters for wallet_sendPreparedCalls (spec-compliant)
+ */
+export interface SendPreparedCallsParams {
+    context: PrepareCallsContext
+    signature: Hex
+    key?: CallKey
+    /** Payment signature for third-party sponsorship (when payer != sender) */
+    paymentSignature?: Hex
+    capabilities?: {
+        feeSignature?: Hex
+    }
+}
+
+/**
+ * Result of wallet_sendPreparedCalls
+ */
+export interface SendPreparedCallsResult {
+    id: string
+}

package/src/rpc/schema/upgradeAccount.ts

@@ -0,0 +1,172 @@
+import type { Address, Hex } from 'viem'
+
+/**
+ * Key types supported for authorization
+ */
+export type KeyType = 'secp256k1' | 'external'
+
+/**
+ * Spend period for spending limits
+ */
+export type SpendPeriod = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year' | 'forever'
+
+/**
+ * Call permission
+ */
+export interface CallPermission {
+    type: 'call'
+    to: Address
+    selector: Hex
+}
+
+/**
+ * Spend permission
+ */
+export interface SpendPermission {
+    type: 'spend'
+    token: Address
+    limit: string
+    period: SpendPeriod
+}
+
+/**
+ * Permission types
+ */
+export type Permission = CallPermission | SpendPermission
+
+/**
+ * Key authorization request
+ */
+export interface AuthorizeKey {
+    expiry: string
+    type: KeyType
+    role: 'admin' | 'normal'
+    publicKey: Hex
+    permissions: Permission[]
+}
+
+/**
+ * Key authorization response (includes hash)
+ */
+export interface AuthorizeKeyResponse extends AuthorizeKey {
+    hash: Hex
+}
+
+/**
+ * EIP-7702 Authorization (unsigned)
+ */
+export interface Authorization {
+    contractAddress: Address
+    chainId: number
+    nonce: number
+}
+
+/**
+ * Signed call for precall execution
+ */
+export interface SignedCall {
+    eoa: Address
+    executionData: Hex
+    nonce: string
+    signature: Hex
+    chainId: string
+}
+
+/**
+ * Parameters for wallet_prepareUpgradeAccount (spec-compliant)
+ */
+export interface PrepareUpgradeParams {
+    /** EOA address to upgrade */
+    address: Address
+    /** Target chain ID (hex), defaults to relayer's chain */
+    chainId?: string
+    /** TownsAccount implementation address, defaults to config */
+    delegation: Address
+    /** Capabilities for the upgrade */
+    capabilities: {
+        authorizeKeys: AuthorizeKey[]
+    }
+}
+
+/**
+ * Context returned by prepareUpgradeAccount (spec-compliant)
+ */
+export interface UpgradeAccountContext {
+    /** EOA address being upgraded */
+    address: Address
+    /** Target chain ID (hex) */
+    chainId: string
+    /** EIP-7702 authorization (unsigned) */
+    authorization: Authorization
+    /** PreCall for key initialization */
+    preCall: SignedCall
+}
+
+/**
+ * Digests to sign for account upgrade
+ */
+export interface UpgradeAccountDigests {
+    /** EIP-7702 authorization digest */
+    auth: Hex
+    /** Precall execution digest */
+    exec: Hex
+}
+
+/**
+ * Capabilities in the upgrade response
+ */
+export interface UpgradeAccountCapabilities {
+    authorizeKeys: AuthorizeKeyResponse[]
+}
+
+/**
+ * Result of wallet_prepareUpgradeAccount (spec-compliant)
+ */
+export interface PrepareUpgradeResult {
+    /** Chain ID (hex) */
+    chainId: string
+    /** Context to pass to upgradeAccount */
+    context: UpgradeAccountContext
+    /** Digests to sign */
+    digests: UpgradeAccountDigests
+    /** EIP-712 typed data for the exec signature */
+    typedData: {
+        domain: Record<string, unknown>
+        types: Record<string, unknown>
+        primaryType: string
+        message: Record<string, unknown>
+    }
+    /** Capabilities with processed keys */
+    capabilities: UpgradeAccountCapabilities
+}
+
+/**
+ * Signatures for wallet_upgradeAccount
+ */
+export interface UpgradeAccountSignatures {
+    /** EIP-7702 authorization signature */
+    auth: Hex
+    /** Precall execution signature */
+    exec: Hex
+}
+
+/**
+ * Parameters for wallet_upgradeAccount (spec-compliant)
+ */
+export interface UpgradeAccountParams {
+    /** Context from prepareUpgradeAccount */
+    context: UpgradeAccountContext
+    /** Both signatures */
+    signatures: UpgradeAccountSignatures
+}
+
+/**
+ * Result of wallet_upgradeAccount
+ *
+ * Returns success: true only after the delegation tx is mined and confirmed.
+ * This allows clients to proceed immediately without polling.
+ */
+export interface UpgradeAccountResult {
+    success: boolean
+    txHash?: string
+}

package/src/rpc/schema/verifySignature.ts

@@ -0,0 +1,27 @@
+import type { Address, Hex } from 'viem'
+
+/**
+ * Parameters for wallet_verifySignature
+ */
+export interface VerifySignatureParams {
+    address: Address
+    digest: Hex
+    signature: Hex
+    chain_id: string
+}
+
+/**
+ * Proof of valid signature
+ */
+export interface ValidSignatureProof {
+    account: Address
+    key_hash: Hex
+}
+
+/**
+ * Result of wallet_verifySignature
+ */
+export interface VerifySignatureResult {
+    valid: boolean
+    proof: ValidSignatureProof | null
+}