factom

1.0.1

FactomCli

Main class to read and write data from Factom blockchain.

new FactomCli(opts: Object?)
Parameters
opts (Object?) Options of connection to factomd and factom-walletd.
Name Description
opts.factomd ConnectionOptions? Options of connection to factomd.
opts.walletd ConnectionOptions? Options of connection to factom-walletd.
Example
const cli = new FactomCli({
     factomd: {
         host: 'api.factomd.net',
         port: 443,
         protocol: 'https'
     },
     walletd: {
         host: 'localhost',
         user: 'paul',
         password: 'pass'
     }
});
Instance Members
add(obj, ecAddress, options?)
addChain(chain, ecAddress, options?)
addChains(chains, ecAddress, options?)
addEntries(entries, ecAddress, options?)
addEntry(entry, ecAddress, options?)
chainExists(chainId)
commit(obj, ecAddress, commitAckTimeout)
commitChain(chain, ecAddress, commitAckTimeout)
commitEntry(entry, ecAddress, commitAckTimeout)
createEntryCreditPurchaseTransaction(originAddress, recipientAddress, ecAmount, fees?)
createFactoidTransaction(originAddress, recipientAddress, amount, fees?)
factomdApi(method, params?)
getAdminBlock(arg)
getAllEntriesOfChain(chainId)
getBalance(address)
getChainHead(chainId)
getDirectoryBlock(arg)
getDirectoryBlockHead()
getEntry(entryHash)
getEntryBlock(keyMR)
getEntryCreditBlock(arg)
getEntryCreditRate()
getEntryWithBlockContext(entryHash)
getFactoidBlock(arg)
getFirstEntry(chainId)
getHeights()
getPrivateAddress(address)
getTransaction(txId)
reveal(obj, revealAckTimeout)
revealChain(chain, revealAckTimeout)
revealEntry(entry, revealAckTimeout)
rewindChainWhile(chainId, predicate, func)
sendTransaction(transaction, options?)
waitOnCommitAck(txId, timeout)
waitOnFactoidTransactionAck(txId, timeout)
waitOnRevealAck(hash, chainId, timeout)
walletdApi(method, params?)

addressToKey

Extract the key contained in an address. Cannot be used with public FCT address as those contain a RCD hash and not a key (See addressToRcdHash).

addressToKey(address: string): Buffer
Parameters
address (string) Any address, except public FCT address.
Returns
Buffer: Key contained in the address.

addressToRcdHash

Extract the RCD hash from a public FCT address.

addressToRcdHash(address: string): Buffer
Parameters
address (string) Public FCT address.
Returns
Buffer: RCD hash.

AdminBlock

Class representing an Admin block.

new AdminBlock()
Properties
backReferenceHash (string) : Back reference hash.
lookupHash (string) : Lookup hash.
directoryBlockHeight (number) : Directory block height.
previousBackReferenceHash (string) : Back reference hash of previous Admin block.
headerExpansionSize (number) : Header expansion size.
headerExpansionArea (string) : Header expansion area.
bodySize (number) : Size of the body.
entries (Object) : Admin entries. Each entry has its own type (can be identified either by its adminId (number) or its adminCode (string)).
Instance Members
getEntriesOfTypes(types)

EntryBuilder

Class to build an Entry

new EntryBuilder(entry: (Entry | Object)?)
Parameters
entry ((Entry | Object)?) Optional entry to use to initialize the attributes of the builder.
Instance Members
blockContext(blockContext)
build()
chainId(chainId, enc)
content(content, enc)
extId(extId, enc)
extIds(extIds, enc)
timestamp(timestamp)

TransactionBuilder

Class to build a Transaction.

new TransactionBuilder(transaction: Transaction?)
Parameters
transaction (Transaction?) Optional transaction to use to initialize the attributes of the builder.
Instance Members
build()
input(fctAddress, amount)
output(publicAddress, amount)
rcdSignature(rcd, signature)
timestamp(timestamp)

Entry

Class representing an Entry.

