Skip to content

Commit

Permalink
docs: improve docs (#150)
Browse files Browse the repository at this point in the history 
* improved example titles encodeData

* docs: improve docs

Co-authored-by: Fabian Vogelsteller <[email protected]>
  • Loading branch information
@Hugoo @frozeman
Hugoo and frozeman authored May 19, 2022
1 parent 7101412 commit 4e14921
Showing 1 changed file with 66 additions and 120 deletions.
186 changes: 66 additions & 120 deletions docs/classes/ERC725.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ const decodedDataManyKeys = erc725.decodeData({
ERC725.decodePermissions(permission);
```

The function decodes permissions from hexadecimal defined by the [LSP6 KeyManager Standard](https://docs.lukso.tech/standards/universal-profile/lsp6-key-manager).
Decodes permissions from hexadecimal defined by the [LSP6 KeyManager Standard](https://docs.lukso.tech/standards/universal-profile/lsp6-key-manager).

:::info

Expand All @@ -109,9 +109,9 @@ The function decodes permissions from hexadecimal defined by the [LSP6 KeyManage

#### Returns

| Name | Type | Description |
| :------------------ | :----- | :------------------------------------------------------------------------------------------------- |
| `decodedPermission` | Object | An object specifying whether default LSP6 permissions are included in provided hexademical string. |
| Name | Type | Description |
| :------------------- | :----- | :------------------------------------------------------------------------------------------------- |
| `decodedPermissions` | Object | An object specifying whether default LSP6 permissions are included in provided hexademical string. |

#### Example

Expand All @@ -132,22 +132,6 @@ ERC725.decodePermissions('0x0000000000000000000000000000000000000000000000000000
}
*/

myERC725.decodePermissions('0x0000000000000000000000000000000000000000000000000000000000000110'),
/**
{
CHANGEOWNER: false,
CHANGEPERMISSIONS: false,
ADDPERMISSIONS: false,
SETDATA: false,
CALL: true,
STATICCALL: false,
DELEGATECALL: false,
DEPLOY: false,
TRANSFERVALUE: true,
SIGN: false,
}
*/

ERC725.decodePermissions('0x000000000000000000000000000000000000000000000000000000000000000a'),
/**
{
Expand All @@ -164,21 +148,8 @@ ERC725.decodePermissions('0x0000000000000000000000000000000000000000000000000000
}
*/

myERC725.decodePermissions('0x000000000000000000000000000000000000000000000000000000000000000a'),
/**
{
CHANGEOWNER: false,
CHANGEPERMISSIONS: true,
ADDPERMISSIONS: false,
SETDATA: true,
CALL: false,
STATICCALL: false,
DELEGATECALL: false,
DEPLOY: false,
TRANSFERVALUE: false,
SIGN: false,
}
*/
// This method is also available on the instance:
myErc725.decodePermissions('0x0000000000000000000000000000000000000000000000000000000000000110'),
```

---
Expand All @@ -189,10 +160,12 @@ myERC725.decodePermissions('0x00000000000000000000000000000000000000000000000000
erc725.encodeData(data);
```

The function `encodeData` helps you to encode the data of a smart contract according to your `ERC725JSONSchema` so that you can store the information in smart contracts.
Encode the data of a smart contract according to your `ERC725JSONSchema` so that you can store the information in smart contracts.

:::tip

When encoding JSON, it is possible to pass in the JSON object and the URL where it is available publicly. The JSON will be hashed with `keccak256`.

:::

#### Parameters
Expand All @@ -211,9 +184,9 @@ The key can be either the named key (i.e. `LSP3Profile`) or the hashed key (with

After the `data` is encoded, the object is ready to be stored in smart contracts.

#### Single-Key Example 1
#### Examples

```javascript title="Encoding the object with one key"
```javascript title="Encode a JSONURL with json and uploaded URL"
const encodedDataOneKey = erc725.encodeData({
LSP3Profile: {
json: profileJson,
Expand Down Expand Up @@ -256,9 +229,7 @@ erc725.encodeData({
*/
```

#### Single-Key Example 2

```javascript title="Encoding the object with one key"
```javascript title="Encode a JSONURL with json, hash function, hash and uploaded URL"
const encodedDataOneKeyV2 = erc725.encodeData({
LSP3Profile: {
hashFunction: 'keccak256(utf8)',
Expand All @@ -274,9 +245,7 @@ const encodedDataOneKeyV2 = erc725.encodeData({
*/
```

#### Multi-Key Example

```javascript title="Encoding the object with multiple keys"
```javascript title="Encode multiple keys at once"
const encodedDataManyKeys = erc725.encodeData({
LSP3Profile: {
hashFunction: 'keccak256(utf8)',
Expand Down Expand Up @@ -317,7 +286,7 @@ const encodedDataManyKeys = erc725.encodeData({
ERC725.encodeKeyName(keyName);
```

The function hashes a key name for use on an [ERC725Y contract](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-725.md#erc725y) according to the [LSP2 ERC725Y JSON Schema Standard](https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md).
Hashes a key name for use on an [ERC725Y contract](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-725.md#erc725y) according to the [LSP2 ERC725Y JSON Schema Standard](https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-2-ERC725YJSONSchema.md).

:::info

Expand Down Expand Up @@ -351,14 +320,8 @@ ERC725.encodeKeyName(
);
// '0x4b80742d0000000082ac0000cafecafecafecafecafecafecafecafecafecafe'

myERC725.encodeKeyName('LSP3Profile');
// '0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5'
myERC725.encodeKeyName('SupportedStandards:ERC725Account');
// '0xeafec4d89fa9619884b6b89135626455000000000000000000000000afdeb5d6'
myERC725.encodeKeyName(
'AddressPermissions:Permissions:cafecafecafecafecafecafecafecafecafecafe',
);
// '0x4b80742d0000000082ac0000cafecafecafecafecafecafecafecafecafecafe'
// This method is also available on the instance:
myErc725.encodeKeyName('LSP3Profile');
```

---
Expand All @@ -369,7 +332,7 @@ myERC725.encodeKeyName(
ERC725.encodePermissions(permissions);
```

The function encodes permissions into a hexadecimal string as defined by the [LSP6 KeyManager Standard](https://docs.lukso.tech/standards/universal-profile/lsp6-key-manager).
Encodes permissions into a hexadecimal string as defined by the [LSP6 KeyManager Standard](https://docs.lukso.tech/standards/universal-profile/lsp6-key-manager).

:::info

Expand All @@ -379,9 +342,9 @@ The function encodes permissions into a hexadecimal string as defined by the [LS

#### Parameters

| Name | Type | Description |
| :------------ | :----- | :---------------------------------------------------------------------------- |
| `permissions` | Object | An object with [LSP6 KeyManager Permissions] as keys and a `boolean` as value |
| Name | Type | Description |
| :------------ | :----- | :----------------------------------------------------------------------------- |
| `permissions` | Object | An object with [LSP6 KeyManager Permissions] as keys and a `boolean` as value. |

Any ommited permissions will default to `false`.

Expand All @@ -408,41 +371,27 @@ ERC725.encodePermissions({
}),
// '0x0000000000000000000000000000000000000000000000000000000000000110'


myERC725.encodePermissions({
CHANGEOWNER: false,
CHANGEPERMISSIONS: false,
ADDPERMISSIONS: false,
SETDATA: false,
CALL: true,
STATICCALL: false,
DELEGATECALL: false,
DEPLOY: false,
TRANSFERVALUE: true,
SIGN: false,
}),
// '0x0000000000000000000000000000000000000000000000000000000000000110'

// Any ommited Permissions will default to false
ERC725.encodePermissions({
CHANGEPERMISSIONS: true,
SETDATA: true,
}),
// '0x000000000000000000000000000000000000000000000000000000000000000a'

myERC725.encodePermissions({

// This method is also available on the instance:
myErc725.encodePermissions({
CHANGEPERMISSIONS: true,
SETDATA: true,
}),
// '0x000000000000000000000000000000000000000000000000000000000000000a'
```

---

## fetchData

```js
erc725.fetchData(keyOrKeys?);
erc725.fetchData([keys]);
```

The `fetchData` function fetches smart contract data and can additionally return [`JSONURL`](https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-2-ERC725YJSONSchema.md#jsonurl) or [`ASSETURL`](https://github.com/lukso-network/LIPs/blob/master/LSPs/LSP-2-ERC725YJSONSchema.md#asseturl) data from IPFS, HTTP, or HTTPS endpoints.
Expand All @@ -455,19 +404,17 @@ To ensure **data authenticity** `fetchData` compares the `hash` of the fetched J

#### Parameters

| Name | Type | Description |
| :----------- | :----------------------------- | :--------------------------------------------------------------------------------------------------- |
| `keyOrKeys?` | string or <br/> string[&nbsp;] | The name(s) (or the encoded name(s) as schema key) of the element(s) in the smart contract's schema. |
If no key (or keys) are set, the function will fetch all the schema keys given at instantiation.
| Name | Type | Description |
| :---------------- | :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keys` (optional) | string or <br/> string[&nbsp;] | The name(s) (or the encoded name(s) as schema key) of the element(s) in the smart contract's schema. If no keys are set, it will fetch all the schema keys given at instantiation. |

#### Returns

| Name | Type | Description |
| :-------- | :----------- | :--------------------------------------------------------------- |
| `Promise` | &ltObject&gt | An object depending on the `valueContent` of the schema element. |
| Name | Type | Description |
| :-------- | :----- | :--------------------------------------------------------------- |
| `Promise` | Object | An object depending on the `valueContent` of the schema element. |

Besides the `valueContent`, the function works like the [`getData()`](#getdata) function.
Besides the `valueContent`, it works like the [`getData()`](#getdata) function.

:::info

Expand Down Expand Up @@ -559,11 +506,11 @@ const dataManyKeys = await erc725.fetchData([
## getData

```js
erc725.getData(keyOrKeys?);
erc725.getData([keys]);
```

The function gets **decoded data** for one, many, or all of the specified `ERC725` smart contract's keys.
When omitting the `key`or `keys[]` parameter, the function will give back every key (as per `ERC725JSONSchema` definition).
Gets **decoded data** for one, many, or all of the specified `ERC725` smart contract's keys.
When omitting the `keys` parameter, it will give back every key (as per `ERC725JSONSchema` definition).

:::caution

Expand All @@ -575,17 +522,15 @@ When omitting the `key`or `keys[]` parameter, the function will give back every

#### Parameters

| Name | Type | Description |
| :----------- | :----------------------------- | :--------------------------------------------------------------------------------------------------- |
| `keyOrKeys?` | string or <br/> string[&nbsp;] | The name(s) (or the encoded name(s) as schema key) of the element(s) in the smart contract's schema. |
If no keys are set, the function will fetch all the keys of the schema given at instantiation.
| Name | Type | Description |
| :---------------- | :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keys` (optional) | string or <br/> string[&nbsp;] | The name(s) (or the encoded name(s) as schema key) of the element(s) in the smart contract's schema. If no keys are set, it will fetch all the keys of the schema given at instantiation. |

#### Returns

| Name | Type | Description |
| :-------- | :----------- | :------------------------------------------------------------------------------------------------ |
| `Promise` | &ltObject&gt | With the schema element key names as properties and the corresponding **decoded** data as values. |
| Name | Type | Description |
| :-------- | :----- | :------------------------------------------------------------------------------------------------ |
| `Promise` | Object | With the schema element key names as properties and the corresponding **decoded** data as values. |

:::info

Expand Down Expand Up @@ -662,24 +607,24 @@ const dataManyKeys = await erc725.getData([
## getOwner

```js
erc725.getOwner(address);
erc725.getOwner([address]);
```

The function is an added utility method that returns the contract owner and is not directly related to ERC725 specifications.
Returns the contract owner and is not directly related to ERC725 specifications.

#### Parameters

| Name | Type | Description |
| :--------- | :----- | :---------------------------------------- |
| `address?` | string | The contract or EOA address of the owner. |
| Name | Type | Description |
| :------------------- | :----- | :---------------------------------------- |
| `address` (optional) | string | The contract or EOA address of the owner. |

If no address is set, the function will return the owner of the contract used to initialise the ERC725() class.
If no address is set, will return the owner of the contract used to initialise the ERC725 class.

#### Returns

| Name | Type | Description |
| :-------- | :---------- | :---------------------------------------- |
| `Promise` | &lt;any&gt; | The contract or EOA address of the owner. |
| Name | Type | Description |
| :-------- | :----- | :---------------------------------------- |
| `Promise` | string | The contract or EOA address of the owner. |

:::info

Expand All @@ -693,7 +638,8 @@ The address of the contract owner as stored in the contract.
// If no address is set, it will return the owner of the contract used to initialise the ERC725() class.
await erc725.getOwner();
// '0x94933413384997F9402cc07a650e8A34d60F437A'
// You can also get the owner of a specific contract by setting the address paramater

// You can also get the owner of a specific contract by setting the address parameter
await erc725.getOwner('0x3000783905Cc7170cCCe49a4112Deda952DDBe24');
// '0x7f1b797b2Ba023Da2482654b50724e92EB5a7091'
```
Expand All @@ -703,29 +649,29 @@ await erc725.getOwner('0x3000783905Cc7170cCCe49a4112Deda952DDBe24');
## getSchema

```js
erc725.getSchema(keyOrKeys?, providedSchemas);
erc725.getSchema(keys [, providedSchemas]);
```

The function 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:
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/erc725.js/tree/main/schemas) folder (which includes all [LSPs](https://github.com/lukso-network/LIPs/tree/main/LSPs)),
- that were provided at ERC725 initialisation, and
- that were provided in the function call (`providedSchemas`).

#### Parameters

| Name | Type | Description |
| :---------------- | :----------------------------- | :--------------------------------------------------------------------------------------- |
| `keyOrKeys?` | string or <br/> string[&nbsp;] | The key(s) you are trying to get the schema for. |
| `providedSchemas` | ERC725JSONSchema[&nbsp;] | An array of extra [LSP-2 ERC725YJSONSchema] objects that can be used to find the schema. |
| Name | Type | Description |
| :--------------------------- | :----------------------------- | :--------------------------------------------------------------------------------------- |
| `keys` | string or <br/> string[&nbsp;] | The key(s) you are trying to get the schema for. |
| `providedSchemas` (optional) | ERC725JSONSchema[&nbsp;] | An array of extra [LSP-2 ERC725YJSONSchema] objects that can be used to find the schema. |

#### Returns

| Name | Type | Description |
| :------- | :------------------ | :------------------------------------------------------------------------------------------- |
| `result` | ERC725JSONSchema | If the function has the parameter `keyOrKeys?` is a string and the schema was found. |
| `result` | Record &ltstring&gt | If the function has the parameter `keyOrKeys?` is a string[&nbsp;] 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` | Record string | If the parameter `keys` is a string[&nbsp;] and the schema was found. |
| `result` | null | If the schema was not found. |

#### Example using a predefined LSP3 schema

Expand Down Expand Up @@ -800,7 +746,7 @@ erc725.getSchema(
erc725.isValidSignature(messageOrHash, signature);
```

The function checks if a signature was signed by the `owner` of the ERC725 Account contract, according to [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271). If the `owner` is a contract itself, it will delegate the `isValidsignature()` call to the owner contract if it supports [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271). Otherwise, the function will fail.
Checks if a signature was signed by the `owner` of the ERC725 Account contract, according to [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271). If the `owner` is a contract itself, it will delegate the `isValidsignature()` call to the owner contract if it supports [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271). Otherwise, it will fail.

#### Parameters

Expand All @@ -819,9 +765,9 @@ The function checks if a signature was signed by the `owner` of the ERC725 Accou

#### Returns

| Name | Type | Description |
| :-------- | :------------ | :------------------------------------------------------------- |
| `Promise` | &ltboolean&gt | `true` if signature is valid, `false` if signature is invalid. |
| Name | Type | Description |
| :-------- | :------ | :------------------------------------------------------------- |
| `Promise` | boolean | `true` if signature is valid, `false` if signature is invalid. |

:::info

Expand Down

0 comments on commit 4e14921

Please sign in to comment.