Obsolete Altchain Integration Service API

See: VAIF

Note: Inputs and outputs are shown as JSON structures but they should be built as Protobuf structures using the integration.proto that contains the communication scheme (See: https://github.com/VeriBlock/alt-integration-proto/blob/master/proto/integration.proto)

Note: veriblockPublication and altPublication structures are omitted for readability

Security API

ResetSecurity

Description

Erase the database storage for VeriBlock and Bitcoin SPV view.

Expected call frequency

Once, when doing an Altchain daemon initial setup

Called by

Called during the daemon startup sequence

Example

//Input:
{ }

//Output:
{ "result": true }

AddGenesisVeriBlock

Description

Add initial VeriBlock block. VeriBlock storage should be empty before adding Genesis block.

Expected call frequency

Once, when doing an Altchain daemon initial setup

Called by

Called during the daemon startup sequence

Example

//Input:
{ "height": 1, "version": 1, "previousBlock": "010203040506", "previousKeystone": "0708090A0B0C", "secondPreviousKeystone": "0D0E0F101112", "merkleRoot": "131415161718", "timestamp": 1, "difficulty" : 1, "nonce" : 1 }

//Output:
{ "result": true }

AddGenesisBitcoin

Description

Add initial Bitcoin block. Bitcoin storage should be empty before adding Genesis block.

Expected call frequency

Once, when doing an Altchain daemon initial setup

Called by

Called during the daemon startup sequence

Example

//Input:
{ "version": 1, "previousBlock": "010203040506", "merkleRoot": "131415161718", "timestamp": 1, "bits" : 1, "nonce" : 1 }

//Output:
{ "result": true }

AddPayloads

Description

Adds one or more VTBs and/or ATVs to the integration point’s SPV-level view of the VeriBlock (and by extension, Bitcoin) blockchain.

Expected call frequency

On every altchain block

Called by

Called during block validation

Example

//Input:
{ "blockIndex": { "height": 1, "hash": "010203040506" }, "veriblockPublications": [<veriblockPublication>], "altPublications": [<altPublication>] }

//Output:
{ "result": true }

RemovePayloads

Description

Removes VTBs and ATVs (if applicable) which were associated with a particular altchain height.

Expected call frequency

Rarely

Called by

Called during fork resolution and blockchain rollbacks

Example

//Input:
{ "blockIndex": { "height": 1, "hash": "010203040506" } }

//Output:
{ "result": true }

AddTemporaryPayloads

Description

Temporarily adds one or more VTBs and/or the VBK header knowledge from one or more ATVs to the integration point’s SPV-level view of the VeriBlock (and by extension, Bitcoin) blockchain.

Expected call frequency

Rarely

Called by

Called during fork resolution

Example

//Input:
{ "veriblockPublications": [<veriblockPublication>], "altPublications": [<altPublication>] }

//Output:
{ "result": true }

ClearTemporaryPayloads

Description

Clears the effects of all VTB and/or ATV payloads which were added using AddTemporaryPayloads. This returns the SPV views of VeriBlock and Bitcoin back to the deterministic view based only on VTB (and ATV, when relevant) payloads in the current main altchain fork.

Expected call frequency

Rarely

Called by

Called during fork resolution

Example

//Input:
{ }

//Output:
{ "result": true }

SimplifyVTBs

Description

Given a list of VTBs, returns a reduced list of VTBs which communicate the “same” information regarding the state of the SPV-level view of VeriBlock and Bitcoin that the integration point provides. This allows altchains to de-duplicate VTBs which provide redundant information, keeping only the ones which provide the best VeriBlock-to-Bitcoin publication for each keystone period covered by the list of VTBs provided.

Expected call frequency

When block is mined by the PoP miner

Called by

Called by the NodeCore on request by the PoP miner

Example

//Input:
{ "veriblockPublications": [<veriblockPublication>] }

//Output:
{ "result": { "result": true }, "veriblockPublications": [<veriblockPublication>] }

CheckATVAgainstView

Description

Checks that an ATV connects to the known VeriBlock view.

Expected call frequency

On every new PoP transaction

Called by

Called during PoP transaction validation

Example

//Input:
{ "altPublication": <altPublication> }

//Output:
{ "result": true }

CheckVTBInternally

Description

Runs internal validity checks on a VeriBlock-to-Bitcoin publication.

Expected call frequency

On every new PoP transaction

Called by

Called during PoP transaction validation

Example

//Input:
{ "veriblockPublication": <veriblockPublication> }

//Output:
{ "result": true }

CheckATVInternally

Description

Runs internal validity checks an altchain-to-VeriBlock publication.

Expected call frequency

On every new PoP transaction

Called by

Called during PoP transaction validation

Example

//Input:
{ "altPublication": <altPublication> }

//Output:
{ "result": true }

GetMainVBKHeightOfATV

Description

Returns the height of the VeriBlock block containing the provided ATV.

Expected call frequency

When block is mined by the PoP miner

Called by

Called by the NodeCore on request by the PoP miner

Example

//Input:
{ "altPublication": <altPublication> }

//Output:
{ "result": { "result": true }, "height": 1 }

Rewards API

Note: calculatorConfig structure is omitted for readability

ResetRewards

Description

Prepares the Rewards Calculation engine: resets inner state, resets the calculator config to the default state.

Expected call frequency

Once, when doing an Altchain daemon initial setup

Called by

Called during the daemon startup sequence

Example

//Input:
{ }

//Output:
{ "result": true }

GetCalculator

Description

Returns calculator config.

Expected call frequency

Once, when doing an Altchain daemon initial setup

Called by

Called during the daemon startup sequence

Example

//Input:
{ }

//Output:
{ "result": { "result": true }, "calculator": <calculatorConfig> }

SetCalculator

Description

Sets new calculator config.

Expected call frequency

Once, when doing an Altchain daemon initial setup

Called by

Called during the daemon startup sequence

Example

//Input:
{ "calculator": <calculatorConfig> }

//Output:
{ "result": true }

RewardsCalculateScore

Description

Calculate PoP score for the given altchain block. All existing endorsements should be provided for the scored block.

Expected call frequency

On every mined block

Called by

Called during adding of the block to the blockchain

Example

//Input:
{ "endorsementsForBlock": [ { "blockVbkHeight": 1, "endorsementsInBlock": [ "address": "0102030405", "txid": "060708090A" ] } ] }

//Output:
{ "result": { "result": true }, "score": "100" }

RewardsCalculateOutputs

Description

Calculate the PoP reward for the given block. All existing endorsements should be provided for the scored block. Rewards are returned as a set of outputs. Each outputs contains the reward recipient address and reward amount.

Expected call frequency

On every mined block

Called by

Called during adding of the block to the blockchain

Example

//Input:
{ "blockAltHeight": 1,  "endorsementsForBlock": [ { "blockVbkHeight": 1, "endorsementsInBlock": [ "address": "0102030405", "txid": "060708090A" ] } ], "difficulty": "100" }

//Output:
{ "result": { "result": true }, "totalReward": "100", "blockReward": "100", "outputs": [ "address": "0102030405", "reward": "100" ] }

Deserialize API

Note: publicationData, bitcoinTransaction, veriBlockBlock, veriBlockTransaction, veriBlockPoPTransaction, output, address, bitcoinBlock, veriBlockMerklePath, merklePath structures are omitted for readability

Note: 'data' is serialized by the Serialize API of the Service

ParseAltPublication

Description

Parses serialized AltPublication (ATV) structure from VeriBlock binary format.

Expected call frequency

On every PoP transaction

Called by

Called when new PoP transaction arrives and we want to validate or store it in the database

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "altPublication": <altPublication> }