new Entry(builder: EntryBuilder)
Parameters
builder (EntryBuilder)
Properties
chainId (Buffer) : Chain ID.
extIds (Array<Buffer>) : External IDs.
content (Buffer) : Content.
timestamp (number) : Timestamp in milliseconds for the commit.
blockContext (EntryBlockContext) : Block context. This property is not populated when using the method getEntry.
Example
const myEntry = Entry.builder()
.chainId('9107a308f91fd7962fecb321fdadeb37e2ca7d456f1d99d24280136c0afd55f2')
.extId('6d79206578742069642031') // If no encoding parameter is passed as 2nd argument, 'hex' is used as default
.extId('Some external ID', 'utf8')
.content('My new content',  'utf8')
.build();
Static Members
builder(entry?)
Instance Members
chainIdHex
contentHex
ecCost()
extIdsHex
hash()
hashHex()
marshalBinary()
marshalBinaryHex()
payloadSize()
rawDataSize()
remainingFreeBytes()
remainingMaxBytes()
size()
toObject()

Transaction

Class representing a Factoid transaction.

new Transaction(builder: TransactionBuilder, blockContext: TransactionBlockContext?)
Parameters
builder (TransactionBuilder)
blockContext (TransactionBlockContext?)
Properties
id (string) : Transaction ID.
timestamp (number) : Timestamp in milliseconds.
inputs (Array<TransactionAddress>) : Inputs.
factoidOutputs (Array<TransactionAddress>) : Factoid outputs.
entryCreditOutputs (Array<TransactionAddress>) : Entry Credit outputs.
totalInputs (number) : Total amount of factoshis as input of this transaction.
totalFactoidOutputs (number) : Total amount of factoshis as factoid outputs of this transaction.
totalEntryCreditOutputs (number) : Total amount of factoshis as entry credit outputs of this transaction.
feesPaid (number) : Fees paid in this transaction.
blockContext (TransactionBlockContext) : Block context.
rcds (Array<Buffer>) : RCDs.
signatures (Array<Buffer>) : Signatures.
Example
const transaction = Transaction.builder()
  .input('Fs2w6VL6cwBqt6SpUyPLvdo9TK834gCr52Y225z8C5aHPAFav36X', 14000000)
  .input('Fs2E6iXCLAKDiPqVtfxtuQCKsTe7o6DJFDnht1wST53s4ibtdu9f', 1010000 + fees)
  .output('FA3syRxpYEvFFvoN4ZfNRJVQdumLpTK4CMmMUFmKGeqyTNgsg5uH', 5000000)
  .output('FA24PAtyZWWVAPm95ZCVpwyY6RYHeCMTiZt2v4VQAY8aBXMUZteF', 10000000)
   // Note that the line below is to buy Entry Credits (see the address type) and the amount is in Factoshis like other outputs: 
   // it is *not* the number of Entry Credits you are purchasing.
  .output('EC2UFobcsWom2NvyNDN67Q8eTdpCQvwYe327ZeGTLXbYaZ56e3QR', 10000)
  .build()
Static Members
builder(transaction?)
Instance Members
computeEcRequiredFees(opts?)
computeRequiredFees(ecRate, opts?)
isSigned()
marshalBinary()
validateFees(ecRate)

FactomdCli

Factomd API client.

new FactomdCli(conf: ConnectionOptions?)

Extends BaseCli

Parameters
conf (ConnectionOptions?) Factomd connection options.
Instance Members
call(method, params?)

WalletdCli

Walletd API client.

new WalletdCli(conf: ConnectionOptions?)

Extends BaseCli

Parameters
conf (ConnectionOptions?) Walletd connection options.
Instance Members
call(method, params)

Chain

Class representing a Chain.

new Chain(arg: (Entry | Chain))
Parameters
arg ((Entry | Chain)) First entry of the chain or another chain to copy.
Properties
id (Buffer) : Chain ID.
firstEntry (Entry) : First entry of the chain.
Instance Members
ecCost()
idHex
toObject()

composeChain

Compose the commit and reveal of a Chain, that can then be used as inputs of the factomd APIs commit-chain and reveal-chain.

composeChain(chain: Chain, ecAddress: string, signature: (string | Buffer)?): {commit: Buffer, reveal: Buffer}
Parameters
chain (Chain) Chain to compose the commit and reveal of.
ecAddress (string) Entry Credit address that pays for the commit, either private (Es) or public (EC). If a public EC address is provided it is necessary to manually pass the signature of the commit as a 3rd argument (use case for hardware wallets)
signature ((string | Buffer)?) Optional signature of the commit (composeChainLedger). Only necessary if a public EC address was passed as 2nd argument.
Returns
{commit: Buffer, reveal: Buffer}: Chain commit and reveal.

