From e7bb62c248f2b5c61fff9bcbb6a0a76b7b5feb0f Mon Sep 17 00:00:00 2001 From: CJ42 Date: Sat, 4 May 2024 00:50:47 +0100 Subject: [PATCH 1/4] chore(wip): improve documentation structure of _erc725.js_ --- docs/examples.md | 21 +++++++ docs/overview.md | 151 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 172 insertions(+) create mode 100644 docs/examples.md create mode 100644 docs/overview.md 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/overview.md b/docs/overview.md new file mode 100644 index 00000000..2e74d2ab --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,151 @@ +# 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 +- hashData +- 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 +- getVerificationMethod +- hashData +- 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... From c90a7ae8b1bf19250fc49a942cee7123d9858a23 Mon Sep 17 00:00:00 2001 From: CJ42 Date: Mon, 6 May 2024 14:24:56 +0100 Subject: [PATCH 2/4] docs: improve section for getting started --- docs/getting-started.md | 128 ++++++++++++++++++++++------------------ 1 file changed, 70 insertions(+), 58 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 5b97cf89..e4a63d74 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,19 +5,17 @@ sidebar_position: 1 # Getting Started :::caution -This package is currently in the early stages of development. Please use it for testing or experimentation purposes only. +This package is currently in the early stages of development. Feel free to [report issues or feature requests](https://github.com/ERC725Alliance/erc725.js/issues) through the Github repository. ::: -The `@erc725/erc725.js` package allows you to interact with the ERC-725 schemas easily. +github badge +npm badge -- GitHub repo: https://github.com/ERC725Alliance/erc725.js -- NPM: https://www.npmjs.com/package/@erc725/erc725.js +

