shell-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,7 @@
+export { bytesToHexAddress, PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizeHexAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
+export { createShellProvider, createShellPublicClient, createShellWsClient, ShellProvider, shellDevnet, } from "./provider.js";
+export { accountManagerAddress, accountManagerHexAddress, clearValidationCodeSelector, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, isSystemContractAddress, rotateKeySelector, setValidationCodeSelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
+export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashTransaction, hexBytes, } from "./transactions.js";
+export { assertSignerMatchesKeystore, decryptKeystore, exportEncryptedKeyJson, parseEncryptedKey, validateEncryptedKeyAddress, } from "./keystore.js";
+export { adapterFromKeyPair, generateAdapter, generateMlDsa65KeyPair, generateSlhDsaKeyPair, MlDsa65Adapter, SlhDsaAdapter, } from "./adapters.js";
+export { buildShellSignature, KEY_TYPE_TO_SIGNATURE_TYPE, publicKeyFromHex, ShellSigner, SIGNATURE_TYPE_IDS, signatureTypeFromKeyType, } from "./signer.js";

package/dist/keystore.d.ts

@@ -0,0 +1,99 @@
+import { ShellSigner } from "./signer.js";
+import type { ShellEncryptedKey, SignatureTypeName } from "./types.js";
+/**
+ * Parsed metadata from an encrypted Shell keystore file.
+ *
+ * Produced by {@link parseEncryptedKey}; does **not** contain the decrypted private key.
+ */
+export interface ParsedShellKeystore {
+    /** The raw keystore object as parsed from JSON. */
+    raw: ShellEncryptedKey;
+    /** Resolved signature algorithm name. */
+    signatureType: SignatureTypeName;
+    /** Numeric algorithm ID (0/1/2). */
+    algorithmId: number;
+    /** Raw public key bytes decoded from `raw.public_key`. */
+    publicKey: Uint8Array;
+    /** Canonical `pq1…` address derived from `publicKey`. */
+    canonicalAddress: string;
+    /** `0x`-prefixed hex representation of the same address. */
+    hexAddress: string;
+}
+/**
+ * Parse a Shell keystore file (string or object) and extract public metadata.
+ *
+ * Does **not** decrypt the private key. Use {@link decryptKeystore} for full
+ * decryption.
+ *
+ * @param input - Keystore JSON string or already-parsed {@link ShellEncryptedKey} object.
+ * @returns {@link ParsedShellKeystore} with algorithm info, public key, and derived addresses.
+ * @throws {Error} If `key_type` is not a recognised algorithm.
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseEncryptedKey(readFileSync("key.json", "utf8"));
+ * console.log(parsed.canonicalAddress); // pq1…
+ * console.log(parsed.signatureType);    // "MlDsa65"
+ * ```
+ */
+export declare function parseEncryptedKey(input: string | ShellEncryptedKey): ParsedShellKeystore;
+/**
+ * Parse a keystore and verify that the declared address matches the public key.
+ *
+ * @param input - Keystore JSON string or object.
+ * @returns {@link ParsedShellKeystore} if validation passes.
+ * @throws {Error} If the declared address does not match the address derived from the public key.
+ *
+ * @example
+ * ```typescript
+ * const parsed = validateEncryptedKeyAddress(json); // throws if tampered
+ * ```
+ */
+export declare function validateEncryptedKeyAddress(input: string | ShellEncryptedKey): ParsedShellKeystore;
+/**
+ * Serialise a keystore to a pretty-printed JSON string.
+ *
+ * @param input - Keystore JSON string or object.
+ * @returns Indented JSON string (2-space indent).
+ */
+export declare function exportEncryptedKeyJson(input: string | ShellEncryptedKey): string;
+/**
+ * Assert that a {@link ShellSigner} corresponds to the given keystore.
+ *
+ * Checks that the signature algorithm and derived address both match.
+ *
+ * @param signer - The signer to verify.
+ * @param keystore - The parsed keystore to compare against.
+ * @throws {Error} If the algorithm or address does not match.
+ *
+ * @example
+ * ```typescript
+ * assertSignerMatchesKeystore(signer, parsed); // throws on mismatch
+ * ```
+ */
+export declare function assertSignerMatchesKeystore(signer: ShellSigner, keystore: ParsedShellKeystore): void;
+/**
+ * Decrypt a Shell keystore file and return a ready-to-use {@link ShellSigner}.
+ *
+ * **KDF**: argon2id (parameters from `kdf_params`)
+ * **Cipher**: xchacha20-poly1305 (24-byte nonce from `cipher_params`)
+ * **Plaintext layout**: `[secret_key_bytes][public_key_bytes]`
+ *
+ * The decrypted public key is compared against `raw.public_key` to detect
+ * wrong passwords or corrupt files before returning the signer.
+ *
+ * @param input - Keystore JSON string or object.
+ * @param password - The passphrase used to encrypt the key.
+ * @returns A fully configured `ShellSigner` ready for signing transactions.
+ * @throws {Error} If the KDF or cipher is unsupported.
+ * @throws {Error} If decryption fails (wrong password or corrupt ciphertext).
+ * @throws {Error} If the decrypted public key does not match the stored one.
+ *
+ * @example
+ * ```typescript
+ * const signer = await decryptKeystore(readFileSync("key.json", "utf8"), "my-passphrase");
+ * console.log(signer.getAddress()); // pq1…
+ * const hash = await provider.sendTransaction(await signer.buildSignedTransaction(…));
+ * ```
+ */
+export declare function decryptKeystore(input: string | ShellEncryptedKey, password: string): Promise<ShellSigner>;

package/dist/keystore.js

@@ -0,0 +1,166 @@
+/**
+ * Encrypted keystore utilities for Shell Chain.
+ *
+ * Shell keystore files are JSON objects that store a post-quantum private key
+ * encrypted with:
+ * - **KDF**: argon2id (memory-hard password derivation)
+ * - **Cipher**: xchacha20-poly1305 (authenticated encryption)
+ *
+ * They are generated by the Shell CLI (`shell key generate`) and are
+ * compatible with the SDK's `decryptKeystore` function.
+ *
+ * Plaintext layout after decryption: `[secret_key_bytes][public_key_bytes]`.
+ *
+ * @module keystore
+ */
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { argon2id } from "hash-wasm";
+import { derivePqAddressFromPublicKey, normalizeHexAddress, normalizePqAddress } from "./address.js";
+import { adapterFromKeyPair } from "./adapters.js";
+import { ShellSigner, publicKeyFromHex, signatureTypeFromKeyType } from "./signer.js";
+const SIG_IDS = { Dilithium3: 0, MlDsa65: 1, SphincsSha2256f: 2 };
+/**
+ * Parse a Shell keystore file (string or object) and extract public metadata.
+ *
+ * Does **not** decrypt the private key. Use {@link decryptKeystore} for full
+ * decryption.
+ *
+ * @param input - Keystore JSON string or already-parsed {@link ShellEncryptedKey} object.
+ * @returns {@link ParsedShellKeystore} with algorithm info, public key, and derived addresses.
+ * @throws {Error} If `key_type` is not a recognised algorithm.
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseEncryptedKey(readFileSync("key.json", "utf8"));
+ * console.log(parsed.canonicalAddress); // pq1…
+ * console.log(parsed.signatureType);    // "MlDsa65"
+ * ```
+ */
+export function parseEncryptedKey(input) {
+    const raw = typeof input === "string" ? JSON.parse(input) : input;
+    const signatureType = signatureTypeFromKeyType(raw.key_type);
+    const algorithmId = SIG_IDS[signatureType];
+    const publicKey = publicKeyFromHex(raw.public_key);
+    const canonicalAddress = derivePqAddressFromPublicKey(publicKey, algorithmId);
+    const hexAddress = normalizeHexAddress(canonicalAddress);
+    return { raw, signatureType, algorithmId, publicKey, canonicalAddress, hexAddress };
+}
+/**
+ * Parse a keystore and verify that the declared address matches the public key.
+ *
+ * @param input - Keystore JSON string or object.
+ * @returns {@link ParsedShellKeystore} if validation passes.
+ * @throws {Error} If the declared address does not match the address derived from the public key.
+ *
+ * @example
+ * ```typescript
+ * const parsed = validateEncryptedKeyAddress(json); // throws if tampered
+ * ```
+ */
+export function validateEncryptedKeyAddress(input) {
+    const parsed = parseEncryptedKey(input);
+    const declared = normalizePqAddress(parsed.raw.address);
+    if (declared !== parsed.canonicalAddress) {
+        throw new Error("keystore address mismatch: declared=" + declared + " derived=" + parsed.canonicalAddress);
+    }
+    return parsed;
+}
+/**
+ * Serialise a keystore to a pretty-printed JSON string.
+ *
+ * @param input - Keystore JSON string or object.
+ * @returns Indented JSON string (2-space indent).
+ */
+export function exportEncryptedKeyJson(input) {
+    return JSON.stringify(typeof input === "string" ? JSON.parse(input) : input, null, 2);
+}
+/**
+ * Assert that a {@link ShellSigner} corresponds to the given keystore.
+ *
+ * Checks that the signature algorithm and derived address both match.
+ *
+ * @param signer - The signer to verify.
+ * @param keystore - The parsed keystore to compare against.
+ * @throws {Error} If the algorithm or address does not match.
+ *
+ * @example
+ * ```typescript
+ * assertSignerMatchesKeystore(signer, parsed); // throws on mismatch
+ * ```
+ */
+export function assertSignerMatchesKeystore(signer, keystore) {
+    if (signer.signatureType !== keystore.signatureType) {
+        throw new Error("algorithm mismatch: signer=" + signer.signatureType + " keystore=" + keystore.signatureType);
+    }
+    const addr = signer.getAddress();
+    if (addr !== keystore.canonicalAddress) {
+        throw new Error("address mismatch: signer=" + addr + " keystore=" + keystore.canonicalAddress);
+    }
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        throw new Error("invalid hex");
+    const buf = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < buf.length; i++)
+        buf[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return buf;
+}
+/**
+ * Decrypt a Shell keystore file and return a ready-to-use {@link ShellSigner}.
+ *
+ * **KDF**: argon2id (parameters from `kdf_params`)
+ * **Cipher**: xchacha20-poly1305 (24-byte nonce from `cipher_params`)
+ * **Plaintext layout**: `[secret_key_bytes][public_key_bytes]`
+ *
+ * The decrypted public key is compared against `raw.public_key` to detect
+ * wrong passwords or corrupt files before returning the signer.
+ *
+ * @param input - Keystore JSON string or object.
+ * @param password - The passphrase used to encrypt the key.
+ * @returns A fully configured `ShellSigner` ready for signing transactions.
+ * @throws {Error} If the KDF or cipher is unsupported.
+ * @throws {Error} If decryption fails (wrong password or corrupt ciphertext).
+ * @throws {Error} If the decrypted public key does not match the stored one.
+ *
+ * @example
+ * ```typescript
+ * const signer = await decryptKeystore(readFileSync("key.json", "utf8"), "my-passphrase");
+ * console.log(signer.getAddress()); // pq1…
+ * const hash = await provider.sendTransaction(await signer.buildSignedTransaction(…));
+ * ```
+ */
+export async function decryptKeystore(input, password) {
+    const parsed = validateEncryptedKeyAddress(input);
+    const ek = parsed.raw;
+    if (ek.kdf !== "argon2id")
+        throw new Error("unsupported kdf: " + ek.kdf);
+    if (ek.cipher !== "xchacha20-poly1305")
+        throw new Error("unsupported cipher: " + ek.cipher);
+    const salt = hexToBytes(ek.kdf_params.salt);
+    const nonce = hexToBytes(ek.cipher_params.nonce);
+    const ciphertext = hexToBytes(ek.ciphertext);
+    const derivedKeyHex = await argon2id({
+        password,
+        salt,
+        iterations: ek.kdf_params.t_cost,
+        memorySize: ek.kdf_params.m_cost,
+        parallelism: ek.kdf_params.p_cost,
+        hashLength: 32,
+        outputType: "hex",
+    });
+    const derivedKey = hexToBytes(derivedKeyHex);
+    const chacha = xchacha20poly1305(derivedKey, nonce);
+    const plaintext = chacha.decrypt(ciphertext);
+    const pubkeyLen = parsed.publicKey.length;
+    const skLen = plaintext.length - pubkeyLen;
+    if (skLen <= 0) {
+        throw new Error("payload too short: " + plaintext.length + " bytes");
+    }
+    const secretKey = plaintext.slice(0, skLen);
+    const derivedPubkey = plaintext.slice(skLen);
+    if (!derivedPubkey.every((b, i) => b === parsed.publicKey[i])) {
+        throw new Error("decrypted public key mismatch");
+    }
+    const adapter = adapterFromKeyPair(parsed.signatureType, parsed.publicKey, secretKey);
+    return new ShellSigner(parsed.signatureType, adapter);
+}

package/dist/provider.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Shell Chain RPC provider.
+ *
+ * Wraps a [viem](https://viem.sh) `PublicClient` for standard `eth_*` methods
+ * and adds raw JSON-RPC support for Shell-specific methods (`shell_*`).
+ *
+ * @example
+ * ```typescript
+ * import { createShellProvider } from "shell-sdk/provider";
+ *
+ * const provider = createShellProvider();
+ * const block    = await provider.client.getBlockNumber();
+ * const hash     = await provider.sendTransaction(signedTx);
+ * ```
+ *
+ * @module provider
+ */
+import { type Chain, type PublicClient } from "viem";
+import type { SignedShellTransaction } from "./types.js";
+/**
+ * Pre-configured viem chain definition for Shell Devnet.
+ *
+ * - Chain ID: `424242`
+ * - HTTP RPC: `http://127.0.0.1:8545`
+ * - WebSocket RPC: `ws://127.0.0.1:8546`
+ * - Native currency: SHELL (18 decimals)
+ */
+export declare const shellDevnet: {
+    blockExplorers?: {
+        [key: string]: {
+            name: string;
+            url: string;
+            apiUrl?: string | undefined;
+        };
+        default: {
+            name: string;
+            url: string;
+            apiUrl?: string | undefined;
+        };
+    } | undefined | undefined;
+    blockTime?: number | undefined | undefined;
+    contracts?: {
+        [x: string]: import("viem").ChainContract | {
+            [sourceId: number]: import("viem").ChainContract | undefined;
+        } | undefined;
+        ensRegistry?: import("viem").ChainContract | undefined;
+        ensUniversalResolver?: import("viem").ChainContract | undefined;
+        multicall3?: import("viem").ChainContract | undefined;
+        erc6492Verifier?: import("viem").ChainContract | undefined;
+    } | undefined;
+    ensTlds?: readonly string[] | undefined;
+    id: 424242;
+    name: "Shell Devnet";
+    nativeCurrency: {
+        readonly decimals: 18;
+        readonly name: "SHELL";
+        readonly symbol: "SHELL";
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["http://127.0.0.1:8545"];
+            readonly webSocket: readonly ["ws://127.0.0.1:8546"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    testnet?: boolean | undefined | undefined;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+};
+/** Options accepted by the provider and client factory functions. */
+export interface CreateShellPublicClientOptions {
+    /** Override the viem chain config. Defaults to {@link shellDevnet}. */
+    chain?: Chain;
+    /** Override the HTTP RPC URL. Defaults to the chain's first HTTP URL. */
+    rpcHttpUrl?: string;
+    /** Override the WebSocket RPC URL. Defaults to the chain's first WS URL. */
+    rpcWsUrl?: string;
+}
+/** A typed alias for a viem `PublicClient`. */
+export type ShellPublicClient = PublicClient;
+/**
+ * RPC client for Shell Chain.
+ *
+ * Combines a viem `PublicClient` (accessible via `.client`) for all standard
+ * Ethereum JSON-RPC methods with direct `fetch`-based calls for Shell-specific
+ * `shell_*` methods.
+ *
+ * Prefer constructing via {@link createShellProvider} rather than instantiating
+ * this class directly.
+ */
+export declare class ShellProvider {
+    /** Underlying viem `PublicClient` for standard `eth_*` methods. */
+    readonly client: ShellPublicClient;
+    /** HTTP RPC URL used for Shell-specific JSON-RPC calls. */
+    readonly rpcHttpUrl: string;
+    constructor(client: ShellPublicClient, rpcHttpUrl: string);
+    private request;
+    /**
+     * Retrieve the on-chain public key for an address.
+     *
+     * Calls `shell_getPqPubkey`. Returns `null` if the address has not yet
+     * submitted a transaction (public key is only recorded on first send).
+     *
+     * @param address - A `pq1…` or `0x…` address.
+     * @returns Hex-encoded public key string, or `null` if unknown.
+     */
+    getPqPubkey(address: string): Promise<string | null>;
+    /**
+     * Broadcast a signed Shell transaction.
+     *
+     * Calls `shell_sendTransaction`.
+     *
+     * @param signedTransaction - A fully-signed transaction built with {@link ShellSigner.buildSignedTransaction}.
+     * @returns The transaction hash as a hex string.
+     * @throws {Error} If the node rejects the transaction.
+     */
+    sendTransaction(signedTransaction: SignedShellTransaction): Promise<string>;
+    /**
+     * Fetch paginated transaction history for an address.
+     *
+     * Calls `shell_getTransactionsByAddress`.
+     *
+     * @param address - The address to query.
+     * @param options - Optional pagination and block range filters.
+     * @param options.fromBlock - Start of block range (inclusive).
+     * @param options.toBlock - End of block range (inclusive).
+     * @param options.page - Zero-based page index.
+     * @param options.limit - Maximum number of results per page.
+     * @returns Raw paginated response from the node.
+     */
+    getTransactionsByAddress(address: string, options?: {
+        fromBlock?: number;
+        toBlock?: number;
+        page?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    /**
+     * Fetch all transaction receipts for a block.
+     *
+     * Calls `eth_getBlockReceipts`.
+     *
+     * @param block - Block identifier: `"latest"`, `"earliest"`, or a hex block number.
+     * @returns Array of transaction receipt objects.
+     */
+    getBlockReceipts(block: string): Promise<unknown[]>;
+}
+/**
+ * Create a viem `PublicClient` connected to Shell Chain over HTTP.
+ *
+ * @param options - Optional chain and URL overrides.
+ * @returns A configured viem `PublicClient`.
+ *
+ * @example
+ * ```typescript
+ * const client = createShellPublicClient();
+ * const blockNumber = await client.getBlockNumber();
+ * ```
+ */
+export declare function createShellPublicClient(options?: CreateShellPublicClientOptions): ShellPublicClient;
+/**
+ * Create a viem `PublicClient` connected to Shell Chain over WebSocket.
+ *
+ * Useful for subscribing to `newHeads`, `logs`, and other real-time events.
+ *
+ * @param options - Optional chain and URL overrides.
+ * @returns A configured viem `PublicClient` using a WebSocket transport.
+ * @throws {Error} If no WebSocket URL is available for the chain.
+ *
+ * @example
+ * ```typescript
+ * const wsClient = createShellWsClient();
+ * const unwatch = wsClient.watchBlocks({ onBlock: (block) => console.log(block.number) });
+ * ```
+ */
+export declare function createShellWsClient(options?: CreateShellPublicClientOptions): ShellPublicClient;
+/**
+ * Create a {@link ShellProvider} — the recommended entry point for interacting
+ * with Shell Chain.
+ *
+ * Combines a viem HTTP `PublicClient` with Shell-specific RPC helpers.
+ *
+ * @param options - Optional chain and URL overrides.
+ * @returns A fully configured `ShellProvider`.
+ *
+ * @example
+ * ```typescript
+ * const provider = createShellProvider();
+ * const balance  = await provider.client.getBalance({ address: signer.getHexAddress() });
+ * const hash     = await provider.sendTransaction(signedTx);
+ * ```
+ */
+export declare function createShellProvider(options?: CreateShellPublicClientOptions): ShellProvider;

package/dist/provider.js

@@ -0,0 +1,208 @@
+/**
+ * Shell Chain RPC provider.
+ *
+ * Wraps a [viem](https://viem.sh) `PublicClient` for standard `eth_*` methods
+ * and adds raw JSON-RPC support for Shell-specific methods (`shell_*`).
+ *
+ * @example
+ * ```typescript
+ * import { createShellProvider } from "shell-sdk/provider";
+ *
+ * const provider = createShellProvider();
+ * const block    = await provider.client.getBlockNumber();
+ * const hash     = await provider.sendTransaction(signedTx);
+ * ```
+ *
+ * @module provider
+ */
+import { createPublicClient, defineChain, http, webSocket, } from "viem";
+/**
+ * Pre-configured viem chain definition for Shell Devnet.
+ *
+ * - Chain ID: `424242`
+ * - HTTP RPC: `http://127.0.0.1:8545`
+ * - WebSocket RPC: `ws://127.0.0.1:8546`
+ * - Native currency: SHELL (18 decimals)
+ */
+export const shellDevnet = defineChain({
+    id: 424242,
+    name: "Shell Devnet",
+    nativeCurrency: {
+        decimals: 18,
+        name: "SHELL",
+        symbol: "SHELL",
+    },
+    rpcUrls: {
+        default: {
+            http: ["http://127.0.0.1:8545"],
+            webSocket: ["ws://127.0.0.1:8546"],
+        },
+    },
+});
+/**
+ * RPC client for Shell Chain.
+ *
+ * Combines a viem `PublicClient` (accessible via `.client`) for all standard
+ * Ethereum JSON-RPC methods with direct `fetch`-based calls for Shell-specific
+ * `shell_*` methods.
+ *
+ * Prefer constructing via {@link createShellProvider} rather than instantiating
+ * this class directly.
+ */
+export class ShellProvider {
+    /** Underlying viem `PublicClient` for standard `eth_*` methods. */
+    client;
+    /** HTTP RPC URL used for Shell-specific JSON-RPC calls. */
+    rpcHttpUrl;
+    constructor(client, rpcHttpUrl) {
+        this.client = client;
+        this.rpcHttpUrl = rpcHttpUrl;
+    }
+    async request(method, params) {
+        const response = await fetch(this.rpcHttpUrl, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method,
+                params,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`rpc request failed: ${response.status} ${response.statusText}`);
+        }
+        const body = (await response.json());
+        if ("error" in body && body.error) {
+            throw new Error(`[${body.error.code}] ${body.error.message}`);
+        }
+        return body.result;
+    }
+    /**
+     * Retrieve the on-chain public key for an address.
+     *
+     * Calls `shell_getPqPubkey`. Returns `null` if the address has not yet
+     * submitted a transaction (public key is only recorded on first send).
+     *
+     * @param address - A `pq1…` or `0x…` address.
+     * @returns Hex-encoded public key string, or `null` if unknown.
+     */
+    async getPqPubkey(address) {
+        return this.request("shell_getPqPubkey", [address]);
+    }
+    /**
+     * Broadcast a signed Shell transaction.
+     *
+     * Calls `shell_sendTransaction`.
+     *
+     * @param signedTransaction - A fully-signed transaction built with {@link ShellSigner.buildSignedTransaction}.
+     * @returns The transaction hash as a hex string.
+     * @throws {Error} If the node rejects the transaction.
+     */
+    async sendTransaction(signedTransaction) {
+        return this.request("shell_sendTransaction", [signedTransaction]);
+    }
+    /**
+     * Fetch paginated transaction history for an address.
+     *
+     * Calls `shell_getTransactionsByAddress`.
+     *
+     * @param address - The address to query.
+     * @param options - Optional pagination and block range filters.
+     * @param options.fromBlock - Start of block range (inclusive).
+     * @param options.toBlock - End of block range (inclusive).
+     * @param options.page - Zero-based page index.
+     * @param options.limit - Maximum number of results per page.
+     * @returns Raw paginated response from the node.
+     */
+    async getTransactionsByAddress(address, options = {}) {
+        return this.request("shell_getTransactionsByAddress", [
+            address,
+            options.fromBlock ?? null,
+            options.toBlock ?? null,
+            options.page ?? null,
+            options.limit ?? null,
+        ]);
+    }
+    /**
+     * Fetch all transaction receipts for a block.
+     *
+     * Calls `eth_getBlockReceipts`.
+     *
+     * @param block - Block identifier: `"latest"`, `"earliest"`, or a hex block number.
+     * @returns Array of transaction receipt objects.
+     */
+    async getBlockReceipts(block) {
+        return this.request("eth_getBlockReceipts", [block]);
+    }
+}
+/**
+ * Create a viem `PublicClient` connected to Shell Chain over HTTP.
+ *
+ * @param options - Optional chain and URL overrides.
+ * @returns A configured viem `PublicClient`.
+ *
+ * @example
+ * ```typescript
+ * const client = createShellPublicClient();
+ * const blockNumber = await client.getBlockNumber();
+ * ```
+ */
+export function createShellPublicClient(options = {}) {
+    const chain = options.chain ?? shellDevnet;
+    const rpcHttpUrl = options.rpcHttpUrl ?? chain.rpcUrls.default.http[0];
+    return createPublicClient({
+        chain,
+        transport: http(rpcHttpUrl),
+    });
+}
+/**
+ * Create a viem `PublicClient` connected to Shell Chain over WebSocket.
+ *
+ * Useful for subscribing to `newHeads`, `logs`, and other real-time events.
+ *
+ * @param options - Optional chain and URL overrides.
+ * @returns A configured viem `PublicClient` using a WebSocket transport.
+ * @throws {Error} If no WebSocket URL is available for the chain.
+ *
+ * @example
+ * ```typescript
+ * const wsClient = createShellWsClient();
+ * const unwatch = wsClient.watchBlocks({ onBlock: (block) => console.log(block.number) });
+ * ```
+ */
+export function createShellWsClient(options = {}) {
+    const chain = options.chain ?? shellDevnet;
+    const rpcWsUrl = options.rpcWsUrl ?? chain.rpcUrls.default.webSocket?.[0];
+    if (!rpcWsUrl) {
+        throw new Error("chain does not define a default WebSocket RPC URL");
+    }
+    return createPublicClient({
+        chain,
+        transport: webSocket(rpcWsUrl),
+    });
+}
+/**
+ * Create a {@link ShellProvider} — the recommended entry point for interacting
+ * with Shell Chain.
+ *
+ * Combines a viem HTTP `PublicClient` with Shell-specific RPC helpers.
+ *
+ * @param options - Optional chain and URL overrides.
+ * @returns A fully configured `ShellProvider`.
+ *
+ * @example
+ * ```typescript
+ * const provider = createShellProvider();
+ * const balance  = await provider.client.getBalance({ address: signer.getHexAddress() });
+ * const hash     = await provider.sendTransaction(signedTx);
+ * ```
+ */
+export function createShellProvider(options = {}) {
+    const client = createShellPublicClient(options);
+    const chain = options.chain ?? shellDevnet;
+    const rpcHttpUrl = options.rpcHttpUrl ?? chain.rpcUrls.default.http[0];
+    return new ShellProvider(client, rpcHttpUrl);
+}