composeChainCommit

Compose the commit of a Chain, that can then be used as input of the factomd API commit-chain. Note that if the chain first entry doesn't have a timestamp set the library will use Date.now() as the default for the commit timestamp.

composeChainCommit(chain: Chain, ecAddress: string, signature: (string | Buffer)?): Buffer
Parameters
chain (Chain) Chain to compose the commit of.
ecAddress (string) Entry Credit address that pays for the commit, either private (Es) or public (EC). If a public EC address is provided it is necessary to provide the signature of the commit as a 3rd argument (use case for hardware wallets)
signature ((string | Buffer)?) Optional signature of the commit (composeChainLedger). Only necessary if a public EC address was passed as 2nd argument.
Returns
Buffer: Chain commit.

composeChainReveal

Compose the reveal of a Chain, that can then be used as input of the factomd API reveal-chain.

composeChainReveal(chain: Chain): Buffer
Parameters
chain (Chain) Chain to compose the reveal of.
Returns
Buffer: Chain reveal.

composeEntry

Compose the commit and reveal of an Entry, that can then be used as inputs of the factomd APIs commit-entry and reveal-entry.

composeEntry(entry: Entry, ecAddress: string, signature: (string | Buffer)?): {commit: Buffer, reveal: Buffer}
Parameters
entry (Entry) Entry to compose the commit and reveal of.
ecAddress (string) Entry Credit address that pays for the commit, either private (Es) or public (EC). If a public EC address is provided it is necessary to manually pass the signature of the commit as a 3rd argument (use case for hardware wallets)
signature ((string | Buffer)?) Optional signature of the commit (composeEntryLedger). Only necessary if a public EC address was passed as 2nd argument.
Returns
{commit: Buffer, reveal: Buffer}: Entry commit and reveal.

composeEntryCommit

Compose the commit of an Entry, that can then be used as input of the factomd API commit-entry. Note that if the Entry doesn't have a timestamp set the library will use Date.now() as the default for the commit timestamp.

composeEntryCommit(entry: Entry, ecAddress: string, signature: (string | Buffer)?): Buffer
Parameters
entry (Entry) Entry to compose the commit of.
ecAddress (string) Entry Credit address that pays for the commit, either private (Es) or public (EC). If a public EC address is provided it is necessary to provide the signature of the commit as a 3rd argument (use case for hardware wallets)
signature ((string | Buffer)?) Optional signature of the commit (composeEntryLedger). Only necessary if a public EC address was passed as 2nd argument.
Returns
Buffer: Entry commit.

composeEntryReveal

Compose the reveal of an Entry, that can then be used as input of the factomd API reveal-entry.

composeEntryReveal(entry: Entry): Buffer
Parameters
entry (Entry) Entry to compose the reveal of.
Returns
Buffer: Entry reveal.

computeChainId

Compute the ID of a Chain provided its first entry.

computeChainId(firstEntry: Entry): Buffer
Parameters
firstEntry (Entry) The first entry of the chain.
Returns
Buffer: Chain ID.

computeChainTxId

Compute the transaction ID of the Chain commit. The transaction ID is dependent on the timestamp set in the chain first entry. Note that if the timestamp is not set the library uses Date.now() as the default, changing the result of this function if called at different times.

computeChainTxId(chain: Chain): Buffer
Parameters
chain (Chain)
Returns
Buffer: The transaction id of the Chain commit.

computeEntryTxId

Compute the transaction ID of the Entry commit. The transaction ID is dependent on the timestamp set in the entry. Note that if the timestamp is not set the library uses Date.now() as the default, changing the result of this function if called at different times.

computeEntryTxId(entry: Entry): Buffer
Parameters
entry (Entry)
Returns
Buffer: The transaction id of the Entry commit.

ConnectionOptions

Describe the options of connection to factomd or factom-walletd.

ConnectionOptions

Type: Object

