epistery 1.3.8 → 1.4.0

package/src/chains/Chain.ts

@@ -0,0 +1,221 @@
+import { ethers } from 'ethers';
+import { ProviderConfig } from '../utils/types';
+
+/**
+ * Per-chain fee data, returned in the shape ethers v5 expects on a transaction.
+ * EIP-1559 chains return maxFeePerGas/maxPriorityFeePerGas.
+ * Legacy chains return gasPrice.
+ */
+export interface ChainFeeData {
+  maxFeePerGas?: ethers.BigNumber;
+  maxPriorityFeePerGas?: ethers.BigNumber;
+  gasPrice?: ethers.BigNumber;
+}
+
+/**
+ * Optional per-chain knobs that root config can override without editing code.
+ * Each subclass reads only what it cares about.
+ */
+export interface ChainPolicy {
+  // EIP-1559 floors (in gwei)
+  minPriorityFeeGwei?: number;
+  maxFeeMultiplier?: number;        // applied to max(networkMax, minPriority * 2)
+  // Legacy gas
+  minGasPriceGwei?: number;
+  // Gas limit estimation safety
+  gasLimitMultiplier?: number;      // applied to estimateGas result
+}
+
+/**
+ * Extended provider config that may carry per-chain policy + a private RPC URL.
+ * The plain `ProviderConfig` from utils/types stays the wire/storage shape;
+ * `ChainConfig` is what the Chain object actually holds in memory.
+ */
+export interface ChainConfig extends ProviderConfig {
+  publicRpc?: string;
+  privateRpc?: string;
+  policy?: ChainPolicy;
+}
+
+/**
+ * Base class for an EVM chain. Subclasses override only the policy hooks
+ * that are actually different from the EIP-1559 default.
+ *
+ * The Chain object owns:
+ *   - the JsonRpcProvider (with explicit network info, fixing "could not detect network")
+ *   - per-chain fee policy (getFeeData)
+ *   - the contract Proxy that injects fee data into write calls
+ *   - gas-limit estimation with a per-chain safety multiplier
+ *
+ * The Chain object does NOT own:
+ *   - wallets / private keys
+ *   - contract ABIs
+ *   - domain config storage
+ */
+export class Chain {
+  readonly chainId: number;
+  readonly name: string;
+  readonly rpc: string;                       // private/server-side RPC (with API key if any)
+  readonly publicRpc: string | undefined;     // public RPC (safe to expose to browsers)
+  readonly currency: { name: string; symbol: string; decimals: number };
+  readonly policy: ChainPolicy;
+
+  private _provider: ethers.providers.JsonRpcProvider | null = null;
+
+  constructor(config: ChainConfig) {
+    if (config.chainId == null) {
+      throw new Error(`Chain config missing chainId: ${JSON.stringify(config)}`);
+    }
+    this.chainId = Number(config.chainId);
+    this.name = config.name;
+    this.rpc = config.privateRpc || config.rpc;
+    this.publicRpc = config.publicRpc || config.rpc;
+    this.currency = {
+      name: config.nativeCurrencyName || '',
+      symbol: config.nativeCurrencySymbol || '',
+      decimals: config.nativeCurrencyDecimals || 18,
+    };
+    this.policy = config.policy || {};
+  }
+
+  /**
+   * Lazily-built provider with explicit network info.
+   * Passing `{ name, chainId }` to the JsonRpcProvider constructor avoids
+   * ethers' "could not detect network" error when the RPC is briefly
+   * unreachable at startup — ethers will skip its eth_chainId probe.
+   */
+  get provider(): ethers.providers.JsonRpcProvider {
+    if (!this._provider) {
+      this._provider = new ethers.providers.JsonRpcProvider(this.rpc, {
+        name: this.name,
+        chainId: this.chainId,
+      });
+    }
+    return this._provider;
+  }
+
+  /** EIP-1559 by default. Subclasses override for legacy gasPrice chains. */
+  supportsEIP1559(): boolean {
+    return true;
+  }
+
+  /**
+   * Default fee policy: pass through whatever the network reports via
+   * eth_feeHistory / eth_gasPrice. Subclasses override to apply per-chain
+   * floors (Polygon's 25 gwei priority floor, JOC's gasPrice floor, etc.).
+   */
+  async getFeeData(): Promise<ChainFeeData> {
+    const fd = await this.provider.getFeeData();
+    if (this.supportsEIP1559() && fd.maxFeePerGas && fd.maxPriorityFeePerGas) {
+      return {
+        maxFeePerGas: fd.maxFeePerGas,
+        maxPriorityFeePerGas: fd.maxPriorityFeePerGas,
+      };
+    }
+    if (fd.gasPrice) {
+      return { gasPrice: fd.gasPrice };
+    }
+    throw new Error(`Chain ${this.name} (${this.chainId}) returned no usable fee data`);
+  }
+
+  /**
+   * Estimate gas limit with this chain's safety multiplier.
+   * Used by callers that need to populate gasLimit explicitly (e.g. for
+   * pre-funding calculations). Most write calls will let ethers estimate
+   * automatically; this is for the cases where ethers' estimate is unsafe
+   * (Polygon Amoy, JOC) and a multiplier is required.
+   */
+  async estimateGas(
+    populated: ethers.providers.TransactionRequest
+  ): Promise<ethers.BigNumber> {
+    const estimate = await this.provider.estimateGas(populated);
+    const multiplier = this.policy.gasLimitMultiplier ?? 1.3;
+    // Multiply via integer math to stay in BigNumber-land.
+    const num = Math.round(multiplier * 100);
+    return estimate.mul(num).div(100);
+  }
+
+  /**
+   * Wrap an ethers.Contract so every state-mutating method automatically
+   * receives this chain's fee data as the transaction overrides argument.
+   *
+   * Uses Object.create (prototype chain) — the wrapper object gets its own
+   * writable properties for the write methods while reads of everything else
+   * (.address, .signer, view functions, .interface, etc.) fall through to
+   * the original contract via the prototype.
+   *
+   * Why not a Proxy: ethers v5 defines ABI methods with defineReadOnly
+   * (non-writable, non-configurable). V8's proxy invariant requires get
+   * traps to return the *original* value for such properties — returning a
+   * wrapped function throws TypeError. Object.create avoids this because
+   * the own properties on the child shadow the prototype's frozen ones.
+   *
+   * NOTE: epistery-host's DomainChain does NOT use this because all its
+   * write call sites already pass feeData explicitly. This method exists
+   * for other consumers (e.g. CLI tools, agents) that want automatic fee
+   * injection without threading overrides through every call.
+   *
+   * @param contract - the ethers.Contract instance
+   * @param abi - the same ABI used to construct the contract; needed to
+   *              identify which methods are state-mutating.
+   */
+  wrapContract<T extends ethers.Contract>(contract: T, abi: ReadonlyArray<any>): T {
+    const writeFns = new Set<string>();
+    for (const item of abi) {
+      if (item.type !== 'function') continue;
+      if (item.stateMutability === 'view' || item.stateMutability === 'pure') continue;
+      if (typeof item.name === 'string') writeFns.add(item.name);
+    }
+    const chain = this;
+    const wrapped = Object.create(contract);
+
+    for (const name of writeFns) {
+      const original = contract[name as keyof T];
+      if (typeof original !== 'function') continue;
+      Object.defineProperty(wrapped, name, {
+        value: async function (...args: any[]) {
+          let overrides: any;
+          const last = args[args.length - 1];
+          if (Chain.isOverridesObject(last)) {
+            const fee = await chain.getFeeData();
+            overrides = { ...fee, ...last };
+            args[args.length - 1] = overrides;
+          } else {
+            overrides = await chain.getFeeData();
+            args.push(overrides);
+          }
+          return (original as Function).apply(contract, args);
+        },
+        writable: true,
+        configurable: true,
+      });
+    }
+
+    return wrapped as T;
+  }
+
+  /**
+   * Recognize a transaction-overrides object so we don't mistake it for a
+   * positional argument. Excludes BigNumbers and arrays explicitly.
+   */
+  static isOverridesObject(x: any): boolean {
+    if (!x || typeof x !== 'object') return false;
+    if (Array.isArray(x)) return false;
+    if (ethers.BigNumber.isBigNumber(x)) return false;
+    return (
+      'gasPrice' in x ||
+      'maxFeePerGas' in x ||
+      'maxPriorityFeePerGas' in x ||
+      'gasLimit' in x ||
+      'nonce' in x ||
+      'value' in x ||
+      'from' in x ||
+      'type' in x
+    );
+  }
+
+  /** Convenience: gwei → BigNumber wei */
+  protected gwei(n: number): ethers.BigNumber {
+    return ethers.utils.parseUnits(String(n), 'gwei');
+  }
+}

