Documentation

Getting Started

The purpose of eztz.js is to allow developers to easily integrate the Tezos blockchain within web and node-based apps. Inspired by ethereum's web3 library, eztz contains a very broad range of Tezos related functions. eztz can communicate with any Tezos node that exposes the RPC API, and provides the ability to generate keys, sign/verify messages, interact with contracts and more.

Checkout the readme for Installation and Usage instructions.

API Reference

The eztz library is split into 4 main parts:

• eztz.crypto - responsible for key generation, message signing and verification
• eztz.node - responsible for communication and connection with Tezos nodes
• eztz.rpc - a direct representation of the Tezos node JSON RPC API
• eztz.contract - responsible for interacting with and deploying contracts

There are also 2 additional helper parts:

• eztz.utility - a number of utility functions
• eztz.prefix - various Tezos specific prefixes to be used with key base58check encode/decode
• eztz.watermark - an object containing the various watermarks used by Tezos for marking operations
• eztz.library - an object containing all of the root libraries used by eztz

eztz.crypto

The crypto object provides key generation, message signing and verification functionality.

eztz.crypto.generateKeys(mnemonic, passphrase)

Returns an object with generated keys and associated data in a deterministic way

{
    mnemonic : mnemonic, // The mneomic used
    passphrase : passphrase, // The passphrase used
    sk : sk, // The secret/private key hash (sk - starts with edsk)
    pk : pk, // The public key hash (pk - starts with edpk)
    pkh : pkh, // The public key hash (pkh or id - starts with tz1)
}

eztz.crypto.generateKeysNoSeed()

Returns an object with generated keys and associated data in a non-deterministic way

{
    sk : sk, // The secret/private key hash (sk - starts with edsk)
    pk : pk, // The public key hash (pk - starts with edpk)
    pkh : pkh, // The public key hash (pkh or id - starts with tz1)
}

eztz.crypto.sign(bytes, sk, wm)

Returns an object of the signed bytes to use with the Tezos network with the provided watermark (wm).

{
    bytes: bytes, // original bytes
    sig: sig, // signature of signed bytes, ArrayBuffer
    edsig: edsig, // b58cencoded edsig for signature
    sbytes: sbytes, // hex encoded string containing the original bytes followed by the signature
}

eztz.crypto.verify(bytes, signature, pk)

Returns true if signature is a verified signature of bytes using the sk of pk. False otherwise.

eztz.crypto.generateMnemonic()

Returns a mnemonic to be used for the key generator (string)

eztz.crypto.checkAddress(address)

Returns true if address is a correctly formatted tz1 address (checksum verification), otherwise false.

eztz.crypto.extractKeys(sk)

With a given edsk, a full set of extracted keys will be returned.

eztz.crypto.extractEncryptedKeys(esk)

With a given edesk and encryption password, a full set of extracted keys will be returned. This effectively allows extraction of an encrypted edesk key from the tezos-client.

eztz.crypto.checkAddress(address)

Returns true if address is a correctly formatted tz1 address (checksum verification), otherwise false.

eztz.node

The node object is required for communicating with a Tezos Node (or Node Network).

eztz.node.setProvider(provider)

Sets the provider to be used by the node object for communication. Ensure the RPC API layer has been exposed.

eztz.node.resetProvider()

Resets the provider to the eztz default - https://tezrpc.me Node Network

eztz.node.setDebugMode(bool)

When set to true, the script will output RPC queries and responses via console.log

eztz.node.query(endpoint, data)

Sends a RPC API request to _endpoint _with optional data and returns a Promise with the response.

eztz.node.query("/blocks/head/hash").then(function(res){
  console.log(res);
}).catch(function(e){});

eztz.rpc

The rpc object is designed to implement the Tezos RPC API directly - this is currently in development, but we will be working toward completing this ASAP.

eztz.rpc.getHead()

Returns a eztz.node.query Promise containing the current head object returned from the connected node.

eztz.rpc.getHead().then(function(res){
  console.log(res); // Head object
}).catch(function(e){});

eztz.rpc.sendOperation(from, operation, keys)

If keys.sk is set to false, this will return an object containing an unsigned operation. This can then be signed and submitted using the "eztz.rpc.inject" call.

Otherwise, this returns a eztz.node.query Promise containing the operation hash object returned from the connected node. If keys is set to false, the "0 key" will be used to sign the operation (anonymous operation).

var operation = {
  "kind": "transaction",
  "amount": 1000000, // This is in mutez, i.e. 1000000 = 1.00 tez
  "destination": "tz1NhhF1S6qhhEepykUyFmpvd6wBuTAbmToD"
};
eztz.rpc.sendOperation(from, operation, keys).then(function(res){
  console.log(res); // Operation result
}).catch(function(e){});

eztz.rpc.getBalance(address)

Returns a eztz.node.query Promise containing the balance of address

eztz.rpc.getBalance("tz1...").then(function(res){
  console.log(res); // Balance
}).catch(function(e){});

eztz.rpc.getDelegate(address)

Returns a eztz.node.query Promise containing the balance of address

eztz.rpc.getBalance("tz1...").then(function(res){
  console.log(res); // Balance
}).catch(function(e){});

eztz.rpc.getHeadHash()

Returns a eztz.node.query Promise containing the balance of address

eztz.rpc.getBalance("tz1...").then(function(res){
  console.log(res); // Balance
}).catch(function(e){});

eztz.rpc.account(keys, amount, spendable, delegatable, delegate, fee)

Returns a eztz.node.query Promise containing the balance of address

eztz.rpc.getBalance("tz1...").then(function(res){
  console.log(res); // Balance
}).catch(function(e){});

eztz.contract

This object provides some easy functions to interact directly with smart contracts on the Tezos blockchain.

eztz.contract.originate(address)

WIP

eztz.contract.storage(contractAddress)

Returns a eztz.node.query Promise containing the balance of address

eztz.contract.storage("TZ1...").then(function(res){
  console.log(res); // Raw storage JSON object for contractAddress
}).catch(function(e){});

eztz.contract.load(contractAddress)

Returns a promise that will resolve with the contract object from the RPC API

eztz.contract.load("TZ1...").then(function(res){
  console.log(res); // Contract Object
}).catch(function(e){});

eztz.contract.watch(contractAddress, interval, callback)

Returns a interval object that watches the smart contract storage associated with the given address. The watch polls based on the interval input (in seconds) and runs callback if the storage is updated. callback should accept one variable, which is the updated storage (converted to JSON array)

eztz.contract.watch("TZ1...", 2, function(s){
  console.log("New storage", s);
});

eztz.contract.send(contractAddress, keys, amount, parameter, fee)

Sends a transaction to the contractAddress using keys with the amount, parameter and fee specified. Returns a promise.

eztz.contract.send("TZ1...", keys, 100, "Unit", .5).then(function(res){
  console.log(res); // Operation result
}).catch(function(e){});