eosjs v22.1.0
Eosjs
General purpose library for the EOS blockchain.
Usage (read-only)
Eos = require('eosjs') // Eos = require('./src')
// API, note: to use a local testnet, use Eos.Localnet()
let eos = Eos.Testnet()
// All API methods print help when called with no-arguments.
eos.getBlock()
// Next, your going to need eosd running on localhost:8888
// If a callback is not provided, a Promise is returned
eos.getBlock(1).then(result => {console.log(result)})
// Parameters can be sequential or an object
eos.getBlock({block_num_or_id: 1}).then(result => console.log(result))
// Callbacks are similar
callback = (err, res) => {err ? console.error(err) : console.log(res)}
eos.getBlock(1, callback)
eos.getBlock({block_num_or_id: 1}, callback)
// Provide an empty object or a callback if an API call has no arguments
eos.getInfo({}).then(result => {console.log(result)})
API methods and documentation are generated from:
Configuration
Eos = require('eosjs') // Eos = require('./src')
// Optional configuration..
config = {
keyProvider: ['PrivateKeys...'], // WIF string or array of keys..
httpEndpoint: 'http://127.0.0.1:8888',
mockTransactions: () => 'pass', // or 'fail'
transactionHeaders: (expireInSeconds, callback) => {
callback(null/*error*/, headers)
},
expireInSeconds: 60,
broadcast: true,
debug: false,
sign: true
}
eos = Eos.Localnet(config)
mockTransactions
(optional)pass
- do not broadcast, always pretend that the transaction workedfail
- do not broadcast, pretend the transaction failednull|undefined
- broadcast as usual
transactionHeaders
(optional) - manually calculate transaction header. This may be provided so eosjs does not need to make header related API calls to eosd. This callback is called for every transaction. Headers are documented here eosjs-api#headers.
Options
Options may be provided immediately after parameters.
Example: eos.transfer(params, options)
options = {
broadcast: true,
sign: true,
authorization: null
}
- authorization
{array<auth>|auth}
- identifies the signing account and permission typically in a multi-sig configuration. Authorization may be a string formatted asaccount@permission
or anobject<{actor: account, permission}>
.- If missing default authorizations will be calculated.
- If provided additional authorizations will not be added.
- Sorting is always performed (by account name).
Usage (read/write)
If you use the Testnet, you'll need to replace the private key in keyProvider.
Eos = require('eosjs') // Eos = require('./src')
eos = Eos.Localnet({keyProvider: '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'})
// Run with no arguments to print usage.
eos.transfer()
// Usage with options (options are always optional)
options = {broadcast: false}
eos.transfer({from: 'inita', to: 'initb', quantity: '1 EOS', memo: ''}, options)
// Object or ordered args may be used.
eos.transfer('inita', 'initb', '2 EOS', 'memo', options)
// A broadcast boolean may be provided as a shortcut for {broadcast: false}
eos.transfer('inita', 'initb', '1 EOS', '', false)
Read-write API methods and documentation are generated from this schema.
For more advanced signing, see keyProvider
in
eosjs-keygen or
unit test.
Shorthand
Shorthand is available for some types such as Asset and Authority.
For example:
- deposit:
'1 EOS'
is shorthand for1.0000 EOS
- owner:
'EOS6MRy..'
is shorthand for{threshold: 1, keys: [key: 'EOS6MRy..', weight: 1]}
- recovery:
inita
orinita@active
is shorthand{{threshold: 1, accounts: [..actor: inita, permission: active, weight: 1]}}
inita@other
would replace the permissionactive
withother
Eos = require('eosjs') // Eos = require('./src')
initaPrivate = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
initaPublic = 'EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV'
keyProvider = initaPrivate
eos = Eos.Localnet({keyProvider})
eos.newaccount({
creator: 'inita',
name: 'mynewacct',
owner: initaPublic,
active: initaPublic,
recovery: 'inita'
})
Contract
Deploy a smart contract.
The setcode
command accepts WASM text and converts this to binary before
signing and broadcasting. For this, the Binaryen library is used. Because
this is a large library it is not included in eosjs
by default.
Add binaryen to your project:
npm i binaryen
Import and include the library when you configure Eos:
binaryen = require('binaryen')
eos = Eos.Testnet({..., binaryen})
Complete example:
Eos = require('eosjs') // Eos = require('./src')
let {ecc} = Eos.modules
initaPrivate = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'
// New deterministic key for the currency account. Only use a simple
// seedPrivate in production if you want to give away money.
currencyPrivate = ecc.seedPrivate('currency')
currencyPublic = ecc.privateToPublic(currencyPrivate)
keyProvider = [initaPrivate, currencyPrivate]
// Requires a large library, separate from the eosjs bundle
// $ npm install binaryen
binaryen = require('binaryen')
eos = Eos.Localnet({keyProvider, binaryen})
eos.newaccount({
creator: 'inita',
name: 'currency',
owner: currencyPublic,
active: currencyPublic,
recovery: 'inita'
})
contractDir = `${process.env.HOME}/eosio/dawn3/build/contracts/currency`
wast = fs.readFileSync(`${contractDir}/currency.wast`)
abi = fs.readFileSync(`${contractDir}/currency.abi`)
// Publish contract to the blockchain
eos.setcode('currency', 0, 0, wast)
eos.setabi('currency', JSON.parse(abi))
currency = null
// eos.contract(account<string>, [options], [callback])
eos.contract('currency').then(contract => currency = contract)
// Issue is one of the actions in currency.abi
currency.issue('inita', '1000.0000 CUR', {authorization: 'currency'})
Atomic Operations
Blockchain level atomic operations. All will pass or fail.
Eos = require('eosjs') // Eos = require('./src')
keyProvider = [
'5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3',
Eos.modules.ecc.seedPrivate('currency')
]
eos = Eos.Localnet({keyProvider})
// if either transfer fails, both will fail (1 transaction, 2 messages)
eos.transaction(eos =>
{
eos.transfer('inita', 'initb', '1 EOS', '')
eos.transfer('inita', 'initc', '1 EOS', '')
// Returning a promise is optional (but handled as expected)
}
// [options],
// [callback]
)
// transaction on a single contract
eos.transaction('currency', currency => {
currency.transfer('inita', 'initb', '1 CUR', '')
})
// mix contracts in the same transaction
eos.transaction(['currency', 'eosio'], ({currency, eosio}) => {
currency.transfer('inita', 'initb', '1 CUR', '')
eosio.transfer('inita', 'initb', '1 EOS', '')
})
// contract lookups then transactions
eos.contract('currency').then(currency => {
currency.transaction(cur => {
cur.transfer('inita', 'initb', '1 CUR', '')
cur.transfer('initb', 'initc', '1 CUR', '')
})
currency.transfer('inita', 'initb', '1 CUR', '')
})
// Note, the contract method does not take an array. Just use Await or yield
// if multiple contracts are needed outside of a transaction.
Usage (manual)
A manual transaction provides for more flexibility.
Eos = require('eosjs') // Eos = require('./src')
eos = Eos.Localnet({keyProvider: '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'})
// returns Promise
eos.transaction({
actions: [
{
account: 'eosio',
name: 'transfer',
authorization: [{
actor: 'inita',
permission: 'active'
}],
data: {
from: 'inita',
to: 'initb',
quantity: '7 EOS',
memo: ''
}
}
]
})
Development
From time-to-time the eosjs and eosd binary format will change between releases
so you may need to start eosd
with the --skip-transaction-signatures
parameter
to get your transactions to pass.
Note, package.json
has a "main" pointing to ./lib
. The ./lib
folder is for
es2015 code built in a separate step. If your changing and testing code,
import from ./src
instead.
Eos = require('./src')
Use Node v8+ to package-lock.json
.
Related Libraries
These libraries are exported from eosjs
or may be used separately.
var {api, ecc, json, Fcbuffer, format} = Eos.modules
format ./format.md
- Blockchain name validation
- Asset string formatting
- Remote API to an EOS blockchain node (eosd)
- Use this library directly if you need read-only access to the blockchain (don't need to sign transactions).
- Private Key, Public Key, Signature, AES, Encryption / Decryption
- Validate public or private keys
- Encrypt or decrypt with EOS compatible checksums
- Calculate a shared secret
- Blockchain definitions (api method names, blockchain operations, etc)
- Maybe used by any language that can parse json
- Kept up-to-date
- private key storage and key management
- Binary serialization used by the blockchain
- Clients sign the binary form of the transaction
- Essential so the client knows what it is signing
Browser
git clone https://github.com/EOSIO/eosjs.git
cd eosjs
npm install
npm run build
# builds: ./dist/eos.js
<script src="eos.js"></script>
<script>
var eos = Eos.Testnet()
//...
</script>
Environment
Node 6+ and browser (browserify, webpack, etc)
React Native should work, create an issue if you find a bug.
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago