ethereum client

packages/README.md

@@ -8,7 +8,6 @@
 - `packages/messages` -> `@oyaprotocol/messages`
 - `packages/ipfs` -> `@oyaprotocol/ipfs`
 - `packages/ethereum` -> `@oyaprotocol/ethereum`
-- `packages/verification` -> `@oyaprotocol/verification`
 
 ## Import Strategy
 
@@ -25,4 +24,6 @@
 
 ## Current Constraints
 
-- These package shells do not define functional ownership yet.
+- `@oyaprotocol/ipfs`, `@oyaprotocol/ethereum`, and `@oyaprotocol/utils` expose functional kernel APIs.
+- `@oyaprotocol/messages` is still a placeholder package shell.
+- Proposal or proof verification packages are intentionally not represented here yet; those may be implemented later in a lower-level language while TypeScript packages focus on network interactions.

packages/ethereum/README.md

@@ -1,7 +1,26 @@
 # @oyaprotocol/ethereum
 
-Placeholder shell for the Oya Ethereum package.
+Ethereum JSON-RPC utilities for Oya kernel code. This package is a hardened kernel surface: callers provide explicit transport settings and explicit `fetch` implementations instead of relying on process-level defaults.
 
 ## Public Entrypoint
 
 - `@oyaprotocol/ethereum`
+
+## Current Surface
+
+- `createHttpConfig(options)`: validate explicit HTTP transport settings, re-exported from `@oyaprotocol/utils`.
+- `requestEthereumJsonRpc(options)`: send one JSON-RPC POST request with explicit config and injected `fetch`, returning the raw `result`, attempt count, id, and parsed response payload.
+- `ethSendRawTransaction(options)`: submit a signed raw transaction and return the transaction hash with attempt metadata. Callers may pass `transactionHash` when they already know the hash, allowing the wrapper to verify duplicate-style retry errors with `eth_getTransactionByHash`.
+- `EthereumJsonRpcError`: thrown when an HTTP-successful JSON-RPC response contains an `error` payload.
+- `HttpStatusError`: thrown when the HTTP response itself is not successful, re-exported from `@oyaprotocol/utils`.
+- `EthereumRawTransactionRecoveryError`: thrown when raw transaction submission may have succeeded before a retry returned a duplicate-style error, but the wrapper could not verify the supplied transaction hash.
+
+## Behavior
+
+`createHttpConfig(...)` accepts the shared `CreateHttpConfigOptions` shape from `@oyaprotocol/utils`. The `url` value is normalized by trimming trailing slashes before JSON-RPC requests are sent.
+
+`requestEthereumJsonRpc(...)` owns the JSON-RPC envelope and request headers. It sends `content-type: application/json`, rejects caller-provided `content-type` config headers, enforces a request timeout, retries transient HTTP/network failures only for read-only Ethereum methods, and treats JSON-RPC error payloads as non-retryable semantic errors.
+
+`ethSendRawTransaction(...)` does not sign transactions and does not compute transaction hashes. It expects callers to provide a signed raw transaction. If `transactionHash` is supplied and a retry of `eth_sendRawTransaction` returns duplicate-style JSON-RPC errors such as `already known` or `nonce too low`, the wrapper checks `eth_getTransactionByHash(transactionHash)` before returning a recovered result. Without `transactionHash`, those cases are surfaced as `EthereumRawTransactionRecoveryError` because the package cannot verify acceptance without Keccak hashing.
+
+This package does not sign transactions, encode ABIs, read environment variables, or own RPC endpoint discovery. Callers are responsible for preparing JSON-RPC params, including converting `bigint` values to Ethereum quantity hex before calling the raw request primitive.

packages/ethereum/dist/index.d.ts

@@ -1,4 +1,6 @@
-export declare const packageInfo: Readonly<{
-    name: "@oyaprotocol/ethereum";
-    status: "placeholder";
-}>;
+export { createHttpConfig, HttpStatusError } from '@oyaprotocol/utils';
+export type { CreateHttpConfigOptions, HttpConfig, HttpFetchLike, HttpPostFetchLike, HttpPostFetchOptions, HttpStatusErrorOptions, HttpTextResponse, } from '@oyaprotocol/utils';
+export { EthereumRawTransactionRecoveryError, ethSendRawTransaction, } from './transactions.js';
+export type { EthSendRawTransactionOptions, EthSendRawTransactionResult, } from './transactions.js';
+export { EthereumJsonRpcError, requestEthereumJsonRpc, } from './request-utils.js';
+export type { RequestEthereumJsonRpcOptions, RequestEthereumJsonRpcResult, } from './request-utils.js';

packages/ethereum/dist/request-utils.d.ts

@@ -0,0 +1,36 @@
+import type { HttpConfig, HttpPostFetchLike } from '@oyaprotocol/utils';
+export interface RequestEthereumJsonRpcOptions {
+    config: HttpConfig;
+    fetch: HttpPostFetchLike<string>;
+    method: string;
+    params?: readonly unknown[];
+    id?: string | number;
+    signal?: AbortSignal;
+}
+export interface RequestEthereumJsonRpcResult<TResult = unknown> {
+    result: TResult;
+    attemptCount: number;
+    id: string | number;
+    response: unknown;
+}
+interface EthereumJsonRpcErrorOptions {
+    method: string;
+    response: unknown;
+    attemptCount?: number;
+}
+interface JsonRpcErrorPayload {
+    code?: unknown;
+    message?: unknown;
+    data?: unknown;
+}
+declare class EthereumJsonRpcError extends Error {
+    readonly attemptCount: number;
+    readonly code: number | null;
+    readonly data?: unknown;
+    readonly method: string;
+    readonly response: unknown;
+    constructor(error: JsonRpcErrorPayload, { method, response, attemptCount }: EthereumJsonRpcErrorOptions);
+}
+declare function requestEthereumJsonRpcWithCustomRetryPolicy<TResult = unknown>({ config, fetch, method, params, id, signal, }: RequestEthereumJsonRpcOptions, shouldRetryJsonRpcMethod: (method: string) => boolean): Promise<RequestEthereumJsonRpcResult<TResult>>;
+declare function requestEthereumJsonRpc<TResult = unknown>(options: RequestEthereumJsonRpcOptions): Promise<RequestEthereumJsonRpcResult<TResult>>;
+export { EthereumJsonRpcError, requestEthereumJsonRpc, requestEthereumJsonRpcWithCustomRetryPolicy, };