ParsePublicationData

Description

Parses serialized PublicationData structure from VeriBlock binary format.

Expected call frequency

On every PoP transaction

Called by

Called when new PoP transaction arrives and we want to validate or store it in the database

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "publicationData": <publicationData> }

ParseBitcoinTransaction

Description

Parses serialized Bitcoin transaction from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "bitcoinTransaction": <bitcoinTransaction> }

ParseVeriBlockBlock

Description

Parses serialized VeriBlock block from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "veriBlockBlock": <veriBlockBlock> }

ParseVeriBlockTransaction

Description

Parses serialized VeriBlock transaction from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "veriBlockTransaction": <veriBlockTransaction> }

ParseVeriBlockPublication

Description

Parses serialized VeriBlock publication (VTB) structure from VeriBlock binary format.

Expected call frequency

On every PoP transaction

Called by

Called when new PoP transaction arrives and we want to validate or store it in the database

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "veriBlockPublication": <veriBlockPublication> }

ParseVeriBlockPopTx

Description

Parses serialized VeriBlock PoP transaction from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "veriBlockPoPTransaction": <veriBlockPoPTransaction> }

ParseOutput

Description

Parses serialized VeriBlock Output structure from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "output": <output> }

ParseAddress

Description

Parses serialized VeriBlock Address structure from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "address": <address> }

