fix: enforce Design by Contract preconditions and add JSDoc annotations

Add @precondition, @postcondition, @throws, and @invariant JSDoc
annotations to all public SDK methods matching the spec contracts.

Add missing runtime precondition enforcement:
- switchChain() now checks connected state before chain validation
- execute() now validates params.chainId against supportedChains

Author: fernandomg

src/sdk/core/chain/explorer.ts

@@ -8,8 +8,10 @@ type ExplorerParams =
 /**
  * Builds an explorer URL for a transaction, address, or block.
  *
- * Returns null if the chain is not found, has no explorer config, or the
- * requested path type (e.g. blockPath) is not defined for that explorer.
+ * @precondition registry is a valid ChainRegistry
+ * @precondition params.chainId identifies a chain, params contains exactly one of tx/address/block
+ * @postcondition returns a fully qualified URL string, or null if chain/explorer/path not found
+ * @postcondition if explorer.queryParams is defined, they are appended as URL search params
  */
 export function getExplorerUrl(registry: ChainRegistry, params: ExplorerParams): string | null {
   const descriptor = registry.getChain(params.chainId)

src/sdk/core/chain/registry.ts

@@ -18,8 +18,11 @@ export interface ChainRegistry {
 /**
  * Creates an immutable ChainRegistry from the provided descriptors.
  *
- * Throws ChainRegistryConflictError at construction time if any two descriptors
- * share the same chainId or the same caip2Id.
+ * @precondition no two descriptors share the same chainId
+ * @precondition no two descriptors share the same caip2Id
+ * @postcondition registry is immutable — lookups never mutate internal state
+ * @postcondition getAllChains() returns a copy of the input array
+ * @throws {ChainRegistryConflictError} if any two descriptors share the same chainId or caip2Id
  */
 export function createChainRegistry(chains: ChainDescriptor[]): ChainRegistry {
   const byChainId = new Map<string | number, ChainDescriptor>()

src/sdk/core/evm/server-wallet.ts

@@ -31,6 +31,14 @@ export interface EvmServerWalletConfig {
 /**
  * Creates a server-side EVM wallet adapter backed by a private key.
  * Returns no Provider — server wallets have no UI layer.
+ *
+ * @precondition config.privateKey is a valid hex-encoded private key
+ * @precondition config.chain is a valid viem Chain
+ * @postcondition returned adapter.chainType === 'evm'
+ * @postcondition returned bundle has no Provider (server wallets have no UI)
+ * @invariant adapter.chainType never changes after construction
+ * @invariant adapter.supportedChains never changes after construction
+ * @invariant getStatus().connected === true (always connected)
  */
 export function createEvmServerWallet(config: EvmServerWalletConfig): WalletAdapterBundle {
   const account = privateKeyToAccount(config.privateKey)
@@ -58,6 +66,13 @@ export function createEvmServerWallet(config: EvmServerWalletConfig): WalletAdap
       },
     },
 
+    /**
+     * No-op connect — server wallet is always connected via private key.
+     *
+     * @precondition none
+     * @postcondition returns WalletConnection with the private key account
+     * @postcondition result.accounts.length === 1
+     */
     async connect(_options?: ConnectOptions): Promise<WalletConnection> {
       return {
         accounts: [account.address],
@@ -66,7 +81,12 @@ export function createEvmServerWallet(config: EvmServerWalletConfig): WalletAdap
       }
     },
 
-    // Server wallet is always connected — reconnect() always returns a connection, never null.
+    /**
+     * Always returns a connection — server wallet is always connected.
+     *
+     * @precondition none
+     * @postcondition always returns WalletConnection (never null)
+     */
     async reconnect(): Promise<WalletConnection | null> {
       return {
         accounts: [account.address],
@@ -75,10 +95,24 @@ export function createEvmServerWallet(config: EvmServerWalletConfig): WalletAdap
       }
     },
 
+    /**
+     * No-op — private key wallet is always connected and cannot be disconnected.
+     *
+     * @precondition none
+     * @postcondition getStatus().connected remains true
+     */
     async disconnect(): Promise<void> {
       // no-op: private key wallet is always connected
     },
 
+    /**
+     * Returns wallet status — always connected for server wallets.
+     *
+     * @precondition none
+     * @postcondition connected === true
+     * @postcondition activeAccount === the private key's derived address
+     * @invariant status never changes for a private key wallet
+     */
     getStatus(): WalletStatus {
       return {
         connected: true,
@@ -88,6 +122,13 @@ export function createEvmServerWallet(config: EvmServerWalletConfig): WalletAdap
       }
     },
 
+    /**
+     * Emits current status immediately; no further changes occur for a server wallet.
+     *
+     * @precondition none
+     * @postcondition listener fires once with current (always-connected) status
+     * @returns unsubscribe function (no-op — status never changes)
+     */
     onStatusChange(listener: (status: WalletStatus) => void): () => void {
       // Emit current status immediately so callers receive initial state without polling.
       listener({
@@ -101,6 +142,12 @@ export function createEvmServerWallet(config: EvmServerWalletConfig): WalletAdap
       }
     },
 
+    /**
+     * Signs an arbitrary message with the server wallet's private key.
+     *
+     * @precondition none (server wallet is always connected)
+     * @postcondition result.address matches the private key's derived address
+     */
     async signMessage(input: SignMessageInput): Promise<SignatureResult> {
       const message = input.message instanceof Uint8Array ? { raw: input.message } : input.message
       const signature = await walletClient.signMessage({ message } as Parameters<
@@ -109,6 +156,12 @@ export function createEvmServerWallet(config: EvmServerWalletConfig): WalletAdap
       return { signature, address: account.address }
     },
 
+    /**
+     * Signs EIP-712 typed data with the server wallet's private key.
+     *
+     * @precondition none (server wallet is always connected)
+     * @postcondition result.address matches the private key's derived address
+     */
     async signTypedData(input: SignTypedDataInput): Promise<SignatureResult> {
       const signature = await walletClient.signTypedData({
         domain: input.domain,
@@ -119,10 +172,22 @@ export function createEvmServerWallet(config: EvmServerWalletConfig): WalletAdap
       return { signature, address: account.address }
     },
 
+    /**
+     * Returns the viem WalletClient — always available for server wallets.
+     *
+     * @precondition none
+     * @postcondition always returns the WalletClient (never null)
+     */
     async getSigner(): Promise<ChainSigner | null> {
       return walletClient
     },
 
+    /**
+     * Always throws — server wallets are bound to a single chain.
+     *
+     * @precondition none
+     * @throws {CapabilityNotSupportedError} always (switchChain not supported)
+     */
     async switchChain(_chainId: string | number): Promise<void> {
       throw new CapabilityNotSupportedError('switchChain')
     },

src/sdk/core/evm/transaction.test.ts

@@ -3,7 +3,7 @@ import { mainnet } from 'viem/chains'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { TransactionRef } from '../adapters/transaction'
-import { InsufficientFundsError, InvalidSignerError } from '../errors'
+import { ChainNotSupportedError, InsufficientFundsError, InvalidSignerError } from '../errors'
 import { createEvmTransactionAdapter } from './transaction'
 import type { EvmContractCall, EvmRawTransaction } from './types'
 
@@ -192,6 +192,25 @@ describe('createEvmTransactionAdapter', () => {
     ).rejects.toThrow(InvalidSignerError)
   })
 
+  it('throws ChainNotSupportedError when execute targets an unsupported chain', async () => {
+    const adapter = createEvmTransactionAdapter({
+      chains: [mainnet],
+      transports: { [mainnet.id]: http() },
+    })
+
+    const mockWalletClient = {
+      sendTransaction: vi.fn().mockResolvedValue('0xhash'),
+      writeContract: vi.fn(),
+    }
+
+    await expect(
+      adapter.execute(
+        { chainId: 999999, payload: { to: '0xabc' as `0x${string}` } as EvmRawTransaction },
+        mockWalletClient as never,
+      ),
+    ).rejects.toThrow(ChainNotSupportedError)
+  })
+
   it('returns TransactionRef with hash for EvmRawTransaction', async () => {
     const adapter = createEvmTransactionAdapter({
       chains: [mainnet],

src/sdk/core/evm/transaction.ts

@@ -16,7 +16,7 @@ import type {
   TransactionResult,
 } from '../adapters/transaction'
 import type { ChainSigner } from '../adapters/wallet'
-import { InsufficientFundsError, InvalidSignerError } from '../errors'
+import { ChainNotSupportedError, InsufficientFundsError, InvalidSignerError } from '../errors'
 import { fromViemChain } from './chains'
 import type { EvmContractCall, EvmRawTransaction, EvmTransactionPayload } from './types'
 
@@ -41,6 +41,12 @@ function isWalletClient(signer: unknown): signer is WalletClient {
 
 /**
  * Creates an EVM TransactionAdapter backed by viem's PublicClient (reads) and WalletClient (writes).
+ *
+ * @precondition config.chains entries must have corresponding transports
+ * @postcondition returned adapter.chainType === 'evm'
+ * @postcondition returned adapter.supportedChains matches config.chains (mapped via fromViemChain)
+ * @invariant adapter.chainType never changes after construction
+ * @invariant adapter.supportedChains never changes after construction
  */
 export function createEvmTransactionAdapter(
   config: EvmTransactionConfig = { chains: [], transports: {} },
@@ -72,6 +78,14 @@ export function createEvmTransactionAdapter(
       confirmationModel: 'blockConfirmations',
     },
 
+    /**
+     * Estimates gas and validates readiness for the given transaction params.
+     *
+     * @precondition params.chainId is in supportedChains
+     * @postcondition if ready === true -> execute() can be called with these params
+     * @postcondition if ready === false -> reason explains why (human-readable)
+     * @throws {InsufficientFundsError} if balance too low for gas estimation
+     */
     async prepare(params: TransactionParams): Promise<PrepareResult> {
       const numericId =
         typeof params.chainId === 'string' ? Number.parseInt(params.chainId, 10) : params.chainId
@@ -138,10 +152,25 @@ export function createEvmTransactionAdapter(
       }
     },
 
+    /**
+     * Submits the transaction to the network via the provided WalletClient signer.
+     *
+     * @precondition signer is a valid WalletClient for this adapter's chainType
+     * @precondition params.chainId is in supportedChains
+     * @postcondition returns TransactionRef with a unique id (tx hash)
+     * @postcondition the transaction has been submitted to the network (not yet confirmed)
+     * @throws {InvalidSignerError} if signer is not a WalletClient
+     * @throws {ChainNotSupportedError} if chainId not in supportedChains
+     */
     async execute(params: TransactionParams, signer: ChainSigner): Promise<TransactionRef> {
       if (!isWalletClient(signer)) {
         throw new InvalidSignerError('WalletClient')
       }
+      const numericId =
+        typeof params.chainId === 'string' ? Number.parseInt(params.chainId, 10) : params.chainId
+      if (!publicClients.has(numericId)) {
+        throw new ChainNotSupportedError(params.chainId)
+      }
 
       const payload = params.payload as EvmTransactionPayload
 
@@ -171,6 +200,14 @@ export function createEvmTransactionAdapter(
       return { chainType: 'evm', id: hash as string, chainId: params.chainId }
     },
 
+    /**
+     * Waits for the transaction to be confirmed or times out.
+     *
+     * @precondition ref was returned by a previous execute() call on this adapter
+     * @postcondition result.status is 'success', 'reverted', or 'timeout'
+     * @postcondition if 'success' -> result.receipt contains a viem TransactionReceipt
+     * @throws never (timeout returns TransactionResult with status: 'timeout')
+     */
     async confirm(ref: TransactionRef, options?: ConfirmOptions): Promise<TransactionResult> {
       const publicClient = getPublicClient(ref.chainId)
       const hash = ref.id as Hex

src/sdk/core/evm/wallet.test.ts

@@ -292,9 +292,16 @@ describe('createEvmWalletAdapter — unit tests', () => {
 
   describe('switchChain()', () => {
     it('throws ChainNotSupportedError for unsupported chainId', async () => {
+      vi.mocked(getAccount).mockReturnValue(makeConnectedAccount())
       const { adapter } = makeAdapter()
       await expect(adapter.switchChain(999999)).rejects.toThrow(ChainNotSupportedError)
     })
+
+    it('throws WalletNotConnectedError when switchChain is called while disconnected', async () => {
+      vi.mocked(getAccount).mockReturnValue(makeDisconnectedAccount())
+      const { adapter } = makeAdapter()
+      await expect(adapter.switchChain(mainnet.id)).rejects.toThrow(WalletNotConnectedError)
+    })
   })
 
   // -------------------------------------------------------------------------