Swiftpack.co - Package - CityOfZion/neo-js

City of Zion logo


A package for running a node on the neo blockchain.

Build Status npm version


The neo-js package is designed to interface with the Neo blockchain in a number of different ways that are configured by options that are used to initialize a node. A few examples of these different interaction mechanics are defined in the quickstart below as well as in the examples.

note: All blockchain events (Invocation and Deploy) use the RPC calls to interface with the blockchain unless they can be run locally (sometimes referred to as a 'test invoke')

A note on local storage

Currently this module only support MongoDB for synchronizing the blockchain. Future storage types are planning including other NoSQL databases, SQL databases, and in-memory solutions.

This module uses 'lazy caching' to improve performance when using local storage. Blocks are initially downloaded and stored in three collections (blocks, transactions, and addresses) as a result of the sync process. Upon the first request for a specific transaction (as a result of any number of the methods), the transaction will be expanded as described in Neon wallet architecture and updated in the collection. The next time the block is requested, the expanded transaction will already be available in the collection.

This mechanic is also used for address balances. Upon requesting an update for an asset balance, the transaction collection is analyzed and the asset balance is stored in an account collection along with the max block height during the calculation. Upon future requests for the asset balance, the asset collection is first queried for previous balance. The asset balance is then updated using only the new blocks since the previous calculation event.

System Recommendations

  • NodeJS 8+
  • MongoDB 3.0+


Install the package using:

$ npm install --save @cityofzion/neo-js

Alternatively, to access to the latest available code, you can reference to the git repository directly:

$ npm install --save CityOfZion/neo-js#develop

note: neo-js requires that MongoDB server is installed to run the instance as a full node. Installation instructions can be found in MongoDB installation manual.

Quick Start

const Node = require('@cityofzion/neo-js')

To create a new blockchain instance:

// create the local node instance that will interface with the rpc methods
const nodeT = new Node({ network: 'testnet' }) //on testnet
const nodeM = new Node({ network: 'mainnet' }) //on mainnet

nodeT.mesh.rpc('getBlock', 1000) //get block 1000 from testnet
nodeM.mesh.rpc('getBlock', 1000) //get block 1000 from mainnet

This will create a new node instance and configure it to sync the blockchain to a 3 mongoDB collections that we define:

const options = {
  network: 'testnet',
  storage: {
    model: 'mongoDB',
    collectionNames: {
      blocks: 'b_neo_t_blocks',
      transactions: 'b_neo_t_transactions',
      addresses: 'b_neo_t_addresses'

// create the local node instance and get the local block count after 5 seconds.
const node = new Node(options)

setTimeout(() => {
    .then( (res) => console.log(res) )
}, 5000)


Documentation (incomplete) for the project can be found at:

  • http://cityofzion.io/neo-js/

Self-documented code examples are available as part of the project source code:

  • https://github.com/CityOfZion/neo-js/blob/master/examples


neo-js always encourages community code contribution. Before contributing please read the contributor guidelines and search the issue tracker as your issue may have already been discussed or fixed. To contribute, fork neo-js, commit your changes and submit a pull request.

By contributing to neo-js, you agree that your contributions will be licensed under its MIT license.



Stars: 50
Help us keep the lights on


Used By

Total: 0


v0.6.0 - Jan 8, 2018

The neo-js 0.6.0 feature release key enhancements:

  • System asset support
  • Wallet support
  • Ability to connect to private blockchain networks

v0.5.11 - Jan 2, 2018

neo-js packge is now available on NPM under the CityOfZion organization scope:

  • https://www.npmjs.com/package/@cityofzion/neo-js

v0.5.0 - Nov 28, 2017

neo-js 0.5 maintenance release key enhancements:

  1. neo-js code base has been largely rearchitected and large amounts of the code have been rewritten to improve scalability and legibility.
  2. Substantial User Experience enhancements have been made. These changes BREAK existing usage so reference the documentation and Examples.
  3. Test Coverage has been extended to all RPC methods.
  4. Examples of module usage are now provided in the examples directory.
  5. Documentation Improvements & Misc Bug fixes
  6. Modular storage type support allows local nodes to easily sync to different data warehouses.
  7. Chain synchronization is now handled by the mesh features of a node.