oo7 Parity Reference - Wiki Parity Ethereum Documentation

For oo7-parity version 0.6.0.

oo7-parity is a Parity-centric Ethereum middleware designed to sit between your front-end and a Parity Ethereum node. It is based on oo7 and parity.js (our low-level JS API for the Parity/Ethereum RPC). It makes heavy use of Bonds to deliver an effortless UI development experience that results in a responsive, reactive UI. It works best with the Parity Ethereum node, but is partially compatible with other clients, too.

A Bond is like a Promise in that it’s an asynchronously provided value. However, unlike a Promise it autonomously stays up to date. Bonds may be subscripted, transformed and composed. oo7-react.js exists for tying Bonds into the React library, trivially allowing the UI to display up-to-date information from the block chain.

Installation

oo7-parity.js is available on NPM:

npm install --save oo7-parity

It brings in oo7, the underlying Bonds library items of which you will probably want to use and @parity/parity.js, the low-level Parity/Ethereum API library.

If you are working on the UI with React, you’ll probably want to install parity-reactive-ui.js too (which brings in oo7-react, the oo7 bindings for React and semantic-ui, a nice front-end UI toolkit):

npm install --save parity-reactive-ui

Usage

Most of the API oo7-parity provides is contained within a single object: bonds. The majority of this document details each of the members of this object and how to use them. The rest of the API is compose of a number of utility functions to facilitate certain common actions required when working with oo7-parity.

Utilities

There are several utility functions in oo7-parity:

ABIs

A number of standard ABIs are provided as part of oo7-parity, useful for constructing contracts:

bonds

Setup & options

