feat: export function to get verification method

ERC725Alliance · May 21, 2024 · f426a31 · f426a31
1 parent b1784ef
commit f426a31
Show file tree

Hide file tree

Showing 3 changed files with 273 additions and 25 deletions.
diff --git a/docs/methods/external-data-source-utilities.md b/docs/methods/external-data-source-utilities.md
@@ -0,0 +1,209 @@
+---
+sidebar_position: 1
+---
+
+# External Data Source utilities (`VerifiableURI` and `JSONURI`)
+
+## encodeDataSourceWithHash
+
+```js
+const myErc725 = new ERC725();
+myErc725.encodeDataSourceWithHash(verification, dataSource);
+```
+
+OR
+
+```js
+ERC725.encodeDataSourceWithHash(verification, dataSource);
+```
+
+Encode a verifiableURI providing the hashing function of the json file (method), the hash of the json file (data) and the url where the json file is stored.
+
+#### Parameters
+
+| Name           | Type                          | Description                                                                                                              |
+| :------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| `verification` | `undefined` or `Verification` | Verification is an object containing the hashing function of the json file (method) and the hash of the json file (data) |
+| `dataSource`   | `string`                      | The url where the json file is stored.                                                                                   |
+
+<details>
+    <summary>Types details</summary>
+
+```js
+interface Verification {
+    method: SUPPORTED_VERIFICATION_METHODS | string;
+    data: string;
+    source?: string;
+}
+
+type SUPPORTED_VERIFICATION_METHODS =
+    | SUPPORTED_VERIFICATION_METHOD_STRINGS
+    | SUPPORTED_VERIFICATION_METHOD_HASHES;
+
+enum SUPPORTED_VERIFICATION_METHOD_STRINGS {
+    KECCAK256_UTF8 = 'keccak256(utf8)',
+    KECCAK256_BYTES = 'keccak256(bytes)',
+}
+
+enum SUPPORTED_VERIFICATION_METHOD_HASHES {
+    HASH_KECCAK256_UTF8 = '0x6f357c6a',
+    HASH_KECCAK256_BYTES = '0x8019f9b1',
+}
+```
+
+</details>
+
+#### Returns
+
+| Name            | Type   | Description       |
+| :-------------- | :----- | :---------------- |
+| `verifiableURI` | string | The verifiableURI |
+
+#### Examples
+
+<details>
+    <summary>Encode a <code>VerifiableURI</code> providing the hashing function, the JSON hash and the uploaded URL</summary>
+
+```javascript title="Encode a VerifiableURI providing the hashing function, the JSON hash and the uploaded URL"
+const verifiableURI = myErc725.encodeDataSourceWithHash(
+  {
+    method: 'keccak256(utf8)',
+    data: '0x820464ddfac1bec070cc14a8daf04129871d458f2ca94368aae8391311af6361',
+  },
+  'ifps://QmYr1VJLwerg6pEoscdhVGugo39pa6rycEZLjtRPDfW84UAx',
+);
+/**
+0x00006f357c6a0020820464ddfac1bec070cc14a8daf04129871d458f2ca94368aae8391311af6361696670733a2f2f516d597231564a4c776572673670456f73636468564775676f3339706136727963455a4c6a7452504466573834554178
+*/
+```
+
+</details>
+
+## decodeDataSourceWithHash
+
+```js
+const myErc725 = new ERC725();
+myErc725.decodeDataSourceWithHash(verifiableURI);
+```
+
+```js
+ERC725.decodeDataSourceWithHash(verifiableURI);
+```
+
+Decode a verifiableURI into the hash function of the json file, the hash of the json file and the url where the json file is stored.
+
+#### Parameters
+
+| Name            | Type     | Description       |
+| :-------------- | :------- | :---------------- |
+| `verifiableURI` | `string` | The verifiableURI |
+
+#### Returns
+
+| Name                   | Type              | Description                                                                                                |
+| :--------------------- | :---------------- | :--------------------------------------------------------------------------------------------------------- |
+| `decodedVerifiableURI` | `URLDataWithHash` | Object containing the hash function, the hash of the JSON file and the link where the json file is stored. |
+
+<details>
+    <summary>Types details</summary>
+
+```js
+interface URLDataWithHash {
+  verification: Verification;
+  url: string
+}
+
+interface Verification {
+method: SUPPORTED_VERIFICATION_METHODS | string;
+data: string;
+source?: string;
+}
+
+type SUPPORTED_VERIFICATION_METHODS =
+| SUPPORTED_VERIFICATION_METHOD_STRINGS
+| SUPPORTED_VERIFICATION_METHOD_HASHES;
+
+enum SUPPORTED_VERIFICATION_METHOD_STRINGS {
+KECCAK256_UTF8 = 'keccak256(utf8)',
+KECCAK256_BYTES = 'keccak256(bytes)',
+}
+
+enum SUPPORTED_VERIFICATION_METHOD_HASHES {
+HASH_KECCAK256_UTF8 = '0x6f357c6a',
+HASH_KECCAK256_BYTES = '0x8019f9b1',
+}
+
+```
+
+</details>
+
+#### Examples
+
+<details>
+    <summary>Decode a <code>VerifiableURI</code></summary>
+
+```javascript title="Decode a VerifiableURI"
+const decodedVerifiableURI = myErc725.decodeDataSourceWithHash(
+  '0x00006f357c6a0020820464ddfac1bec070cc14a8daf04129871d458f2ca94368aae8391311af6361696670733a2f2f516d597231564a4c776572673670456f73636468564775676f3339706136727963455a4c6a7452504466573834554178',
+);
+/**
+verification: {
+    data: '820464ddfac1bec070cc14a8daf04129871d458f2ca94368aae8391311af6361',
+    method: 'keccak256(utf8)',
+  }
+url: 'ifps://QmYr1VJLwerg6pEoscdhVGugo39pa6rycEZLjtRPDfW84UAx'
+*/
+```
+
+</details>
+
+## getVerificationMethod
+
+```js
+const myErc725 = new ERC725();
+myErc725.getVerificationMethod(nameOrSig);
+```
+
+```js
+ERC725.getVerificationMethod(nameOrSig);
+```
+
+```js
+import { getVerificationMethod } from '@erc725/erc725.js';
+getVerificationMethod(nameOrSig);
+```
+
+Get the verification method definition, including the name, signature and related method.
+
+method: (data: string | object | Uint8Array | null) => string;
+name: SUPPORTED_VERIFICATION_METHOD_STRINGS;
+sig: SUPPORTED_VERIFICATION_METHODS;
+
+#### Parameters
+
+| Name        | Type   | Description                                 |
+| :---------- | :----- | :------------------------------------------ |
+| `nameOrSig` | string | The 4 bytes hex of the verification method. |
+
+#### Returns
+
+| Name | Type   | Description                                                                             |
+| :--- | :----- | :-------------------------------------------------------------------------------------- |
+|      | object | An object containing the name, signature and method related to the verification method. |
+
+### Example
+
+```javascript title="Example of the method"
+getVerificationMethod('0x6f357c6a');
+/*
+{
+  method: [Function: keccak256Method],
+  name: 'keccak256(utf8)',
+  sig: '0x6f357c6a'
+}
+*/
+```
+
+## hashData
+
+## isDataAuthentic
diff --git a/src/index.ts b/src/index.ts
@@ -17,6 +17,7 @@
  * @author Robert McLeod <@robertdavid010>
  * @author Fabian Vogelsteller <fabian@lukso.network>
  * @author Hugo Masclet <@Hugoo>