Properties
host (string?) : IP or hostname. Default to localhost.
port (number?) : Port. Default to 8088 for factomd and 8089 for walletd.
path (string?) : Path to V2 API. Default to /v2.
debugPath (string?) : Path to debug API. Default to /debug.
user (string?) : User for basic authentication.
password (string?) : Password for basic authentication.
protocol (string?) : http or https. Default to http.
rejectUnauthorized (boolean?) : Set to false to allow connection to a node with a self-signed certificate. Default to true.
retry (Object?) : Retry strategy. For the detail of the options see https://github.com/tim-kos/node-retry#retrytimeoutsoptions . Default to {retries: 4, factor: 2, minTimeout: 500, maxTimeout: 2000}
Example
const cli = new FactomdCli({
     host: '52.202.51.228',
     port: 8088,
     path: '/',
     debugPath: '/debug',
     user: 'paul',
     password: 'pwd',
     protocol: 'https',
     rejectUnauthorized: false,
     retry: {
         retries: 4,
         factor: 2,
         minTimeout: 500,
         maxTimeout: 2000
     }
});

DirectoryBlock

Class representing a Directory block.

new DirectoryBlock()
Properties
keyMR (string) : Key Merkel Root.
height (number) : Height.
previousBlockKeyMR (string) : Key Merkel Root of the previous Directory block.
timestamp (number) : UNIX timestamp (seconds).
fullHash (string) : Full hash of the block. Only available when the block is queried by height.
previousFullHash (string) : Full hash of the previous Directory block. Only available when the block is queried by height.
bodyKeyMR (string) : Key Merkle Root of the block body. Only available when the block is queried by height.
adminBlockRef (string) : Reference to the admin block.
entryCreditBlockRef (string) : Reference to the entry credit block.
factoidBlockRef (string) : Reference to the factoid block.
entryBlockRefs (Array<{chainId: string, keyMR: string}>) : References to the entry blocks.

EntryBlock

Class representing an Entry block.

new EntryBlock()
Properties
keyMR (string) : Key Mertle Root.
previousBlockKeyMR (string) : Key Mertle Root of the previous Entry block.
directoryBlockHeight (number) : Directory block height.
timestamp (number) : UNIX timestamp (seconds).
chainId (string) : Chain ID.
sequenceNumber (number) : Sequence number of this block relative to that sub chain.
entryRefs (Array<{entryHash: string, timestamp: number}>) : References to entries with their UNIX timestamps.

EntryBlockContext

Block context of an Entry.

EntryBlockContext

Type: Object

Properties
entryTimestamp (number) : Epoch timestamp (in seconds) of the entry.
directoryBlockHeight (number) : Directory Block height.
entryBlockTimestamp (number) : Epoch timestamp (in seconds) of the Entry Block.
entryBlockSequenceNumber (number) : Entry Block sequence number.
entryBlockKeyMR (string) : Entry Block KeyMR.

EntryCreditBlock

Class representing an Entry Credit block.

new EntryCreditBlock()
Properties
headerHash (string) : Hash of the header.
fullHash (string) : Full hash.
headerExpansionArea (string) : Header expansion area.
bodyHash (string) : Hash of the body.
previousHeaderHash (string) : Hash of the previous Entry Credit block header.
previousFullHash (string) : Full hash of the previous Entry Credit block.
directoryBlockHeight (number) : Directory block height.
bodySize (number) : Size of the body.
objectCount (number) : Object count.
minuteIndexes (Array<number>) : Delimitation of the commits for each minute. Use method getCommitsForMinute rather than using this attribute directly.
commits (Array<{version: number, millis: number, entryHash: string, credits: number, ecPublicKey: string, signature: string}>) : Array of commits.
Instance Members
getCommitsForMinute(minute)

FactoidBlock

Class representing a Factoid block.

new FactoidBlock()
Properties
keyMR (string) : Key Mertle Root.
bodyMR (string) : Merkle Root of the body.
previousBlockKeyMR (string) : Key Merkle Root of the previous Factoid block.
ledgerKeyMR (string) : Ledger Key Merkle Root.
previousLedgerKeyMR (string) : Ledger Key Merkle Root of the previous Factoid block.
entryCreditRate (number) : Entry credit rate.
directoryBlockHeight (number) : Directory block height.
transactions (Array<Transaction>) : Array of Factoid transactions part of this block.
Instance Members
getCoinbaseTransaction()

generateRandomEcAddress

