Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/EOSIO/eosjs
General purpose library for the EOSIO blockchain.
https://github.com/EOSIO/eosjs
Last synced: 11 days ago
JSON representation
General purpose library for the EOSIO blockchain.
- Host: GitHub
- URL: https://github.com/EOSIO/eosjs
- Owner: EOSIO
- License: mit
- Archived: true
- Created: 2017-08-03T18:17:52.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-08-01T01:38:25.000Z (over 2 years ago)
- Last Synced: 2024-10-18T09:36:43.656Z (21 days ago)
- Language: TypeScript
- Homepage: http://eosio.github.io/eosjs
- Size: 15.7 MB
- Stars: 1,433
- Watchers: 109
- Forks: 463
- Open Issues: 53
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-eos-security - EOS JS - General purpose library for the EOS blockchain. (EOS Smart Contract Development / Programming tools)
- awesome-EOS - eosjs - EOS API wrapper for JS. (Language Support / JavaScript)
- awesome-eosio - EOSIO/eosjs - Official JavaScript SDK. (Developers / Libraries and Frameworks)
- awesome-eos - eosjs-api - EOS api wrapper for JS (Language Support / JavaScript)
- awesome_eos - eosjs-api - Offical EOS api wrapper for JS (Language Support / JavaScript)
README
# eosjs
[![Build Status](https://github.com/eosio/eosjs/workflows/CI/badge.svg?branch=master)](https://github.com/EOSIO/eosjs/actions) [![npm version](https://badge.fury.io/js/eosjs.svg)](https://badge.fury.io/js/eosjs) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![npm](https://img.shields.io/npm/dw/eosjs.svg)Javascript API for integration with EOSIO-based blockchains using [EOSIO RPC API](https://developers.eos.io/eosio-nodeos/reference).
Documentation can be found [here](https://eosio.github.io/eosjs)
## Installation
### NPM
The official distribution package can be found at [npm](https://www.npmjs.com/package/eosjs).
### Add dependency to your project
`yarn add eosjs`
### Using with Typescript
In order to get access to the `TextEncoding` and `TextDecoding` types, you need to add `@types/text-encoding` as a dev dependency:
`yarn add --dev @types/text-encoding`If you're using Node (not a browser) then you'll also need to make sure the `dom` lib is referenced in your `tsconfig.json`:
```
{
"compilerOptions": {
"lib": [..., "dom"]
}
}
```### Browser Distribution
Clone this repository locally then run `yarn build-web`. The browser distribution will be located in `dist-web` and can be directly copied into your project repository. The `dist-web` folder contains minified bundles ready for production, along with source mapped versions of the library for debugging. For full browser usage examples, [see the documentation](https://eosio.github.io/eosjs/guides/1.-Browsers.html).
## Import
### ES Modules
Importing using ESM syntax is supported using TypeScript, [webpack](https://webpack.js.org/api/module-methods), or [Node.js with `--experimental-modules` flag](https://nodejs.org/api/esm.html)
```js
import { Api, JsonRpc, RpcError } from 'eosjs';
import { JsSignatureProvider } from 'eosjs/dist/eosjs-jssig'; // development only
```### CommonJS
Importing using commonJS syntax is supported by Node.js out of the box.
```js
const { Api, JsonRpc, RpcError } = require('eosjs');
const { JsSignatureProvider } = require('eosjs/dist/eosjs-jssig'); // development only
const fetch = require('node-fetch'); // node only; not needed in browsers
const { TextEncoder, TextDecoder } = require('util'); // node only; native TextEncoder/Decoder
```## Basic Usage
### Signature Provider
The Signature Provider holds private keys and is responsible for signing transactions.
***Using the JsSignatureProvider in the browser is not secure and should only be used for development purposes. Use a secure vault outside of the context of the webpage to ensure security when signing transactions in production***
```js
const defaultPrivateKey = "5JtUScZK2XEp3g9gh7F8bwtPTRAkASmNrrftmx4AxDKD5K4zDnr"; // bob
const signatureProvider = new JsSignatureProvider([defaultPrivateKey]);
```### JSON-RPC
Open a connection to JSON-RPC, include `fetch` when on Node.js.
```js
const rpc = new JsonRpc('http://127.0.0.1:8888', { fetch });
```### API
Include textDecoder and textEncoder when using in Node. You may exclude these when running in a browser since most modern browsers now natively support these. If your browser does not support these (https://caniuse.com/#feat=textencoder), then you can import them as a dependency through the following deprecated npm package: https://www.npmjs.com/package/text-encoding
```js
const api = new Api({ rpc, signatureProvider, textDecoder: new TextDecoder(), textEncoder: new TextEncoder() });
```### Sending a transaction
`transact()` is used to sign and push transactions onto the blockchain with an optional configuration object parameter. This parameter can override the default value of `broadcast: true`, and can be used to fill TAPOS fields given `expireSeconds` and either `blocksBehind` or `useLastIrreversible`. Given no configuration options, transactions are expected to be unpacked with TAPOS fields (`expiration`, `ref_block_num`, `ref_block_prefix`) and will automatically be broadcast onto the chain.
```js
(async () => {
const result = await api.transact({
actions: [{
account: 'eosio.token',
name: 'transfer',
authorization: [{
actor: 'useraaaaaaaa',
permission: 'active',
}],
data: {
from: 'useraaaaaaaa',
to: 'useraaaaaaab',
quantity: '0.0001 SYS',
memo: '',
},
}]
}, {
blocksBehind: 3,
expireSeconds: 30,
});
console.dir(result);
})();
```### Error handling
use `RpcError` for handling RPC Errors
```js
...
try {
const result = await api.transact({
...
} catch (e) {
console.log('\nCaught exception: ' + e);
if (e instanceof RpcError)
console.log(JSON.stringify(e.json, null, 2));
}
...
```## Contributing
[Contributing Guide](./CONTRIBUTING.md)
[Code of Conduct](./CONTRIBUTING.md#conduct)
## License
[MIT](./LICENSE)
## Important
See [LICENSE](./LICENSE) for copyright and license terms.
All repositories and other materials are provided subject to the terms of this [IMPORTANT](./IMPORTANT.md) notice and you must familiarize yourself with its terms. The notice contains important information, limitations and restrictions relating to our software, publications, trademarks, third-party resources, and forward-looking statements. By accessing any of our repositories and other materials, you accept and agree to the terms of the notice.