-## Installation +The `@erc725/erc725.js` package allows you to retrieve, encode and decode data easily from any ERC725Y smart contracts using ERC725Y JSON Schemas. -```bash -npm install @erc725/erc725.js -``` +## Installation :::info @@ -25,36 +23,24 @@ If you install it on the backend side, you may need to also install [`isomorphic ::: -## Instantiation - -You need to initialise the ERC725 object with a [schema](https://docs.lukso.tech/tools/erc725js/schemas), a contract address, and an RPC URL. - -```js -const address = '0x0Dc07C77985fE31996Ed612F568eb441afe5768D'; -const RPC_URL = 'https://rpc.testnet.lukso.network'; -const config = { - ipfsGateway: 'https://YOUR-IPFS-GATEWAY/ipfs/', - gas: 20_000_000, // optional, default is 1_000_000 -}; +```bash +npm install @erc725/erc725.js ``` -### TypeScript +## Usage > If you are using ES6 `import` statements in Node.js, make sure your file has a `.mjs` extension, or that your project is set up to support ES6 modules. -```ts -import { ERC725, ERC725JSONSchema } from '@erc725/erc725.js'; +There are 3 main ways to use _erc725.js_. + +### Option 1: using with schema only + +Create an instance of `ERC725` with just a [schema](https://docs.lukso.tech/tools/erc725js/schemas): **useful for just encoding / decoding data.** + +```js +import ERC725, { ERC725JSONSchema } from '@erc725/erc725.js'; -// Part of LSP3-UniversalProfile Schema -// https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-3-UniversalProfile.md const schemas: ERC725JSONSchema[] = [ - { - name: 'SupportedStandards:LSP3Profile', - key: '0xeafec4d89fa9619884b600005ef83ad9559033e6e941db7d7c495acdce616347', - keyType: 'Mapping', - valueType: 'bytes', - valueContent: '0x5ef83ad9', - }, { name: 'LSP3Profile', key: '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5', @@ -62,26 +48,21 @@ const schemas: ERC725JSONSchema[] = [ valueType: 'bytes', valueContent: 'VerifiableURI', }, - { - name: 'LSP1UniversalReceiverDelegate', - key: '0x0cfc51aec37c55a4d0b1a65c6255c4bf2fbdf6277f3cc0730c45b828b6db8b47', - keyType: 'Singleton', - valueType: 'address', - valueContent: 'Address', - }, ]; -const erc725 = new ERC725(schemas, address, RPC_URL, config); +const erc725 = new ERC725(schemas); ``` -### JavaScript +### Option 2: connect a contract to fetch + decode data from + +Same as option 1 where you can pass an ERC725Y contract address, an RPC URL and some additional confits (IPFS gateway): **useful to fetch and decode data automatically from a contract deployed on a network**. ```js -import { ERC725 } require('@erc725/erc725.js'); +import ERC725, { ERC725JSONSchema } from '@erc725/erc725.js'; -// Part of LSP3-UniversalProfile Schema -// https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-3-UniversalProfile.md -const schemas = [ +// Part of LSP3-Profile-Metadata Schema +// https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-3-Profile-Metadata.md +const schemas: ERC725JSONSchema[] = [ { name: 'SupportedStandards:LSP3Profile', key: '0xeafec4d89fa9619884b600005ef83ad9559033e6e941db7d7c495acdce616347', @@ -104,11 +85,54 @@ const schemas = [ valueContent: 'Address', }, ]; +const address = '0x0Dc07C77985fE31996Ed612F568eb441afe5768D'; +const RPC_URL = 'https://rpc.testnet.lukso.network'; +const config = { + ipfsGateway: 'https://YOUR-IPFS-GATEWAY/ipfs/', + gas: 20_000_000, // optional, default is 1_000_000 +}; const erc725 = new ERC725(schemas, address, RPC_URL, config); ``` -## Usage +### Option 3: use only specific functions + +You can import only specific functions (or using static methods of the `ERC725` class): **useful when needing only specific functionalities for your dApp (_e.g:_ decoding `VerifiableURI`, encoding dynamic keys).** + +```js +import { + encodeValueType, + encodeDataSourceWithHash, + decodeDataSourceWithHash, +} from '@erc725/erc725.js'; + +const someNumber = encodeValueType('uint128', 3); +// 0x00000000000000000000000000000003 + +const reEncodedVerifiableURI = decodeDataSourceWithHash( + '0x00006f357c6a0020820464ddfac1bec070cc14a8daf04129871d458f2ca94368aae8391311af6361696670733a2f2f516d597231564a4c776572673670456f73636468564775676f3339706136727963455a4c6a7452504466573834554178', +); +// verification: { +// data: '820464ddfac1bec070cc14a8daf04129871d458f2ca94368aae8391311af6361', +// method: 'keccak256(utf8)', +// source: 'ifps://QmYr1VJLwerg6pEoscdhVGugo39pa6rycEZLjtRPDfW84UAx' +// }, + +const verifiableURI = encodeDataSourceWithHash( + { + method: 'keccak256(utf8)', + data: '820464ddfac1bec070cc14a8daf04129871d458f2ca94368aae8391311af6361', + }, + 'ifps://QmYr1VJLwerg6pEoscdhVGugo39pa6rycEZLjtRPDfW84UAx', +); +// 0x00006f357c6a0020820464ddfac1bec070cc14a8daf04129871d458f2ca94368aae8391311af6361696670733a2f2f516d597231564a4c776572673670456f73636468564775676f3339706136727963455a4c6a7452504466573834554178 +``` + +## Functionalities + +:::tip Try it out +Try running the code snippets below within your browser using [StackBlitz](https://stackblitz.com/edit/erc725js-instantiation?devtoolsheight=66&file=index.js). +::: ```js await erc725.getOwner(); @@ -153,19 +177,7 @@ await erc725.fetchData('LSP3Profile'); // downloads and verifies the linked JSON */ ``` -:::tip Try it out -You can run the code snippet within your browser using the corresponding [StackBlitz example](https://stackblitz.com/edit/erc725js-instantiation?devtoolsheight=66&file=index.js). - -:::note -Whenever you can you should import `ERC725` via the named export. However currently we are also providing a default export. - -```javascript -import ERC725 from 'erc725.js'; -``` - -::: - -After the instance has been created, it is still possible to change settings through the options property. +After the `ERC725` instance has been created, it is still possible to change settings through the `options` property. ```javascript myERC725.options.schema = '' // change schema From 00a3ec82aefce7511838ac0b581430b35b9b10a2 Mon Sep 17 00:00:00 2001 From: CJ42 Date: Mon, 6 May 2024 14:36:09 +0100 Subject: [PATCH 3/4] docs: simplify README --- README.md | 34 +++++++---- docs/examples.md | 21 ------- docs/overview.md | 151 ----------------------------------------------- 3 files changed, 21 insertions(+), 185 deletions(-) delete mode 100644 docs/examples.md delete mode 100644 docs/overview.md diff --git a/README.md b/README.md index f4f7c7e6..a21dbf00 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

@erc725/erc725.js

-

Allows for interacting with ERC725Y compliant contracts on an EVM blockchain.

+

Allows for to read, encode and decode data from ERC725Y compliant contracts using ERC725Y JSON schemas.

@@ -27,6 +27,8 @@ ## Installation +> If you install it on the backend side, you may need to also install [`isomorphic-fetch`](https://www.npmjs.com/package/isomorphic-fetch). + ```shell script npm install @erc725/erc725.js ``` @@ -37,11 +39,11 @@ import { ERC725 } from '@erc725/erc725.js'; import ERC725 from '@erc725/erc725.js'; ``` -If you install it on the backend side, you may need to also install [`isomorphic-fetch`](https://www.npmjs.com/package/isomorphic-fetch). - ## Instantiation -You need to initialise the ERC725 object with a [schema](https://docs.lukso.tech/tools/erc725js/schemas), a contract address, and an RPC URL. +> If you are using ES6 `import` statements in Node.js, make sure your file has a `.mjs` extension, or that your project is set up to support ES6 modules. + +You can initialize the ERC725 object with a [schema](https://docs.lukso.tech/tools/erc725js/schemas), a contract address, and an RPC URL. ```js const address = '0x0Dc07C77985fE31996Ed612F568eb441afe5768D'; @@ -52,15 +54,14 @@ const config = { }; ``` -### TypeScript - -> If you are using ES6 `import` statements in Node.js, make sure your file has a `.mjs` extension, or that your project is set up to support ES6 modules. +