package/src/chains/EthereumChain.ts

@@ -0,0 +1,23 @@
+import { Chain } from './Chain';
+import { registerChain } from './registry';
+
+/**
+ * Ethereum mainnet (chainId 1).
+ *
+ * Standard EIP-1559 behavior — ethers' getFeeData is accurate here.
+ * No floors, no special multipliers. The base class default works as-is;
+ * this subclass exists for the registry and for future overrides.
+ */
+export class EthereumChain extends Chain {
+  static chainId = 1;
+}
+
+/**
+ * Sepolia testnet (chainId 11155111). Same behavior as Ethereum mainnet.
+ */
+export class SepoliaChain extends Chain {
+  static chainId = 11155111;
+}
+
+registerChain(EthereumChain.chainId, EthereumChain);
+registerChain(SepoliaChain.chainId, SepoliaChain);

package/src/chains/JapanOpenChain.ts

@@ -0,0 +1,37 @@
+import { ethers } from 'ethers';
+import { Chain, ChainFeeData } from './Chain';
+import { registerChain } from './registry';
+
+/**
+ * Japan Open Chain (chainId 81).
+ *
+ * Why this class exists: JOC is a legacy gasPrice chain. Its base fee is
+ * effectively zero, but the RPC enforces a high *minimum* gas price (around
+ * 30 gwei). EIP-1559 fields are not honored — submitting a transaction with
+ * maxFeePerGas/maxPriorityFeePerGas instead of gasPrice gets rejected.
+ *
+ * The base class would happily try to use EIP-1559; we override
+ * supportsEIP1559() to false and return only `gasPrice`, clamped to the
+ * configured floor.
+ */
+export class JapanOpenChain extends Chain {
+  static chainId = 81;
+
+  supportsEIP1559(): boolean {
+    return false;
+  }
+
+  protected minGasPrice(): ethers.BigNumber {
+    return this.gwei(this.policy.minGasPriceGwei ?? 30);
+  }
+
+  async getFeeData(): Promise<ChainFeeData> {
+    const fd = await this.provider.getFeeData();
+    const floor = this.minGasPrice();
+    const networkPrice = fd.gasPrice ?? floor;
+    const gasPrice = networkPrice.gt(floor) ? networkPrice : floor;
+    return { gasPrice };
+  }
+}
+
+registerChain(JapanOpenChain.chainId, JapanOpenChain);

