zChain
zChain API Documentation
API documentation for the zChain class. Implementation can be found at https://github.com/zer0-os/zChain/tree/main/packages/zchain-core.

Table of Contents

  • Initialize a zChain node
    • Initialize
  • Public Instance Methods
    • zchain.startDaemon(zIdName, listenAddrs?)
    • zchain.load()
    • zchain.subscribe(channel)
    • zchain.unsubscribe(channel)
    • zchain.publish(channel, message, channels)
  • zChain properties
    • zchain.ipfs
    • zchain.node
    • zchain.zId
      • zId.createNew()
      • zId.createFromName(name)
    • zchain.peerDiscovery
      • peerDiscovery.addBootstrapNodes(nodes[])
      • peerDiscovery.onConnect(handler: () => {}))
      • peerDiscovery.onDiscover(handler: () => {}))
      • peerDiscovery.handleProtocol(protocol, handler: () => {})
    • zchain.zStore
      • zStore.init()
      • zStore.appendZChainMessageToFeed(feedStore, message, channels, network?)
      • zStore.getMessagesOnFeed(peerIdStr, n)
      • zStore.getNameAndPeerID(peerIdOrName)
      • zStore.setNameInAddressBook(peerId, name, force)
      • zStore.addEthAddressAndSignature(ethAddress, ethSignature, setAsDefault)
      • zStore.updateDefaultEthAddress(ethAddress)
      • zStore.getPeerEthAddressAndSignature(peerID)

Initialize a zChain node

initialize(name, listenAddrs)

Creates and returns an instance of an initialized zChain node. During initialization we:
  • initialize a new zId (ipfs peerID using zIdName). If you're initializing a node for the first time (i.e ~/.zchain/zId/<name>.json) does not exist, a new peer-id will be generated and saved there. If a peer-id by this name already exists, then that exisinting node (& configuration) will be used to initialize that node.
  • save peer-id at ~/.zchain/zId/<name>.json
  • initialize an ipfs node (at ~/.zchain/ipfs/<name>/)
  • initialize zStore (orbit-db storage for messages, at ~/.zchain/db/<name>/)
  • initialize discovery class (for discovery & connections)
function initialize( name: string, listenAddrs: string[] ): Promise<Libp2p>
Arguments
Descriptions
name (string)
zId Name assigned to this node by the end user
listenAddrs (string[], optional)
Additional multiaddrs this node can listen to.
Usage:
1
const zChain = new ZCHAIN();
2
await zChain.initialize('node-a', [ '/ip4/0.0.0.0/tcp/0', .. ]);
Copied!

Public Instance Methods

zchain.startDaemon(name, listenAddrs?)

Similar to initialize(), but it starts a new ipfs daemon, which other terminal/processes can connect to using an http endpoint. Note that this won't open/load the databases. This function is meant to run the ipfs node only (as a daemon).
Arguments
Descriptions
name (string)
zId Name assigned to this node by the end user
listenAddrs (string[], optional)
Additional multiaddrs this node can listen to.
Usage:
1
const daemon = await this.zchain.startDaemon('my-daemon');
Copied!

zchain.load()

Connects to an existing ipfs daemon (fails otherwise, you must run start daemon before). Opens and loads up the databases. The usecase for startDaemon & load() could be within a CLI. On one screen you start the daemon, and on another you connect to it, laod the databases, and execute the commands.

zchain.subscribe(channel)

Subscribe to a particular channel (topic in pubsub messaging system). After subscribing to a topic, any message published on that topic will be received by this node.
Arguments
Descriptions
channel (string)
Name of channel to subscribe
Usage:
1
node.subscribe('#meow');
Copied!

zchain.unsubscribe(channel)

Unsubscribe from a particular channel (topic in pubsub messaging system). After unsubscribing from a topic, you will no longer receive any message published on that topic.
Arguments
Descriptions
channel (string)
Name of channel to unsubscribe
Usage:
1
node.unsubscribe('#meow');
Copied!

zchain.publish(channel, message, channels)

Publish a message on a channel(topic).
Arguments
Descriptions
channel (string)
Name of the channel accross which message will be published
message (string)
The message.s this node can listen to.
channels (string[])
Array of channels (if same message is published on multiple channels, this should be passed).
Usage:
1
// publish message on channel #meow (& pass the other channels the message is being published to)
2
await node.publish('#meow', "bird bird bird!", [ '#meow', '#everything', '#zero' ]);
Copied!

zChain properties

zChain class properties.

ipfs