+ TypeScript ```ts import { ERC725, ERC725JSONSchema } from '@erc725/erc725.js'; -// Part of LSP3-UniversalProfile Schema -// https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-3-UniversalProfile.md +// Part of LSP3-Profile-Metadata Schema +// https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-3-Profile-Metadata.md const schemas: ERC725JSONSchema[] = [ { name: 'SupportedStandards:LSP3Profile', @@ -88,13 +89,16 @@ const schemas: ERC725JSONSchema[] = [ const erc725 = new ERC725(schemas, address, RPC_URL, config); ``` -### JavaScript +
+ +
+ Javascript ```js -import { ERC725 } require('@erc725/erc725.js'); +const { ERC725 } = require('@erc725/erc725.js'); -// Part of LSP3-UniversalProfile Schema -// https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-3-UniversalProfile.md +// Part of LSP3-Profile-Metadata Schema +// https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-3-Profile-Metadata.md const schemas = [ { name: 'SupportedStandards:LSP3Profile', @@ -122,8 +126,12 @@ const schemas = [ const erc725 = new ERC725(schemas, address, RPC_URL, config); ``` +
+ ## Usage +> See the **Getting Started** pages for more examples on how to use )_erc725.js_ + ```js await myErc725.getOwner(); // > '0x28D25E70819140daF65b724158D00c373D1a18ee' diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index 2ad7e894..00000000 --- a/docs/examples.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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/overview.md b/docs/overview.md deleted file mode 100644 index 2e74d2ab..00000000 --- a/docs/overview.md +++ /dev/null @@ -1,151 +0,0 @@ -# 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 -- hashData -- 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 -- getVerificationMethod -- hashData -- 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... From f14be19a09299acb19381235011ad316ee0ceecd Mon Sep 17 00:00:00 2001 From: CJ42 Date: Tue, 7 May 2024 11:53:27 +0100 Subject: [PATCH 4/4] docs: address review comments for grammar and typos --- README.md | 4 ++-- docs/getting-started.md | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a21dbf00..ce22f125 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

@erc725/erc725.js

-

Allows for to read, encode and decode data from ERC725Y compliant contracts using ERC725Y JSON schemas.

+

Allows to read, encode and decode data from ERC725Y compliant contracts using ERC725Y JSON schemas.

@@ -130,7 +130,7 @@ const erc725 = new ERC725(schemas, address, RPC_URL, config); ## Usage -> See the **Getting Started** pages for more examples on how to use )_erc725.js_ +> See the **Getting Started** pages for more examples on how to use _erc725.js_ ```js await myErc725.getOwner(); diff --git a/docs/getting-started.md b/docs/getting-started.md index e4a63d74..d2527739 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -33,9 +33,9 @@ npm install @erc725/erc725.js There are 3 main ways to use _erc725.js_. -### Option 1: using with schema only +### Option 1: use a schema for encoding / decoding data -Create an instance of `ERC725` with just a [schema](https://docs.lukso.tech/tools/erc725js/schemas): **useful for just encoding / decoding data.** +Create an instance of `ERC725` with just a [schema](https://docs.lukso.tech/tools/erc725js/schemas). **Useful for just encoding / decoding data.** ```js import ERC725, { ERC725JSONSchema } from '@erc725/erc725.js'; @@ -53,9 +53,9 @@ const schemas: ERC725JSONSchema[] = [ const erc725 = new ERC725(schemas); ``` -### Option 2: connect a contract to fetch + decode data from +### Option 2: connect to a smart contract to fetch/decode data -Same as option 1 where you can pass an ERC725Y contract address, an RPC URL and some additional confits (IPFS gateway): **useful to fetch and decode data automatically from a contract deployed on a network**. +Same as option 1 where you can pass an ERC725Y contract address, an RPC URL and some additional configurations (e.g: IPFS gateway). **Useful to fetch and decode data automatically from a contract deployed on a network**. ```js import ERC725, { ERC725JSONSchema } from '@erc725/erc725.js'; @@ -95,9 +95,9 @@ const config = { const erc725 = new ERC725(schemas, address, RPC_URL, config); ``` -### Option 3: use only specific functions +### Option 3: use specific functions or static methods -You can import only specific functions (or using static methods of the `ERC725` class): **useful when needing only specific functionalities for your dApp (_e.g:_ decoding `VerifiableURI`, encoding dynamic keys).** +You can import specific functions or use static methods from the `ERC725` class. **Useful to add only specific functionalities to your dApp (_e.g:_ decoding `VerifiableURI`, encoding dynamic keys).** ```js import {