refactor: introduce @expects tag and relabel unenforced @precondition annotations across SDK

fernandomg · fernandomg · commit f56c340b1271 · 2026-04-09T21:37:13.000+02:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -100,6 +100,7 @@ The `/issue` skill applies these labels automatically when creating issues via C
 - Path aliases: `@/src/*` and `@packageJSON`
 - All env vars prefixed with `PUBLIC_` and validated in `src/env.ts`
 - JSDoc comments on exported functions/components (follow existing patterns)
+- Use `@precondition` in JSDoc ONLY for conditions enforced at runtime with a throw/guard. Use `@expects` for documented assumptions the caller is responsible for (TypeScript-enforced, gracefully handled, or downstream-validated). If you write `@precondition`, the function MUST validate and throw on violation.
 
 ## Styling
 
diff --git a/src/sdk/core/chain/explorer.ts b/src/sdk/core/chain/explorer.ts
@@ -8,8 +8,8 @@ type ExplorerParams =
 /**
  * Builds an explorer URL for a transaction, address, or block.
  *
- * @precondition registry is a valid ChainRegistry
- * @precondition params.chainId identifies a chain, params contains exactly one of tx/address/block
+ * @expects registry is a valid ChainRegistry
+ * @expects 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
  */
diff --git a/src/sdk/core/errors/format.ts b/src/sdk/core/errors/format.ts
@@ -11,7 +11,7 @@
 /**
  * Extracts shortMessage from viem errors, walking the cause chain if needed.
  *
- * @precondition error is any value (null-safe)
+ * @expects error is any value (null-safe)
  * @postcondition returns the first shortMessage or details found, or null
  */
 export function extractViemErrorMessage(error: unknown): string | null {
@@ -40,7 +40,7 @@ export function extractViemErrorMessage(error: unknown): string | null {
  * Strips technical data (hex, addresses, viem internals) from error messages.
  * Acts as a safety net so no raw data leaks to the user.
  *
- * @precondition message is a non-empty string
+ * @expects message is a non-empty string
  * @postcondition returns a sanitized string with technical data removed
  */
 export function sanitizeErrorMessage(message: string): string {
@@ -81,7 +81,7 @@ export function sanitizeErrorMessage(message: string): string {
  * 3. Extract revert reason from "execution reverted: ..." pattern
  * 4. Sanitize remaining verbose messages (strip hex, addresses, technical blocks)
  *
- * @precondition error is any value — string, Error, viem error, null, undefined
+ * @expects error is any value — string, Error, viem error, null, undefined
  * @postcondition returns a clean, user-friendly string (never empty, never throws)
  */
 export function formatErrorMessage(error: unknown): string {
diff --git a/src/sdk/core/evm/read-client.ts b/src/sdk/core/evm/read-client.ts
@@ -6,7 +6,7 @@ import type { EndpointConfig } from '../chain/descriptor'
 /**
  * Read-only client factory for EVM chains. Wraps viem's createPublicClient.
  *
- * @precondition endpoint.url is a valid JSON-RPC URL
+ * @expects endpoint.url is a valid JSON-RPC URL
  * @postcondition returns a viem PublicClient for read-only chain queries
  */
 export const evmReadClientFactory: ReadClientFactory<PublicClient> = {
diff --git a/src/sdk/core/evm/server-wallet.ts b/src/sdk/core/evm/server-wallet.ts
@@ -33,7 +33,7 @@ export interface EvmServerWalletConfig {
  * 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
+ * @expects 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
diff --git a/src/sdk/core/evm/transaction.ts b/src/sdk/core/evm/transaction.ts
@@ -98,7 +98,7 @@ export function createEvmTransactionAdapter(
     /**
      * Estimates gas and validates readiness for the given transaction params.
      *
-     * @precondition params.chainId is in supportedChains
+     * @expects 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
@@ -225,7 +225,7 @@ export function createEvmTransactionAdapter(
     /**
      * Waits for the transaction to be confirmed or times out.
      *
-     * @precondition ref was returned by a previous execute() call on this adapter
+     * @expects 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')
diff --git a/src/sdk/core/evm/wallet.ts b/src/sdk/core/evm/wallet.ts
@@ -288,7 +288,7 @@ export function createEvmWalletAdapter(config: EvmWalletConfig): EvmWalletAdapte
      * Signs EIP-712 typed data with the connected wallet.
      *
      * @precondition getStatus().connected === true
-     * @precondition metadata.capabilities.signTypedData === true
+     * @expects metadata.capabilities.signTypedData === true
      * @postcondition result.address matches the signing account
      * @throws {WalletNotConnectedError} if not connected
      * @throws {SigningRejectedError} if user cancels
diff --git a/src/sdk/core/read-client.ts b/src/sdk/core/read-client.ts
@@ -5,7 +5,7 @@ import type { ChainRegistry } from './chain/registry'
  * Creates a typed read-only client using a specific factory.
  * For CLI tools, agent scripts, and other non-React consumers.
  *
- * @precondition chainId is registered in the registry
+ * @expects chainId is registered in the registry
  * @postcondition returns a typed client, or null if chain/endpoint not found
  */
 export function createReadClient<TClient>(
@@ -28,7 +28,7 @@ export function createReadClient<TClient>(
  * Resolves a read-only client from a heterogeneous factory array.
  * For multi-VM loops where the chain type isn't known ahead of time.
  *
- * @precondition chainId is registered in the registry
+ * @expects chainId is registered in the registry
  * @postcondition returns a client, or null if chain/factory/endpoint not found
  */
 export function resolveReadClient(
diff --git a/src/sdk/core/utils/wrap-adapter.ts b/src/sdk/core/utils/wrap-adapter.ts
@@ -16,7 +16,7 @@ export interface WrapAdapterHooks {
    * Always return an args array — return the input unchanged for pass-through.
    * Errors propagate (not fire-and-forget).
    *
-   * @precondition args is the original arguments array
+   * @expects args is the original arguments array
    * @postcondition returned array replaces args for the method call
    * @throws any error thrown here aborts the method call
    */
@@ -41,7 +41,7 @@ export interface WrapAdapterHooks {
    * Always return a value — return the input unchanged for pass-through.
    * Errors propagate (not fire-and-forget).
    *
-   * @precondition result is the resolved value from the method
+   * @expects result is the resolved value from the method
    * @postcondition returned value replaces the method result
    * @throws any error thrown here aborts the call
    */
@@ -66,7 +66,7 @@ function collectMethodKeys(obj: object): string[] {
  *
  * Execution order: `beforeCall` -> `onBefore` -> method -> `onAfter` -> `afterCall`
  *
- * @precondition adapter is a non-null object
+ * @expects adapter is a non-null object
  * @postcondition returned object has the same interface as adapter with hooks applied
  * @throws errors from `beforeCall`/`afterCall` propagate; observation hook errors are swallowed
  */
diff --git a/src/sdk/react/components/WalletGuard.tsx b/src/sdk/react/components/WalletGuard.tsx
@@ -25,7 +25,7 @@ export interface WalletGuardProps {
   /**
    * Level 4 escape hatch: explicit wallet adapter — bypasses provider resolution.
    * Only applies in single-chain mode (not with `require` prop).
-   * @precondition if adapter provided, require must not be set (single-chain mode only)
+   * @expects if adapter provided, require must not be set (single-chain mode only)
    */
   adapter?: WalletAdapter
   children?: ReactNode
@@ -51,7 +51,7 @@ export interface WalletGuardProps {
  * - **Single-chain** (chainId/chainType props): uses useWallet for one adapter
  * - **Multi-chain** (require prop): uses useMultiWallet, checks each requirement
  *
- * @precondition Either `require` or `chainId`/`chainType` should be provided, not both
+ * @expects Either `require` or `chainId`/`chainType` should be provided, not both
  * @postcondition Renders children only when all wallet requirements are satisfied
  * @throws Never — renders fallback UI or null instead of throwing
  */
@@ -74,7 +74,7 @@ export const WalletGuard: FC<WalletGuardProps> = (props) => {
 
 /**
  * Internal component for single-chain wallet gating (original behavior).
- * @precondition useWallet hook is available via provider context
+ * @expects useWallet hook is available via provider context
  * @postcondition Renders children when wallet is connected to the correct chain
  */
 const SingleChainGuard: FC<WalletGuardProps> = ({
@@ -119,7 +119,7 @@ interface MultiChainGuardProps extends WalletGuardProps {
 /**
  * Internal component for multi-chain wallet gating.
  * Iterates requirements and renders fallback for the first unmet one.
- * @precondition useMultiWallet hook is available via provider context
+ * @expects useMultiWallet hook is available via provider context
  * @postcondition Renders children only when every requirement has a connected wallet
  */
 const MultiChainGuard: FC<MultiChainGuardProps> = ({
diff --git a/src/sdk/react/evm/read-only.ts b/src/sdk/react/evm/read-only.ts
@@ -13,8 +13,8 @@ export interface UseEvmReadOnlyOptions {
  * Typed EVM read-only hook. Returns a viem PublicClient for the given chain.
  * Self-sufficient — works even without provider readClientFactories configured.
  *
- * @precondition Must be called inside a DAppBoosterProvider
- * @precondition chainId must be an EVM chain registered in the provider
+ * @expects Must be called inside a DAppBoosterProvider
+ * @expects chainId must be an EVM chain registered in the provider
  * @postcondition returns { client: PublicClient | null, chain, address, explorerAddressUrl }
  */
 export function useEvmReadOnly(options: UseEvmReadOnlyOptions): UseReadOnlyReturn<PublicClient> {
diff --git a/src/sdk/react/evm/wallet-bundle.tsx b/src/sdk/react/evm/wallet-bundle.tsx
@@ -34,8 +34,8 @@ export interface EvmWalletBundleConfig {
  * Wraps the core createEvmWalletAdapter with WagmiProvider, QueryClientProvider, and the
  * connector's WalletProvider.
  *
- * @precondition config.chains.length >= 1
- * @precondition config.connector provides createConfig, WalletProvider, and useConnectModal
+ * @expects config.chains.length >= 1
+ * @expects config.connector provides createConfig, WalletProvider, and useConnectModal
  * @postcondition returned bundle.adapter.chainType === 'evm'
  * @postcondition returned bundle.Provider wraps children with wagmi + query + connector providers
  */
diff --git a/src/sdk/react/hooks/useMultiWallet.ts b/src/sdk/react/hooks/useMultiWallet.ts
@@ -10,13 +10,13 @@ export interface UseMultiWalletReturn {
   wallets: Record<string, UseWalletReturn>
   /**
    * Returns the wallet entry whose adapter matches the given chainType.
-   * @precondition chainType is a non-empty string
+   * @expects chainType is a non-empty string
    * @postcondition returns the first matching UseWalletReturn or undefined
    */
   getWallet(chainType: string): UseWalletReturn | undefined
   /**
    * Returns the wallet entry whose adapter's supportedChains includes the given chainId.
-   * @precondition chainId is a string or number identifying a chain
+   * @expects chainId is a string or number identifying a chain
    * @postcondition returns the first matching UseWalletReturn or undefined
    */
   getWalletByChainId(chainId: string | number): UseWalletReturn | undefined
diff --git a/src/sdk/react/hooks/useReadOnly.ts b/src/sdk/react/hooks/useReadOnly.ts
@@ -10,7 +10,7 @@ export interface UseReadOnlyOptions<TClient = unknown> {
   address?: string
   /**
    * Level 4 escape hatch: explicit factory — bypasses provider resolution.
-   * @precondition factory.chainType should match the chain's chainType
+   * @expects factory.chainType should match the chain's chainType
    */
   factory?: ReadClientFactory<TClient>
 }
@@ -30,8 +30,8 @@ export interface UseReadOnlyReturn<TClient = unknown> {
  * The client is created by the matching ReadClientFactory — either from the explicit `factory` option
  * (Level 4 bypass) or from the provider's readClientFactories.
  *
- * @precondition Must be called inside a DAppBoosterProvider
- * @precondition options.chainId identifies a chain registered in the provider config
+ * @expects Must be called inside a DAppBoosterProvider
+ * @expects options.chainId identifies a chain registered in the provider config
  * @postcondition returns chain descriptor and read-only client (null when chain/factory/endpoint missing)
  * @postcondition returns address as-is from options, or null when not provided
  * @postcondition returns explorerAddressUrl when both address and chain explorer config are present
diff --git a/src/sdk/react/hooks/useTransaction.ts b/src/sdk/react/hooks/useTransaction.ts
@@ -32,12 +32,12 @@ export interface UseTransactionOptions {
   confirmOptions?: ConfirmOptions
   /**
    * Explicit transaction adapter — bypasses provider resolution when set.
-   * @precondition if provided, must support the chainId used in execute()/prepare()
+   * @expects if provided, must support the chainId used in execute()/prepare()
    */
   transactionAdapter?: TransactionAdapter
   /**
    * Explicit wallet adapter — bypasses provider resolution when set.
-   * @precondition if provided, must be connected when execute() is called
+   * @expects if provided, must be connected when execute() is called
    */
   walletAdapter?: WalletAdapter
 }
@@ -88,7 +88,7 @@ function fireLifecycle<K extends keyof TransactionLifecycle>(
  * Executes a chain transaction through the registered TransactionAdapter,
  * managing phase transitions, preSteps, lifecycle hooks, and error state.
  *
- * @precondition must be called inside a DAppBoosterProvider
+ * @expects must be called inside a DAppBoosterProvider
  * @postcondition execute() runs the full cycle: prepare -> preSteps -> submit -> confirm
  * @postcondition lifecycle hooks fire: global (from provider) first, per-transaction (from options) second
  * @postcondition hook errors in lifecycle callbacks are logged but never abort the transaction
diff --git a/src/sdk/react/hooks/useWallet.ts b/src/sdk/react/hooks/useWallet.ts
@@ -62,7 +62,7 @@ interface ResolvedAdapter {
 /**
  * Resolves a single WalletAdapter from the registered adapters using the provided options.
  *
- * @precondition if options.adapter is set, it is used directly (bypasses provider resolution)
+ * @expects if options.adapter is set, it is used directly (bypasses provider resolution)
  * @precondition if options.chainType is set, at least one adapter must match that chainType
  * @precondition if options.chainId is set, at least one adapter must support that chainId
  * @postcondition if exactly one adapter is registered and no options given, returns that adapter
@@ -111,7 +111,7 @@ function resolveAdapter(
  * Pass `chainType`, `chainId`, or `adapter` in options to disambiguate when multiple adapters
  * are registered. With a single adapter and no options, it resolves automatically.
  *
- * @precondition must be called inside a DAppBoosterProvider
+ * @expects must be called inside a DAppBoosterProvider
  * @precondition if multiple adapters registered, options must include chainType, chainId, or adapter
  * @postcondition status is reactive — re-renders on every wallet status change
  * @postcondition signMessage/signTypedData fire global walletLifecycle hooks from provider
diff --git a/src/sdk/react/internal/walletLifecycle.ts b/src/sdk/react/internal/walletLifecycle.ts
@@ -9,7 +9,7 @@ import type {
 /**
  * Invokes a single WalletLifecycle hook by key, swallowing any error it throws.
  *
- * @precondition key must be a valid WalletLifecycle method name
+ * @expects key must be a valid WalletLifecycle method name
  * @postcondition the hook is called with args if defined; errors are logged, never propagated
  * @throws never — errors thrown by hooks are caught and logged to console.error
  */
@@ -32,7 +32,7 @@ export function fireWalletLifecycle<K extends keyof WalletLifecycle>(
 /**
  * Wraps adapter.signMessage with lifecycle dispatch (onSign, onSignComplete, onSignError).
  *
- * @precondition adapter must implement signMessage
+ * @expects adapter must implement signMessage
  * @postcondition returned function delegates to adapter.signMessage with full lifecycle hooks
  * @throws re-throws the original error from adapter.signMessage after firing onSignError
  */
@@ -58,7 +58,7 @@ export function wrapSignMessage(
  * Wraps adapter.signTypedData with lifecycle dispatch (onSign, onSignComplete, onSignError).
  * Returns undefined when the adapter does not support signTypedData.
  *
- * @precondition adapter may or may not have signTypedData
+ * @expects adapter may or may not have signTypedData
  * @postcondition returns undefined if adapter.signTypedData is not defined
  * @postcondition returned function (when defined) delegates with full lifecycle hooks
  * @throws re-throws the original error from adapter.signTypedData after firing onSignError
diff --git a/src/sdk/react/lifecycle/createNotificationLifecycle.ts b/src/sdk/react/lifecycle/createNotificationLifecycle.ts
@@ -52,7 +52,7 @@ export interface SigningNotificationLifecycleOptions {
 /**
  * Builds an explorer URL suffix for a transaction, or empty string if unavailable.
  *
- * @precondition ref.id is a valid transaction hash and ref.chainId is a known chain
+ * @expects ref.id is a valid transaction hash and ref.chainId is a known chain
  * @postcondition returns a string like ' — https://etherscan.io/tx/0x...' or ''
  */
 function buildExplorerSuffix(registry: ChainRegistry | undefined, ref: TransactionRef): string {
@@ -68,7 +68,7 @@ function buildExplorerSuffix(registry: ChainRegistry | undefined, ref: Transacti
  *
  * Pass the result to useTransaction({ lifecycle }) or TransactionButton lifecycle prop.
  *
- * @precondition toaster implements the ToasterAPI interface
+ * @expects toaster implements the ToasterAPI interface
  * @postcondition returned lifecycle fires toasts for onSubmit, onConfirm, onReplace, and onError
  * @postcondition when registry is provided, confirm and replace toasts include explorer URLs
  */
@@ -120,7 +120,7 @@ export function createNotificationLifecycle({
 /**
  * Creates a WalletLifecycle that fires toast notifications for signing operations.
  *
- * @precondition toaster implements the ToasterAPI interface
+ * @expects toaster implements the ToasterAPI interface
  * @postcondition returned lifecycle fires toasts for onSign, onSignComplete, and onSignError
  */
 export function createSigningNotificationLifecycle({

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ import type { EndpointConfig } from '../chain/descriptor'`
`6`	`6`	`/**`
`7`	`7`	`* Read-only client factory for EVM chains. Wraps viem's createPublicClient.`
`8`	`8`	`*`
`9`		`- * @precondition endpoint.url is a valid JSON-RPC URL`
	`9`	`+ * @expects endpoint.url is a valid JSON-RPC URL`
`10`	`10`	`* @postcondition returns a viem PublicClient for read-only chain queries`
`11`	`11`	`*/`
`12`	`12`	`export const evmReadClientFactory: ReadClientFactory<PublicClient> = {`
Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ export interface EvmServerWalletConfig {`
`33`	`33`	`* Returns no Provider — server wallets have no UI layer.`
`34`	`34`	`*`
`35`	`35`	`* @precondition config.privateKey is a valid hex-encoded private key`
`36`		`- * @precondition config.chain is a valid viem Chain`
	`36`	`+ * @expects config.chain is a valid viem Chain`
`37`	`37`	`* @postcondition returned adapter.chainType === 'evm'`
`38`	`38`	`* @postcondition returned bundle has no Provider (server wallets have no UI)`
`39`	`39`	`* @invariant adapter.chainType never changes after construction`
Original file line number	Diff line number	Diff line change
`@@ -288,7 +288,7 @@ export function createEvmWalletAdapter(config: EvmWalletConfig): EvmWalletAdapte`
`288`	`288`	`* Signs EIP-712 typed data with the connected wallet.`
`289`	`289`	`*`
`290`	`290`	`* @precondition getStatus().connected === true`
`291`		`- * @precondition metadata.capabilities.signTypedData === true`
	`291`	`+ * @expects metadata.capabilities.signTypedData === true`
`292`	`292`	`* @postcondition result.address matches the signing account`
`293`	`293`	`* @throws {WalletNotConnectedError} if not connected`
`294`	`294`	`* @throws {SigningRejectedError} if user cancels`