From e7bb62c248f2b5c61fff9bcbb6a0a76b7b5feb0f Mon Sep 17 00:00:00 2001
From: CJ42
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.
-## 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 = '@erc725/erc725.js
-
@@ -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.
+
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.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);
```
+@erc725/erc725.js
-
@@ -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 {