The ipfs node. Repo located at ~/.zchain/ipfs/<zIdName>/. Read more about the ipfs API docs here.

node

Libp2p node. Libp2p is a modular system of protocols, specifications, and libraries that enable the development of peer-to-peer network applications. As the network layer for IPFS, Libp2p provides flexible solutions for essential peer-to-peer elements like transport, security, peer routing, and content discovery. Libp2p node is derived from ipfs.libp2p.

zId

Class representing zchain id (a persistent peer id accross zchain nodes).
zId.createFromName(name)
Creates a new peerid or load an exsiting peerID from a name.
Arguments
Descriptions
name (string)
Name assigned to the zChain node. For more information, check zChain.initialize().

peerDiscovery

Class to handle Peer Discovery, connections and protocols by libp2p node
peerDiscovery.addBootstrapNodes(nodes)
Adds a list of bootstrapped nodes to the ipfs node. A bootstrap node is a node which the ipfs node connects to initally during start.
peerDiscovery.onConnect (handler)
On Connect handler, triggered after a new connection is established.
Parameters:
  • handler ((connection: Libp2p.Connection) => void): callback after new connection is established.
peerDiscovery.onDiscover (handler)
On Discover handler, triggered after a new peer os discovered.
Parameters:
  • handler ((peerId: PeerId) => void): callback after new peer is discovered.
peerDiscovery.handleProtocol(protocol handler: (props: Libp2p.HandlerProps) => void)
Handle listen protocol for libp2p node.
Parameters:
  • protocol (string): The protocol name to listen to. eg. /chat/1.0.0.
  • handler ((props: Libp2p.HandlerProps) => void): Callback after protocol is negotiated.

zStore

Class to handle Peer Discovery, connections and protocols by libp2p node
zStore.init()
Initializes storage for zChain. We use orbitdb (a serverless, distributed, peer-to-peer database.) as our primary database. The store is initialized at ~/.zchain/db/<zIdName>/
During initialization we load the following databases:
  • open and load the feed database (your local messages feed).
  • open and load the local address book db.
zStore.appendZChainMessageToFeed(feedStore, message, channels, network?)
Appends a new zchain message to the local feed.
Arguments
Descriptions
feedStore (string)
The feed store (orbitdb database) to append the message to.which message will be published
message (string)
The message.s this node can listen to.
channels (string[])
Array of channels (if same message is published on multiple channels, this should be passed).
network (string, optional)
Name of the network, if the message is being published on a channel in a network.
zStore.getMessagesOnFeed(peerIdStr, n)
Returns last "n" messages published by a node. Loads last "n" entry from the local feed database, and logs them.
Arguments
Descriptions
peerIdStr (string)
Peer ID as base58-encoded string.
n (number)
Number of messages to display.
zStore.getNameAndPeerID(peerIdOrName)
Determines {peerId, name, display string} for given peerId/name from the local address book.
Arguments
Descriptions
peerIdOrName (string)
Peer ID as base58-encoded string, or the peer name.
zStore.setNameInAddressBook(peerId, name, force)
Sets a name of the peerId in the local address book database. Throws an error if force is false and a display name is already present.
Arguments
Descriptions
peerId (string)
The peerID (as base58 encoded string).
name (string)
Display name to set for this peerID.
force (boolean, optional)
If true, updates the displayName for a peer, if it has already set previously.
zStore.addEthAddressAndSignature(ethAddress, ethSignature, setAsDefault)
Stores an ethereum address (checksumed) and associated signature in the global metaData database. The unique peerID of the user must be signed with the associated ethereum account's private key, and the resulting signature *must* be passed in this function. Otherwise, the verification fails. You can also add multiple addresses, associated with a peerID. By default, the first entry is set as the "default address" for that peer. You can change it later.
Arguments
Descriptions
ethAddress (string)
Ethereum account address.
ethSignature (string)
Signature (obtained by signing the peerID as message, with the eth account)
setAsDefault (boolean, optional)
If true, updates the default address to the ethAddress passed.
zStore.updateDefaultEthAddress(ethAddress)
Updates the default ethereum address for the peer. Throws an error if ethereum address has not been added yet (with verification)
Arguments
Descriptions
ethAddress (string)
Ethereum account address to update the default address to.
zStore.getPeerEthAddressAndSignature(peerID)
Returns an array of associated ethereum addresses + signatures for the given peer, along with the default eth address.
Arguments
Descriptions
peerID (string)
The unique peerID for which to query the associated addresses + signatures.
Last modified 13d ago