archon.utils¶
This package provides utility functions that can be used to validate hashes of Evidence
and MetaEvidence
Note
If using /ipfs/...
URIs the the IPFS Gateway will be used to fetch and validate the data.
Warning
It is not recommended that you link directly to an IPFS
gateway in the evidence because it will not be able to be verified without a custom hashing function. The IPFS
protocol does transformations on the data before hashing, therefore a hash can not be verified naively using the resulting IPFS
multihash and the original file contents.
validateFileFromURI()¶
archon.utils.validateFileFromURI(fileURI, options={});
Takes a the URI of the file and validates the hash. In order for to validate the hash,
the original multihash
must be included as:
- The suffix of the URI (e.g.
https://file-uri/QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9
) - As a member of the
options
parameter (e.g.options.hash = 'QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9'
) - In the resulting file JSON using the key
selfHash
Parameters¶
fileURI
-String
: The URI where the file can be fetched. Currently only support protocols:http(s)://
,/ipfs/
options
-Object
: Optional parameters.
The options parameter can include:
Key | Type | Description |
---|---|---|
preValidated | bool | If file has been pre-validated this will just fetch file and set isValid = true. |
hash | string | The original hash to compare the file against. |
strict | bool | If true, an error will throw if hash or chain ID validations fail. |
strictHashes | bool | [DEPRECATED] If true, an error will throw if hash validations fail. |
customHashFn | fn | A custom hash function to use to validate the file. |
Returns¶
Promise.<Object>
- Promise that resolves to an object containing the file as well as if the file is valid
{
file: <String|Object>,
isValid: <Bool>
}
Example¶
archon.utils.validateFileFromURI(
'https://s3.us-east-2.amazonaws.com/kleros-examples/exampleEvidence.txt',
{
hash: 'Bce1WTQa7bfrJMFdEJuWV2xHsmj5JcDDyqBKGXu6PHZsn5e5oxkJ8cMJcuFDK1VsQYBtfrzgWkKCovWSvsacgN1XTj'
}
).then(data => {
console.log(data)
})
> {
file: 'This is an example evidence file. Here we could have...',
isValid: true
}
validMultihash()¶
archon.utils.validMultihash(multihashHex, file, customHashFn=null);
Verify if the multihash
of a file matches the file contents.
Note
Hashes should be base58 encoded Strings
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.
Parameters¶
multihashHex
-String
: The base58 multihash hex string.file
-Object|String
: The raw File or JSON object we are verifying the hash of.customHashFn
-Function
:<optional>
A custom hashing algorithm used to generate original hash.
Returns¶
Bool
- If the provided hash and file are valid.
Example¶
archon.utils.validMultihash(
'Bce1WTQa7bfrJMFdEJuWV2xHsmj5JcDDyqBKGXu6PHZsn5e5oxkJ8cMJcuFDK1VsQYBtfrzgWkKCovWSvsacgN1XTj',
'This is an example evidence file. Here we could have some document...'
)
> true
multihashFile()¶
archon.utils.multihashFile(file, multicode, customHashFn=null);
Generate the base58 multihash hex of a file
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.
Parameters¶
file
-Object|String
: The raw File or JSON object to hashmulticode
-Number
: The multihash hashing algorithm identifier.customHashFn
-Function
:<optional>
A custom hashing algorithm used to generate the hash.
Returns¶
String
- base58 multihash of file.
Example¶
archon.utils.multihashFile(
'This is an example evidence file. Here we could have some document...',
0x1B // 27 => keccak-256
)
> "Bce1WTQa7bfrJMFdEJuWV2xHsmj5JcDDyqBKGXu6PHZsn5e5oxkJ8cMJcuFDK1VsQYBtfrzgWkKCovWSvsacgN1XTj"