ParseBitcoinBlock

Description

Parses serialized Bitcoin block from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "bitcoinBlock": <bitcoinBlock> }

ParseVeriBlockMerklePath

Description

Parses serialized VeriBlock Merkle Path structure from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes> }

//Output:
{ "result": { "result": true }, "veriBlockMerklePath": <veriBlockMerklePath> }

ParseMerklePath

Description

Parses serialized Merkle Path structure from VeriBlock binary format.

Expected call frequency

Never

Called by

Called in tests only

Example

//Input:
{ "data": <bytes>, "subject": <bytes> }

//Output:
{ "result": { "result": true }, "merklePath": <merklePath> }

Serialize API

Note: publicationData, bitcoinTransaction, veriBlockBlock, veriBlockTransaction, veriBlockPoPTransaction, output, address, bitcoinBlock, veriBlockMerklePath, merklePath structures are omitted for readability

SerializeAltPublication

Description

Serializes AltPublication (ATV) structure to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "altPublication": <altPublication> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializePublicationData

Description

Serializes PublicationData structure to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "publicationData": <publicationData> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeBitcoinTransaction

Description

Serializes Bitcoin transaction to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "bitcoinTransaction": <bitcoinTransaction> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeVeriBlockBlock

Description

Serializes VeriBlock block to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "veriBlockBlock": <veriBlockBlock> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeVeriBlockTransaction

Description

Serializes VeriBlock transaction to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "veriBlockTransaction": <veriBlockTransaction> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeVeriBlockPublication

Description

Serializes VeriBlock publication (VTB) structure to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "veriBlockPublication": <veriBlockPublication> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeVeriBlockPopTx

Description

Serializes VeriBlock PoP transaction to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "veriBlockPoPTransaction": <veriBlockPoPTransaction> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeOutput

Description

Serializes VeriBlock Output structure to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "output": <output> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeAddress

Description

Serializes VeriBlock Address structure to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "address": <address> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeBitcoinBlock

Description

Serializes Bitcoin block to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "bitcoinBlock": <bitcoinBlock> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeVeriBlockMerklePath

Description

Serializes VeriBlock Merkle Path structure to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "veriBlockMerklePath": <veriBlockMerklePath> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

SerializeMerklePath

Description

Serializes Merkle Path structure to VeriBlock binary format.

Expected call frequency

When PoP miner builds a transaction

Called by

Called when PoP miner prepares data for the NodeCore

Example

//Input:
{ "merklePath": <merklePath> }

//Output:
{ "result": { "result": true }, "data": <bytes> }

Validation API

Note: publicationData, bitcoinTransaction, veriBlockBlock, veriBlockTransaction, veriBlockPoPTransaction, output, address, bitcoinBlock, veriBlockMerklePath, merklePath structures are omitted for readability

VerifyVeriBlockPoPTx

Description

Performs validation of the VeriBlock PoP transaction. Transaction is validated for:

• Valid signature
• Valid Bitcoin transaction
• Valid Bitcoin Merkle Path
• Valid Bitcoin blocks (passed as transaction context)

Expected call frequency

On every new PoP transaction

Called by

Called when daemon validates PoP transaction

Example

//Input:
{ "veriBlockPoPTransaction": <veriBlockPoPTransaction> }

//Output:
{ "result": true }

CheckSignatureVeriBlockPoPTx

Description

Performs validation of the VeriBlock PoP transaction signature.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "veriBlockPoPTransaction": <veriBlockPoPTransaction> }

//Output:
{ "result": true }

CheckBitcoinTransactionForPoPData

Description

Performs validation of the Bitcoin transaction contained in the VeriBlock PoP transaction.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "veriBlockPoPTransaction": <veriBlockPoPTransaction> }

//Output:
{ "result": true }

CheckBitcoinMerklePathVeriBlockPoPTx

Description

Performs validation of the Bitcoin Merkle Path contained in the VeriBlock PoP transaction.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "veriBlockPoPTransaction": <veriBlockPoPTransaction> }

