diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 00000000..2ad7e894 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,21 @@ +# Examples + +- Fetch data from smart contracts + decode in one go! + +- Create basic schemas + +- Encode / Decode Links to external sources (`VerifiableURI`) + +- Map infos to specific addresses or identifiers + + - Using Dynamic Keys + +- Create Lists with keyType Arrays + + - Adding + - Deleting + - Updating + +- Store multiple infos under one data key with tuples + +- Use `CompactBytesArray` for efficient storing + retrieval diff --git a/docs/methods/external-data-source-utilities.md b/docs/methods/external-data-source-utilities.md index ef1c824b..8850aec1 100644 --- a/docs/methods/external-data-source-utilities.md +++ b/docs/methods/external-data-source-utilities.md @@ -17,6 +17,14 @@ OR ERC725.encodeDataSourceWithHash(verification, dataSource); ``` +OR + +```js +import { encodeDataSourceWithHash } from '@erc725/erc725.js'; + +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 @@ -132,7 +140,6 @@ enum SUPPORTED_VERIFICATION_METHOD_HASHES { HASH_KECCAK256_UTF8 = '0x6f357c6a', HASH_KECCAK256_BYTES = '0x8019f9b1', } - ``` @@ -204,6 +211,75 @@ getVerificationMethod('0x6f357c6a'); */ ``` -## hashData - ## isDataAuthentic + +```js +const myErc725 = new ERC725(); +ERC725.isDataAuthentic(data, verificationOptions); +``` + +```js +ERC725.isDataAuthentic(data, verificationOptions); +``` + +```js +import { isDataAuthentic } from '@erc725/erc725.js'; + +isDataAuthentic(data, verificationOptions); +``` + +Hashes the `data` passed as parameter using the specified hashing functions (available under `method` in the `verificationOption` object) and compares the result with the provided hash. + +:::info +This method will console an error if the hash provided as `data` and the expected hash obtained using the verification method do not match. +::: + +#### Parameters + +| Name | Type | Description | +| :-------------------- | :----------------------- | :---------------------------------- | +| `data` | `string` or `Uint8Array` | The data to be hashed and verified. | +| `verificationOptions` | `Verification` | An object as defined below | + +
+ Types details + +```js + KECCAK256_UTF8 = , + KECCAK256_BYTES = , + HASH_KECCAK256_UTF8 = , + HASH_KECCAK256_BYTES = , + +export interface Verification { + data: string; + method: 'keccak256(utf8)' | 'keccak256(bytes)' | '0x6f357c6a' | '0x8019f9b1' | string; + source?: string; +} +``` + +
+ +#### Returns + +| Name | Type | Description | +| :--- | :-------- | :-------------------------------------------------------------------------------------------- | +| | `boolean` | `true` if the data is authentic according to the verification method used, `false` otherwise. | + +### Example + +```javascript title="isDataAuthentic example" +myErc725.myMethod(); +/* +Document an example of the output here +*/ +``` + +/\*\* + +- Hashes the data received with the specified hashing function, +- and compares the result with the provided hash. + \*/ + export function isDataAuthentic( + data: string | Uint8Array, + options: Verification, + ): boolean { diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 00000000..157590b3 --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,148 @@ +# Overview + +## Types + +- ERC725JSONSchema, +- ERC725JSONSchemaKeyType, +- ERC725JSONSchemaValueContent, +- ERC725JSONSchemaValueType, +- Permissions, +- ERC725Config, +- KeyValuePair, +- ProviderTypes +- DynamicNameSchema +- DecodeDataInput, +- DecodeDataOutput, +- EncodeDataInput, +- FetchDataOutput, + +_there is even more..._ + +## Encoding utilities + +- encodeData +- encodeKey -> necessary? +- encodeKeyName +- encodeKeyValue +- encodeArrayKey +- encodeValueType, +- encodeValueContent, + +## Decoding utilities + +- decodeData +- decodeKey +- decodeKeyPart +- decodeKeyValue +- decodeMappingKey +- decodeValueType, +- decodeValueContent, + +## Permissions utilities + +- encodePermissions +- decodePermissions +- checkPermissions +- mapPermission -> Super useful! + +## Fetching data + +- getDataFromExternalSources +- ERC725.getData +- ERC725.fetchData +- ERC725.getOwner +- ERC725.isValidSignature + +**These to be discussed** + +- getArrayValues +- getDataMultiple +- getData + +## External Data Source utilities (`VerifiableURI` and `JSONURI`) + +- encodeDataSourceWithHash, +- decodeDataSourceWithHash, +- getVerificationMethod +- isDataAuthentic + +## Schema utilities + +- getSchema +- getSchemaElement +- getSchemaElementForDynamicKeyName +- validateSchemas +- generateSchemasFromDynamicKeys + +## Dynamic Keys utilities + +- encodeDynamicKeyPart +- encodeDynamicMapping +- encodeDynamicMappingWithGrouping +- encodeDynamicKeyName +- generateDynamicKeyName +- isDynamicKeyPart +- isDynamicKeyName +- splitMultiDynamicKeyNamePart + +## Helpers + +- convertIPFSGatewayUrl +- duplicateMultiTypeERC725SchemaEntry +- guessKeyTypeFromKeyName +- isValidUintSize +- isValidByteSize +- isValueContentLiteralHex +- isValid32ByteHexString + +## Tuple utilities + +- encodeTupleKeyValue +- decodeTupleKeyValue +- isValidTuple + +--- + +These functions are not exported (yet!) + +- validateSchemas +- duplicateMultiTypeERC725SchemaEntry +- convertIPFSGatewayUrl +- generateSchemasFromDynamicKeys +- encodeKeyValue +- guessKeyTypeFromKeyName -> can be renamed to `get`? +- encodeTupleKeyValue +- encodeKey -> necessary? +- isValidTuple +- decodeKeyValue +- isDataAuthentic +- splitMultiDynamicKeyNamePart +- isValidUintSize +- isValidByteSize +- isValueContentLiteralHex +- getSchemaElementForDynamicKeyName +- getSchemaElement +- getArrayValues +- getDataMultiple +- getData +- encodeDynamicKeyPart +- encodeDynamicMapping +- encodeDynamicMappingWithGrouping +- encodeDynamicKeyName +- generateDynamicKeyName +- isValid32ByteHexString +- mapPermission -> Super useful! +- isDynamicKeyPart +- decodeKeyPart +- isValidTuple +- decodeTupleKeyValue -> strange we don't have `encodeTupleKeyValue` +- decodeKey + +These types should be exported: + +- DynamicNameSchema +- DecodeDataInput, +- DecodeDataOutput, +- EncodeDataInput, +- FetchDataOutput, +- there is even more... diff --git a/src/lib/getDataFromExternalSources.test.ts b/src/lib/getDataFromExternalSources.test.ts index c8cd7659..0bd38310 100644 --- a/src/lib/getDataFromExternalSources.test.ts +++ b/src/lib/getDataFromExternalSources.test.ts @@ -20,10 +20,11 @@ import { ERC725JSONSchema } from '../types/ERC725JSONSchema'; import { getDataFromExternalSources } from './getDataFromExternalSources'; import { DecodeDataOutput } from '../types/decodeData'; +import { URLDataWithHash } from '../types'; const IPFS_GATEWAY_MOCK = 'https://mock-ipfs.mock/ipfs/'; -describe('getDataFromExternalSources', () => { +describe.only('getDataFromExternalSources', () => { it('should not throw if the value of a JSONURL/ASSETURL is null', async () => { const schemas: ERC725JSONSchema[] = [ { @@ -52,4 +53,35 @@ describe('getDataFromExternalSources', () => { ); }).to.not.throw(); }); + + it("should return the right data when the schema's valueContent is VerifiableURI", async () => { + const schema: ERC725JSONSchema = { + name: 'LSP3Profile', + key: '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', + keyType: 'Singleton', + valueType: 'bytes', + valueContent: 'VerifiableURI', + }; + + const dataFromChain: DecodeDataOutput[] = [ + { + name: 'LSP3Profile', + key: '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', + value: { + verification: { + data: '0x00006f357c6a0020db864ed42104cee179785036cb4ff1183ebc57e5532ae766ad8533fa48acfbb3697066733a2f2f516d644d4755787551736d3155395173386f4a536e3550665934423161704747373559425278515079627452566d', + method: 'keccak256(utf8)', + }, + } as URLDataWithHash, + }, + ]; + + const result = await getDataFromExternalSources( + [schema], + dataFromChain, + IPFS_GATEWAY_MOCK, + ); + + console.log('result', result); + }); }); diff --git a/src/lib/getDataFromExternalSources.ts b/src/lib/getDataFromExternalSources.ts index 7c898417..de35abde 100644 --- a/src/lib/getDataFromExternalSources.ts +++ b/src/lib/getDataFromExternalSources.ts @@ -132,6 +132,15 @@ export const getDataFromExternalSources = ( if (isDataAuthentic(value, urlDataWithHash.verification)) { return { ...dataEntry, value }; } + console.log('receivedData', receivedData); + console.log( + 'urlDataWithHash.verification', + urlDataWithHash.verification, + ); + console.log( + 'isDataAuthentic(receivedData, urlDataWithHash.verification)', + isDataAuthentic(receivedData, urlDataWithHash.verification), + ); if (isDataAuthentic(receivedData, urlDataWithHash.verification)) { return { ...dataEntry, value }; } diff --git a/src/lib/utils.ts b/src/lib/utils.ts index 4c4b6386..82d3e664 100644 --- a/src/lib/utils.ts +++ b/src/lib/utils.ts @@ -558,16 +558,16 @@ export function hashData( */ export function isDataAuthentic( data: string | Uint8Array, - options: Verification, + verificationOptions: Verification, ): boolean { - if (!options || !options.method) { + if (!verificationOptions || !verificationOptions.method) { return true; } - const dataHash = hashData(data, options.method); - if (dataHash !== options.data) { + const dataHash = hashData(data, verificationOptions.method); + if (dataHash !== verificationOptions.data) { console.error( - `Hash mismatch, returned JSON hash ("${dataHash}") is different from expected hash: "${options.method}"`, + `Hash mismatch, returned JSON hash ("${dataHash}") is different from expected hash: "${verificationOptions.method}"`, ); return false; }