Documentation

Before you begin...

You might want to familiarise yourself with some Mochimo codebase lingo...

Transaction Buffer
The entire TX object used for communication between nodes

Transaction Data
The data contained within the Transaction Buffer (usually a Network Transaction)

Capability Bits
The bits of a byte after the version byte of a transaction buffer, indicating a Node's capabilities on the network

Operation Codes
Number codes used during socket connection to request certain operations with the Mochimo Network

Transaction Address
The full quantum resistant address used by the Mochimo Cryptocurrency Network

Source/Destination/Change Addresses
Due to the security concern of using "One Time Signatures" (see WOTS+), a standard transaction consists of 3 addressable parts:

The source address; the address where funds are transferred from,
The destination address; the address where funds are transferred to (the amount of funds that are transferred to this address is determined by the value of an associated "sendtotal" property), and
The change address; the address where the remaining funds that weren't sent to the destination address are received (the amount of funds that are transferred to this address is determined by the value of an associated "changetotal" property)

With that out of the way, let's begin...

Modules

Mochimo: Initialize integration with the Mochimo Cryptocurrency Network.

Classes

LEntry ⇐ Uint8Array: LEntry class objects are only accessible via the Block class.
The Ledger Entry class is a Uint8Array of static size containing a full WOTS+ address and a 64-bit balance.
TXEntry ⇐ Uint8Array: The Transaction class is a Uint8Array of static size containing all elements required for inclusion in a valid Mochimo Block or TX Object. TXEntry is typically used for reading transactions from a Mochimo Block.
BlockTrailer ⇐ Uint8Array: The BlockTrailer class is a Uint8Array of static size containing the trailer elements appended to a valid Mochimo Block. BlockTrailers can be joined together in series to create a historically verifiable chain known as a Tfile.
Block ⇐ Uint8Array: The Block class is a Uint8Array consisting of 3 main parts; a block header, block contents, and a block trailer. The contents of a block can be either transactions (for a normal block), ledger entries (for a neogenesis block), or empty (for a pseudo block).
Tfile ⇐ Uint8Array: The Tfile class is a Uint8Array desgined to contain all or part of the historically verifiable chain known as a Tfile in the Mochimo ecosystem.
Node: The Node class is primarily used to communicate with network peers connected to the Mochimo Cryptocurrency Network.
Tx ⇐ Uint8Array: The Tx class is a Uint8Array of static size representing the Transaction Buffer used to communicate with network peers.
Wots: The Wots class provides utility functions to generate, sign and verify WOTS+ addresses used by the Mochimo Network Blockchain, as well as a few pointer constants for positions of intra-address components.

Mochimo

Initialize integration with the Mochimo Cryptocurrency Network.

Example

const Mochimo = require('mochimo');

Mochimo
- ~constants : Object
- ~getBalance(peer, address, isTag) ⇒ Promise
- ~getBlock(peer, [bnum]) ⇒ Promise
- ~getHash(peer, [bnum]) ⇒ Promise
- ~getNetworkPeers(startPeers) ⇒ Promise
- ~getPeerlist(peer) ⇒ Promise
- ~getTfile(peer, [bnum], [count]) ⇒ Promise

Mochimo~constants : `Object`

Mochimo constants, used throughout the ecosystem of Mochimo protocols.

Kind: inner constant of Mochimo
Properties

