Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
281 lines (221 sloc) 5.44 KB

Nimiq Core API documentation

This documentation describes the API of the Betanet branch.

All Nimiq Core classes reside in the Nimiq. namespace.

Nimiq

Basic initialization

Nimiq.init($ => {
    // $ is the Nimiq.Core instance
});

Initialization with error callback

  • Nimiq.ERR_WAIT: An instance of Nimiq Core is already running in another window of the same origin. When all other windows are closed, the success callback will be invoked.
  • Nimiq.ERR_UNSUPPORTED: This browser is not supported.
  • Nimiq.ERR_UNKNOWN: An unknown error occured while loading.
  • Nimiq.Wallet.ERR_INVALID_WALLET_SEED : An invalid wallet seed has been provided.
Nimiq.init($ => {
    // $ is the Nimiq.Core instance
}, code => {
    switch (code) {
        case Nimiq.ERR_WAIT:
            alert('Another Nimiq instance is already running');
            break;
        case Nimiq.ERR_UNSUPPORTED:
            alert('Browser not supported');
            break;
        case Nimiq.Wallet.ERR_INVALID_WALLET_SEED:
            alert("Invalid wallet seed");
            break;
        default:
            alert('Nimiq initialization error');
            break;
    }
});

Initialization with options

You can pass some options to initialization.

Option Description
walletSeed Wallet seed (See Nimiq.Wallet)
const options = {
  walletSeed: "d6a651dcc13dab2e9d05d..."
}

Nimiq.init($ => {
    // $ is the Nimiq.Core instance
}, code => {
  // Handle errors
},
  options
);

Get an existing instance

Nimiq.get().then($ => {
    // $ is the Nimiq.Core instance
});

Nimiq.Core

Properties

Methods

No public methods.

Events

No events.

Nimiq.Network

The network will not connect automatically, call $.network.connect() to do so.

Properties

  • peerCount
  • peerCountWebSocket
  • peerCountWebRtc
  • bytesReceived
  • bytesSent

Methods

  • connect()
  • disconnect()

Events

  • peers-changed
  • peer-joined (peer)
  • peer-left (peer)

Examples

Connect to the network:

$.network.connect()

Listen for peer connections:

$.network.on('peers-changed', () => console.log('Peers changed'));
$.network.on('peer-joined', peer => console.log(`Peer ${peer} joined`));
$.network.on('peer-left', peer => console.log(`Peer ${peer} left`));

Nimiq.Consensus

Properties

  • established

Methods

No public methods.

Events

  • syncing (targetHeight)
  • established
  • lost

Examples

Listen for established event:

$.consensus.on('established', () => console.log('consensus established!'))

Nimiq.Accounts

Properties

No public properties.

Methods

  • getBalance(address)
  • commitBlock(block)
  • revertBlock(block)
  • async hash()

Events

  • <<base64(address)>> (balance, address) when balance of address changes.

Examples

Query an account's balance:

$.accounts.getBalance(<<address>>).then(balance => {
    console.log(balance.value)
    console.log(balance.nonce)
})

Listen for an account balance change:

$.accounts.on('a09rjiARiVYh2zJS0/1pYKZg4/A=').then(balance => {
    console.log(balance)
})

Nimiq.Blockchain

Properties

  • head
  • headHash
  • totalWork
  • height
  • path
  • busy

Methods

  • pushBlock(block)
  • getBlock(hash)
  • getNextCompactTarget()
  • async accountsHash()

Events

  • head-changed
  • ready

Examples

Show the blockchain sync progress

let targetHeight = 0;
$.consensus.on('syncing', _targetHeight => {
    targetHeight = _targetHeight;
})

$.blockchain.on('head-changed', () => {
    const height = $.blockchain.height;
    ui.setProgress(height / targetHeight);
})

Nimiq.Mempool

Properties

No public properties.

Methods

  • pushTransaction(transaction)
  • getTransaction(hash)
  • getTransactions(maxCount = 5000)

Events

  • transaction-added
  • transactions-ready

Nimiq.Wallet

Properties

  • address
  • publicKey

Methods

  • createTransaction(recipientAddr, value, fee, nonce)
  • dump()

Events

No events.

Examples

Create a transaction:

$.wallet.createTransaction(recipientAddr, value, fee, nonce).then(transaction => {
    console.log(transaction)
})

Dump and restore wallet:

var walletSeed = $.wallet.dump();
var restoredWallet = await Wallet.load(walletSeed);

Nimiq.Miner

Mining should not start before consensus is established and stop when consensus is lost. The Miner does not explicitely enforce this, but callers should ensure this behavior.

// Start mining automatically once consensus is (re-)established.
$.consensus.on('established', () => $.miner.startWork());

// Stop mining when consensus is lost. All clients should do this!
$.consensus.on('lost', () => $.miner.stopWork());

Properties

  • working
  • address
  • hashrate

Methods

  • startWork()
  • stopWork()

Events

  • start
  • stop
  • block-mined
  • hashrate-changed