The following public functions are exported from this client. Where possible, functions in the client library are written using Promises in the async/await style. The output of each function can be used as the input to the next function with no need to manipulate the data.
Use this function to submit an Array of hashes, and receive back the information needed to later retrieve a proof for each of those hashes using the getProofs() function.
The hashes argument expects an Array of hashes, where each hash is a Hexadecimal String [a-fA-F0-9] between 160 bits (20 Bytes, 40 Hex characters) and 512 bits (64 Bytes, 128 Hex characters) in length. The Hex string must be an even length.
We recommend using the SHA-256 hash function for all hashes submitted.
The optional uris argument accepts an Array of Gateway URIs. Each element of the returned Array is a full URI with scheme://hostname[:port] (e.g. http://127.0.0.1 or http://127.0.0.1:80).
The return value from this function is an Array of Objects, one for each hash submitted. Each result Object has the information needed to retrieve a proof for a submitted hash. There will be one Object for every Gateway a hash was submitted to.
The Array of Objects, referred to as proofHandles can also be submitted directly as the argument to the getProofs() function. It typically takes about 10 seconds for initial Calendar proofs to become available.
The Object will contain:
uri : The URI of the Gateway(s) the hash was submitted to. This is the only Gateway that can retrieve this particular proof.
hash : A copy of the hash that was originally submitted that will be embedded in a future proof. This allows for easier correlation between hashes submitted and the Hash ID handle needed to retrieve a proof.
proofId : The Version 1 UUID that can be used to retrieve the proof for a submitted hash from the /proofs/:id endpoint of the Gateway it was submitted to.
groupId : A Version 1 UUID which is used to group Proof Handles that have the same corresponding hash. The groupId can later be used to optimize the proof retrieval process.
Example Return Value
;[
{
uri: 'http://0.0.0.0',
hash: '1d2a9e92b561440e8d27a21eed114f7018105db00262af7d7087f7dea9986b0a',
proofId: 'df500460-d7d1-11e8-992b-0178d9540713',
groupId: 'dfa4b410-d7d1-11e8-a6e3-c763418c848e'
},
{
uri: 'http://0.0.0.0',
hash: '2d2a9e92b561440e8d27a21eed114f7018105db00262af7d7087f7dea9986b0a',
proofId: 'df502b70-d7d1-11e8-992b-0187b4b6e491',
groupId: 'dfa4b411-d7d1-11e8-a6e3-c763418c848e'
}
]Use this function to submit hashes calculated from an Array of file paths, and receive back the information needed to later retrieve a proof for each of those hashes using the getProofs() function.
By default hashes are submitted to three Gateways to help ensure a proof will become available at the appropriate time. Only one such proof need be permanently stored, the others provide redundancy.
The paths argument expects an Array of valid file paths.
The SHA-256 cryptographic one-way hash function will be used on all files in the paths submitted.
The optional uris argument accepts an Array of Gateways URIs. Each element of the returned Array is a full URI with scheme://hostname[:port] (e.g. http://127.0.0.1 or http://127.0.0.1:80).
The return value from this function is an Array of Objects, one for each hash submitted. Each result Object has the information needed to retrieve a proof for a submitted hash. There will be one Object for every Gateway a hash was submitted to.
The Array of Objects, referred to as proofHandles can also be submitted directly as the argument to the getProofs() function. It typically takes about 10 seconds for initial Calendar proofs to become available.
The Object will contain:
uri : The URI of the Gateway(s) the hash was submitted to. This is the only Gateway that can retrieve this particular proof.
hash : A copy of the hash that was originally submitted that will be embedded in a future proof. This allows for easier correlation between hashes submitted and the Hash ID handle needed to retrieve a proof.
proofId : The Version 1 UUID that can be used to retrieve the proof for a submitted hash from the /proofs/:id endpoint of the Gateway it was submitted to.
path : The path of the file represented by this object.
groupId : A Version 1 UUID which is used to group Proof Handles that have the same corresponding hash. The groupId can later be used to optimize the proof retrieval process.
Example Return Value
;[
{
uri: 'http://0.0.0.0',
hash: '9d2a9e92b561440e8d27a21eed114f7018105db00262af7d7087f7dea9986b0a',
proofId: 'a512e430-d3cb-11e7-aeb7-01eecbb37e34',
path: './datafile.json',
groupId: 'dc1c8cd0-d7d3-11e8-8a5c-7fe62f82e5c3'
},
{
uri: 'http://0.0.0.0',
hash: '9d2a9e92b561440e8d27a21eed114f7018105db00262af7d7087f7dea9986b0a',
proofId: 'a4b6e180-d3cb-11e7-90bc-014342a27e15',
path: './folder/otherfile.csv',
groupId: 'dc1c8cd1-d7d3-11e8-8a5c-7fe62f82e5c3'
}
]This function is used to retrieve Chainpoint proofs from the Gateways that are responsible for creating each proof.
The proofHandles argument accepts an Array of Objects. Each object must have the uri and proofId properties. The argument is of the same form as the output from the submitHashes() function.
The uri property should be the base URI (e.g. http://0.0.0.0) of an online Gateway that is responsible for generating a particular proof.
The proofId property is a valid Version 1 UUID as provided by the return of the submitHashes() function.
This function will return an Array of Objects, each composed of the following properties:
{
proofId: "",
proof: "",
anchorsComplete: []
}proofId : The Version 1 UUID used to retrieve the proof.
proof : The Base64 encoded binary form of the proof. See https://github.com/chainpoint/chainpoint-binary for more information about proof formats. That library can also be used to convert from one form to another. If the proof is not yet available, or cannot be retrieved, this will be set to null.
anchorsComplete : An Array of Strings that indicates which blockchains the proof is anchored to at the time of retrieval. One or more of cal (Calendar), btc (Bitcoin), or eth (Ethereum) (you may also see tcal or tbtc for
testnet calendar anchors and testnet bitcoin anchors respectively). If the proof is not yet available, or cannot be retrieved, this will be set to [] (An empty Array).
Example Return Value
;[
{
proofId: 'e47f00b0-d3fb-11e7-9dd9-015eb614885c',
proof:
'eJylVc1qZFUQ9jlcu+10VZ3/rAKCT+DKTahzqk7SENKhux3HZRRcO/oEo5EZB1wIrn2PgA/jdzMZBye9EDzQNPfce+vUV9/P/e712dheH/z54c/Lw+Fmf7pefxU2drLdXazHpW6ub7ab68P6Wbw7fH3jbz79Z+vuUveX92cTS4qITA85G/Xaau0lsIzcNZN7FIlcrUnPMmz0wtOlNXYvofHrm912O883dv9JcoohGK1iNl0xu660NF8Rl8ktJkmFf1tOPd/58M0ztz+EhFYkKwqfSzhlOpX6xeu+0+tx6fsX3/5ypd2v3ujFxc4v9LDd/by92X//5IHfh16dL1vb3fnbe8tzP96+vLr/4XqzPzyTU06VSuFIdGpJtcxpappm7m3kEgOuJabBJl2GBoCvjv+USubKo1aZpQwfpkEDRauucTYlaaEGppa4FhRLSh2VuVtp1oKpdDWLyW1Gwu3c2G5/2t682l/qSlK+ffW2bUB54OfuACi/PkLBTM8Kpza9JurZrCeeM5GNaDF2Vg0ZPFVPohbbFJ6Wa+dhNErRqTna3Ze7zf7FfV+0AWmEEw7pJMUTkbTGUX5tulv/30PWpgd9z8o3j6z0w3jKyl8ffXz7cgfdxSJubc5AENdE6WYFs7c6eY7SKI3Yi1DsOgTjJHTHKUBxrZah+V9TBNFnXQuVnspsrgapFsy/hcjFZuvoP1QAaD59cPIIdgc0nafW0lWotA8LHojp7WLOTCkPOCR0cJgwnjFnjR6oJ2MgIYtauIh2ibk76gaTisLSa31XB2s+Lsj+gyWS0cYyms+oOmwHwO/Oz/hFFfU0CP2Tt9BhNEmN2oxQbKylhJKxM8a7txY8bx7xrJ7Lw4wwuJGB2VKdnSquLJeStSpVgmAJ7A7vLoaThMOoLTt24JQ+Q9ZjNQOZxuGhSx6Jos/u8FVHY1181NnIK4dGwTKlJTtyVsCNM4DrPtuTmhCHyezchKMs7eYM1OitthkCmAsJUikt8yzRfUQei1o7DN47tIJkOlYzBsScLuFGGMCkwX2Bamla8bYYthVkHQQBpAHe56acyEchDNjisZo12GgKqI20gg1UcYytN4+Ihe5hlh7YJViKozLrAPTpS9dtQp7HaqJLR5MTIcTQCQIpDlbOyF1TpUixjp6RWAvkjkypHGud8C7AxTSP1SzuME9VnGo+Ug8jtw6CK/YlB1F2CIgKNyR1aosXuaWpHmJJedajHFGKnA0yQu5Dsci90BGqYXmTvWFkzXoVyLiARSmlGK4sFITlSPlYTWU4N9tMMLgoOKKJbgesBA/2aAKbxTLr4Iqp41ihNnpY1Kw08/iw5pN0RSS9T9dXnHOssf6njMTnDiKLCHumPvISB8IemuJjWQgx06pDB6CENKFj6DZQJoP78WXo5SEj/wbUW3Ki',
anchorsComplete: ['tcal', 'tbtc']
}
]This function is used to verify proofs by comparing the values arrived at by parsing and performing the operations in a proof against the Chainpoint calendar or public blockchains.
The proofs argument accepts an Array of Strings or Objects.
If a String, it is expected to be a Chainpoint 4.0 proof in either Base64 encoded binary, or JSON-LD form.
If an Object it can be a Chainpoint 4.0 proof as an Object, or have a proof property containing a String proof as described above as is created by the output of getProofs().
Proof types can be mixed freely in the proofs arg Array.
The uri property should be the base URI (e.g. http://0.0.0.0) of an online Gateway that will be responsible for providing a hash value from the Calendar block specified in the proof. The hash value provided will then be compared to the result of calculating all of the operations in the proof locally. If the locally calculated values matches the server provided value it verifies that the proof is valid.
At no time is the proof sent over the Internet during this process (although it is safe to do so).
This function will return an Array of Objects. Each object represents an Anchor in a proof along with all of the relevant data.
For example, a single proof that is anchored to both the Chainpoint Calendar, and to the Bitcoin blockchain, will return two objects. One for each of those anchors.
Example Return Value
;[
{
hash: 'daeaedcd320c0fb2adefaab15ec03a424bb7a89aa0ec918c6c4906c366c67e36',
proof_id: '5e0433d0-46da-11ea-a79e-017f19452571',
hash_received: '2020-02-03T23:10:28Z',
uri: 'http://127.0.0.1/calendar/695928/hash',
type: 'cal',
anchorId: '695928',
expectedValue: 'ff0fb5903d3b6deed2ee2ebc033813e7b0357de4af2e7b1d52784baad40a0d13',
verified: true,
verifiedAt: '2017-11-28T22:52:20Z'
},
{
hash: 'daeaedcd320c0fb2adefaab15ec03a424bb7a89aa0ec918c6c4906c366c67e36',
proof_id: '5e0433d0-46da-11ea-a79e-017f19452571',
hash_received: '2020-02-03T23:10:28Z',
uri: 'http://127.0.0.1/calendar/696030/data',
type: 'btc',
anchorId: '496469',
expectedValue: 'de999f26afcdd855552ca91184aba496baa48bf59a7125180d7c1d7d520ea88b',
verified: true,
verifiedAt: '2017-11-28T22:52:20Z'
}
]This function is used to evaluate proofs and returns the values arrived at by parsing and performing the operations in a proof.
For example, this can be used to easily verify that a proof that is anchored to the Bitcoin blockchain is valid, without trusting any other third party service. The only thing required is a copy of the Bitcoin block headers, available from any BTC full node or block explorer.
The proofs argument accepts an Array of Strings or Objects.
If a String, it is expected to be a Chainpoint 4.0 proof in either Base64 encoded binary, or JSON-LD form.
If an Object it can be a Chainpoint 4.0 proof as an Object, or have a proof property containing a String proof as described above as is created by the output of getProofs().
Proof types can be mixed freely in the proofs arg Array.
This process is handled entirely offline. At no time is the proof sent over the Internet during this process (although it is safe to do so).
This function will return an Array of Objects. Each object represents an Anchor in a proof along with all of the relevant data.
For example, a single proof that is anchored to both the Chainpoint Calendar, and to the Bitcoin blockchain, will return two objects. One for each of those anchors.
Example Return Value
;[
{
hash: 'daeaedcd320c0fb2adefaab15ec03a424bb7a89aa0ec918c6c4906c366c67e36',
proof_id: '5e0433d0-46da-11ea-a79e-017f19452571',
hash_received: '2020-02-03T23:10:28Z',
uri: 'http://127.0.0.1/calendar/695928/hash',
type: 'cal',
anchorId: '695928',
expectedValue: 'ff0fb5903d3b6deed2ee2ebc033813e7b0357de4af2e7b1d52784baad40a0d13'
},
{
hash: 'daeaedcd320c0fb2adefaab15ec03a424bb7a89aa0ec918c6c4906c366c67e36',
proof_id: '5e0433d0-46da-11ea-a79e-017f19452571',
hash_received: '2020-02-03T23:10:28Z',
uri: 'http://127.0.0.1/calendar/696030/data',
type: 'btc',
anchorId: '496469',
expectedValue: 'de999f26afcdd855552ca91184aba496baa48bf59a7125180d7c1d7d520ea88b'
}
]In this case, you can use a block explorer to confirm that BTC block ID 496469 has a block Merkle root value (expectedValue) of de999f26afcdd855552ca91184aba496baa48bf59a7125180d7c1d7d520ea88b. If it does, that means this proof can be provably said to anchor its hash to that Bitcoin block.
This is a utility function that allows you to perform DNS based auto-discovery of a available Core instance URI addresses.
This function is not required to be explicitly called when using the main functions of this library. It will be called internally as needed.
The optional num argument determines the maximum number of Cores that should be returned in a single request in randomized order.
This function returns an Array of String URIs.