Name	Type	Default	Description
INVALID_SOCKET	`Number`	`-1`	Expired/Unused Socket
VETIMEOUT	`Number`	`-1`	Return status for a timeout
VEOK	`Number`	`0`	Return status for no issues
VERROR	`Number`	`1`	Return status for a failure
VEBAD	`Number`	`2`	Return status for a failure and possible malice
C_PUSH	`Number`	`1`	Capability bit indicating the ability to push Candidate Blocks, used primarily by the Mochimo Windows Headless Miner (b00000001)
C_WALLET	`Number`	`2`	Capability bit indicating the operation of a wallet (b00000010)
C_SANCTUARY	`Number`	`4`	Capability bit indicating an activation of the Sanctuary Protocol (b00000100)
C_MFEE	`Number`	`8`	Capability bit indicating the desired Fee change outcome of the Sanctuary Protocol (b00001000)
C_LOGGING	`Number`	`16`	Capability bit indicating the availability of Logging (b00010000)
OP_NULL	`Number`	`0`	Operation code Null; Not used but usually indicating a lack of socket initialization during a transaction of data
OP_HELLO	`Number`	`1`	Operation code Hello; Used as a request code to initiate the first step of a Mochimo 3-way handshake
OP_HELLO_ACK	`Number`	`2`	Operation code Hello Acknowledgement; Used as a return code to indicate the second step of a Mochimo 3-way handshake
OP_TX	`Number`	`3`	Operation code Transaction; Used as request code to send a signed transaction to a Node for distribution across the Mochimo Network
OP_FOUND	`Number`	`4`	Operation code Block Found; Used as a network alert code indicating the existence of a new block update available for download. To obtain the block update, a new socket connection and opcode must be used
OP_GETBLOCK	`Number`	`5`	Operation code Get Block; Used as a request code to get/download a block from a Node. This operation can take some time if requesting a neogensis block, due to network speed and ledger file size
OP_GETIPL	`Number`	`6`	Operation code Get IP List; Used as a request code when requesting a Node's peer list
OP_SEND_BL	`Number`	`7`	Operation code Send Block; Used as a return code for validation when sending a block, usually after an OP_GETBLOCK is received
OP_SEND_IP	`Number`	`8`	Operation code Send IP List; Used as a validation code when sending a peer list, usually after an OP_GETIPL is received
OP_BUSY	`Number`	`9`	Operation code Busy; Used as a return code to indicate that a Node is currently busy and unable to process a request
OP_NACK	`Number`	`10`	Operation code No Acknowledgement operation code? The workings of this code is currently unknown, as it is unused throughout the codebase. I'm sure if I was to ask of it's original purpose I would get a clear and concise response. For now, this obnoxiously unhelpful description will serve as one of my adequate systems of unusual humor
OP_GET_TFILE	`Number`	`11`	Operation code Get Trailer File; Used as a request code to get/download a Node's entire Tfile. This operation can take some time, due to network speed and Tfile size
OP_BALANCE	`Number`	`12`	Operation code Address Balance; Used as a request code when requesting the balance of a Mochimo Address
OP_SEND_BAL	`Number`	`13`	Operation code Send Address Balance; Used as a return code for validation when sending the balance of a Mochimo Address
OP_RESOLVE	`Number`	`14`	Operation code Resolve Tag; Used as a request/return code when requesting the Mochimo Address registered to a Mochimo Tag
OP_GET_CBLOCK	`Number`	`15`	Operation code Get Candidate Block; Used as a request code to get/download a candidate block from a Node. Candidate blocks include all recent transactions for a Windows Headless Miner to find a solution
OP_MBLOCK	`Number`	`16`	Operation code Mined Block; Used as a network alert code indicating that a Windows Headless Miner has found a solution to a candidate block it received and requires assistance distributing the block update. Unlike OP_FOUND, the socket connection stays open to continue sending the block update along with OP_SEND_BL
OP_HASH	`Number`	`17`	Operation code Block Hash; Used as a request/return code when requesting the block hash of a specified block number
OP_TF	`Number`	`18`	Operation code Partial Trailer File; Used as a request code to get/download a section of a Trailer File. Requests can be up to 1000 trailers in size, and the operation is validated with an OP_SEND_BL return code
OP_IDENTIFY	`Number`	`19`	Operation code Identify; Used as a request/return code to identify which nodes have activated the Sanctuary protocol and obtain their Santuary specifications

Example

const Mochimo = require('mochimo');
console.log(`The value of VEOK is available at ${Mochimo.constants.VEOK}`);
console.log(`... and is also available at ${Mochimo.VEOK}`);

Mochimo~getBalance(peer, address, isTag) ⇒ `Promise`

Download a ledger entry from a network peer.

Kind: inner method of Mochimo
Fulfil: ?(external:Lentry) When the address or tag is found, promise resolves a new Mochimo.Lentry() object containing the ledger entry data. When the address or tag is NOT found, promise resolves null.
Reject: Error Error indicating the failure

Param	Type	Description
peer	`String`	IPv4 address of network peer
address	`String` \| `Uint8Array`	A Mochimo WOTS+ address or tagged address to search the ledger for.
isTag	`Boolean`	Indicates that the address is a tag.