+ * @author Jean Cavallera <@CJ42>
  * @date 2020
  */
 
@@ -30,12 +31,17 @@ import {
   convertIPFSGatewayUrl,
   generateSchemasFromDynamicKeys,
   duplicateMultiTypeERC725SchemaEntry,
+  getVerificationMethod,
 } from './lib/utils';
 
 import { getSchema } from './lib/schemaParser';
 import { isValidSignature } from './lib/isValidSignature';
 
-import { DEFAULT_GAS_VALUE } from './constants/constants';
+import {
+  DEFAULT_GAS_VALUE,
+  SUPPORTED_VERIFICATION_METHODS,
+  SUPPORTED_VERIFICATION_METHOD_STRINGS,
+} from './constants/constants';
 import { encodeKeyName, isDynamicKeyName } from './lib/encodeKeyName';
 
 // Types
@@ -87,7 +93,7 @@ export {
 };
 
 export { ERC725Config, KeyValuePair, ProviderTypes } from './types';
-export { encodeData, encodeArrayKey } from './lib/utils';
+export { encodeData, encodeArrayKey, getVerificationMethod } from './lib/utils';
 export { decodeData } from './lib/decodeData';
 export { encodeKeyName, isDynamicKeyName } from './lib/encodeKeyName';
 export { decodeMappingKey } from './lib/decodeMappingKey';
