From 042095986057e7e1c7ebf363bc816936a39d472e Mon Sep 17 00:00:00 2001 From: CJ42 Date: Fri, 24 May 2024 10:01:41 +0200 Subject: [PATCH 1/4] docs: add method docs template --- docs/README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/README.md b/docs/README.md index a35e996d..c2e5c27d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,52 @@ # erc725.js docs The markdown files in this folder are published on the LUKSO docs portal: + +# Method docs template + +You can use the following example below as a template to document any new methods added the library. + +### methodName + +```js +myErc725.methodName(param1, param2, [optionalParams]); +``` + +```js +ERC725.methodName(param1, param2, [optionalParams]); +``` + +Describe your method and how it is intended to be used, the benefits it brings, and any specific behaviour that the functions has. + +#### Parameters + +| Name | Type | Description | +| :------- | :--------------------------------------------------------------------------------------------------------- | :---------- | +| `param1` | `string` | ... | +| `param2` | `string` or
`string[]` or
`number` or
`number[]` or
`boolean` or
`boolean[]` | ... | + +#### Returns + +| Name | Type | Description | +| :--- | :------- | :---------- | +| | `string` | ... | + +#### Examples + +```javascript +import ERC725 from '@erc725/erc725.js'; + +const myErc725 = new ERC725(); + +myErc725.methodName('hello', 5); +// show in comment the expected output of the function +``` + +This method is also available as a static method. + +```javascript +import ERC725 from '@erc725/erc725.js'; + +ERC725.methodName('hello', 5); +// show in comment the expected output of the function +``` From d8ce6acddf14d4bc3d378cd2ad6a56c71cca93c4 Mon Sep 17 00:00:00 2001 From: CJ42 Date: Fri, 24 May 2024 11:09:11 +0200 Subject: [PATCH 2/4] docs: add documentation for `encodeValueContent` --- docs/README.md | 2 +- docs/methods.md | 91 +++++++++++++++++++++++++++++++++++++++-- src/lib/encoder.test.ts | 7 ++++ 3 files changed, 96 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index c2e5c27d..c9ec26fb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ The markdown files in this folder are published on the LUKSO docs portal: -# Method docs template +## Method docs template You can use the following example below as a template to document any new methods added the library. diff --git a/docs/methods.md b/docs/methods.md index 69f7387d..71b52970 100644 --- a/docs/methods.md +++ b/docs/methods.md @@ -524,8 +524,6 @@ myErc725.encodeKeyName('LSP3Profile'); --- -### encodeArrayKey (TBD) - ### encodeValueType ```js @@ -600,7 +598,94 @@ ERC725.encodeValueType('string', 'Hello'); --- -### encodeValueContent (TBD) +### encodeValueContent + +```js +myErc725.encodeValueContent(valueContent, value); +``` + +or + +```js +ERC725.encodeValueContent(valueContent, value); +``` + +or + +```js +import { encodeValueContent } from '@erc725/erc725.js'; +encodeValueContent(valueContent, value); +``` + +Encode `value` into a hex bytestring that can be then fetched, decoded and interpreted as the specified `valueContent`. + +#### Parameters + +| Name | Type | Description | +| :------------- | :------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `valueContent` | `string` | Available options are:
  • `AssetURL`
  • `JSONURL`
  • `Boolean`
  • `Keccak256`
  • `Number`
  • `Address`
  • `String`
  • `Markdown`
  • `URL`
  • `VerifiableURI`
  • `BytesN`
  • `BitArray`
  • `Boolean`
  • Any Hex `Literal` (e.g.: 0x1345ABCD...)
