@dispatchlabs/disnode-sdk

The Dispatch SDK for Node and JavaScript developers.

Please consider following this project's author, [Dispatch Labs](https://github.com/David Hutchings), and consider starring the project to show your ❤️ and support.

Install

Install with npm:

$ npm install --save @dispatchlabs/disnode-sdk

CDN

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/disnode-sdk/dist/disJS.js"></script>

Usage

Node:

var DisNodeSDK = require('@dispatchlabs/disnode-sdk');

JavaScript:

For JavaScript, the top-level object is DisJS. Any of the models and methods below (unless otherwise stated) can be used in the browser by replacing DisNodeSDK with DisJS. For example;

// Create an empty account
var account = new DisJS.Account();

Running examples

Examples are contained in the examples folder and can be executed in Node using:

$ npm install && npm run examples

To execute the JavaScript examples, open the examples/js/index.html file in a browser window.

Models

Account

constructor

Account constructor. Create an instance of an account, which can then be used to interact with the network.

• returns {Object}: instance of Account

Examples

// Create an empty account
let account = new DisNodeSDK.Account();

// Create an account using a known address
let account = new DisNodeSDK.Account('fa61c18114f8ff8aafbeb5d32e1b108e3f6cf30d');

// Create an account using an object
let account = new DisNodeSDK.Account({
 name: 'MyAccount',
 address: 'fa61c18114f8ff8aafbeb5d32e1b108e3f6cf30d',
 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 DisNodeSDK.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 DisNodeSDK.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}: value - The number of tokens to send.
• returns {Transaction}: Returns a transaction which has already been sent.

Example

let account = new DisNodeSDK.Account('fa61c18114f8ff8aafbeb5d32e1b108e3f6cf30d');
// Send one (1) token
let tx = account.sendTokens(new DisNodeSDK.Account().init(), 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.
• {number}: value - The number of tokens to seed the contract with.
• returns {Transaction}: Returns a transaction which has already been sent.

Example

let account = new DisNodeSDK.Account('fa61c18114f8ff8aafbeb5d32e1b108e3f6cf30d');
let compiled = DisNodeSDK.Transaction.compileSource('contract x { function g() { } }');
let contract = account.createContract(compiled.contracts[0].bytecode, compiled.contracts[0].abi, 5);

executeContract

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.
• {number}: value - The number of tokens to send to the contract for the method call.
• returns {Transaction}: Returns a transaction which has already been sent.

Example

let account = new DisNodeSDK.Account('fa61c18114f8ff8aafbeb5d32e1b108e3f6cf30d');
let compiled = DisNodeSDK.Transaction.compileSource('contract x { function g() { } }');
let contract = account.createContract(compiled.contracts[0].bytecode, compiled.contracts[0].abi, 5);
contract.whenStatusEquals('Ok')
  .then(() => {
    account.executeContract(contract, 'g', [], compiled.contracts[0].abi, 5);
  })
  .catch((err) => {
    console.error(err);
  });

Transaction

constructor

Transaction constructor. Create an instance of a transaction, which can then be sent to a delegate.

• returns {Object}: instance of Transaction

Example

// Create a new transaction
let account = new DisNodeSDK.Account().init();
let tx = new DisNodeSDK.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 DisNodeSDK.Account().init();
let tx = new DisNodeSDK.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 DisNodeSDK.Account().init();
let tx = new DisNodeSDK.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 of SDKTimeout: true.

Example

let account = new DisNodeSDK.Account().init();
let tx = new DisNodeSDK.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 DisNodeSDK.Account().init();
let compiled = DisNodeSDK.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 = DisNodeSDK.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 test

Building 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 && verb

Author

Dispatch Labs

• [GitHub Profile](https://github.com/David Hutchings)
• [Twitter Profile](https://twitter.com/David Hutchings)
• LinkedIn Profile

License

Copyright © 2018, Dispatch Labs. Released under the LGPL-3.0 License.

---

This file was generated by verb-generate-readme, v0.8.0, on October 16, 2018.