@@ -684,27 +690,8 @@ export class ERC725 {
     return mapPermission(permission);
   }
 
-  encodeDataSourceWithHash(
-    verification: undefined | Verification,
-    dataSource: string,
-  ): string {
-    return encodeDataSourceWithHash(verification, dataSource);
-  }
-
-  static encodeDataSourceWithHash(
-    verification: undefined | Verification,
-    dataSource: string,
-  ): string {
-    return encodeDataSourceWithHash(verification, dataSource);
-  }
-
-  decodeDataSourceWithHash(value: string): URLDataWithHash {
-    return decodeDataSourceWithHash(value);
-  }
-
-  static decodeDataSourceWithHash(value: string): URLDataWithHash {
-    return decodeDataSourceWithHash(value);
-  }
+  // Encoding methods
+  // ----------------
 
   /**
    * @param type The valueType to encode the value as
@@ -765,6 +752,51 @@ export class ERC725 {
   ): string | URLDataWithHash | number | boolean | null {
     return decodeValueContent(valueContent, value);
   }
+
+  // External Data Source utilities (`VerifiableURI` and `JSONURI`)
+  // ----------------------------------------------------------------
+
+  encodeDataSourceWithHash(
+    verification: undefined | Verification,
+    dataSource: string,
+  ): string {
+    return encodeDataSourceWithHash(verification, dataSource);
+  }
+
+  static encodeDataSourceWithHash(
+    verification: undefined | Verification,
+    dataSource: string,
+  ): string {
+    return encodeDataSourceWithHash(verification, dataSource);
+  }
+
+  decodeDataSourceWithHash(value: string): URLDataWithHash {
+    return decodeDataSourceWithHash(value);
+  }
+
+  static decodeDataSourceWithHash(value: string): URLDataWithHash {
+    return decodeDataSourceWithHash(value);
+  }
+
+  static getVerificationMethod(nameOrSig: string):
+    | {
+        method: (data: string | object | Uint8Array | null) => string;
+        name: SUPPORTED_VERIFICATION_METHOD_STRINGS;
+        sig: SUPPORTED_VERIFICATION_METHODS;
+      }
+    | undefined {
+    return getVerificationMethod(nameOrSig);
+  }
+
+  getVerificationMethod(nameOrSig: string):
+    | {
+        method: (data: string | object | Uint8Array | null) => string;
+        name: SUPPORTED_VERIFICATION_METHOD_STRINGS;
+        sig: SUPPORTED_VERIFICATION_METHODS;
+      }
+    | undefined {
+    return getVerificationMethod(nameOrSig);
+  }
 }
 
 export default ERC725;
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
@@ -47,6 +47,7 @@ import {
   SUPPORTED_VERIFICATION_METHODS,
   SUPPORTED_VERIFICATION_METHODS_LIST,
   COMPACT_BYTES_ARRAY_STRING,
+  SUPPORTED_VERIFICATION_METHOD_STRINGS,
 } from '../constants/constants';
 import {
   decodeValueContent,
@@ -157,7 +158,7 @@ export function encodeKeyValue(
 
 /**
  *
- * @param key The schema key of a schema with keyType = 'Array'
+ * @param key A data key either as a 32 bytes long value, or a data key name of keyType = 'Array'
  * @param index An integer representing the intended array index
  * @return The raw bytes key for the array element
  */
@@ -524,7 +525,13 @@ export function encodeData(
   );
 }
 
-export function getVerificationMethod(nameOrSig: string) {
+export function getVerificationMethod(nameOrSig: string):
+  | {
+      method: (data: string | object | Uint8Array | null) => string;
+      name: SUPPORTED_VERIFICATION_METHOD_STRINGS;
+      sig: SUPPORTED_VERIFICATION_METHODS;
+    }
+  | undefined {
   const verificationMethod = Object.values(HASH_METHODS).find(
     ({ name, sig }) => name === nameOrSig || sig === nameOrSig,
   );