package/src/chains/PolygonChain.ts

@@ -0,0 +1,53 @@
+import { ethers } from 'ethers';
+import { Chain, ChainFeeData } from './Chain';
+import { registerChain } from './registry';
+
+/**
+ * Polygon mainnet (chainId 137).
+ *
+ * Why this class exists: Polygon enforces a hard 25 gwei minimum priority fee
+ * at the RPC level. Transactions submitted with a lower priority fee are
+ * rejected with "max fee per gas less than block base fee" or simply silently
+ * dropped. ethers v5's getFeeData() does NOT know about this floor and will
+ * happily return ~1.5 gwei from eth_feeHistory.
+ *
+ * The fix: clamp maxPriorityFeePerGas to at least 25 gwei (overridable via
+ * policy.minPriorityFeeGwei in root config) and ensure maxFeePerGas >=
+ * 2 * maxPriorityFeePerGas.
+ */
+export class PolygonChain extends Chain {
+  static chainId = 137;
+
+  protected minPriorityFee(): ethers.BigNumber {
+    return this.gwei(this.policy.minPriorityFeeGwei ?? 25);
+  }
+
+  async getFeeData(): Promise<ChainFeeData> {
+    const fd = await this.provider.getFeeData();
+    const floor = this.minPriorityFee();
+
+    const networkPriority = fd.maxPriorityFeePerGas ?? floor;
+    const maxPriorityFeePerGas = networkPriority.gt(floor) ? networkPriority : floor;
+
+    const multiplier = this.policy.maxFeeMultiplier ?? 2;
+    const minMaxFee = maxPriorityFeePerGas.mul(multiplier);
+    const networkMax = fd.maxFeePerGas ?? minMaxFee;
+    const maxFeePerGas = networkMax.gt(minMaxFee) ? networkMax : minMaxFee;
+
+    return { maxPriorityFeePerGas, maxFeePerGas };
+  }
+}
+
+/**
+ * Polygon Amoy testnet (chainId 80002).
+ *
+ * Same fee floor concerns as Polygon mainnet — Amoy is the canonical Polygon
+ * PoS testnet and the RPC enforces an identical 25 gwei priority floor.
+ * Subclassing PolygonChain keeps the policy in one place.
+ */
+export class AmoyChain extends PolygonChain {
+  static chainId = 80002;
+}
+
+registerChain(PolygonChain.chainId, PolygonChain);
+registerChain(AmoyChain.chainId, AmoyChain);

package/src/chains/README.md

