Zcash block interface for JavaScript

A collection of JavaScript classes representing the data contained within Zcash blocks along with a decoder for the binary Zcash block representation.

ZcashBlock is the primary export for this package, it can be used to construct an in-memory representation of a Zcash block along with the child classes (below), or use the ZcashBlock.decode() method to decode from block's raw bytes.

Raw block data, hex encoded, can be obtained via an online API (e.g. https://zcashnetwork.info/api/rawblock/00000001b69a0aedf2e35e4fd072f435835ec48d3acd95ec6a0bcc1cfa12135c) or via the CLI (e.g. zcash-cli getblock 00000001b69a0aedf2e35e4fd072f435835ec48d3acd95ec6a0bcc1cfa12135c 0).

Running JSON.stringify() on a decoded ZcashBlock instance should result in the same data provided by the Zcash CLI, (e.g. zcash-cli getblock 00000001b69a0aedf2e35e4fd072f435835ec48d3acd95ec6a0bcc1cfa12135c) minus some additional properties that are only available when the block is attached to the full blockchain (anchor, height, chainwork, confirmations, valuePools, nextblockhash).

API

Contents

• ZcashBlock.decode()
• ZcashBlock.decodeBlockHeaderOnly()
• class ZcashBlock
  • Constructor: ZcashBlock(version, previousblockhash, merkleroot, finalsaplingroot, time, bits, nonce, solution, hash, transactions)
• ZcashBlock#toSerializable()
• class ZcashCompressedG1
  • Constructor: ZcashCompressedG1(yLsb, x)
• class ZcashCompressedG2
  • Constructor: ZcashCompressedG2(yLsb, x)
• class ZcashFq
  • Constructor: ZcashFq(data)
• class ZcashFq2
  • Constructor: ZcashFq2(data)
• class ZcashJoinSplitDescription
  • Constructor: ZcashJoinSplitDescription(vpubOld, vpubNew, anchor, nullifiers, commitments, ephemeralKey, randomSeed, macs, sproutProof, ciphertexts)
• ZcashJoinSplitDescription#toJSON()
• class ZcashOutPoint
  • Constructor: ZcashOutPoint()
• ZcashOutPoint#toJSON()
• class ZcashOutputDescription
  • Constructor: ZcashOutputDescription(cv, cm, ephemeralKey, encCiphertext, outCiphertext, zkproof)
• ZcashOutputDescription#toJSON()
• class ZcashPHGRProof
  • Constructor: ZcashPHGRProof(gA, gAprime, gB, gBprime, gC, gCprime, gK, gH, yLsb)
• class ZcashSpendDescription
  • Constructor: ZcashSpendDescription(cv, anchor, nullifier, rk, zkproof, spendAuthSig)
• ZcashSpendDescription#toJSON()
• class ZcashTransaction
  • Constructor: ZcashTransaction()
• ZcashTransaction#toJSON()
• ZcashTransaction#toSerializable()
• class ZcashTransactionIn
  • Constructor: ZcashTransactionIn(prevout, scriptSig, sequence)
• ZcashTransactionIn#toJSON()
• class ZcashTransactionOut
  • Constructor: ZcashTransactionOut(value, scriptPubKey)
• ZcashTransactionOut#toJSON()

ZcashBlock.decode()

Decode a ZcashBlock from the raw bytes of the block.

Can be used directly as require('zcash-block').decode().

Parameters:

• buffer (Uint8Array|Buffer): the raw bytes of the block to be decoded.

ZcashBlock.decodeBlockHeaderOnly()

Decode only the header section of a ZcashBlock from the raw bytes of the block. This method will exclude the transactions.

Can be used directly as require('zcash-block').decodeBlockHeaderOnly().

Parameters:

• buffer (Uint8Array|Buffer): the raw bytes of the block to be decoded.

class ZcashBlock

A class representation of a Zcash Block, parent for all of the data included in the raw block data in addition to some information that can be calculated based on that data. Properties are intended to match the names that are provided by the Zcash API (hence the casing and some strange names).

Exported as the main object, available as require('zcash-block').

Properties:

• version (number): positive integer
• previousblockhash (Uint8Array|Buffer): 256-bit hash
• merkleroot (Uint8Array|Buffer): 256-bit hash
• finalsaplingroot (Uint8Array|Buffer): 256-bit hash
• time (number): seconds since epoch
• bits (number)
• nonce (Uint8Array|Buffer): 256-bit hash
• solution (Uint8Array|Buffer)
• hash (Uint8Array|Buffer): 256-bit hash, a double SHA2-256 hash of all bytes making up this block (calculated)
• transactions (Array.<ZcashTransaction>)
• difficulty (number): the difficulty for this block (calculated)

Constructor: ZcashBlock(version, previousblockhash, merkleroot, finalsaplingroot, time, bits, nonce, solution, hash, transactions)

Instantiate a new ZcashBlock.

See the class properties for expanded information on these parameters.

ZcashBlock#toSerializable()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

class ZcashCompressedG1

A class representation of a property of a Zcash transaction joinsplit proof.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/CompressedG1').

Properties:

• yLsb (boolean)
• x (Fq)

Constructor: ZcashCompressedG1(yLsb, x)

Instantiate a new ZcashCompressedG1.

See the class properties for expanded information on these parameters.

class ZcashCompressedG2

A class representation of a property of a Zcash transaction joinsplit proof.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/CompressedG2').

Properties:

• yLsb (boolean)
• x (Fq2)

Constructor: ZcashCompressedG2(yLsb, x)

Instantiate a new ZcashCompressedG2.

See the class properties for expanded information on these parameters.

class ZcashFq

A class representation of a property of a Zcash transaction joinsplit proof. Used by ZcashCompressedG1.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/Fq').

Properties:

• data (Uint8Array|Buffer): a 256-bit block of data

Constructor: ZcashFq(data)

Instantiate a new ZcashFq.

See the class properties for expanded information on these parameters.

class ZcashFq2

A class representation of a property of a Zcash transaction joinsplit proof. Used by ZcashCompressedG2.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/Fq2').

Properties:

• data (Uint8Array|Buffer): a 512-bit block of data

Constructor: ZcashFq2(data)

Instantiate a new ZcashFq2.

See the class properties for expanded information on these parameters.

class ZcashJoinSplitDescription

A class representation of a Zcash Transaction's joinsplit, which may or may not be present for a given transaction.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/JoinSplitDescription').

