crypto-aio 0.0.3 → 0.2.0

package/dist/adapters/evm/rawtx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rawtx.js","sourceRoot":"","sources":["../../../src/adapters/evm/rawtx.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a node's rejection claims is checked against the bytes we sent,\n * read here SDK-free. The reader is never stricter than geth: it calls bytes `malformed`\n * only for what geth's RLP decoder also refuses (a broken or non-canonical encoding, an\n * integer with a leading zero or over 256 bits, the wrong number of fields, a `to` that is\n * not 20 bytes), and it reads no access list, so a claim it cannot confirm stays a refusal.\n */\nimport { fromHex } from '../../core/util/bytes';\n\n/** The fields a rejection check reads, of one signed legacy, EIP-2930 or EIP-1559 tx. */\nexport interface EvmSentTx {\n  readonly type: 0 | 1 | 2;\n  /** Absent for a legacy transaction signed without EIP-155 (v of 27 or 28). */\n  readonly chainId?: bigint;\n  readonly maxFeePerGas?: bigint;\n  readonly maxPriorityFeePerGas?: bigint;\n  /** The recovery id: `yParity`, or the legacy `v` reduced to 0 or 1; -1 when neither. */\n  readonly recovery: number;\n  readonly r: bigint;\n  readonly s: bigint;\n}\n\n/**\n * Twice geth's 128 KiB pool limit, checked before any decoding: a bare broadcast may\n * carry any bytes, and untrusted input is capped before it is decoded.\n */\nexport const MAX_SENT_BYTES = 2 * 128 * 1024;\n\nclass Malformed extends Error {}\ntype Item = Uint8Array | readonly Item[];\n\n/** One canonical RLP item at `at`, and the offset after it; throws `Malformed`. */\nfunction item(bytes: Uint8Array, at: number): [Item, number] {\n  const lead = bytes[at];\n  if (lead === undefined) throw new Malformed();\n  const span = (offset: number, length: number): [number, number] => {\n    const end = offset + length;\n    if (end > bytes.length) throw new Malformed();\n    return [offset, end];\n  };\n  const longLength = (width: number): number => {\n    const [start, end] = span(at + 1, width);\n    if (bytes[start] === 0) throw new Malformed();\n    let length = 0;\n    for (let i = start; i < end; i++) length = length * 256 + (bytes[i] as number);\n    if (length < 56) throw new Malformed();\n    return length;\n  };\n  if (lead < 0x80) return [bytes.subarray(at, at + 1), at + 1];\n  if (lead <= 0xbf) {\n    const long = lead > 0xb7;\n    const width = long ? lead - 0xb7 : 0;\n    const length = long ? longLength(width) : lead - 0x80;\n    const [start, end] = span(at + 1 + width, length);\n    if (!long && length === 1 && (bytes[start] as number) < 0x80) throw new Malformed();\n    return [bytes.subarray(start, end), end];\n  }\n  const long = lead > 0xf7;\n  const width = long ? lead - 0xf7 : 0;\n  const length = long ? longLength(width) : lead - 0xc0;\n  const [start, end] = span(at + 1 + width, length);\n  const items: Item[] = [];\n  for (let offset = start; offset < end;) {\n    const [next, after] = item(bytes, offset);\n    if (after > end) throw new Malformed();\n    items.push(next);\n    offset = after;\n  }\n  return [items, end];\n}\n\n/** A whole buffer as one list of exactly `fields` items. */\nfunction list(bytes: Uint8Array, fields: number): readonly Item[] {\n  const [value, end] = item(bytes, 0);\n  if (end !== bytes.length || !Array.isArray(value) || value.length !== fields)\n    throw new Malformed();\n  return value as readonly Item[];\n}\n\n/** A canonical unsigned integer of at most `bits` bits. */\nfunction uint(value: Item | undefined, bits: number): bigint {\n  if (!(value instanceof Uint8Array) || value.length * 8 > bits || value[0] === 0)\n    throw new Malformed();\n  let out = 0n;\n  for (const byte of value) out = (out << 8n) | BigInt(byte);\n  return out;\n}\n\nfunction address(value: Item | undefined): void {\n  if (!(value instanceof Uint8Array) || (value.length !== 0 && value.length !== 20))\n    throw new Malformed();\n}\n\n/**\n * The sent bytes as the checks read them: the fields, `'malformed'` when geth could not\n * decode them either, or `undefined` when they are unreadable here but may be valid (an\n * EIP-4844 or EIP-7702 transaction, or more than `MAX_SENT_BYTES`): no claim holds for those.\n */\nexport function readSentTx(hex: string): EvmSentTx | 'malformed' | undefined {\n  if (typeof hex !== 'string' || hex.length > 2 + 2 * MAX_SENT_BYTES) return undefined;\n  let bytes: Uint8Array;\n  try {\n    bytes = fromHex(hex);\n  } catch {\n    return 'malformed';\n  }\n  const type = bytes[0];\n  if (type === undefined) return 'malformed';\n  try {\n    if (type >= 0xc0) {\n      const [nonce, gasPrice, gas, to, value, , v, r, s] = list(bytes, 9);\n      uint(nonce, 64);\n      uint(gasPrice, 256);\n      uint(gas, 64);\n      address(to);\n      uint(value, 256);\n      const vv = uint(v, 256);\n      const eip155 = vv >= 35n;\n      return {\n        type: 0,\n        ...(eip155 ? { chainId: (vv - 35n) / 2n } : {}),\n        recovery: eip155\n          ? Number((vv - 35n) % 2n)\n          : vv === 27n || vv === 28n\n            ? Number(vv - 27n)\n            : -1,\n        r: uint(r, 256),\n        s: uint(s, 256),\n      };\n    }\n    if (type === 1 || type === 2) {\n      const fields = list(bytes.subarray(1), type === 1 ? 11 : 12);\n      const chainId = uint(fields[0], 256);\n      uint(fields[1], 64);\n      const prices = type === 2 ? [uint(fields[2], 256), uint(fields[3], 256)] : [];\n      if (type === 1) uint(fields[2], 256);\n      const rest = type === 1 ? 3 : 4;\n      uint(fields[rest], 64);\n      address(fields[rest + 1]);\n      uint(fields[rest + 2], 256);\n      const [yParity, r, s] = fields.slice(-3);\n      const parity = uint(yParity, 256);\n      return {\n        type,\n        chainId,\n        ...(type === 2\n          ? {\n              maxPriorityFeePerGas: prices[0] as bigint,\n              maxFeePerGas: prices[1] as bigint,\n            }\n          : {}),\n        recovery: parity <= 1n ? Number(parity) : -1,\n        r: uint(r, 256),\n        s: uint(s, 256),\n      };\n    }\n    // geth reads any other first byte above 0x7f as a legacy list, and fails.\n    if (type >= 0x80) return 'malformed';\n    return undefined;\n  } catch (error) {\n    if (error instanceof Malformed) return 'malformed';\n    throw error;\n  }\n}\n\n/** secp256k1's group order. */\nconst N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;\n\n/** geth's `ValidateSignatureValues` with Homestead's low-s rule, over the recovery id. */\nexport function signatureValuesValid(tx: EvmSentTx): boolean {\n  return (\n    (tx.recovery === 0 || tx.recovery === 1) &&\n    tx.r >= 1n &&\n    tx.r < N &&\n    tx.s >= 1n &&\n    tx.s <= N / 2n\n  );\n}\n"]}

package/dist/adapters/evm/reader.d.ts

@@ -0,0 +1,83 @@
+/**
+ * EVM addresses, reads, nonces, finality and the `ext.evm` API. Every call carries the tags
+ * of the `ChainDriver` contract table (`src/core/driver/types.ts`): `read` for point
+ * queries, `monitor` for heights, observations and nonces, and `proof` for the finality
+ * that proofs attest.
+ */
+import type { AddressCodec, ChainReader, DriverBlock, SequenceSource } from '../../core/driver/types';
+import type { Logger } from '../../core/events/logger';
+import type { ChainInfo, NetworkInfo } from '../../core/model/chain';
+import type { EvmNetworkConfig } from './network';
+import type { EvmBlock, EvmCallTags, EvmClient, EvmExt } from './types';
+/** What every EVM port is built from. */
+export interface EvmContext {
+    readonly client: EvmClient;
+    readonly chain: ChainInfo;
+    readonly network: NetworkInfo;
+    readonly config: EvmNetworkConfig;
+    readonly log: Logger;
+}
+export declare const READ: EvmCallTags;
+export declare const MONITOR: EvmCallTags;
+export declare const PROOF: EvmCallTags;
+export declare const withSignal: (tags: EvmCallTags, signal?: AbortSignal) => EvmCallTags;
+export declare function toDriverBlock(block: EvmBlock): DriverBlock;
+/** Whether a definitive (non-ambiguous) JSON-RPC error says the call reverted. */
+export declare function isRevert(error: unknown): boolean;
+/**
+ * How many blocks a proof's final height trails the one endpoint that proposed it, so
+ * a quorum peer up to this far behind that endpoint still attests it.
+ */
+export declare const PEER_SKEW = 2n;
+/**
+ * The highest final block as one endpoint sees it (a `monitor` view): the `finalized` tag,
+ * or the head minus the confirmations; the head read carries the signal of `tags`. Proofs
+ * never use it as a final height: `provenFinal` attests one.
+ */
+export declare function finalizedHeight(ctx: EvmContext, tags: EvmCallTags): Promise<bigint>;
+/**
+ * A height that is final on every endpoint of the proof quorum (`tags`), and the quorum's
+ * block at it when the proof read that block anyway. One endpoint's view (a `monitor` read)
+ * only proposes: the height trails it by `PEER_SKEW` blocks, and the quorum attests it. On
+ * tag networks every quorum endpoint's `finalized` block must be at or past it; on
+ * confirmation networks every one must hold the block that confirms it. So an
+ * endpoint that over-reports cannot advance finality, and a peer that trails the proposer
+ * by up to `PEER_SKEW` blocks still agrees.
+ */
+export declare function provenFinal(ctx: EvmContext, tags: EvmCallTags): Promise<{
+    readonly height: bigint;
+    readonly block?: EvmBlock;
+}>;
+/**
+ * The quorum's block at `height` when `height` is final on every endpoint of the proof
+ * quorum (`tags`), else `null`. Anchored at `height` itself, not at any endpoint's view:
+ * honest endpoints disagree only while `height` is final on one and not yet on another, and
+ * that decides nothing (a retryable `PROVIDER_INCONSISTENT`).
+ */
+export declare function finalBlockAt(ctx: EvmContext, height: bigint, tags: EvmCallTags): Promise<EvmBlock | null>;
+export declare function createEvmAddressCodec(client: EvmClient): AddressCodec;
+/** Whether a definitive (non-ambiguous) JSON-RPC error says the EVM stopped the code. */
+export declare function isExecutionFailure(error: unknown): boolean;
+/** An ERC-20 `balanceOf` at `latest`; `ASSET_RESOLUTION` when the contract gives none. */
+export declare function erc20Balance(client: EvmClient, token: string, owner: string, tags: EvmCallTags): Promise<bigint>;
+/**
+ * An `eth_call` at `latest` to a method the contract may lack: `null` when the call reverts
+ * or the VM stops it, as a call to a missing method does (the dispatcher reverts, or older
+ * code hits an invalid opcode). Any other JSON-RPC error is the node's and is rethrown
+ * retryable, and everything else propagates unchanged: a failed read is never an answer.
+ */
+export declare function callIfPresent(client: EvmClient, request: {
+    readonly to: string;
+    readonly data: string;
+}, tags: EvmCallTags): Promise<string | null>;
+/**
+ * Whether a token answers `deprecated()` with `true` at `latest`, as Tether's `TetherToken`
+ * does once its owner deprecates it for an upgraded contract (`upgradedAddress`). Only a
+ * definitive answer decides: a contract without the method (a revert, a VM failure, `0x`,
+ * or an answer that is not one ABI `bool`) is not deprecated, and a failed read throws
+ * (`callIfPresent`), so it is never taken for either answer.
+ */
+export declare function erc20Deprecated(client: EvmClient, token: string, tags: EvmCallTags): Promise<boolean>;
+export declare function createEvmReader(ctx: EvmContext): ChainReader;
+export declare function createEvmSequence(client: EvmClient): SequenceSource;
+export declare function createEvmExt(client: EvmClient): EvmExt;

package/dist/adapters/evm/reader.js

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PEER_SKEW = exports.withSignal = exports.PROOF = exports.MONITOR = exports.READ = void 0;
+exports.toDriverBlock = toDriverBlock;
+exports.isRevert = isRevert;
+exports.finalizedHeight = finalizedHeight;
+exports.provenFinal = provenFinal;
+exports.finalBlockAt = finalBlockAt;
+exports.createEvmAddressCodec = createEvmAddressCodec;
+exports.isExecutionFailure = isExecutionFailure;
+exports.erc20Balance = erc20Balance;
+exports.callIfPresent = callIfPresent;
+exports.erc20Deprecated = erc20Deprecated;
+exports.createEvmReader = createEvmReader;
+exports.createEvmSequence = createEvmSequence;
+exports.createEvmExt = createEvmExt;
+const error_1 = require("../../core/errors/error");
+const client_1 = require("./client");
+const decode_1 = require("./decode");
+exports.READ = { purpose: 'read', retry: 'safe' };
+exports.MONITOR = { purpose: 'monitor', retry: 'safe' };
+exports.PROOF = { purpose: 'proof', retry: 'safe', quorum: 'proof' };
+const withSignal = (tags, signal) => signal ? { ...tags, signal } : tags;
+exports.withSignal = withSignal;
+function toDriverBlock(block) {
+    return {
+        height: block.number,
+        hash: block.hash,
+        parentHash: block.parentHash,
+        timestamp: block.timestamp,
+        transactionIds: block.transactions,
+    };
+}
+/** Whether a definitive (non-ambiguous) JSON-RPC error says the call reverted. */
+function isRevert(error) {
+    if (!(0, error_1.isCryptoAioError)(error, 'RPC_ERROR') || error.ambiguous)
+        return false;
+    const { rpcCode, rpcMessage } = error.details ?? {};
+    return rpcCode === 3 || /revert/i.test(String(rpcMessage ?? error.message));
+}
+/**
+ * How many blocks a proof's final height trails the one endpoint that proposed it, so
+ * a quorum peer up to this far behind that endpoint still attests it.
+ */
+exports.PEER_SKEW = 2n;
+/** `height - depth`, or genesis. */
+const below = (height, depth) => height > depth ? height - depth : 0n;
+/**
+ * A quorum key under which every endpoint whose block is at or past `height` agrees,
+ * so honest endpoints at different heights agree, and one that is not there disagrees.
+ * A malformed answer throws, which the transport counts as a disagreement.
+ */
+const atOrPast = (height) => (result) => result !== null &&
+    (0, client_1.quantity)(result.number, 'block number') >= height;
+/** Whether every quorum endpoint's `finalized` block is at or past `height`. */
+async function finalizedAtOrPast(ctx, height, tags) {
+    const block = await ctx.client.getBlock('finalized', {
+        ...tags,
+        quorumKey: atOrPast(height),
+    });
+    // The endpoints agreed on the predicate, so the first one's block states it for all.
+    return block !== null && block.number >= height;
+}
+/**
+ * The highest final block as one endpoint sees it (a `monitor` view): the `finalized` tag,
+ * or the head minus the confirmations; the head read carries the signal of `tags`. Proofs
+ * never use it as a final height: `provenFinal` attests one.
+ */
+async function finalizedHeight(ctx, tags) {
+    const { finality } = ctx.config;
+    if (finality.kind === 'confirmations') {
+        const head = await ctx.client.blockNumber((0, exports.withSignal)(exports.MONITOR, tags.signal));
+        return below(head, BigInt(finality.confirmations - 1));
+    }
+    const block = await ctx.client.getBlock('finalized', tags);
+    if (!block) {
+        throw new error_1.ProviderError('PROVIDER_UNAVAILABLE', 'the endpoint reports no finalized block');
+    }
+    return block.number;
+}
+/**
+ * A height that is final on every endpoint of the proof quorum (`tags`), and the quorum's
+ * block at it when the proof read that block anyway. One endpoint's view (a `monitor` read)
+ * only proposes: the height trails it by `PEER_SKEW` blocks, and the quorum attests it. On
+ * tag networks every quorum endpoint's `finalized` block must be at or past it; on
+ * confirmation networks every one must hold the block that confirms it. So an
+ * endpoint that over-reports cannot advance finality, and a peer that trails the proposer
+ * by up to `PEER_SKEW` blocks still agrees.
+ */
+async function provenFinal(ctx, tags) {
+    const { finality } = ctx.config;
+    const view = (0, exports.withSignal)(exports.MONITOR, tags.signal);
+    if (finality.kind === 'confirmations') {
+        const confirming = below(await ctx.client.blockNumber(view), exports.PEER_SKEW);
+        const block = await ctx.client.getBlock(confirming, tags);
+        if (block?.number !== confirming) {
+            throw new error_1.ProviderError('PROVIDER_INCONSISTENT', 'the endpoints do not hold the confirming block');
+        }
+        const height = below(confirming, BigInt(finality.confirmations - 1));
+        return height === confirming ? { height, block } : { height };
+    }
+    const height = below(await finalizedHeight(ctx, view), exports.PEER_SKEW);
+    if (!(await finalizedAtOrPast(ctx, height, tags))) {
+        throw new error_1.ProviderError('PROVIDER_INCONSISTENT', 'the endpoints do not attest the proposed finalized block');
+    }
+    return { height };
+}
+/**
+ * The quorum's block at `height` when `height` is final on every endpoint of the proof
+ * quorum (`tags`), else `null`. Anchored at `height` itself, not at any endpoint's view:
+ * honest endpoints disagree only while `height` is final on one and not yet on another, and
+ * that decides nothing (a retryable `PROVIDER_INCONSISTENT`).
+ */
+async function finalBlockAt(ctx, height, tags) {
+    const { client } = ctx;
+    const { finality } = ctx.config;
+    if (finality.kind === 'tag') {
+        if (!(await finalizedAtOrPast(ctx, height, tags)))
+            return null;
+        return client.getBlock(height, tags);
+    }
+    // The block that gives `height` its confirmations; with one, it is `height`'s own.
+    const depth = BigInt(finality.confirmations - 1);
+    const confirming = await client.getBlock(height + depth, tags);
+    if (confirming === null)
+        return null;
+    return depth === 0n ? confirming : client.getBlock(height, tags);
+}
+function createEvmAddressCodec(client) {
+    return {
+        validate: (value) => client.isAddress(value),
+        normalize: (value) => {
+            if (!client.isAddress(value)) {
+                throw new error_1.ValidationError('INVALID_ADDRESS', 'not an EVM address');
+            }
+            const canonical = client.checksum(value);
+            return { canonical, display: canonical };
+        },
+        fromPublicKey: (publicKey) => {
+            // The client's strict decode already throws a specific `INVALID_ADDRESS`.
+            const canonical = client.addressFromPublicKey(publicKey);
+            return { canonical, display: canonical };
+        },
+    };
+}
+const assetError = (reason) => new error_1.ValidationError('ASSET_RESOLUTION', reason);
+/** geth's texts for an EVM that stopped the called code itself (`core/vm/errors.go`). */
+const VM_FAILURE = /^(out of gas|invalid opcode|invalid jump destination|stack (underflow|limit reached)|write protection|return data out of bounds)/i;
+/** Whether a definitive (non-ambiguous) JSON-RPC error says the EVM stopped the code. */
+function isExecutionFailure(error) {
+    if (!(0, error_1.isCryptoAioError)(error, 'RPC_ERROR') || error.ambiguous)
+        return false;
+    const { rpcMessage } = error.details ?? {};
+    return typeof rpcMessage === 'string' && VM_FAILURE.test(rpcMessage);
+}
+/** An ERC-20 `balanceOf` at `latest`; `ASSET_RESOLUTION` when the contract gives none. */
+async function erc20Balance(client, token, owner, tags) {
+    const data = await client.call({ to: token, data: client.abi.encodeBalanceOf(owner) }, 'latest', tags);
+    try {
+        return client.abi.decodeUint256(data);
+    }
+    catch {
+        throw assetError('the token contract returned no balance');
+    }
+}
+/**
+ * An `eth_call` at `latest` to a method the contract may lack: `null` when the call reverts
+ * or the VM stops it, as a call to a missing method does (the dispatcher reverts, or older
+ * code hits an invalid opcode). Any other JSON-RPC error is the node's and is rethrown
+ * retryable, and everything else propagates unchanged: a failed read is never an answer.
+ */
+async function callIfPresent(client, request, tags) {
+    try {
+        return await client.call(request, 'latest', tags);
+    }
+    catch (error) {
+        if (isRevert(error) || isExecutionFailure(error))
+            return null;
+        if ((0, error_1.isCryptoAioError)(error, 'RPC_ERROR')) {
+            throw (0, error_1.withContext)(error, {}, { retryable: true });
+        }
+        throw error;
+    }
+}
+/** An ABI `bool` that is `true`: one word, exactly 1 (`call` answers lower-case). */
+const TRUE_WORD = /^0x0{63}1$/;
+/**
+ * Whether a token answers `deprecated()` with `true` at `latest`, as Tether's `TetherToken`
+ * does once its owner deprecates it for an upgraded contract (`upgradedAddress`). Only a
+ * definitive answer decides: a contract without the method (a revert, a VM failure, `0x`,
+ * or an answer that is not one ABI `bool`) is not deprecated, and a failed read throws
+ * (`callIfPresent`), so it is never taken for either answer.
+ */
+async function erc20Deprecated(client, token, tags) {
+    const data = await callIfPresent(client, { to: token, data: client.abi.encodeDeprecated() }, tags);
+    return data !== null && TRUE_WORD.test(data);
+}
+function tokenOf(asset) {
+    if (asset === 'native' || asset.standard !== 'erc20') {
+        throw assetError(`EVM tokens use the 'erc20' standard`);
+    }
+    return asset.contract;
+}
+/** The text of an ABI `string`, or of a `bytes32` (older tokens such as MKR return one). */
+function symbolText(client, data) {
+    try {
+        return client.abi.decodeString(data);
+    }
+    catch {
+        if (!/^0x[0-9a-fA-F]{64}$/.test(data))
+            throw assetError('the token symbol is unreadable');
+        return Buffer.from(data.slice(2), 'hex').toString('utf8').replace(/\0+$/, '');
+    }
+}
+/**
+ * Token metadata is read under the proof quorum, stricter than the contract table's
+ * minimum. The core caches it for the container's life, and one endpoint's wrong `decimals`
+ * (a lagging, misrouted or buggy backend) would mis-scale every amount by orders of
+ * magnitude until restart. `decimals` never changes, so honest endpoints always agree.
+ */
+const METADATA = { ...exports.READ, quorum: 'proof' };
+function createEvmReader(ctx) {
+    const { client } = ctx;
+    /**
+     * A revert or a VM execution failure is the token's own permanent problem
+     * (`ASSET_RESOLUTION`, which the core caches until restart, even if the call would
+     * later run). Any other JSON-RPC error is the node's, so it is rethrown retryable: a
+     * provider fault never pins a token. Everything else propagates unchanged: a
+     * misconfigured endpoint stays final, and a retryable failure is already retryable.
+     */
+    const tokenCall = async (contract, data) => {
+        try {
+            return await client.call({ to: contract, data }, 'latest', METADATA);
+        }
+        catch (error) {
+            if (isRevert(error))
+                throw assetError('the token contract reverted');
+            if (isExecutionFailure(error))
+                throw assetError('the token contract failed to run');
+            if ((0, error_1.isCryptoAioError)(error, 'RPC_ERROR')) {
+                throw (0, error_1.withContext)(error, {}, { retryable: true });
+            }
+            throw error;
+        }
+    };
+    return {
+        getBalance: async (address, asset) => {
+            if (asset === 'native')
+                return client.getBalance(address, 'latest', exports.READ);
+            return erc20Balance(client, tokenOf(asset), address, exports.READ);
+        },
+        getBlockHeight: () => client.blockNumber(exports.MONITOR),
+        getFinalizedHeight: () => finalizedHeight(ctx, exports.MONITOR),
+        getBlock: async (ref) => {
+            const block = await client.getBlock(ref, exports.READ);
+            return block ? toDriverBlock(block) : null;
+        },
+        getTransaction: async (id) => {
+            const tx = await client.getTransaction(id, exports.READ);
+            if (!tx)
+                return null;
+            const receipt = tx.blockHash !== null ? await client.getReceipt(id, exports.READ) : null;
+            return (0, decode_1.decodeTransaction)(client.abi, tx, receipt, undefined, ctx.config);
+        },
+        /**
+         * With an ordering, the token verdict on one of our own Attempts. Without one (a
+         * status lookup by id, for a transaction the library does not manage) the chain's
+         * view, so a third party's call that shares the `transfer` selector is not reported
+         * failed.
+         */
+        observe: async (ref, ordering) => {
+            const tx = await client.getTransaction(ref.id, exports.MONITOR);
+            if (!tx)
+                return { seen: 'none' };
+            const receipt = tx.blockHash === null ? null : await client.getReceipt(ref.id, exports.MONITOR);
+            return ordering === undefined
+                ? (0, decode_1.chainObservation)(tx, receipt)
+                : (0, decode_1.evmObservation)(client.abi, tx, receipt);
+        },
+        getTokenMetadata: async (ref) => {
+            const contract = tokenOf(ref);
+            const decimalsData = await tokenCall(contract, client.abi.encodeDecimals());
+            if (decimalsData === '0x')
+                throw assetError('no token contract at this address');
+            let decimals;
+            try {
+                decimals = client.abi.decodeUint256(decimalsData);
+            }
+            catch {
+                throw assetError('the token decimals are unreadable');
+            }
+            if (decimals > 255n)
+                throw assetError('the token decimals are out of range');
+            const symbol = symbolText(client, await tokenCall(contract, client.abi.encodeSymbol()));
+            if (!symbol)
+                throw assetError('the token has no symbol');
+            return { symbol, decimals: Number(decimals) };
+        },
+        normalizeTokenRef: (ref) => {
+            const contract = tokenOf(ref);
+            if (!client.isAddress(contract))
+                throw assetError('not an EVM contract address');
+            return { standard: 'erc20', contract: client.checksum(contract) };
+        },
+    };
+}
+function createEvmSequence(client) {
+    return {
+        pending: (address) => client.getTransactionCount(address, 'pending', exports.MONITOR),
+        latest: (address) => client.getTransactionCount(address, 'latest', exports.MONITOR),
+    };
+}
+function createEvmExt(client) {
+    return {
+        evm: {
+            getNonce: async (address, block = 'latest') => {
+                if (block !== 'latest' && block !== 'pending') {
+                    throw new error_1.ValidationError('INVALID_INTENT', `block must be 'latest' or 'pending'`);
+                }
+                const codec = createEvmAddressCodec(client);
+                return client.getTransactionCount(codec.normalize(address).canonical, block, exports.READ);
+            },
+        },
+    };
+}
+//# sourceMappingURL=reader.js.map

package/dist/adapters/evm/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../../src/adapters/evm/reader.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * EVM addresses, reads, nonces, finality and the `ext.evm` API. Every call carries the tags\n * of the `ChainDriver` contract table (`src/core/driver/types.ts`): `read` for point\n * queries, `monitor` for heights, observations and nonces, and `proof` for the finality\n * that proofs attest.\n */\nimport type {\n  AddressCodec,\n  ChainReader,\n  DriverBlock,\n  SequenceSource,\n} from '../../core/driver/types';\nimport {\n  ProviderError,\n  ValidationError,\n  isCryptoAioError,\n  withContext,\n} from '../../core/errors/error';\nimport type { Logger } from '../../core/events/logger';\nimport type { AssetMetadata, AssetRef, TokenRef } from '../../core/model/asset';\nimport type { ChainInfo, NetworkInfo } from '../../core/model/chain';\nimport { quantity } from './client';\nimport { chainObservation, decodeTransaction, evmObservation } from './decode';\nimport type { EvmNetworkConfig } from './network';\nimport type { EvmBlock, EvmCallTags, EvmClient, EvmExt } from './types';\n\n/** What every EVM port is built from. */\nexport interface EvmContext {\n  readonly client: EvmClient;\n  readonly chain: ChainInfo;\n  readonly network: NetworkInfo;\n  readonly config: EvmNetworkConfig;\n  readonly log: Logger;\n}\n\nexport const READ: EvmCallTags = { purpose: 'read', retry: 'safe' };\nexport const MONITOR: EvmCallTags = { purpose: 'monitor', retry: 'safe' };\nexport const PROOF: EvmCallTags = { purpose: 'proof', retry: 'safe', quorum: 'proof' };\n\nexport const withSignal = (tags: EvmCallTags, signal?: AbortSignal): EvmCallTags =>\n  signal ? { ...tags, signal } : tags;\n\nexport function toDriverBlock(block: EvmBlock): DriverBlock {\n  return {\n    height: block.number,\n    hash: block.hash,\n    parentHash: block.parentHash,\n    timestamp: block.timestamp,\n    transactionIds: block.transactions,\n  };\n}\n\n/** Whether a definitive (non-ambiguous) JSON-RPC error says the call reverted. */\nexport function isRevert(error: unknown): boolean {\n  if (!isCryptoAioError(error, 'RPC_ERROR') || error.ambiguous) return false;\n  const { rpcCode, rpcMessage } = error.details ?? {};\n  return rpcCode === 3 || /revert/i.test(String(rpcMessage ?? error.message));\n}\n\n/**\n * How many blocks a proof's final height trails the one endpoint that proposed it, so\n * a quorum peer up to this far behind that endpoint still attests it.\n */\nexport const PEER_SKEW = 2n;\n\n/** `height - depth`, or genesis. */\nconst below = (height: bigint, depth: bigint): bigint =>\n  height > depth ? height - depth : 0n;\n\n/**\n * A quorum key under which every endpoint whose block is at or past `height` agrees,\n * so honest endpoints at different heights agree, and one that is not there disagrees.\n * A malformed answer throws, which the transport counts as a disagreement.\n */\nconst atOrPast =\n  (height: bigint) =>\n  (result: unknown): boolean =>\n    result !== null &&\n    quantity((result as { readonly number?: unknown }).number, 'block number') >= height;\n\n/** Whether every quorum endpoint's `finalized` block is at or past `height`. */\nasync function finalizedAtOrPast(\n  ctx: EvmContext,\n  height: bigint,\n  tags: EvmCallTags,\n): Promise<boolean> {\n  const block = await ctx.client.getBlock('finalized', {\n    ...tags,\n    quorumKey: atOrPast(height),\n  });\n  // The endpoints agreed on the predicate, so the first one's block states it for all.\n  return block !== null && block.number >= height;\n}\n\n/**\n * The highest final block as one endpoint sees it (a `monitor` view): the `finalized` tag,\n * or the head minus the confirmations; the head read carries the signal of `tags`. Proofs\n * never use it as a final height: `provenFinal` attests one.\n */\nexport async function finalizedHeight(\n  ctx: EvmContext,\n  tags: EvmCallTags,\n): Promise<bigint> {\n  const { finality } = ctx.config;\n  if (finality.kind === 'confirmations') {\n    const head = await ctx.client.blockNumber(withSignal(MONITOR, tags.signal));\n    return below(head, BigInt(finality.confirmations - 1));\n  }\n  const block = await ctx.client.getBlock('finalized', tags);\n  if (!block) {\n    throw new ProviderError(\n      'PROVIDER_UNAVAILABLE',\n      'the endpoint reports no finalized block',\n    );\n  }\n  return block.number;\n}\n\n/**\n * A height that is final on every endpoint of the proof quorum (`tags`), and the quorum's\n * block at it when the proof read that block anyway. One endpoint's view (a `monitor` read)\n * only proposes: the height trails it by `PEER_SKEW` blocks, and the quorum attests it. On\n * tag networks every quorum endpoint's `finalized` block must be at or past it; on\n * confirmation networks every one must hold the block that confirms it. So an\n * endpoint that over-reports cannot advance finality, and a peer that trails the proposer\n * by up to `PEER_SKEW` blocks still agrees.\n */\nexport async function provenFinal(\n  ctx: EvmContext,\n  tags: EvmCallTags,\n): Promise<{ readonly height: bigint; readonly block?: EvmBlock }> {\n  const { finality } = ctx.config;\n  const view = withSignal(MONITOR, tags.signal);\n  if (finality.kind === 'confirmations') {\n    const confirming = below(await ctx.client.blockNumber(view), PEER_SKEW);\n    const block = await ctx.client.getBlock(confirming, tags);\n    if (block?.number !== confirming) {\n      throw new ProviderError(\n        'PROVIDER_INCONSISTENT',\n        'the endpoints do not hold the confirming block',\n      );\n    }\n    const height = below(confirming, BigInt(finality.confirmations - 1));\n    return height === confirming ? { height, block } : { height };\n  }\n  const height = below(await finalizedHeight(ctx, view), PEER_SKEW);\n  if (!(await finalizedAtOrPast(ctx, height, tags))) {\n    throw new ProviderError(\n      'PROVIDER_INCONSISTENT',\n      'the endpoints do not attest the proposed finalized block',\n    );\n  }\n  return { height };\n}\n\n/**\n * The quorum's block at `height` when `height` is final on every endpoint of the proof\n * quorum (`tags`), else `null`. Anchored at `height` itself, not at any endpoint's view:\n * honest endpoints disagree only while `height` is final on one and not yet on another, and\n * that decides nothing (a retryable `PROVIDER_INCONSISTENT`).\n */\nexport async function finalBlockAt(\n  ctx: EvmContext,\n  height: bigint,\n  tags: EvmCallTags,\n): Promise<EvmBlock | null> {\n  const { client } = ctx;\n  const { finality } = ctx.config;\n  if (finality.kind === 'tag') {\n    if (!(await finalizedAtOrPast(ctx, height, tags))) return null;\n    return client.getBlock(height, tags);\n  }\n  // The block that gives `height` its confirmations; with one, it is `height`'s own.\n  const depth = BigInt(finality.confirmations - 1);\n  const confirming = await client.getBlock(height + depth, tags);\n  if (confirming === null) return null;\n  return depth === 0n ? confirming : client.getBlock(height, tags);\n}\n\nexport function createEvmAddressCodec(client: EvmClient): AddressCodec {\n  return {\n    validate: (value) => client.isAddress(value),\n    normalize: (value) => {\n      if (!client.isAddress(value)) {\n        throw new ValidationError('INVALID_ADDRESS', 'not an EVM address');\n      }\n      const canonical = client.checksum(value);\n      return { canonical, display: canonical };\n    },\n    fromPublicKey: (publicKey) => {\n      // The client's strict decode already throws a specific `INVALID_ADDRESS`.\n      const canonical = client.addressFromPublicKey(publicKey);\n      return { canonical, display: canonical };\n    },\n  };\n}\n\nconst assetError = (reason: string) => new ValidationError('ASSET_RESOLUTION', reason);\n\n/** geth's texts for an EVM that stopped the called code itself (`core/vm/errors.go`). */\nconst VM_FAILURE =\n  /^(out of gas|invalid opcode|invalid jump destination|stack (underflow|limit reached)|write protection|return data out of bounds)/i;\n\n/** Whether a definitive (non-ambiguous) JSON-RPC error says the EVM stopped the code. */\nexport function isExecutionFailure(error: unknown): boolean {\n  if (!isCryptoAioError(error, 'RPC_ERROR') || error.ambiguous) return false;\n  const { rpcMessage } = error.details ?? {};\n  return typeof rpcMessage === 'string' && VM_FAILURE.test(rpcMessage);\n}\n\n/** An ERC-20 `balanceOf` at `latest`; `ASSET_RESOLUTION` when the contract gives none. */\nexport async function erc20Balance(\n  client: EvmClient,\n  token: string,\n  owner: string,\n  tags: EvmCallTags,\n): Promise<bigint> {\n  const data = await client.call(\n    { to: token, data: client.abi.encodeBalanceOf(owner) },\n    'latest',\n    tags,\n  );\n  try {\n    return client.abi.decodeUint256(data);\n  } catch {\n    throw assetError('the token contract returned no balance');\n  }\n}\n\n/**\n * An `eth_call` at `latest` to a method the contract may lack: `null` when the call reverts\n * or the VM stops it, as a call to a missing method does (the dispatcher reverts, or older\n * code hits an invalid opcode). Any other JSON-RPC error is the node's and is rethrown\n * retryable, and everything else propagates unchanged: a failed read is never an answer.\n */\nexport async function callIfPresent(\n  client: EvmClient,\n  request: { readonly to: string; readonly data: string },\n  tags: EvmCallTags,\n): Promise<string | null> {\n  try {\n    return await client.call(request, 'latest', tags);\n  } catch (error) {\n    if (isRevert(error) || isExecutionFailure(error)) return null;\n    if (isCryptoAioError(error, 'RPC_ERROR')) {\n      throw withContext(error, {}, { retryable: true });\n    }\n    throw error;\n  }\n}\n\n/** An ABI `bool` that is `true`: one word, exactly 1 (`call` answers lower-case). */\nconst TRUE_WORD = /^0x0{63}1$/;\n\n/**\n * Whether a token answers `deprecated()` with `true` at `latest`, as Tether's `TetherToken`\n * does once its owner deprecates it for an upgraded contract (`upgradedAddress`). Only a\n * definitive answer decides: a contract without the method (a revert, a VM failure, `0x`,\n * or an answer that is not one ABI `bool`) is not deprecated, and a failed read throws\n * (`callIfPresent`), so it is never taken for either answer.\n */\nexport async function erc20Deprecated(\n  client: EvmClient,\n  token: string,\n  tags: EvmCallTags,\n): Promise<boolean> {\n  const data = await callIfPresent(\n    client,\n    { to: token, data: client.abi.encodeDeprecated() },\n    tags,\n  );\n  return data !== null && TRUE_WORD.test(data);\n}\n\nfunction tokenOf(asset: AssetRef): string {\n  if (asset === 'native' || asset.standard !== 'erc20') {\n    throw assetError(`EVM tokens use the 'erc20' standard`);\n  }\n  return asset.contract;\n}\n\n/** The text of an ABI `string`, or of a `bytes32` (older tokens such as MKR return one). */\nfunction symbolText(client: EvmClient, data: string): string {\n  try {\n    return client.abi.decodeString(data);\n  } catch {\n    if (!/^0x[0-9a-fA-F]{64}$/.test(data))\n      throw assetError('the token symbol is unreadable');\n    return Buffer.from(data.slice(2), 'hex').toString('utf8').replace(/\\0+$/, '');\n  }\n}\n\n/**\n * Token metadata is read under the proof quorum, stricter than the contract table's\n * minimum. The core caches it for the container's life, and one endpoint's wrong `decimals`\n * (a lagging, misrouted or buggy backend) would mis-scale every amount by orders of\n * magnitude until restart. `decimals` never changes, so honest endpoints always agree.\n */\nconst METADATA: EvmCallTags = { ...READ, quorum: 'proof' };\n\nexport function createEvmReader(ctx: EvmContext): ChainReader {\n  const { client } = ctx;\n  /**\n   * A revert or a VM execution failure is the token's own permanent problem\n   * (`ASSET_RESOLUTION`, which the core caches until restart, even if the call would\n   * later run). Any other JSON-RPC error is the node's, so it is rethrown retryable: a\n   * provider fault never pins a token. Everything else propagates unchanged: a\n   * misconfigured endpoint stays final, and a retryable failure is already retryable.\n   */\n  const tokenCall = async (contract: string, data: string): Promise<string> => {\n    try {\n      return await client.call({ to: contract, data }, 'latest', METADATA);\n    } catch (error) {\n      if (isRevert(error)) throw assetError('the token contract reverted');\n      if (isExecutionFailure(error)) throw assetError('the token contract failed to run');\n      if (isCryptoAioError(error, 'RPC_ERROR')) {\n        throw withContext(error, {}, { retryable: true });\n      }\n      throw error;\n    }\n  };\n\n  return {\n    getBalance: async (address, asset) => {\n      if (asset === 'native') return client.getBalance(address, 'latest', READ);\n      return erc20Balance(client, tokenOf(asset), address, READ);\n    },\n    getBlockHeight: () => client.blockNumber(MONITOR),\n    getFinalizedHeight: () => finalizedHeight(ctx, MONITOR),\n    getBlock: async (ref) => {\n      const block = await client.getBlock(ref, READ);\n      return block ? toDriverBlock(block) : null;\n    },\n    getTransaction: async (id) => {\n      const tx = await client.getTransaction(id, READ);\n      if (!tx) return null;\n      const receipt = tx.blockHash !== null ? await client.getReceipt(id, READ) : null;\n      return decodeTransaction(client.abi, tx, receipt, undefined, ctx.config);\n    },\n    /**\n     * With an ordering, the token verdict on one of our own Attempts. Without one (a\n     * status lookup by id, for a transaction the library does not manage) the chain's\n     * view, so a third party's call that shares the `transfer` selector is not reported\n     * failed.\n     */\n    observe: async (ref, ordering) => {\n      const tx = await client.getTransaction(ref.id, MONITOR);\n      if (!tx) return { seen: 'none' };\n      const receipt =\n        tx.blockHash === null ? null : await client.getReceipt(ref.id, MONITOR);\n      return ordering === undefined\n        ? chainObservation(tx, receipt)\n        : evmObservation(client.abi, tx, receipt);\n    },\n    getTokenMetadata: async (ref: TokenRef): Promise<AssetMetadata> => {\n      const contract = tokenOf(ref);\n      const decimalsData = await tokenCall(contract, client.abi.encodeDecimals());\n      if (decimalsData === '0x') throw assetError('no token contract at this address');\n      let decimals: bigint;\n      try {\n        decimals = client.abi.decodeUint256(decimalsData);\n      } catch {\n        throw assetError('the token decimals are unreadable');\n      }\n      if (decimals > 255n) throw assetError('the token decimals are out of range');\n      const symbol = symbolText(\n        client,\n        await tokenCall(contract, client.abi.encodeSymbol()),\n      );\n      if (!symbol) throw assetError('the token has no symbol');\n      return { symbol, decimals: Number(decimals) };\n    },\n    normalizeTokenRef: (ref) => {\n      const contract = tokenOf(ref);\n      if (!client.isAddress(contract)) throw assetError('not an EVM contract address');\n      return { standard: 'erc20', contract: client.checksum(contract) };\n    },\n  };\n}\n\nexport function createEvmSequence(client: EvmClient): SequenceSource {\n  return {\n    pending: (address) => client.getTransactionCount(address, 'pending', MONITOR),\n    latest: (address) => client.getTransactionCount(address, 'latest', MONITOR),\n  };\n}\n\nexport function createEvmExt(client: EvmClient): EvmExt {\n  return {\n    evm: {\n      getNonce: async (address, block = 'latest') => {\n        if (block !== 'latest' && block !== 'pending') {\n          throw new ValidationError(\n            'INVALID_INTENT',\n            `block must be 'latest' or 'pending'`,\n          );\n        }\n        const codec = createEvmAddressCodec(client);\n        return client.getTransactionCount(\n          codec.normalize(address).canonical,\n          block,\n          READ,\n        );\n      },\n    },\n  };\n}\n"]}

package/dist/adapters/evm/rpc.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The clients' common path to the core transport. `EthersClient` (directly) and
+ * `Web3Client` (through its EIP-1193 `request` object) end here, so each JSON-RPC
+ * call carries the purpose, retry class, quorum, fanout and signal of the driver method that
+ * made it.
+ */
+import type { Transport } from '../../core/transport/types';
+import type { EvmCallTags } from './types';
+/**
+ * The consensus facts of a block read with its transactions to find the one that
+ * consumed a nonce: the block's number and hash, and each transaction's hash, sender and
+ * nonce, with the recipient and calldata that the token verdict reads.
+ */
+export declare function blockTransactionsKey(result: unknown): unknown;
+/**
+ * The tags of a `crypto-aio/native` client's request: plain reads, except a broadcast, which
+ * is one: a failure after the transport may have delivered it is `ambiguous`, never an
+ * invitation to sign again with a new nonce.
+ */
+export declare const nativeTags: (method: string) => EvmCallTags;
+/**
+ * The consensus facts compared under a quorum, per JSON-RPC method. Node implementations
+ * return extra or differently formatted fields (`size`, `totalDifficulty`, L2 extras), so a
+ * quorum over whole objects would report disagreement where there is none.
+ */
+export declare function quorumKeyFor(method: string): ((result: unknown) => unknown) | undefined;
+/**
+ * One JSON-RPC call through the transport, under the calling driver method's tags. A quorum
+ * compares the caller's own `quorumKey` when it gives one, else the method's consensus
+ * facts; a key never travels without a quorum.
+ */
+export declare function transportCall(transport: Transport, method: string, params: unknown, tags: EvmCallTags): Promise<unknown>;
+/**
+ * Runs `request` (an SDK call whose bridge ends in `call`) and, when its last transport call
+ * failed, rethrows the transport's own error, never an SDK wrapper of it: web3 turns an
+ * "execution reverted" error into a `ContractExecutionError`, which would lose the error's
+ * code and ambiguity. A failure followed by a successful call is forgotten.
+ */
+export declare function throughSdk<T>(request: (call: (method: string, params: unknown) => Promise<unknown>) => Promise<T>, transport: Transport, tags: EvmCallTags): Promise<T>;