@@ -0,0 +1,109 @@
+# `epistery/chains`
+
+Each EVM chain epistery talks to is represented by a `Chain` object. The
+`Chain` class owns everything chain-specific: the JSON-RPC provider, the fee
+policy, the gas-limit estimation strategy, and the contract Proxy that
+injects per-chain fee data into write transactions. Wallets, ABIs, and
+domain config storage are *not* the chain's job.
+
+## Adding a new chain
+
+A new chain is one file. No edits to `Chain.ts`, `registry.ts`, or any
+existing chain class.
+
+```ts
+// src/chains/MyNewChain.ts
+import { ethers } from 'ethers';
+import { Chain, ChainFeeData } from './Chain';
+import { registerChain } from './registry';
+
+export class MyNewChain extends Chain {
+  static chainId = 1234;
+
+  // Override only what's actually different from the EIP-1559 default.
+  // Skip this method entirely if the network behaves normally.
+  async getFeeData(): Promise<ChainFeeData> {
+    const fd = await this.provider.getFeeData();
+    // ... whatever this chain needs ...
+    return { maxFeePerGas: ..., maxPriorityFeePerGas: ... };
+  }
+}
+
+registerChain(MyNewChain.chainId, MyNewChain);
+```
+
+Then add **one** line to `src/chains/index.ts`:
+
+```ts
+export { MyNewChain } from './MyNewChain';
+```
+
+That export both makes the class importable and triggers the
+`registerChain()` call at module load.
+
+## Adding a chain *without* editing the package
+
+A downstream consumer (e.g. an agent, a host, an app) can register its own
+chain without forking epistery. Write the same kind of file in your own
+codebase, then `import` it once during startup:
+
+```ts
+import 'my-app/chains/MyNewChain';
+```
+
+The registry is a module-scoped `Map`, so the registration is idempotent
+and survives across the entire process.
+
+## What goes in a Chain subclass
+
+Override only the hooks that are actually different from the generic
+EIP-1559 default. The base class is intentionally usable as-is for any
+well-behaved EVM chain — you don't need a subclass to support a new chain
+unless that chain misbehaves in some way.
+
+| Hook                  | Why you'd override it                                          |
+| --------------------- | -------------------------------------------------------------- |
+| `getFeeData()`        | Network ignores `eth_feeHistory`, has a fee floor, etc.        |
+| `supportsEIP1559()`   | Legacy gasPrice-only chain (e.g. Japan Open Chain).            |
+| `estimateGas()`       | RPC's gas estimate is unreliable; need a different multiplier. |
+| `wrapContract()`      | Almost never. Only if the chain needs different override merging. |
+
+## Per-chain config knobs
+
+Each chain reads its policy knobs from the `policy` field of the provider
+config in epistery's root config file. These are *optional* — defaults are
+in code, so a fresh install Just Works:
+
+```ini
+[[default.providers]]
+name = "Polygon Mainnet"
+chainId = 137
+publicRpc = "https://polygon-rpc.com"
+privateRpc = "https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY"
+nativeCurrencyName = "POL"
+nativeCurrencySymbol = "POL"
+
+# These all live under [[default.providers.policy]] and are optional.
+[default.providers.policy]
+minPriorityFeeGwei = 25     # Polygon's RPC floor
+maxFeeMultiplier = 2        # maxFeePerGas >= 2 * maxPriorityFeePerGas
+gasLimitMultiplier = 1.3    # estimateGas safety margin
+```
+
+If you find yourself adding a new policy field, add it to `ChainPolicy` in
+`Chain.ts` and document it here. Don't smuggle ad-hoc fields in via casts.
+
+## What this replaces
+
+Before this module, gas/fee logic lived in three different places:
+
+1. `epistery/src/utils/Utils.ts` — `getGasPriceWithBuffer`, `addGasBuffer`,
+   `FALLBACK_GAS_LIMIT`, hard-coded constants for Polygon mainnet/Amoy.
+2. `epistery-host/utils/DomainChain.mjs` — a parallel `getFeeData()` and a
+   contract-mutation wrapper that crashed under ESM strict mode.
+3. Anywhere a developer constructed a bare `new ethers.providers.JsonRpcProvider(rpc)`
+   without an explicit network — the source of every "could not detect network"
+   warning in the logs.
+
+All three should call `chainFor(domainConfig.provider)` and use the
+returned `Chain` instance.