Example

const Mochimo = require('mochimo');
const taggedAddress = '696c6c616d616e7564690000';

// request ledger entry balance and print results
Mochimo.getBalance('127.0.0.1', taggedAddress, true).then(lentry => {
  if (lentry === null) console.error('address not found in ledger');
  else {
    console.log('Full address:', lentry.address);
    console.log('Address tag:', lentry.tag);
    console.log('Balance:', lentry.balance);
  }
}).catch(console.error);

Mochimo~getBlock(peer, [bnum]) ⇒ `Promise`

Download a Mochimo Block file from a network peer.

Kind: inner method of Mochimo
Fulfil: Block A new Mochimo.Block() object containing the downloaded block data
Reject: Error Error indicating the failure

Param	Type	Description
peer	`String`	IPv4 address of network peer
[bnum]	`BigInt` \| `Number`	Blockchain number to download ^{Omit parameter to get peer's current block}

Example

const fsp = require('fs').promises;
const Mochimo = require('mochimo');

// download and write block data to file, else write error to stderr
Mochimo.getBlock('127.0.0.1', 123456).then(block => {
  return fsp.writeFile('000000000001e240.bc', block);
}).catch(console.error);

Mochimo~getHash(peer, [bnum]) ⇒ `Promise`

Download a Mochimo Block Hash from a network peer.

Kind: inner method of Mochimo
Fulfil: String The block hash represented as a string
Reject: Error Error indicating the failure

Param	Type	Description
peer	`String`	IPv4 address of network peer
[bnum]	`BigInt` \| `Number`	Blockchain number of desired hash ^{Omit parameter to get peer's current block}

Example

const Mochimo = require('mochimo');

// download and write block data to file, else write error to stderr
Mochimo.getBlock('127.0.0.1', 0).then(hash => {
  console.log('Genesis block hash: ' + hash);
}).catch(console.error);

Mochimo~getNetworkPeers(startPeers) ⇒ `Promise`

Get a list of available (non-busy) Mochimo Network peers.

Kind: inner method of Mochimo
Fulfil: Array.<String> An array of current network peers
Reject: Error Error indicating a failure

Param	Type	Description
startPeers	`Array.<String>` \| `String`	Either a single, or an array of, IPv4 addresses to network peers

Example

const Mochimo = require('mochimo');

// get list of peers and write to stdout, else write error to stderr
Mochimo.getNetworkPeers('127.0.0.1').then((list) => {
  console.log('Found %d Network Peers:\n%O', value.length, value));
}).catch(console.error);

Mochimo~getPeerlist(peer) ⇒ `Promise`

Download a peerlist from a network peer.

Kind: inner method of Mochimo
Fulfil: Array.<String> Array of peers as IPv4 strings
Reject: Error Error indicating a failure

Param	Type	Description
peer	`String`	IPv4 address of network peer

Example

const Mochimo = require('mochimo');

// request peerlist from network peer
Mochimo.getPeerlist('127.0.0.1').then(peerlist => {
  console.log('Peerlist: %O', peerlist);
}).catch(console.error);

Mochimo~getTfile(peer, [bnum], [count]) ⇒ `Promise`

Download partial or full Trailer file from a network peer.

Kind: inner method of Mochimo
Fulfil: Tfile A new Mochimo.Tfile() object containing the downloaded trailer data
Reject: Error Error indicating a failure

Param	Type	Description
peer	`String`	IPv4 address of network peer
[bnum]	`Number`	The first trailer to download (max 32bit number) ^{Omit parameter to download full trailer file (tfile.dat)}
[count]	`Number`	The number of trailers to download (max 1000) ^{Omit parameter to download one (1) trailer}

Example

const fsp = require('fs').promises;
const Mochimo = require('mochimo');

// download and write partial tfile to file, else write error to stderr
Mochimo.getTfile('127.0.0.1', 0, 24).then(tfile => {
  return fsp.writeFile('partialt_file.dat', tfile);
}).catch(console.error);

LEntry ⇐ `Uint8Array`

LEntry class objects are only accessible via the Block class.
The Ledger Entry class is a Uint8Array of static size containing a full WOTS+ address and a 64-bit balance.

Kind: global class
Extends: Uint8Array

LEntry ⇐ Uint8Array
- new LEntry([input], [byteOffset])
- instance
  - .address : String
  - .balance : BigInt
  - .tag : String
  - .toJSON() ⇒ Object
- static
  - .length : Number
  - .ADDRESSp : Number
  - .TAGp : Number
  - .BALANCEp : Number

new LEntry([input], [byteOffset])

Create a new Ledger Entry for the handling of an address-balance pair.

Param	Type	Default	Description
[input]	`Buffer` \| `ArrayBuffer`		An existing ledger entry or wots address (as a Buffer only). ^{When input is a Buffer, a new underyling Uint8Array is created and set with the contents of input. When input is an ArrayBuffer, a new "view" of the ArrayBuffer is created.}
[byteOffset]	`Number`	`0`	The byte offset of the ledger entry view, when `input` is an ArrayBuffer. ^{Does nothing when input is not an ArrayBuffer.}

lentry.address : `String`

The full 2208 byte Mochimo address, in hexadecimal format

Kind: instance property of LEntry
Default: "0000... <4416 characters>"
Throws:

TypeError when set an invalid data type*
^{*Valid data
types are hexadecimal String, Array or
TypedArray.}
TypeError when set a value of invalid length*
^{*Must be 4416 hexadecimal character String or 2208 byte Array.}

lentry.balance : `BigInt`

The associated balance, in nanoMochimo

Kind: instance property of LEntry
Default: 0n
Throws:

TypeError when set value cannot be converted to the original type

lentry.tag : `String`

The tag attached to the ledger address, in hexadecimal format

Kind: instance property of LEntry
Default: "0000... <24 characters>"
Throws:

TypeError when set an invalid data type*
^{*Valid data
types are hexadecimal String, Array or
TypedArray.}
TypeError when set a value of invalid length*
^{*Must be 24 hexadecimal character String or 12 byte Array.}

lentry.toJSON() ⇒ `Object`

Kind: instance method of LEntry
Returns: Object - LEntry class object, in JSON format
Properties

Name	Type	Description
address	`Number`	refer to LEntry class properties
balance	`Number`
tag	`Number`

LEntry.length : `Number`

Breakdown:

WOTS+ address, 2208 bytes
Balance (64bit), 8 bytes

Kind: static property of LEntry
Constant_value: 2216

LEntry.ADDRESSp : `Number`

FOR ADVANCED USE ONLY!
Array pointer to address

Kind: static property of LEntry
Constant_value: 0

LEntry.TAGp : `Number`

FOR ADVANCED USE ONLY!
Array pointer to tag

Kind: static property of LEntry
Constant_value: 2196

LEntry.BALANCEp : `Number`

FOR ADVANCED USE ONLY!
Array pointer to balance

Kind: static property of LEntry
Constant_value: 2208

TXEntry ⇐ `Uint8Array`

The Transaction class is a Uint8Array of static size containing all elements required for inclusion in a valid Mochimo Block or TX Object. TXEntry is typically used for reading transactions from a Mochimo Block.

Kind: global class
Extends: Uint8Array

TXEntry ⇐ Uint8Array
- new TXEntry([input], [byteOffset])
- instance
  - .srcaddr : String
  - .srctag : String
  - .dstaddr : String
  - .dsttag : String
  - .chgaddr : String
  - .chgtag : String
  - .sendtotal : BigInt
  - .changetotal : BigInt
  - .txfee : BigInt
  - .txsig : String
  - .txid : String
  - .toJSON(minify) ⇒ Object
- static
  - .SRCADDRp : Number
  - .DSTADDRp : Number
  - .CHGADDRp : Number
  - .SENDTOTALp : Number
  - .CHANGETOTALp : Number
  - .TXFEEp : Number
  - .TXSIGp : Number
  - .TXIDp : Number
  - .length : Number

new TXEntry([input], [byteOffset])

Create a new Transaction Entry.

Param	Type	Default	Description
[input]	`Buffer` \| `ArrayBuffer`		An existing transaction entry. ^{When input is a Buffer, a new underyling Uint8Array is created and set with the contents of input. When input is an ArrayBuffer, a new "view" of the ArrayBuffer is created.}
[byteOffset]	`Number`	`0`	The byte offset of the transaction entry view, when `input` is an ArrayBuffer. Does nothing when `input` is not an ArrayBuffer.