necjs/dist/provider.d.ts

NECJS SDK for NCOG Earth Chain RPC

/**
 * Represents a structured error returned from a JSON-RPC call.
 */
export declare class RpcError extends Error {
    readonly code: number;
    readonly data?: any;
    constructor(message: string, code: number, data?: any);
}
export type ProviderRequestMiddleware = (payload: any) => Promise<any> | any;
export type ProviderResponseMiddleware = (response: any, payload: any) => Promise<any> | any;
/**
 * The Provider class is a low-level wrapper for making JSON-RPC requests to an NCOG chain node.
 * It handles request creation, error parsing, and provides convenience methods for all standard RPC calls.
 */
export declare class Provider {
    private url;
    private idCounter;
    private requestMiddleware;
    private responseMiddleware;
    /**
     * Register a request middleware function. Called before sending each request.
     */
    useRequest(middleware: ProviderRequestMiddleware): void;
    /**
     * Register a response middleware function. Called after receiving each response.
     */
    useResponse(middleware: ProviderResponseMiddleware): void;
    /**
     * @param url The URL of the JSON-RPC endpoint (e.g., "http://localhost:8545").
     */
    constructor(url: string);
    /**
     * Performs a raw JSON-RPC request. This is the core private method used by all others.
     * @param method The RPC method name.
     * @param params An array of parameters for the RPC method.
     * @returns The result from the RPC call.
     * @throws {RpcError} if the RPC call returns a JSON-RPC error object.
     * @throws {Error} for network or other request-level errors.
     */
    private rpc;
    /**
     * Performs a batch of JSON-RPC requests. Returns an array of results/errors in the same order.
     * @param calls Array of { method, params } objects.
     * @returns Array of results or errors (in order).
     */
    batchRpc(calls: {
        method: string;
        params?: any[];
    }[]): Promise<any[]>;
    /**
     * Provides a public way to make any RPC call, for methods not explicitly wrapped.
     * @param method The RPC method name.
     * @param params An array of parameters for the RPC method.
     */
    callRpc(method: string, params?: any[]): Promise<any>;
    /**
     * Returns the client version of the node.
     */
    clientVersion(): Promise<string>;
    /**
     * Returns the current network ID.
     */
    netVersion(): Promise<string>;
    /**
     * Returns true if the client is actively listening for network connections.
     */
    listening(): Promise<boolean>;
    /**
     * Returns the number of peers currently connected to the client.
     */
    peerCount(): Promise<string>;
    /**
     * Returns the current protocol version.
     */
    protocolVersion(): Promise<string>;
    /**
     * Returns an object with data about the sync status or `false` if not syncing.
     */
    syncing(): Promise<any>;
    /**
     * Returns the coinbase address of the client.
     */
    coinbase(): Promise<string>;
    /**
     * Returns the number of hashes per second that the node is mining with.
     */
    hashrate(): Promise<string>;
    /**
     * Returns the current chain ID.
     */
    getChainId(): Promise<number>;
    /**
     * Returns the current price per gas in wei.
     */
    getGasPrice(): Promise<string>;
    /**
     * Returns a list of accounts owned by the client.
     */
    accounts(): Promise<string[]>;
    /**
     * Returns the number of the most recent block.
     */
    getBlockNumber(): Promise<number>;
    /**
     * Returns the balance of an account in wei.
     * @param address The address to get the balance of.
     * @param tag The block tag (e.g., "latest", "earliest", "pending", or a block number). Defaults to "latest".
     */
    getBalance(address: string, tag?: string): Promise<number>;
    /**
     * Returns the value from a storage position at a given address.
     * @param address Address of the storage.
     * @param position Hex of the position in storage.
     * @param tag Block tag. Defaults to "latest".
     */
    getStorageAt(address: string, position: string, tag?: string): Promise<string>;
    /**
     * Returns the number of transactions sent from an address.
     * @param address The address.
     * @param tag The block tag. Defaults to "latest".
     */
    getTransactionCount(address: string, tag?: string): Promise<number>;
    /**
     * Returns the number of transactions in a block from a block matching the given block number.
     * @param tag The block tag.
     */
    getBlockTransactionCountByNumber(tag: string): Promise<number>;
    /**
     * Returns the code at a given address.
     * @param address The address.
     * @param tag The block tag. Defaults to "latest".
     */
    getCode(address: string, tag?: string): Promise<string>;
    /**
     * Returns a block matching the given block number.
     * @param tag The block tag or number.
     * @param full If true, returns full transaction objects; otherwise, only transaction hashes.
     */
    getBlockByNumber(tag: string, full?: boolean): Promise<any>;
    /**
     * Returns a block matching the given block hash.
     * @param hash The hash of the block.
     * @param full If true, returns full transaction objects; otherwise, only transaction hashes.
     */
    getBlockByHash(hash: string, full?: boolean): Promise<any>;
    /**
     * Calculates a signature for data, using a specific account.
     * The account must be unlocked on the node.
     * @param address The address to sign with.
     * @param data The data to sign.
     */
    sign(address: string, data: string): Promise<string>;
    /**
     * Asks the remote node to sign a transaction with an unlocked account.
     * @param txObj The transaction object to sign.
     * @returns An object containing the raw signed transaction and the decoded transaction fields.
     */
    signTransaction(txObj: any): Promise<{
        raw: string;
        tx: any;
    }>;
    /**
     * Submits a transaction to be signed and broadcasted by the remote node.
     * The `from` account must be unlocked.
     * @param obj The transaction object.
     */
    sendTransaction(obj: any): Promise<string>;
    /**
     * Submits a pre-signed transaction to the network.
     * @param signedTx The hex-encoded signed transaction.
     * @returns The transaction hash.
     */
    sendRawTransaction(signedTx: string): Promise<string>;
    /**
     * Executes a message call immediately without creating a transaction on the block-chain (read-only).
     * @param tx The transaction call object.
     * @param tag The block tag. Defaults to "latest".
     */
    call(tx: {
        from?: string;
        to: string;
        gas?: string;
        gasPrice?: string;
        value?: string;
        data?: string;
    }, tag?: string): Promise<string>;
    /**
     * Estimates the gas necessary to execute a specific transaction.
     * @param obj The transaction object.
     */
    estimateGas(obj: any): Promise<number>;
    /**
     * Returns a transaction by its hash.
     * @param hash The hash of the transaction.
     */
    getTransactionByHash(hash: string): Promise<any>;
    /**
     * Returns the receipt of a transaction by its hash.
     * @param hash The hash of the transaction.
     */
    getTransactionReceipt(hash: string): Promise<any>;
    /**
     * Returns an array of all logs matching a given filter object.
     * @param filter The filter object.
     */
    getLogs(filter: any): Promise<any[]>;
    /**
     * Used for submitting a proof-of-work solution.
     */
    submitWork(nonce: string, powHash: string, mixDigest: string): Promise<any>;
    /**
     * Used for obtaining a proof-of-work problem.
     */
    getWork(): Promise<any>;
    /**
     * Creates a new account in the node's keystore.
     * @param password The password to protect the account with.
     */
    newAccount(password: string): Promise<string>;
    /**
     * Imports an unencrypted private key into the node's keystore.
     * @param privateKey The raw private key.
     * @param password The password to encrypt the key with.
     */
    importRawKey(privateKey: string, password: string): Promise<string>;
    /**
     * Signs data with a specific account.
     * The account must be unlocked on the node.
     * @param data The data to sign.
     * @param address The address to sign with.
     * @param password The password for the account.
     */
    personalSign(data: string, address: string, password: string): Promise<string>;
    /**
     * Recovers the address that signed a piece of data.
     * @param data The original data.
     * @param signature The signature.
     */
    ecRecover(data: string, signature: string): Promise<string>;
    /**
     * Unlocks a specified account for a given duration.
     * @param address The address to unlock.
     * @param password The account's password.
     * @param duration The duration in seconds to keep the account unlocked. Defaults to 300.
     */
    unlockAccount(address: string, password: string, duration?: number): Promise<boolean>;
    /**
     * Locks a specified account.
     * @param address The address to lock.
     */
    lockAccount(address: string): Promise<boolean>;
    /**
     * Sends a transaction from an account in the node's keystore.
     * @param tx The transaction object.
     * @param password The password for the `from` account.
     */
    sendPersonalTransaction(tx: any, password: string): Promise<string>;
    /**
     * Resolves an ENS name to an Ethereum address using the ENS registry contract.
     * @param ensName The ENS name to resolve (e.g., 'vitalik.eth').
     * @param registryAddress The ENS registry contract address (optional, defaults to mainnet address).
     * @returns The resolved Ethereum address, or null if not found.
     */
    resolveEnsName(ensName: string, registryAddress?: string): Promise<string | null>;
}