Properties:

• vpubOld (BigInt): a representation of an amount / value
• vpubNew (BigInt): a representation of an amount / value
• anchor (Uint8Array|Buffer): a 256-bit hash anchoring the joinsplit's position in the commitment tree
• nullifiers (Array.<Uint8Array>|Array.<Buffer>): two 256-bit blocks derived from secrets in the note
• commitments (Array.<Uint8Array>|Array.<Buffer>): two 256-bit blocks representing the spend commitments
• ephemeralKey (Uint8Array|Buffer): a 256-bit hash
• randomSeed (Uint8Array|Buffer): - a 256-bit block
• macs (Array.<Uint8Array>|Array.<Buffer>): two 256-bit hashes required to verify this joinsplit
• sproutProof (Uint8Array|Buffer|PHGRProof): either a GrothProof encoded directly as 192 bytes of binary data or a decoded PHGRProof, depending on the block version.
• ciphertexts (Uint8Array|Buffer): two ciphertexts of 601 bytes each which encode trapdoors, values and other information that the recipient needs, including a memo field.

Constructor: ZcashJoinSplitDescription(vpubOld, vpubNew, anchor, nullifiers, commitments, ephemeralKey, randomSeed, macs, sproutProof, ciphertexts)

Instantiate a new ZcashJoinSplitDescription.

See the class properties for expanded information on these parameters.

ZcashJoinSplitDescription#toJSON()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

class ZcashOutPoint

A class representation of a Zcash OutPoint for a ZcashTransactionIn.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/OutPoint').

Properties:

• hash (Uint8Array|Buffer)
• n (number)

Constructor: ZcashOutPoint()

Instantiate a new ZcashOutPoint.

See the class properties for expanded information on these parameters.

ZcashOutPoint#toJSON()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

class ZcashOutputDescription

A class representation of a Zcash output description.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/OutputDescription').

Properties:

• cv (Uint8Array|Buffer): a 256-bit block representing the value commitment
• cm (Uint8Array|Buffer): a 256-bit block representing the note commitment for the output note
• ephemeralKey (Uint8Array|Buffer): a 256-bit Jubjub public key
• encCiphertext (Uint8Array|Buffer): a 580 byte ciphertext component for the encrypted output note
• outCiphertext (Uint8Array|Buffer): a 80 byte ciphertext component for the encrypted output note
• zkproof (Uint8Array|Buffer): a GrothProof encoded directly as 192 bytes of binary data

