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.- Initialize a zChain node
- Initialize
- Public Instance Methods
- zchain.subscribe(channel)
- zchain.unsubscribe(channel)
- zchain.publish(channel, message, channels)
- zChain properties
- 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)
Creates and returns an instance of an initialized zChain node. During initialization we:
- initialize a new zId (libp2p 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 existing node (& configuration) will be used to initialize zchain. - save peer-id at
~/.zchain/zId/<name>.json
- initialize LeveldbPersistence (level-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:
const zChain = new ZCHAIN();
await zChain.initialize('node-a', [ '/ip4/0.0.0.0/tcp/0', .. ]);
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:
node.subscribe('#meow');
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:
node.unsubscribe('#meow');
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:
// publish message on channel #meow (& pass the other channels the message is being published to)
await node.publish('#meow', "bird bird bird!", [ '#meow', '#everything', '#zero' ]);
zChain
class properties.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.
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() . |
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.
Class to handle Peer Discovery, connections and protocols by libp2p node
zStore.init()
Initializes storage for zChain. We use level-db as our primary database, which is a fast embedded database. It is the underlying technology of IndexedDB. The store is initialized at
~/.zchain/db/<zIdName>/
During initialization we load the following databases:
- open and load the feed databases (replicate among shared peers)
- open and load the local address book yDoc (private yDoc).
- open and load the metaData yDoc (public yDoc storing peer's ethereum addresses and signatures)
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.
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 ethereum address.
Arguments | Descriptions |
---|---|
peerID (string) | The unique peerID for which to query the associated addresses + signatures. |
Last modified 1yr ago