| +| `value` | `string` or
`number` or
`boolean` or
`AssetURLEncode` or
`AssetURLEncode` | The value to encode. | + +#### Returns + +| Name | Type | Description | +| :--- | :------- | :--------------------------------------- | +| | `string` | The `value` encoded as a `valueContent`. | + +#### Examples + +```javascript +import { encodeValueContent } from '@erc725/erc725.js'; + +encodeValueContent('String', 'hello'); +// 0x68656c6c6f + +// BytesN will right pad +encodeValueContent('Bytes8', '0xaabbccdd'); +// 0xaabbccdd00000000 + +// Encoding some markdown +encodeValueContent( + 'Markdown', + `# Lorem Ipsum + dolor sit amet ebriscus lanfogern`, +); +// 0x23204c6f72656d20497073756d0a2020202020202020646f6c6f722073697420616d6574206562726973637573206c616e666f6765726 + +encodeValueContent('URL', 'http://test.com'); +// 0x687474703a2f2f746573742e636f6d + +encodeValueContent('VerifiableURI', { + verification: { + method: 'keccak256(utf8)', + data: '0x027547537d35728a741470df1ccf65de10b454ca0def7c5c20b257b7b8d16168', + }, + url: 'http://test.com/asset.glb', +}); +// 0x00006f357c6a0020027547537d35728a741470df1ccf65de10b454ca0def7c5c20b257b7b8d16168687474703a2f2f746573742e636f6d2f61737365742e676c62 + +encodeValueContent('VerifiableURI', { + verification: { + method: '0x00000000', + data: '0x', + }, + url: 'https://name.universal.page/', +}); +// 0x000000000000000068747470733a2f2f6e616d652e756e6976657273616c2e706167652f +``` + +This method is also available as a static method or as a method from the `ERC725` instance. + +```javascript +import ERC725 from '@erc725/erc725.js'; + +ERC725.encodeValueContent('String', 'hello'); +// 0x68656c6c6f + +const erc725 = new ERC725(); +erc725.encodeValueContent('String', 'hello'); +// 0x68656c6c6f +``` --- diff --git a/src/lib/encoder.test.ts b/src/lib/encoder.test.ts index aa6b62f0..be0f45d2 100644 --- a/src/lib/encoder.test.ts +++ b/src/lib/encoder.test.ts @@ -938,6 +938,13 @@ describe('encoder', () => { decodedValue: '# hello', encodedValue: '0x232068656c6c6f', }, + { + valueContent: 'Markdown', + decodedValue: `# Lorem Ipsum + dolor sit amet ebriscus lanfogern`, + encodedValue: + '0x23204c6f72656d20497073756d0a2020202020202020646f6c6f722073697420616d6574206562726973637573206c616e666f6765726e', + }, { valueContent: 'URL', decodedValue: 'http://test.com', From e4f33ea354884e5730ebc40ba61b611db7ed5eb3 Mon Sep 17 00:00:00 2001 From: CJ42 Date: Fri, 24 May 2024 12:08:26 +0200 Subject: [PATCH 3/4] docs: add missing methods `getSchema` and `getDataFromExternalSources` --- docs/methods.md | 233 +++++++++++++++++++++++++++++++++- src/types/ERC725JSONSchema.ts | 2 +- 2 files changed, 232 insertions(+), 3 deletions(-) diff --git a/docs/methods.md b/docs/methods.md index 71b52970..ffbf5b76 100644 --- a/docs/methods.md +++ b/docs/methods.md @@ -999,7 +999,7 @@ Available `valueContent` are: | :------------- | :--------------------------------------------------------------------------------------- | :------------------------------------------- | | `decodedValue` | `string` or
`URLDataWithHash` or
`number` or
`boolean` or
`null` | A value decoded according to `valueContent`. | -### Examples +#### Examples ```javascript title="decodeValueContent example" erc725js.decodeValueContent( @@ -1136,6 +1136,103 @@ myErc725.decodeMappingKey( --- +### getSchema + +```js +myErc725.getSchema(keys [, providedSchemas]); +``` + +Parses a hashed key or a list of hashed keys and will attempt to return its corresponding [LSP2 ERC725YJSONSchema](https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md) object. Additionally, it will look for a corresponding key within the schemas: + +- in the [`schemas`](https://github.com/ERC725Alliance/myErc725.js/tree/main/schemas) folder (which includes all [LSPs](https://github.com/lukso-network/LIPs/tree/main/LSPs)), +- that were provided at ERC725 initialization, and +- that were provided in the function call (`providedSchemas`). + +#### Parameters + +##### 1. `keys` - String or array of Strings + +The key(s) you are trying to get the schema for. + +##### 2. `providedSchemas` - Object (optional) + +An array of extra [LSP-2 ERC725YJSONSchema] objects that can be used to find the schema. + +#### Returns + +| Name | Type | Description | +| :------- | :--------------- | :-------------------------------------------------------------------- | +| `result` | ERC725JSONSchema | If the parameter `keys` is a string and the schema was found. | +| `result` | Record string | If the parameter `keys` is a string[ ] and the schema was found. | +| `result` | null | If the schema was not found. | + +#### Example using a predefined LSP3 schema + +```javascript title="Parsing the hashed key from the LSP3 schema" +myErc725.getSchema( + '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', +); +/** +{ + name: 'LSP3Profile', + key: '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', + keyType: 'Singleton', + valueContent: 'VerifiableURI', + valueType: 'bytes' +} +*/ +myErc725.getSchema([ + '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', + '0x3a47ab5bd3a594c3a8995f8fa58d087600000000000000000000000000000001', +]); +/** +{ + '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5': { + name: 'LSP3Profile', + key: '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', + keyType: 'Singleton', + valueContent: 'VerifiableURI', + valueType: 'bytes' + }, + '0x3a47ab5bd3a594c3a8995f8fa58d087600000000000000000000000000000001': { + name: 'LSP12IssuedAssets[1]', + key: '0x7c8c3416d6cda87cd42c71ea1843df28ac4850354f988d55ee2eaa47b6dc05cd', + keyType: 'Singleton', + valueContent: 'Address', + valueType: 'address' + } +} +*/ +``` + +#### Example using a custom schema + +```javascript title="Parsing the hashed key from a custom schema" +myErc725.getSchema( + '0x777f55baf2e0c9f73d3bb456dfb8dbf6e609bf557969e3184c17ff925b3c402c', + [ + { + name: 'ParameterSchema', + key: '0x777f55baf2e0c9f73d3bb456dfb8dbf6e609bf557969e3184c17ff925b3c402c', + keyType: 'Singleton', + valueContent: 'VerifiableURI', + valueType: 'bytes', + }, + ], +); +/** +{ + name: 'ParameterSchema', + key: '0x777f55baf2e0c9f73d3bb456dfb8dbf6e609bf557969e3184c17ff925b3c402c', + keyType: 'Singleton', + valueContent: 'VerifiableURI', + valueType: 'bytes', +} +*/ +``` + +--- + ## Fetching Data ### fetchData @@ -1182,7 +1279,7 @@ The name(s) (or the encoded name(s) as schema key) of the element(s) in the smar ::: -### All-Keys Example +#### All-Keys Example ```javascript title="Receiving all keys from the schema" import ERC725 from '@erc725/erc725.js'; @@ -1893,6 +1990,138 @@ url: 'ifps://QmYr1VJLwerg6pEoscdhVGugo39pa6rycEZLjtRPDfW84UAx' +### getDataFromExternalSources + +```js +getDataFromExternalSources(schema, dataFromChain, ipfsGateway, [ + (throwException = true), +]); +``` + +Retrieve the data(s) stored on IPFS using one (or multiple) IPFS CID(s) and link(s) under the `dataFromChain` parameter. + +#### Parameters + +| Name | Type | Description | +| :-------------------------- | :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | +| `schema` | `ERC725JSONSchema[]` | A list of JSON schemas for some given data keys. | +| `dataFromChain` | `DecodeDataOutput[]` | ... | +| `ipfsGateway` | `string` | The URL to use to fetch data from the IPFS network. | +| `throwException` (optional) | `boolean` | Define if the function should throw an error when fetching data. Set to `true` by default. This is useful for handling exceptions differently. | + +
+ Types details + +```js +interface ERC725JSONSchema { + name: string; // Describes the name of the key, SHOULD be composed of the Standards name + sub type. e.g: LSP2Name + key: string; // The keccak256 hash of the name. This is the actual key that MUST be retrievable via ERC725Y.getData(bytes32 key) + keyType: ERC725JSONSchemaKeyType | string; // Types that determine how the values should be interpreted. + valueContent: ERC725JSONSchemaValueContent | string; // string holds '0x1345ABCD...' If the value content are specific bytes, than the returned value is expected to equal those bytes. + valueType: ERC725JSONSchemaValueType | string; // The type of the value. This is used to determine how the value should be encoded / decode (`string` for tuples and CompactBytesArray). +} + +interface DecodeDataOutput { + value: Data | Data[] | URLDataWithHash | null; + name: string; + key: string; +} + +type Data = string | number | boolean | null; + +interface URLDataWithHash extends URLData { + verification: Verification; // | string is to allow use of string directly without importing the enum + json?: never; +} + +interface URLData { + url: string; +} +``` + +
+ +#### Returns + +| Name | Type | Description | +| :--- | :------- | :---------- | +| | `object` | ... | + +#### Examples + +```javascript +import { getDataFromExternalSources } from '@erc725/erc725.js'; + +const schema = [ + { + name: 'LSP3Profile', + key: '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', + keyType: 'Singleton', + valueType: 'bytes', + valueContent: 'VerifiableURI', + }, +]; + +const dataFromChain = [ + { + name: 'LSP3Profile', + key: '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', + value: { + verification: { + data: '0xdb864ed42104cee179785036cb4ff1183ebc57e5532ae766ad8533fa48acfbb3', + method: 'keccak256(utf8)', + }, + url: 'ipfs://QmdMGUxuQsm1U9Qs8oJSn5PfY4B1apGG75YBRxQPybtRVm', + }, + }, +]; +const ipfsGateway = 'https://my-ipfs-gateway.com/ipfs/'; + +await getDataFromExternalSources(schema, dataFromChain, ipfsGateway); +/** +{ + name: 'LSP3Profile', + key: '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', + value: { + LSP3Profile: { + name: 'test', + description: '', + tags: ['profile'], + links: [], + profileImage: [ + { + width: 1024, + height: 709, + verification: { + method: 'keccak256(bytes)', + data: '0x6a0a28680d65b69f5696859be7e0fcebbbcf0df47f1f767926de35402c7d525c', + }, + url: 'ipfs://QmVUYyft3j2JVrG4RzDe1Qx7K5gNtJGFhrExHQFeiRXz1C', + }, + // more images... + ], + backgroundImage: [ + { + width: 1800, + height: 1012, + verification: { + method: 'keccak256(bytes)', + data: '0x3f6be73b35d348fb8f0b87a47d8c8b6b9db8858ee044cb13734cdfe5d28031d8', + }, + url: 'ipfs://QmfLCPmL31f31RRB4R7yoTg3Hsk5PjrWyS3ZaaYyhRPT4n', + }, + // more images... + ], + }, + }, + }, + ]); + }); + */ +``` + +--- + ### getVerificationMethod ```js diff --git a/src/types/ERC725JSONSchema.ts b/src/types/ERC725JSONSchema.ts index 1aa64f08..c2115c85 100644 --- a/src/types/ERC725JSONSchema.ts +++ b/src/types/ERC725JSONSchema.ts @@ -157,7 +157,7 @@ export function isValidValueType( * Detailed information available on [LSP-2-ERC725YJSONSchema](https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-2-ERC725YJSONSchema.md) */ export interface ERC725JSONSchema { - name: string; // Describes the name of the key, SHOULD compromise of the Standards name + sub type. e.g: LSP2Name + name: string; // Describes the name of the key, SHOULD be composed of the Standards name + sub type. e.g: LSP2Name key: string; // The keccak256 hash of the name. This is the actual key that MUST be retrievable via ERC725Y.getData(bytes32 key) keyType: ERC725JSONSchemaKeyType | string; // Types that determine how the values should be interpreted. valueContent: ERC725JSONSchemaValueContent | string; // string holds '0x1345ABCD...' If the value content are specific bytes, than the returned value is expected to equal those bytes. From 2a67f2673ed0495054c5a85665b4d318fd066a91 Mon Sep 17 00:00:00 2001 From: CJ42 Date: Wed, 29 May 2024 15:23:53 +0200 Subject: [PATCH 4/4] docs: add missing descriptions for parameters and return examples --- docs/methods.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/methods.md b/docs/methods.md index ffbf5b76..32cc3852 100644 --- a/docs/methods.md +++ b/docs/methods.md @@ -1160,11 +1160,11 @@ An array of extra [LSP-2 ERC725YJSONSchema] objects that can be used to find the #### Returns -| Name | Type | Description | -| :------- | :--------------- | :-------------------------------------------------------------------- | -| `result` | ERC725JSONSchema | If the parameter `keys` is a string and the schema was found. | -| `result` | Record string | If the parameter `keys` is a string[ ] and the schema was found. | -| `result` | null | If the schema was not found. | +| Name | Type | Description | +| :------- | :----------------- | :-------------------------------------------------------------------- | +| `result` | `ERC725JSONSchema` | If the parameter `keys` is a string and the schema was found. | +| `result` | `string[]` | If the parameter `keys` is a string[ ] and the schema was found. | +| `result` | `null` | If the schema was not found. | #### Example using a predefined LSP3 schema @@ -1998,14 +1998,14 @@ getDataFromExternalSources(schema, dataFromChain, ipfsGateway, [ ]); ``` -Retrieve the data(s) stored on IPFS using one (or multiple) IPFS CID(s) and link(s) under the `dataFromChain` parameter. +Retrieve the data stored on IPFS using one (or multiple) IPFS CID(s) and link(s) under the `dataFromChain` parameter. #### Parameters | Name | Type | Description | | :-------------------------- | :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | `schema` | `ERC725JSONSchema[]` | A list of JSON schemas for some given data keys. | -| `dataFromChain` | `DecodeDataOutput[]` | ... | +| `dataFromChain` | `DecodeDataOutput[]` | A list of data output previously fetched from the ERC725Y contract via [`getData(...)](#getdata) or [`fetchData`](#fetchdata) | | `ipfsGateway` | `string` | The URL to use to fetch data from the IPFS network. | | `throwException` (optional) | `boolean` | Define if the function should throw an error when fetching data. Set to `true` by default. This is useful for handling exceptions differently. | @@ -2037,15 +2037,19 @@ interface URLDataWithHash extends URLData { interface URLData { url: string; } + +interface GetDataExternalSourcesOutput extends DecodeDataOutput { + value: any; +} ``` #### Returns -| Name | Type | Description | -| :--- | :------- | :---------- | -| | `object` | ... | +| Name | Type | Description | +| :--- | :------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | +| | `GetDataExternalSourcesOutput[]` (see above) | An array of objects that contain the result of the data fetch inside the `.value` property. Can be anything from a `string` to a JSON object. | #### Examples @@ -2140,10 +2144,6 @@ 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 |