Constructor: ZcashOutputDescription(cv, cm, ephemeralKey, encCiphertext, outCiphertext, zkproof)

Instantiate a new ZcashOutputDescription.

See the class properties for expanded information on these parameters.

ZcashOutputDescription#toJSON()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

class ZcashPHGRProof

A class representation of a Zcash transaction joinsplit proof.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/PHGRProof').

Properties:

• gA (CompressedG1)
• gAprime (CompressedG1)
• gB (CompressedG2)
• gBprime (CompressedG1)
• gC (CompressedG1)
• gCprime (CompressedG1)
• gK (CompressedG1)
• gH (CompressedG1)
• yLsb (boolean)

Constructor: ZcashPHGRProof(gA, gAprime, gB, gBprime, gC, gCprime, gK, gH, yLsb)

Instantiate a new ZcashPHGRProof.

class ZcashSpendDescription

A class representation of a Zcash spend description.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/SpendDescription').

Properties:

• cv (Uint8Array|Buffer): a 256-bit value commitment to the value of the input note
• anchor (Uint8Array|Buffer): a 256-bit Merkle root of the Sapling note commitment tree at some block height in the past
• nullifier (Uint8Array|Buffer): a 256-bit nullifier of the input note
• rk (Uint8Array|Buffer): a 256-bit randomized public key for spendAuthSig
• zkproof (Uint8Array|Buffer): a GrothProof encoded directly as 192 bytes of binary data
• spendAuthSig (Uint8Array|Buffer): a 512-bit signature authorizing this spend

Constructor: ZcashSpendDescription(cv, anchor, nullifier, rk, zkproof, spendAuthSig)

Instantiate a new ZcashSpendDescription.

See the class properties for expanded information on these parameters.

ZcashSpendDescription#toJSON()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

class ZcashTransaction

A class representation of a Zcash Transaction, multiple of which are contained within each ZcashBlock.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/Transaction').

Properties:

• overwintered (boolean)
• version (number)
• versionGroupId (number)
• vin (Array.<ZcashTransactionIn>)
• vout (Array.<ZcashTransactionIn>)
• lockTime (number)
• expiryHeight (number|null)
• valueBalance (BigInt|null)
• shieldedSpend (Array.<ZcashSpendDescription>|null)
• shieldedOutput (Array.<ZcashOutputDescription>|null)
• joinSplitPubKey (Uint8Array|Buffer|null)
• joinSplits (Array.<ZcashJoinSplitDescription>|null)
• joinSplitSig (Uint8Array|Buffer|null)
• bindingSig (Uint8Array|Buffer|null)
• hash (Uint8Array|Buffer)

Constructor: ZcashTransaction()

Instantiate a new ZcashTransaction.

See the class properties for expanded information on these parameters.

ZcashTransaction#toJSON()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

ZcashTransaction#toSerializable()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

class ZcashTransactionIn

A class representation of a Zcash TransactionIn, multiple of which are contained within each ZcashTransaction.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/TransactionIn').

Properties:

• prevout (ZcashOutPoint)
• scriptSig (Uint8Array|Buffer): an arbitrary length byte array
• sequence (number)

Constructor: ZcashTransactionIn(prevout, scriptSig, sequence)

Instantiate a new ZcashTransactionIn.

See the class properties for expanded information on these parameters.

ZcashTransactionIn#toJSON()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

The serailizable form converts this object to { coinbase: scriptSig, sequence: sequence } to match the Zcash API output.

class ZcashTransactionOut

A class representation of a Zcash TransactionOut, multiple of which are contained within each ZcashTransaction.

This class isn't explicitly exported, access it for direct use with require('zcash-block/classes/TransactionOut').

Properties:

• value (BigInt): an amount / value for this TransactionOut
• scriptPubKey (Uint8Array|Buffer): an arbitrary length byte array

Constructor: ZcashTransactionOut(value, scriptPubKey)

Instantiate a new ZcashTransactionOut.

See the class properties for expanded information on these parameters.

ZcashTransactionOut#toJSON()

Convert to a serializable form that has nice stringified hashes and other simplified forms. May be useful for simplified inspection.

The serialized version includes the raw value as valueZat while value is a proper Zcash coin value.

License and Copyright

Copyright 2019 Rod Vagg

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.