Registry / http-networking / eosjs
library22.1.0jsnpmunverified

EOSJS is the official JavaScript library for interacting with EOSIO blockchain APIs. It provides a comprehensive set of tools for sending transactions, querying blockchain state, managing accounts, and performing cryptographic operations like signing and verifying. The current stable version is 22.1.0, which introduces support for read-only transactions within smart contracts via HTTP-RPC and action return values. Historically, the library has undergone significant internal changes, such as the switch from `eosjs-ecc` to the `elliptic` cryptography library in v21.0.2, while striving to maintain a stable public API. Releases often include security, stability, and miscellaneous fixes, with release candidates preceding major version bumps. It is a critical component for building applications that interact with EOSIO-based blockchains, offering robust TypeScript support and keeping pace with new blockchain features.

npm install eosjs
INSTALL
IMPORT
SIG · EOSJS
E
eosjs
http-networkingjavascriptv22.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

JsonRpc
import { JsonRpc } from 'eosjs';
const JsonRpc = require('eosjs').JsonRpc;
The primary class for making RPC calls to an EOSIO node. Recommended for ESM environments, use dynamic import or ensure proper CommonJS interoperability for CJS.
Api
import { Api, RpcInterfaces, SignatureProvider, TransactConfig } from 'eosjs';
import Api from 'eosjs';
Main API class for building and pushing transactions. Requires a `SignatureProvider` and `JsonRpc` instance. Named import is standard. Accompanying types like `RpcInterfaces` are also commonly imported.
PrivateKey
import { PrivateKey } from 'eosjs/dist/eosjs-key-conversions';
import { PrivateKey } from 'eosjs';
Cryptographic utilities like `PrivateKey`, `PublicKey`, and `Signature` are typically exported from internal 'dist' paths (e.g., `eosjs/dist/eosjs-key-conversions`) in newer versions, or from `eosjs-ecc` in older versions. Always verify the exact path for your specific `eosjs` version.
JsSignatureProvider
import { JsSignatureProvider } from 'eosjs/dist/eosjs-jssig';
import { JsSignatureProvider } from 'eosjs';
A common in-memory signature provider for development and testing. Like key conversion utilities, it resides in a specific `dist` submodule.

Demonstrates how to initialize `eosjs` with `JsonRpc` and `Api`, perform a read-only query using `get_table_rows`, and provides a commented-out example of pushing a transaction.