//Output:
{ "result": true }

CheckBitcoinBlocksVeriBlockPoPTx

Description

Performs validation of the Bitcoin blocks contained in the VeriBlock PoP transaction.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "veriBlockPoPTransaction": <veriBlockPoPTransaction> }

//Output:
{ "result": true }

VerifyVeriBlockPublication

Description

Performs validation of the VeriBlock Publication (VTB). Publication is validated for:

• Valid VeriBlock transaction
• Valid VeriBlock Merkle Path
• Valid Bitcoin blocks (passed as publication context)

Expected call frequency

On every new PoP transaction

Called by

Called when daemon validates PoP transaction

Example

Input:
{ "veriBlockPublication": <veriBlockPublication> }

//Output:
{ "result": true }

CheckBlocksVeriBlockPublication

Description

Performs validation of the Bitcoin blocks contained in the VeriBlock Publication.

Expected call frequency

Never

Called by

Called only in tests

Example

Input:
{ "veriBlockPublication": <veriBlockPublication> }

//Output:
{ "result": true }

CheckMerklePathVeriBlockPublication

Description

Performs validation of the VeriBlock Merkle Path contained in the VeriBlock Publication.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "veriBlockPublication": <veriBlockPublication> }

//Output:
{ "result": true }

VerifyVeriBlockTransaction

Description

Performs validation of the VeriBlock Transaction. Transaction is validated for:

• Valid signature

Expected call frequency

On every new PoP transaction

Called by

Called when daemon validates PoP transaction

Example

//Input:
{ "veriBlockTransaction": <veriBlockTransaction> }

//Output:
{ "result": true }

CheckSignatureVeriBlockTransaction

Description

Performs validation of the VeriBlock Transaction signature.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "veriBlockTransaction": <veriBlockTransaction> }

//Output:
{ "result": true }

VerifyVeriBlockBlock

Description

Performs validation of the VeriBlock Block. Block is validated for:

• Valid Proof of Work
• Valid time of the block

Expected call frequency

On every new PoP transaction

Called by

Called when daemon validates PoP transaction

Example

//Input:
{ "veriBlockBlock": <veriBlockBlock> }

//Output:
{ "result": true }

CheckProofOfWorkVeriBlockBlock

Description

Performs validation of the VeriBlock Block Proof of Work (block difficulty).

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "veriBlockBlock": <veriBlockBlock> }

//Output:
{ "result": true }

CheckMaximumDriftVeriBlockBlock

Description

Performs validation of the VeriBlock Block timestamp.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "veriBlockBlock": <veriBlockBlock> }

//Output:
{ "result": true }

VerifyBitcoinBlock

Description

Performs validation of the Bitcoin Block. Block is validated for:

• Valid Proof of Work
• Valid time of the block

Expected call frequency

On every new PoP transaction

Called by

Called when daemon validates PoP transaction

Example

//Input:
{ "bitcoinBlock": <bitcoinBlock> }

//Output:
{ "result": true }

CheckProofOfWorkBitcoinBlock

Description

Performs validation of the Bitcoin Block Proof of Work (block difficulty).

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "bitcoinBlock": <bitcoinBlock> }

//Output:
{ "result": true }

CheckMaximumDriftBitcoinBlock

Description

Performs validation of the Bitcoin Block timestamp.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "bitcoinBlock": <bitcoinBlock> }

//Output:
{ "result": true }

VerifyAltPublication

Description

Performs validation of the Altchain Publication (ATV). Publication is validated for:

• Valid VeriBlock PoP transaction
• Valid VeriBlock Merkle Path
• Valid Bitcoin blocks (passed as publication context)

Expected call frequency

On every new PoP transaction

Called by

Called when daemon validates PoP transaction

Example

//Input:
{ "altPublication": <altPublication> }

//Output:
{ "result": true }

CheckMerklePathAltPublication

Description

Performs validation of the VeriBlock Merkle Path contained in the Altchain Publication.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "altPublication": <altPublication> }

//Output:
{ "result": true }

CheckBlocksAltPublication

Description

Performs validation of the Bitcoin blocks contained in the Altchain Publication.

Expected call frequency

Never

Called by

Called only in tests

Example

//Input:
{ "altPublication": <altPublication> }

//Output:
{ "result": true }