The main API object contains the logic for succinctly interacting with a Parity (or Parity-compatible Ethereum) node. It requires the address of such a node for it to work. oo7-parity exports the bonds object which is instantiated with the default address of a node (it uses the endpoint address injected by the environment and falls back on http://127.0.0.1:8545). This should work as expected in most circumstances.

If you need to alter this in some way, this is possible through changes to the exported options symbol. By changing its fields, you are able to configure how the exported bonds object works. The fields of options are:

If multiple independent instances of Bonds are required (e.g. because you wish to communicate with multiple nodes sitting on multiple chains at simultaneously), then you can easily use the exported Bonds constructor which accepts a single parameter of type Api.Transport, detailing the transport mechanism to the node.

Notes on Usage

Ensure you import the bonds object:

import {bonds} from 'oo7-parity';

In this reference, for brevity we have dropped the prefix of bonds..

All arguments may be given as one of:

Note that items with no trailing parens should not be used as functions - they are Bonds in their own right e.g. this is right: bonds.head.then(console.log); ...head().then... is wrong.

The type after => denotes the value type of Bond returned.

If a function may take multiple types of parameters, then each type is separated with a pipe |.

If a function’s parameter is optional, then a ? immediately follows it.

If an item only works when the Ethereum client is Parity, then the item’s prototype is followed with “[parity]”.

If the parameter of a function’s usage is non-obvious, then a : is appended, followed by an informative name.

One item (blocks) is denoted an array: it may be dereferenced as an array e.g. bonds.blocks[bonds.height].

Items that return Arrays or Objects may be dereferenced directly, e.g. bonds.head.author would be the Bond that evaluates to the author of the block currently at the head of the chain.

Chain Inspection

Accounts Inspection

Signer

State Inspection

Node Status

Version Inspection

Chain Metadata

P2P Network

Block Authoring (aka “mining”)

Other Services

Transaction Queue

Consensus & Updates

Basic Contracts

Composite Bonds

Basic Types

Object Types

Objects going from one type to another are denoted { KeyType -> ValueType }. Others are listed here.

Block

Equivalent to “a block object”, described at eth_getBlockByHash RPC.

Equivalent to Block, except that individual transactions are not provided.

Transaction

Equivalent to “a transaction object”, described at eth_getTransactionByHash RPC.

Receipt

Equivalent to “a transaction receipt object”, described at eth_getTransactionReceipt RPC.

AccountInfo

Information describing a controlled account.

Keys

Example:

{
  "name": "Main Account"
}

TransactionStatus

The current status of a transaction to be committed to the blockchain. Must contain exactly one of the following keys.

Keys

Example:

{
   "estimating": null
}

DeployStatus

The status of a contract-deployment transaction. Exactly equivalent to TransactionStatus, except that when there exists a confirmed key, there also exists a deployed key:

Keys

SignatureStatus

The current status of a message to be signed. Must contain exactly one of the following keys.

Keys

Example:

{
   "signed": "0x1b0749bc94188f3d06b00217fe384a8aced3a9f6b4f21e22a4eed73e4e3f036a4913b439ed3fab0985353e9f0c9d748d42f6c1786726c6ab530c1f66772c6e5d63"
}

ABISpec

An ABI specification, as described in the Ethereum wiki article.

ChainStatus

Information on the status of the portion of the chain maintained locally. Equivalent to “the status object” described for the parity_chainStatus RPC.

Peers

Information on the peers known by the node.

Keys

Example:

{
  "active": "0",
  "connected": "1",
  "max": "25",
  "peers": [
    {
      "caps": [
        "eth/62",
        "eth/63",
        "par/1",
        "par/2"
      ],
      "id": "2aa81bd0a761cd4f02c934dcf3f81c5b65953e51ab5ba03ceb1f125eb06418a1cdffb1c9d01871aa7bd456f3fce35e745608189ad1164f72b2161634b0c3f6ea",
      "name": "Parity/v1.6.5-beta-987390f-20170328/x86_64-linux-gnu/rustc1.16.0",
      "network": {
        "localAddress": "192.168.0.15:63340",
        "remoteAddress": "188.166.240.190:30303"
      },
      "protocols": {
        "eth": {
          "difficulty": "2.03152996722570234887659664506662254654900182e+44",
          "head": "daac19a336359bc4a46b06bfc47e9aa62f5cde2974c987a70213fa2431a8d9d5",
          "version": 2
        }
      }
    }
  ]
}

LocalTransactionInfo

Information concerning a locally-submitted transaction.

Keys

Example:

{
  "status": "mined",
  "transaction": LocalTransaction
}

LocalTransaction

Information representing a local Transaction pending finalisation.

Keys

Example as with Transaction object, but also:

Example:

{
  "blockHash": null,
  "blockNumber": "0",
  "condition": {
    "block": "747000"
  },
  "creates": "",
  "from": "0x006E778F0fde07105C7adDc24b74b99bb4A89566",
  "gas": "21000",
  "gasPrice": "100000000000",
  "hash": "0x780b0a0c19819bd84a11bc050cb7b230de0d68bd08ed8cfd2f4c4db7cb7e2b78",
  "input": "0x",
  "networkId": 42,
  "nonce": "286",
  "publicKey": "0x46dc2dfd10421a5cb2e8750c54b4a991478ce8d026df4c1b7101b053a5dc8af8756c862978945f78ae47e35f93898c6f9d42ec8622c65f61ccb91c622a8749d9",
  "r": "0x87b4fbf8199018ee6501e8224b81b252a092ee1a961fa2e700f97e101e85e5b3",
  "raw": "0xf86e82011e85174876e8008252089400bc2ebf1d5a3f2f6a0aeb017c47a3d4739cd3b4880de0b6b3a76400008077a087b4fbf8199018ee6501e8224b81b252a092ee1a961fa2e700f97e101e85e5b3a02622b0b498406d78b06aa8aa6581137fc25b29010008f9af3878b4c1698337e2",
  "s": "0x2622b0b498406d78b06aa8aa6581137fc25b29010008f9af3878b4c1698337e2",
  "standardV": "0x0",
  "to": "0x00bc2EBf1d5a3F2F6a0aEb017C47a3D4739CD3B4",
  "transactionIndex": "0",
  "v": "0x77",
  "value": "1000000000000000000"
}

PropagationInfo

Information on the network propagation of a transaction.

Keys

Example:

{
  "firstSeen": 745512,
  "propagatedTo": {
      "0x48caeceb2724f2f71406990aa81efe87f8c53f26441d891473da2ae50cc138f238addc0e46b5aee240db55de8c711daac53d7b32a3f13e30edb86a3ca7c2700b": 1
  }
}

ReleaseInfo

Information concerning available updates.

Keys

Example

{
  "fork": 0,
  "this_fork": null,
  "track": new ReleaseVersion()
}

VersionInfo

Description of a release of Parity.

Keys

Example

{
  "binary": "0xf4e506d60763739ff9d59dfac577c71a3791512d7c552f8aa209d4069c11a9db",
  "fork": 0,
  "is_critical": false,
  "version": {
    "hash": "0x987390fb7d9f42a97c34aba254a8b9d8efd461d7",
    "track": "beta",
    "version": {
      "major": 1,
      "minor": 6,
      "patch": 5
    }
  }
}

Contract

An object representing a (deployed) instance of a contract. Contains one basic field and then additional functions for each of three types of items within the contract: public fields and constant functions; other (state-mutating) public functions and events.

Basic Keys

Fields and constant functions

These are the simplest to use. Each such item is represented as a function. This takes arguments in the case of a parameterised constant function or when the field represents an array, struct or mapping, correlated accordingly. Each parameter may itself be a Bond.

When the function is invoked, a Bond is returned expressing the ongoing value that the contract gives when queried. This is reactive to all changes, including those in the contract’s state, on its address (should that be a Bond) and on its parameters (where they are Bonds).

Example:

// Prints `gavofyork`'s address to the console.
bonds.registry.lookupAddress('gavofyork', 'A').log()

State-mutating functions

Each such item is represented as a function. This takes arguments exactly correlating to the function it maps from. When the function is invoked, a TransactionStatus bond is returned, tracking the state of the transaction required to execute and finalise that function.

The parameters of these functions may be Bonds, but the resultant Bond is not reactive to changes in parameters since they are one-off commands only.

Example:

// Prints a message depending on whether we managed to change the address of `gavofyork`.
import {sha3} from 'oo7-parity';
let b = bonds.registry.setAddress(sha3('gavofyork'), 'A', bonds.me);
b.tie(s => {
   if (s.failed) { console.log(`setAddress failed: ${s.failed}`); }
   else if (s.confirmed) { console.log(`setAddress completed at #${s.confirmed.blockNumber}`); }
   else { return; }
   b.untie();
})

Events

Events are represented as functions providing a Bond representing the state of a particular query. The query is described with two parameters passed to the function; both are given as objects. The value of the Bond is simply an array of (matching) events emitted by the contract. The first describes a filter applied over any or all of the indexed event arguments, allowing the resultant Bond to contain only events that match this filter. The second allows the provision of further options to govern which, and a limit on how many, events are contained in the Bond’s value.

Result value

This is an array of objects describing specific events emitted by the contract. Keys include:

In addition to these keys, further keys are provided for each event argument, named according to the corresponding argument in the original event.

First parameter: filter

This is the first of two parameters and helps filter events in the resultant array. filter is an object where each key must be the name of an event parameter marked indexed. The value may be either a required value for that parameter to be, or an array of alternative values.

All keys stated must be fulfilled for an event to be returned.

Second parameter: options

This is the second of two parameters. options is an object with three keys:

BadgeInfo

Information concerning a badge.

Keys

NamesInfo

Information detailing how an identity is named by various naming systems.

Keys