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:

  1. The suffix of the URI (e.g. https://file-uri/QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9)
  2. As a member of the options parameter (e.g. options.hash = 'QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9')
  3. In the resulting file JSON using the key selfHash

Parameters

  1. fileURI - String: The URI where the file can be fetched. Currently only support protocols: http(s)://, /ipfs/
  2. 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

  1. multihashHex - String: The base58 multihash hex string.
  2. file - Object|String: The raw File or JSON object we are verifying the hash of.
  3. 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

  1. file - Object|String: The raw File or JSON object to hash
  2. multicode - Number: The multihash hashing algorithm identifier.
  3. 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"