@dispatchlabs/dispatch-js 
The Dispatch SDK for Node and JavaScript developers.
Please consider following this project's author, LinkedIn Profile, and consider starring the project to show your
Install
Install with npm:
$ npm install --save @dispatchlabs/dispatch-jsCDN
The JavaScript version of the SDK may be included on the pae with the following CDN location:
<script src="https://cdn.jsdelivr.net/npm/@dispatchlabs/dispatch-js/dist/dispatch.js"></script>Migrating from disnode_sdk
If you are moving from our previous SDK (disnode_sdk) to this version you will need to replace all occurrences of DisNodeSDK and/or DisJS to Dispatch.
Usage
Node:
var Dispatch = require('@dispatchlabs/dispatch-js');
// or
import Dispatch from '@dispatchlabs/dispatch-js';JavaScript:
For JavaScript, the top-level object is Dispatch.
Running examples
Examples are contained in the examples folder and can be executed in Node using:
$ npm install && npm run examplesTo execute the JavaScript examples, open the examples/js/index.html file in a browser window.
Changing the network the SDK talks to
In node_modules/@dispatchlabs/dispatch-js/lib/config.json you will see the various environments. Use development for building and testing,
To change the environment set NODE_ENV:
$ NODE_ENV=development node myScript.jsBy default the SDK talks to the production network.
Models
Account
constructor
Account constructor. Create an instance of an account, which can then be used to interact with the network.
-
returns{Object}: instance ofAccount
Examples
// Create an empty account
let account = new Dispatch.Account();
account.init();// Create an account using a known address
let account = new Dispatch.Account('fa61c18114f8ff8aafbeb5d32e1b108e3f6cf30d');// Create an account using a private key (the address and public key will be filled in automatically)
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});refresh
Refreshes the account balance and access info (created and updated dates) from a delegate.
-
returns{Promise}: Promise that will return the result of the Delegate request after updating account object.
Example
let account = new Dispatch.Account('fa61c18114f8ff8aafbeb5d32e1b108e3f6cf30d');
account.refresh()
.then(() => {
console.log(account);
})
.catch((err) => {
console.error(err);
});init
Generaes a new private key for the account object (replacing one if present).
-
returns{Account}: Returns the account object for use in chaining.
Example
let account = new Dispatch.Account();
account.init();
console.log(account);sendTokens
Creates and sends a transaction that will transfer tokens from the source account, to the target account.
Params
- {string|Account}: to - The address or Account to send the tokens to.
- {number}: The number of Divitos to send. 1 Divvy = 100,000,000 Divitos
-
returns{Transaction}: Returns a transaction which has already been sent.
Example
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});
// Send one (1) token
let tx = account.sendTokens(new Dispatch.Account().init(), 1);
// Or - to send to an address without making an account
let tx = account.sendTokens("dbf2bb4792c1ae1338b1cdc55a9f68e0e62c0fb8", 1);createContract
Creates and sends a transaction from the account that will create a new Smart Contract.
Params
- {string}: code - Bytecode of a compiled contract.
- {string|array}: code - The ABI of the contract.
-
returns{Transaction}: Returns a transaction which has already been sent.
Example
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});
let compiled = Dispatch.Transaction.compileSource('contract x { function g() { } }');
let contract = account.createContract(compiled.contracts[0].bytecode, compiled.contracts[0].abi);executeRead
Calls a Smart-Contract from the account that will emulate executing a method and return the result without costing hertz or writing a transaction to the ledger.
Params
- {string|Account|Transaction}: to - The address of an existing contract, an Account representing the contract, or the contract creation Transaction.
- {string}: method - The method in the contract to call.
- {array}: params - The parameters to use during the method call.
-
returns{Transaction}: Returns a transaction which has already been sent.
Example
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});
let compiled = Dispatch.Transaction.compileSource('contract x { function g() { } }');
let contract = account.createContract(compiled.contracts[0].bytecode, compiled.contracts[0].abi);
contract.whenStatusEquals('Ok')
.then(() => {
account.executeRead(contract, 'g', [])
.then((result) => {
console.log('Contract Read result:\n' + JSON.stringify(result) + '\n');
}, (err) => {
console.log('Contract Read result error:\n' + JSON.stringify(err) + '\n');
});
})
.catch((err) => {
console.error(err);
});
// Or - to call a method on a deployed contract
account.executeWrite("dbf2bb4792c1ae1338b1cdc55a9f68e0e62c0fb8", 'g', []);executeWrite
Creates and sends a transaction from the account that will execute a method on an existing Smart Contract.
Params
- {string|Account|Transaction}: to - The address of an existing contract, an Account representing the contract, or the contract creation Transaction.
- {string}: method - The method in the contract to call.
- {array}: params - The parameters to use during the method call.
-
returns{Transaction}: Returns a transaction which has already been sent.
Example
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});
let compiled = Dispatch.Transaction.compileSource('contract x { function g() { } }');
let contract = account.createContract(compiled.contracts[0].bytecode, compiled.contracts[0].abi);
contract.whenStatusEquals('Ok')
.then(() => {
account.executeWrite(contract, 'g', [])
.whenStatusEquals('Ok')
.then((result) => {
console.log('Contract Write result:\n' + JSON.stringify(result) + '\n');
}, (err) => {
console.log('Contract Write result error:\n' + JSON.stringify(err) + '\n');
});
})
.catch((err) => {
console.error(err);
});
// Or - to call a method on a deployed contract
account.executeWrite("dbf2bb4792c1ae1338b1cdc55a9f68e0e62c0fb8", 'g', []);Transaction
constructor
Transaction constructor. Create an instance of a transaction, which can then be sent to a delegate.
-
returns{Object}: instance ofTransaction
Example
// Create a new transaction
let account = new Dispatch.Account().init();
let tx = new Dispatch.Transaction({from: account});send
Sends the transaction to a delegate.
-
returns{Promise}: Promise that will return the result of the Delegate request.
Example
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});
let tx = new Dispatch.Transaction({from: account});
tx.send()
.then((result) => {
console.log(result);
})
.catch((err) => {
console.error(err);
});status
Requests the current status of the transaction from a delegate.
-
returns{Promise}: Promise that will return the result of the status check.
Example
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});
let tx = new Dispatch.Transaction({from: account});
tx.send();
tx.status()
.then((result) => {
console.log(result);
})
.catch((err) => {
console.error(err);
});whenStatusEquals
Waits until the status of the transaction matches the value provided, then resolves. Rejects after 5 seconds or when the transaction hits a non-matching final state.
Params
- {string}: status - Desired status for the transaction to acheive.
-
returns{Promise}: Promise that will return the result of the status check. If a timeout occured, the returned data will be the latest known state along with a key ofSDKTimeout: true.
Example
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});
let tx = new Dispatch.Transaction({from: account});
tx.send();
tx.whenStatusEquals('Ok')
.then((result) => {
console.log(result);
})
.catch((err) => {
console.error(err);
});compileSource
Static method to compile Solidity code directly.
Params
- {string}: source - Solidity source code containing one or more contracts.
-
returns{compiledSource}: Compiled output JSON.
Example
let account = new Dispatch.Account({
name: 'MyAccount',
privateKey: '472ba91402425b58a2eebf932812f20c6d7f6297bba1f83d9a58116ae6512d9e'
});
let compiled = Dispatch.Transaction.compileSource('contract x { function g() { } }');
if (compiled.errors.length > 0) {
// Errors are fatal
console.error(compiled.errors);
} else {
// Warnings are non-fatal
if (compiled.warnings.length > 0) {
console.log(compiled.warnings);
}
// compiled.contracts contains the name, bytecode, and abi for each contract contained within the source
const contract = account.createContract(compiled.contracts[0].bytecode, compiled.contracts[0].abi);
}compile
Static method to compile complex Solidity JSON structures.
Params
- {object}: input - Full Solidity JSON structure. See Compiler Input and Output JSON Description.
-
returns{object}: Compiled output JSON.
Example
let compiled = Dispatch.Transaction.compile({language: 'Solidity', sources: { source: { content: 'contract x { function g() { } }' }}});About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm testBuilding docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verbAuthor
David Hutchings at Dispatch Labs
License
Copyright © 2018, Dispatch Labs. Released under the LGPL-2.1 License.
This file was generated by verb-generate-readme, v0.8.0, on October 16, 2018.
