Obsolete Altchain Integration Service API
This page refers to an earlier external service. It Became obsolete with the embedded C++ Library.
See: VAIF, Altchain_Integration_Service
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
Contents
- 1 Security API
- 2 Rewards API
- 3 Deserialize API
- 4 Serialize API
- 4.1 SerializeAltPublication
- 4.2 SerializePublicationData
- 4.3 SerializeBitcoinTransaction
- 4.4 SerializeVeriBlockBlock
- 4.5 SerializeVeriBlockTransaction
- 4.6 SerializeVeriBlockPublication
- 4.7 SerializeVeriBlockPopTx
- 4.8 SerializeOutput
- 4.9 SerializeAddress
- 4.10 SerializeBitcoinBlock
- 4.11 SerializeVeriBlockMerklePath
- 4.12 SerializeMerklePath
- 5 Validation API
- 5.1 VerifyVeriBlockPoPTx
- 5.2 CheckSignatureVeriBlockPoPTx
- 5.3 CheckBitcoinTransactionForPoPData
- 5.4 CheckBitcoinMerklePathVeriBlockPoPTx
- 5.5 CheckBitcoinBlocksVeriBlockPoPTx
- 5.6 VerifyVeriBlockPublication
- 5.7 CheckBlocksVeriBlockPublication
- 5.8 CheckMerklePathVeriBlockPublication
- 5.9 VerifyVeriBlockTransaction
- 5.10 CheckSignatureVeriBlockTransaction
- 5.11 VerifyVeriBlockBlock
- 5.12 CheckProofOfWorkVeriBlockBlock
- 5.13 CheckMaximumDriftVeriBlockBlock
- 5.14 VerifyBitcoinBlock
- 5.15 CheckProofOfWorkBitcoinBlock
- 5.16 CheckMaximumDriftBitcoinBlock
- 5.17 VerifyAltPublication
- 5.18 CheckMerklePathAltPublication
- 5.19 CheckBlocksAltPublication
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 }