Generate a new random EC address pair (private and public).

generateRandomEcAddress(): {public: string, private: string}
Returns
{public: string, private: string}: Public and private EC addresses.

generateRandomFctAddress

Generate a new random FCT address pair (private and public).

generateRandomFctAddress(): {public: string, private: string}
Returns
{public: string, private: string}: Public and private FCT addresses.

getPublicAddress

Get public address corresponding to an address.

getPublicAddress(address: string): string
Parameters
address (string) Any address.
Returns
string: Public address.

isValidAddress

Validate that an address is valid (well formed).

isValidAddress(address: string): boolean
Parameters
address (string) Address to validate
Returns
boolean: True if the address is valid.

isValidEcAddress

Validate if an address is a valid EC address (public or private).

isValidEcAddress(address: string): boolean
Parameters
address (string) Address to validate.
Returns
boolean: True if the address is a valid EC address.

isValidFctAddress

Validate if an address is a valid FCT address (public or private).

isValidFctAddress(address: string): boolean
Parameters
address (string) Address to validate.
Returns
boolean: True if the address is a valid FCT address.

isValidPrivateAddress

Validate if an address is a valid private EC or FCT address.

isValidPrivateAddress(address: string): boolean
Parameters
address (string) Address to validate.
Returns
boolean: True if the address is a valid private EC or FCT address.

isValidPrivateEcAddress

Validate if an address is a valid private EC address.

isValidPrivateEcAddress(address: string): boolean
Parameters
address (string) Address to validate.
Returns
boolean: True if the address is a valid private EC address.

isValidPrivateFctAddress

Validate if an address is a valid private FCT address.

isValidPrivateFctAddress(address: string): boolean
Parameters
address (string) Address to validate.
Returns
boolean: True if the address is a valid private FCT address.

isValidPublicAddress

Validate if an address is a valid public EC or FCT address.

isValidPublicAddress(address: string): boolean
Parameters
address (string) Address to validate.
Returns
boolean: True if the address is a valid public EC or FCT address.

isValidPublicEcAddress

Validate if an address is a valid public EC address.

isValidPublicEcAddress(address: string): boolean
Parameters
address (string) Address to validate.
Returns
boolean: True if the address is a valid public EC address.

isValidPublicFctAddress

Validate if an address is a valid public FCT address.

isValidPublicFctAddress(address: string): boolean
Parameters
address (string) Address to validate.
Returns
boolean: True if the address is a valid public FCT address.

keyToPublicEcAddress

Build a human readable public EC address from a 32-byte key.

keyToPublicEcAddress(key: (Buffer | string)): string
Parameters
key ((Buffer | string)) 32-byte key.
Returns
string: Public EC address.

keyToPublicFctAddress

Build a human readable public FCT address from a key.

keyToPublicFctAddress(key: (Buffer | string)): string
Parameters
key ((Buffer | string))
Returns
string: Public FCT address.

rcdHashToPublicFctAddress

Build a human readable public FCT address from a RCD hash.

rcdHashToPublicFctAddress(rcdHash: (Buffer | string)): string
Parameters
rcdHash ((Buffer | string))
Returns
string: Public FCT address.

seedToPrivateEcAddress

Build a human readable private EC address from a 32-byte seed.

seedToPrivateEcAddress(seed: (Buffer | string)): string
Parameters
seed ((Buffer | string)) 32-byte seed.
Returns
string: Private EC address.

seedToPrivateFctAddress

Build a human readable private FCT address from a 32-byte seed.

seedToPrivateFctAddress(seed: (Buffer | string)): string
Parameters
seed ((Buffer | string)) 32-byte seed.
Returns
string: Private FCT address.

TransactionAddress

Class to hold address and amount of an input/output of a Transaction.

new TransactionAddress(address: string, amount: number)
Parameters
address (string) Factoid or Entry Credit public address.
amount (number) Amount in factoshis (10^-8 Factoids).

TransactionBlockContext

Block context of a Transaction.

TransactionBlockContext

Type: Object

Properties
factoidBlockKeyMR (string) : Factoid Block KeyMR the transaction is part of.
directoryBlockKeyMR (string) : Directory Block KeyMR the transaction was secured in.
directoryBlockHeight (number) : Directory Block height the transaction was secured in.