Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: simplify README, fix incorrect LSP3 reference and improve Getting Started section #431

Merged
merged 4 commits into from
May 7, 2024
Merged

docs: simplify README, fix incorrect LSP3 reference and improve Getting Started section #431

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e7bb62c
chore(wip): improve documentation structure of _erc725.js_
CJ42 May 3, 2024
c90a7ae
docs: improve section for getting started
CJ42 May 6, 2024
00a3ec8
docs: simplify README
CJ42 May 6, 2024
f14be19
docs: address review comments for grammar and typos
CJ42 May 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 21 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<p align="center">
<h1 align="center"><strong>@erc725/erc725.js</strong></h1>
<p align="center">Allows for interacting with <a href="https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-2-ERC725YJSONSchema.md">ERC725Y</a> compliant contracts on an EVM blockchain.</p>
<p align="center">Allows to read, encode and decode data from <a href="https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-2-ERC725YJSONSchema.md">ERC725Y</a> compliant contracts using ERC725Y JSON schemas.</p>
</p>

<p align="center">
Expand All @@ -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
```
Expand All @@ -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';
Expand All @@ -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.
<details>
<summary>TypeScript</summary>

```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',
Expand Down Expand Up @@ -88,13 +89,16 @@ const schemas: ERC725JSONSchema[] = [
const erc725 = new ERC725(schemas, address, RPC_URL, config);
```

### JavaScript
</details>

<details>
<summary>Javascript</summary>

```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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FMI: What s the difference btw LSP3Profile and SupportedStandards:LSP3Profile as a schema?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LSP3Profile = contains the VerifiableURI that links to the JSON file. It is the actual profile metadata

SupportedStandards:LSP3Profile = it is just a data key to confirm that this contract supports the LSP3 Metadata standard, and contain a certain set of keys (only LSP3Profile in this case).

const schemas = [
{
name: 'SupportedStandards:LSP3Profile',
Expand Down Expand Up @@ -122,8 +126,12 @@ const schemas = [
const erc725 = new ERC725(schemas, address, RPC_URL, config);
```

</details>

## Usage

> See the **Getting Started** pages for more examples on how to use _erc725.js_

```js
await myErc725.getOwner();
// > '0x28D25E70819140daF65b724158D00c373D1a18ee'
Expand Down
128 changes: 70 additions & 58 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,83 +5,64 @@ 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.
<a href="https://github.com/ERC725Alliance/erc725.js" target="_blank" rel="noopener noreferrer"><img style={{verticalAlign: 'middle'}} alt="github badge" src="https://img.shields.io/github/v/release/ERC725Alliance/erc725.js?logo=github&label=Github"/></a>
<a href="https://www.npmjs.com/package/@erc725/erc725.js" target="_blank" rel="noopener noreferrer"><img style={{verticalAlign: 'middle'}} alt="npm badge" src="https://img.shields.io/npm/v/@erc725/erc725.js.svg?style=flat&label=NPM&logo=npm"/></a>

- GitHub repo: https://github.com/ERC725Alliance/erc725.js
- NPM: https://www.npmjs.com/package/@erc725/erc725.js
<br/><br/>

## 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

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.

```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: 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.**

```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',
keyType: 'Singleton',
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 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 configurations (e.g: 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',
Expand All @@ -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 specific functions or static methods

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 {
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();
Expand Down Expand Up @@ -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 = '<schema>' // change schema
Expand Down
Loading