Hashing Examples¶
Here are some examples of evidence hashing and validation using archon. To see the full specification of Evidence and MetaEvidence see ERC 1497.
Note
All insignificant whitespace should be removed from JSON files before hashing. You can use JSON.stringify
to remove whitespace.
Hash and Validate Hosted Evidence¶
In this example we will use an example evidence file hosted here: https://s3.us-east-2.amazonaws.com/kleros-examples/exampleEvidence.txt
var Archon = require('@kleros/archon');
var fs = require('fs');
var path = require('path');
// Bring in our evidence file downloaded from the link above to obtain the hash
var file = fs.readFileSync(path.resolve(__dirname, "./exampleEvidence.txt")).toString();
// Hash the file using keccak-256
var evidenceHash = Archon.utils.multihashFile(
file,
0x1B // keccak-256
);
console.log(evidenceHash); // Bce1WTQa7bfrJMFdEJuWV2xHsmj5JcDDyqBKGXu6PHZsn5e5oxkJ8cMJcuFDK1VsQYBtfrzgWkKCovWSvsacgN1XTj
// Validate the hosted file against the hash we just produced.
Archon.utils.validateFileFromURI(
'https://s3.us-east-2.amazonaws.com/kleros-examples/exampleEvidence.txt',
{ hash: evidenceHash }
).then(data => {
console.log(data.isValid); // true
})
Hash and Validate Local Evidence¶
In this example we will use an example evidence file hosted here: https://s3.us-east-2.amazonaws.com/kleros-examples/exampleEvidence.txt
var Archon = require('@kleros/archon');
var fs = require('fs');
var path = require('path');
// Bring in our evidence file downloaded from the link above to obtain the hash
var file = fs.readFileSync(path.resolve(__dirname, "./exampleEvidence.txt")).toString();
// Hash the file using keccak-256
var evidenceHash = Archon.utils.multihashFile(
file,
0x1B // keccak-256
);
console.log(evidenceHash); // Bce1WTQa7bfrJMFdEJuWV2xHsmj5JcDDyqBKGXu6PHZsn5e5oxkJ8cMJcuFDK1VsQYBtfrzgWkKCovWSvsacgN1XTj
// Validate the original file against the hash we just produced.
console.log(Archon.utils.validMultihash(
evidenceHash
file,
); // true
Custom Hash Functions¶
If you would like to use a custom hashing function in your multihash you can pass
one as an optional last parameter to multihashFile
and validMultihash
or
as option.customHashFn
to validateFileFromURI
. For full documentation on these
individual functions see archon.utils.
You might want to do this in cases where you used a non-standard
implementation of the hashing algorithm, or where there needs to be some data transformations
before you apply the hashing algorithm, as is the case with IPFS hashes.
This is only for the initial hashing algorithm in the multihash. Your hashing function should
take a single String
argument and return a String
that is the hex representation of the hash.
- Non standard hash function implementations
Note
You must still include a hashcode even if you are using a custom hash function. In order to have a valid multihash your hash must correspond to a valid hashcode. It is not recommended you use an unsupported hashing function that does not have a hashcode. If your hashes are not valid multihashes, consider validating your hashes outside of Archon.
Warning
If you use a custom hash function other interfaces may not be able to validate your hashes.
Example – Solidity keccak-256¶
Solidity uses a non standard implementation of the keccak-256 hashing algorithm. Therefore if we are using hashes produced by a smart contract we might need to validate using a custom hashing function.
Note
In this example the custom hash function is a non-standard implementation of keccak-256 so it can still use the hashcode 0x1B.
var Archon = require('@kleros/archon');
var Web3 = require('web3')
// Hash our "file" ('12345') using the soliditySha3.
var nonStandardSha3Hash = Archon.utils.multihashFile(
'12345',
0x1B, // keccak-256
Web3.utils.soliditySha3 // custom hash function
);
console.log(nonStandardSha3Hash); // 4ZqgPBxZrZkSXnTBm8G162mXVCNNbWrZa25CcvfGtQV1pRHH6X8vfLi89RKTA4c6tyfQsD5vzGvJozs24XvcLysiC3U6b
// Validate using the standard keccak-256 hashing algorithm.
console.log(Archon.utils.validMultihash(
nonStandardSha3Hash,
'12345'
)) // false
// Validate using the solidity sha3 implementation.
console.log(Archon.utils.validMultihash(
nonStandardSha3Hash,
'12345',
Web3.utils.soliditySha3
)) // true
Hash Validation Troubleshooting¶
Here are some common mistakes that can cause your hashes to fail validation:
- Did not remove all insignificant whitespace before hashing JSON. This means all newlines and spaces in between your JSON values.
- Using a non-standard hash function. Out of the box, Archon supports these hashing algorithms. They are from the javascript library js-sha3. If you used a different hashing algorithm you will need to pass an implementation of it to Archon. See Custom Hashing.
sha2
vssha3
. Many libraries will specify their hashes aresha256
without specifying if they are sha2 or sha3.sha2-256
andsha3-256
are different hashing algorithms and use different hashcodes.- Not using the
base58
representation of the multihash hash. Multihash hashes can be expressed in many bases. Archon is expectingbase58
hashes. - Did not include the original hash in some format to
validateFileFromURI
. Archon accepts hashes as the name of the file with no file type extension or using the propertyselfHash
if the file is JSON. Otherwise if you have an alternate method of obtaining the hash pass it usingoptions.hash
.
Supported Hashing Algorithms and Hashcodes¶
Supported hashing algorithms:
Name | Multicode |
---|---|
sha3-512 | 0x14 |
sha3-384 | 0x15 |
sha3-256 | 0x16 |
sha3-224 | 0x17 |
keccak-224 | 0x1A |
keccak-256 | 0x1B |
keccak-384 | 0x1C |
keccak-512 | 0x1D |
Tip
By default, IPFS uses sha2-256
. Many ethereum hashes are keccak-256
.
Warning
Solidity uses a different implementation of the keccak-256
algorithm. Hashes generated from smart contracts will need a customHashFn
to verify.
Note
All insignificant whitespace should be removed from JSON files before hashing. You can use JSON.stringify
to remove whitespace.
If a different hashing algorithm was used, pass it in the desired function with customHashFn
. The function should expect a single string parameter.
A full list of possible algorithms and multicodes can be found here.