Agrjs
General purpose library for Aggregion blockchain.
Installation
- Install with:
npm install agrjs
Usage
Ways to instantiate eosjs.
const Agr = // Private key or keys (array) provided statically or by way of a function.// For multiple keys, the get_required_keys API is used (more on that below).keyProvider: '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3' // Localhost Testnet (run ./docker/up.sh)const agr = keyProvider // Connect to a testnet or mainnetconst agr = httpEndpoint chainId keyProvider // Cold-storageconst agr = httpEndpoint: null chainId keyProvider // Read-only instance when 'eosjs' is already a dependencyconst agr = /*config*/
No-arguments prints usage.
agr
USAGEgetBlock - Fetch a block from the blockchain. PARAMETERS
All blockchain functions (read and write) follow this pattern:
// If the last argument is a function it is treated as a callbackagr // If a callback is not provided, a Promise is returnedagr // @returns {Promise} // Parameters can be positional or an objectagr // An API with no parameters is invoked with an empty object or callback (avoids logging usage)agr // @returns {Promise}agr
Configuration
const Agr = // Default configurationconst config = chainId: null // 32 byte (64 char) hex string keyProvider: 'PrivateKeys...' // WIF string or array of keys.. httpEndpoint: 'http://127.0.0.1:8888' expireInSeconds: 60 broadcast: true verbose: false // API activity sign: true; const agr = config;
-
chainId
hex
- Unique ID for the blockchain you're connecting to. This is required for valid transaction signing. The chainId is provided via the get_info API call.Identifies a chain by its initial genesis block. All transactions signed will only be valid the blockchain with this chainId. Verify the chainId for security reasons.
-
keyProvider
[array<string>|string|function]
- Provides private keys used to sign transaction. If multiple private keys are found, the APIget_required_keys
is called to discover which signing keys to use. If a function is provided, this function is called for each transaction. -
httpEndpoint
string
- http or https location of a agrnode server providing a chain API. When using agrjs from a browser remember to configure the same origin policy in agrnode or proxy server. For testing, nodeosd configurationaccess-control-allow-origin = *
could be used.Set this value to null for a cold-storage (no network) configuration.
-
expireInSeconds
number
- number of seconds before the transaction will expire. The time is based on the agrnode's clock. An unexpired transaction that may have had an error is a liability until the expiration is reached, this time should be brief. -
broadcast
[boolean=true]
- post the transaction to the blockchain. Use false to obtain a fully signed transaction. -
verbose
[boolean=false]
- verbose logging such as API activity. -
debug
[boolean=false]
- low level debug logging (serialization). -
sign
[boolean=true]
- sign the transaction with a private key. Leaving a transaction unsigned avoids the need to provide a private key. -
mockTransactions (advanced)
mockTransactions: () => null // 'pass', or 'fail'
pass
- do not broadcast, always pretend that the transaction workedfail
- do not broadcast, pretend the transaction failednull|undefined
- broadcast as usual
-
transactionHeaders (advanced) - manually calculate transaction header. This may be provided so agrjs does not need to make header related API calls to agrnode. Used in environments like cold-storage. This callback is called for every transaction.
transactionHeaders: (expireInSeconds, callback) => {callback(null/*error*/, headers)}
-
logger - default logging configuration.
logger:log: configverbose ? consolelog : null // null to disableerror: configverbose ? consoleerror : nullFor example, redirect error logs:
config.logger = {error: (...args) => ..}
Options
Options may be provided after parameters.
NOTE: authorization
is for individual actions, it does not belong in Eos(config)
.
options = authorization: 'alice@active' broadcast: true sign: true
eos
-
authorization
[array<auth>|auth]
- identifies the signing account and permission typically in a multisig 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.
- Performs deterministic sorting by account name
If a default authorization is calculated the action's 1st field must be an account_name. The account_name in the 1st field gets added as the active key authorization for the action.
-
broadcast
[boolean=true]
- post the transaction to the blockchain. Use false to obtain a fully signed transaction. -
sign
[boolean=true]
- sign the transaction with a private key. Leaving a transaction unsigned avoids the need to provide a private key.
Transaction
The transaction function accepts the standard blockchain transaction.
Required transaction header fields will be added unless you are signing without a network connection (httpEndpoint == null). In that case provide you own headers:
// only needed in cold-storage or for offline transactionsconst headers = expiration: '2018-06-14T18:16:10' ref_block_num: 1 ref_block_prefix: 452435776
Create and send (broadcast) a transaction:
/** @return */agr
Named action functions
More concise functions are provided for applications that may use actions more frequently. This avoids having lots of JSON in the code.
// Run with no arguments to print usage.agr // Callback is last, when omitted a promise is returnedagragr // @returns {Promise} // positional parametersagr // named parametersagr // options appear after parametersoptions = broadcast: true sign: true // `false` is a shortcut for {broadcast: false}agr
DecimalPad = AgrmodulesformatDecimalPaduserInput = '10.2'precision = 4assert
Shorthand
Shorthand is available for some types such as Asset and Authority. This syntax
is only for concise functions and does not work when providing entire transaction
objects to agr.transaction
..
For example:
- permission
inita
defaultsinita@active
- authority
'AGR6MRy..'
expands{threshold: 1, keys: [{key: 'AGR6MRy..', weight: 1}]}
- authority
inita
expands{threshold: 1, accounts: [{permission: {actor: 'inita', permission: 'active'}, weight: 1}]}
New Account
New accounts will likely require some staked tokens for RAM and bandwidth.
wif = '5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3'pubkey = 'AGR6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV' agr
Contract
Deploy and call smart contracts.
Compile
If you're loading a wasm file, you do not need binaryen. If you're loading a wast file you can include and configure the binaryen compiler, this is used to compile to wasm automatically when calling setcode.
$ npm install binaryen@37.0.0
binaryen = const agr = keyProvider binaryen
Deploy
const wasm = fs;const abi = fs; // Publish contract to the blockchainagr // @returns {Promise}agr // @returns {Promise}
Fetch a smart contract
// @returns {Promise}agr // Run immediately, `myaction` returns a Promiseagr // Group actions. `transaction` returns a Promise but `myaction` does notagr // Transaction with multiple contractsagr
Offline or cold-storage contract
const agr = httpEndpoint: null const abi = fsagrfcabiCache // Check that the ABI is available (print usage)agr
Offline or cold-storage transaction
// ONLINE // Prepare headersexpireInSeconds = 60 * 60 // 1 hour const agrio = /* {httpEndpoint: 'https://..'} */ const info = await agrconst chainDate = infohead_block_time + 'Z'let expiration = chainDate + expireInSeconds * 1000expiration = expiration0 const block = await agr transactionHeaders = expiration ref_block_num: infolast_irreversible_block_num & 0xFFFF ref_block_prefix: blockref_block_prefix // OFFLINE (bring `transactionHeaders`) // All keys in keyProvider will sign.const agr = httpEndpoint: null chainId keyProvider transactionHeaders transfer = await agrtransferTransaction = transfertransaction // ONLINE (bring `transferTransaction`) const agr = /* {httpEndpoint: 'https://..'} */ processedTransaction = await agr
Custom Token
// more on the contract / transaction syntax await agr const balance = await agrconsole
Calling Actions
Other ways to use contracts and transactions.
// if either transfer fails, both will fail (1 transaction, 2 messages)await agr // transaction on a single contractawait agr // mix contracts in the same transactionawait agr // The contract method does not take an array so must be called once for// each contract that is needed.const myaccount = await agrioawait myaccount // a transaction to a contract instance can specify multiple actionsawait myaccount
Development
From time-to-time the agrks and agrnode binary format will change between releases
so you may need to start agrnode
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 you're changing and testing code,
import from ./src
instead.
= // forceActionDataHex = false helps transaction readability but may trigger back-end bugsconfig = verbose: true debug: false broadcast: true forceActionDataHex: true keyProvider const agr = config
Fcbuffer
The agr
instance can provide serialization:
// 'asset' is a type but could be any struct or type like: transaction or uint8type = type: 1 data: '00ff'buffer = agrfcassert // ABI Serializationagr
Use Node v10+ for package-lock.json
.
Related Libraries
These libraries are integrated into eosjs
seamlessly so you probably do not
need to use them directly. They are exported here giving more API access or
in some cases may be used standalone.
var format api ecc json Fcbuffer = Eosmodules
-
format ./format.md
- Blockchain name validation
- Asset string formatting
-
- Remote API to an EOS blockchain node (nodeos)
- 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 schema)
-
- private key storage and key management
-
- Binary serialization used by the blockchain
- Clients sign the binary form of the transaction
- Allows client to know what it is signing
Environment
Node and browser (es2015)