import { JsonRpc } from 'eosjs'; import { Api, RpcInterfaces } from 'eosjs'; import { JsSignatureProvider } from 'eosjs/dist/eosjs-jssig'; // Example signature provider import { TextEncoder, TextDecoder } from 'util'; // For Node.js environments // Configuration const defaultPrivateKey = process.env.EOS_PRIVATE_KEY ?? ''; // Replace with an actual private key for signing, DO NOT expose in client-side code. const rpcEndpoint = 'https://eos.greymass.com'; // Example public EOS mainnet endpoint // 1. Setup RPC client const rpc = new JsonRpc(rpcEndpoint, { fetch }); // Using global fetch or node-fetch in Node.js // 2. Setup SignatureProvider (required even for read-only if you intend to send transactions later) // For demonstration, using a JS-based signature provider. In production, consider more secure options. const signatureProvider = new JsSignatureProvider([defaultPrivateKey]); // 3. Setup API client const api = new Api({ rpc, signatureProvider, textDecoder: new TextDecoder(), // Required for Node.js textEncoder: new TextEncoder(), // Required for Node.js }); async function runExample() { try { console.log(`Querying a public contract table on ${rpcEndpoint}...`); // Example: Get 'stat' table from 'eosio.token' contract for 'EOS' symbol const tableRows = await rpc.get_table_rows({ json: true, code: 'eosio.token', scope: 'EOS', table: 'stat', lower_bound: null, upper_bound: null, limit: 1, }); console.log('Table Rows (eosio.token, EOS, stat):', JSON.stringify(tableRows, null, 2)); // Example of pushing a transaction (requires a valid private key and account for 'youraccount') // This part is commented out as it requires a real key and funded account to execute. /* if (defaultPrivateKey && defaultPrivateKey !== '') { console.log('Attempting to push a dummy transaction...'); const transactionResult = await api.transact({ actions: [{ account: 'eosio.token', name: 'transfer', authorization: [{ actor: 'youraccount', // Replace with your EOS account name permission: 'active', }], data: { from: 'youraccount', to: 'teamgreymass', // Example recipient quantity: '0.0001 EOS', // Use a small test amount memo: 'Test transfer from eosjs quickstart', }, }] }, { blocksBehind: 3, expireSeconds: 30, }); console.log('Transaction Result:', JSON.stringify(transactionResult, null, 2)); } */ } catch (error) { console.error('Error:', error); if (error instanceof RpcInterfaces.RpcError) { console.error('RPC Error details:', JSON.stringify(error.json, null, 2)); } } } runExample();
Debug
Known issues
breakingEOSJS v22.0.0-rc2 (which became v22.0.0 stable) introduced new endpoints and TypeScript types for Nodeos API plugins. This can lead to type errors in existing TypeScript projects or incorrect endpoint usage if not updated carefully.
fix
Review the official EOSIO API plugin documentation and update your application's code to align with the new endpoints and TypeScript definitions introduced in EOSJS v22.0.0. Pay close attention to any custom API calls.
affects: >=22.0.0
breakingIn EOSJS v21.0.2, the internal cryptographic library was switched from `eosjs-ecc` to `elliptic`. While the public API was largely maintained, projects that relied on internal specifics of `eosjs-ecc` or expected certain key/signature formats might experience breaking changes.
fix
Ensure your application does not rely on internal details of the previous `eosjs-ecc` library. If you have custom cryptographic handling or key format expectations, thoroughly test for compatibility with the new `elliptic` library. Most users should be unaffected if using only the public API.
affects: >=21.0.2
gotchaVersions 21.0.3 and earlier had an issue with `sign`/`recover`/`verify` methods when the `shouldHash` argument was set to `false` while sending *unhashed* data, leading to incorrect cryptographic operations.
fix
For versions 21.0.x, ensure that if you set `shouldHash` to `false`, you are providing data that has already been correctly hashed externally. It is strongly recommended to upgrade to the latest stable version (22.x) to ensure all signing and recovery methods function as expected.
affects: 21.0.0 - 21.0.3
securityEOSJS v21.0.4 addressed several identified security vulnerabilities in underlying dependencies, including `y18n`, `elliptic`, `node-notifier`, `ini`, and `node-fetch`. Older versions are susceptible to these vulnerabilities.
fix
Immediately upgrade to EOSJS v21.0.4 or higher to patch critical security vulnerabilities in the underlying dependencies. This is crucial for application security and supply chain integrity.
affects: <21.0.4
gotchaNewer versions of `eosjs` are often developed with ECMAScript Modules (ESM) in mind, which can lead to import/export issues when used in CommonJS (CJS) environments with `require()`. This can manifest as `TypeError: (0, _eosjs.Api) is not a constructor` or similar.
fix
Prefer `import` statements and configure your project for ESM usage (e.g., by setting `"type": "module"` in `package.json`). If you must use CommonJS, explore dynamic `import()` or specific transpilation configurations, or consider sticking to older `eosjs` versions that offered better CJS compatibility if full CJS support is critical.
affects: >=21.0.0
Errors
Common errors & fixes
TypeError: fetch is not a function
The `JsonRpc` constructor expects a global `fetch` API, which is available in browsers but not natively in Node.js environments prior to Node 18 without a polyfill or explicit import.
fix
In Node.js, install `node-fetch` (e.g., `npm install node-fetch`) and pass it explicitly: `new JsonRpc(rpcEndpoint, { fetch: require('node-fetch') })` or `new JsonRpc(rpcEndpoint, { fetch })` after `import fetch from 'node-fetch'`.
RpcError: unknown key: signature
This error commonly occurs when attempting to push a transaction without a properly configured or working `SignatureProvider`, or if the provided private key is invalid or mismatched for the account's permissions defined in the transaction's `authorization` array.
fix
Ensure your `SignatureProvider` (e.g., `JsSignatureProvider`) is correctly initialized with the private key corresponding to the `actor` and `permission` specified in your transaction's `authorization` array. Double-check the private key and account name for accuracy and that the private key corresponds to the network you're connected to.
TypeError: Cannot read properties of undefined (reading 'textDecoder')
The `Api` constructor requires `textDecoder` and `textEncoder` instances, which are global in modern browser environments but need to be explicitly imported or polyfilled in some Node.js environments.
fix
In Node.js, import `TextEncoder` and `TextDecoder` from the built-in `util` module: `import { TextEncoder, TextDecoder } from 'util';` and pass them to the `Api` constructor: `{ textDecoder: new TextDecoder(), textEncoder: new TextEncoder() }`.
Error: Missing RpcInterfaces.SignatureProvider
The `Api` class constructor strictly requires an instance of a `SignatureProvider` to be passed, even if you only intend to perform read-only operations with the `Api` instance later. This ensures a consistent API interface.
fix
Provide an instance of a `SignatureProvider` (e.g., `JsSignatureProvider` for testing purposes, or a more secure provider for production) to the `Api` constructor. If you only need to query blockchain state and do not intend to send transactions, you can use `JsonRpc` directly without `Api`.
Upgrade
Version history
22.1.0latest on npm
Audit
Dependencies
node-fetchrequiredHTTP client used internally for making RPC calls to EOSIO nodes in Node.js environments. Was explicitly mentioned in v21.0.4 for security fixes, implying its role as a key dependency.
Agent activity
17 hits · last 30 days
node
16
OpenAI (training)
1
Resources
eosjs — npm install eosjs · libregistry