package/src/chains/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Chains module barrel.
+ *
+ * Exports the public API and pulls in the built-in chain subclasses for
+ * their side-effect (each subclass calls registerChain() at module load).
+ *
+ * Adding a new built-in chain: drop a `MyChain.ts` next to this file that
+ * extends Chain and calls `registerChain(MyChain.chainId, MyChain)` at the
+ * bottom, then add one `import './MyChain';` line below. No edits to
+ * Chain.ts or registry.ts.
+ *
+ * Adding a chain from outside this package: write the same kind of file in
+ * your own codebase and `import 'your-package/dist/chains/MyChain';` at app
+ * startup. The Map in registry.ts is module-scoped, so the registration
+ * happens exactly once.
+ */
+
+// Public API
+export { Chain, ChainConfig, ChainFeeData, ChainPolicy } from './Chain';
+export { chainFor, registerChain, hasRegisteredChain, registeredChainIds } from './registry';
+
+// Built-in chains — imported for their registerChain() side effect.
+// Re-exported so callers that want a concrete subclass (e.g. for instanceof
+// checks or to subclass it themselves) can import from the barrel.
+export { PolygonChain, AmoyChain } from './PolygonChain';
+export { EthereumChain, SepoliaChain } from './EthereumChain';
+export { JapanOpenChain } from './JapanOpenChain';

package/src/chains/registry.ts

@@ -0,0 +1,53 @@
+import { Chain, ChainConfig } from './Chain';
+
+type ChainCtor = new (config: ChainConfig) => Chain;
+
+/**
+ * Registry of chainId → Chain subclass.
+ *
+ * Adding a chain is a single-file operation: write `MyChain.ts` extending
+ * `Chain`, and at the bottom of that file call:
+ *
+ *     registerChain(MyChain.chainId, MyChain);
+ *
+ * Then ensure the file is imported once during startup (the built-in
+ * `chains/index.ts` does this for the chains shipped with the package; for
+ * downstream additions, just `import 'mypackage/chains/MyChain'` from your
+ * app entry point).
+ *
+ * No edits to this file or the barrel are required.
+ */
+const REGISTRY = new Map<number, ChainCtor>();
+
+/**
+ * Register a Chain subclass for a given chainId. Overwrites any existing
+ * entry — last write wins, so a downstream app can override a built-in if it
+ * wants different fee policy.
+ */
+export function registerChain(chainId: number, ctor: ChainCtor): void {
+  REGISTRY.set(Number(chainId), ctor);
+}
+
+/**
+ * Get a Chain instance for the given provider config. If no subclass is
+ * registered for the chainId, returns a generic Chain — which uses pure
+ * EIP-1559 with no floors and the standard estimateGas. That works for any
+ * well-behaved EVM chain; misbehaving chains need their own subclass.
+ */
+export function chainFor(config: ChainConfig): Chain {
+  if (config.chainId == null) {
+    throw new Error(`chainFor: provider config missing chainId: ${JSON.stringify(config)}`);
+  }
+  const Ctor = REGISTRY.get(Number(config.chainId)) || Chain;
+  return new Ctor(config);
+}
+
+/** Visible for tests / debug. Returns true if a chainId has a registered subclass. */
+export function hasRegisteredChain(chainId: number): boolean {
+  return REGISTRY.has(Number(chainId));
+}
+
+/** Visible for tests / debug. Returns the list of registered chainIds. */
+export function registeredChainIds(): number[] {
+  return Array.from(REGISTRY.keys());
+}

package/src/utils/Utils.ts

@@ -1,6 +1,7 @@
 import { BigNumberish, ethers, Wallet } from 'ethers';
 import { Config } from './Config';
 import { DomainConfig, RivetItem, Visibility } from './types';
+import { chainFor } from '../chains';
 import * as AgentArtifact from '../../artifacts/contracts/agent.sol/Agent.json';
 
 export class Utils {
@@ -87,8 +88,8 @@ export class Utils {
       }
 
       if (domainConfig.wallet) {
-        const provider = new ethers.providers.JsonRpcProvider(domainConfig.provider?.rpc);
-        this.serverWallet = ethers.Wallet.fromMnemonic(domainConfig.wallet.mnemonic).connect(provider);
+        const chain = chainFor(domainConfig.provider || { chainId: 137, name: 'Polygon Mainnet', rpc: 'https://polygon-rpc.com' });
+        this.serverWallet = ethers.Wallet.fromMnemonic(domainConfig.wallet.mnemonic).connect(chain.provider);
 
         console.log(`Server wallet initialized for domain: ${domain}`);
         console.log(`Wallet address: ${domainConfig.wallet.address}`);

package/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { Utils } from './Utils';
 export { Config } from './Config';
 export { CliWallet } from './CliWallet';
-export * from './types';
+export * from './types';
+export * from '../chains';