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

WIP: V1.0.0 docs #1178

Closed
wants to merge 1 commit into from
Closed

WIP: V1.0.0 docs #1178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
23 changes: 16 additions & 7 deletions docs/docs/developer/allowlists.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ import {
} from "@hypercerts-org/sdk";

const allowlist: Allowlist = [
{ address: "0x123", units: 100 },
{ address: "0xabc", units: 100 },
{ address: "0x123", units: 100n },
{ address: "0xabc", units: 100n },
];
```

Expand Down Expand Up @@ -50,11 +50,11 @@ Finally, the method invokes the `createAllowlist` function on the contract with

Users can claim their fraction tokens for many hypercerts at once using `mintClaimFractionFromAllowlist`. To determine the input the following information is required:

| Variable | Type | Source |
| -------- | ------------ | ------------ |
| claimId | BigNumberish | Hypercert ID |
| units | BigNumberish | Allowlist |
| proof | BytesLike[] | Merkle tree |
| Variable | Type | Source |
| -------- | ----------- | ------------ |
| claimId | bigint | Hypercert ID |
| units | bigint | Allowlist |
| proof | BytesLike[] | Merkle tree |

We store the allowlist and the Merkle tree in the metadata of the Hypercert. To understand the Merkle tree data structures, check out the [OpenZeppelin merkle tree library](https://github.com/OpenZeppelin/merkle-tree). You can get the `proof` and `units` by traversing the merkle tree.

Expand All @@ -66,10 +66,19 @@ import { StandardMerkleTree } from "@openzeppelin/merkle-tree";
const claimId = "0x822f17a9a5eecfd...85254363386255337";
const address = "0xc0ffee254729296a45a3885639AC7E10F9d54979";

// Get modules from client
const { indexer, storage } = hypercertsClient;

// Get claim by ID from indexer
const claimById = await indexer.claimById(claimId);

// Get metadata and token ID from claim
const { uri, tokenID: _id } = claimById.claim;

// Get metadata and tree from storage
const metadata = await storage.getMetadata(uri || "");

// Load tree from metadata
const treeResponse = await storage.getData(metadata.allowList);
const tree = StandardMerkleTree.load(JSON.parse(treeResponse));

Expand Down
94 changes: 25 additions & 69 deletions docs/docs/developer/api/sdk/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Hypercerts SDK Documentation / [Exports](modules.md)

## Quickstart Guide

1. Install the SDK using npm or yarn:
1. Install the SDK using npm, yarn or pnpm:

```bash
npm install @hypercerts-org/sdk
Expand All @@ -26,15 +26,13 @@ import { HypercertClient } from "@hypercerts-org/sdk";

```js
const client = new HypercertClient({
chainId: 5,
provider,
signer,
chain: { id: 5 } // required
nftStorageToken,
web3StorageToken,
});
```

> **Note** If there's no `signer`, `provider`, `nftStorageToken` or `web3StorageToken` provided, the client will run in
> **Note** If there's no `walletClient`, `nftStorageToken` or `web3StorageToken` provided, the client will run in
> [read-only mode](#read-only-mode)

4. Use the client object to interact with the Hypercert network.
Expand Down Expand Up @@ -67,78 +65,36 @@ environment variables for your NFT.storage and web3.storage API keys in your .en

## Config

The SDK will try to determine the `DEFAULT_CHAIN_ID` and use that to inform the configuration. We allow for `overrides`
when creating the SDK by passing configuration variables. Finally, when not defaults or overrides are found, we check
the environment variables.
HypercertClientConfig is a configuration object used when initializing a new instance of the HypercertClient. It allows
you to customize the client by setting your own providers or deployments. At it's simplest, you only need to provide
`chain.id` to initalize the client in `readonly` mode.

| Field | Type | Description |
| --------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `chain` | Object | Partial configuration for the blockchain network. |
| `contractAddress` | String | The address of the deployed contract. |
| `graphUrl` | String | The URL to the subgraph that indexes the contract events. Override for localized testing. |
| `graphName` | String | The name of the subgraph. |
| `nftStorageToken` | String | The API token for NFT.storage. |
| `web3StorageToken` | String | The API token for Web3.storage. |
| `easContractAddress` | String | The address of the EAS contract. |
| `publicClient` | Object | The PublicClient is inherently read-only and is used for reading data from the blockchain. |
| `walletClient` | Object | The WalletClient is used for signing and sending transactions. |
| `unsafeForceOverrideConfig` | Boolean | Boolean to force the use of overridden values. |
| `readOnly` | Boolean | Boolean to assert if the client is in read-only mode. |
| `readOnlyReason` | String | Reason for read-only mode. This is optional and can be used for logging or debugging purposes. |

### Read-only mode

The SDK client will be in read-only mode if any of the following conditions are true:

- The client was initialized without a signer or provider.
- The client was initialized with a provider but not a signer.
- The client was initialized with a signer but not a provider.
- The client was initialized without a walletprovider.
- The contract address is not set.
- The storage layer is in read-only mode.

If any of these conditions are true, the readonly property of the HypercertClient instance will be set to true, and a
warning message will be logged indicating that the client is in read-only mode.

### Defaults

The constants.ts file defines various constants that are used throughout the Hypercert system. Here's a brief
explanation of each constant:

`DEFAULT_CHAIN_ID`: This constant defines the default chain ID to use if no chain ID is specified. In this case, the
default chain ID is set to 5, which corresponds to the Goerli testnet.

Based on `DEFAULT_CHAIN_ID` the SDK will select a `DEPLOYMENT`.

`DEPLOYMENTS`: This constant defines the deployments that are managed by the Hypercert system. Each Deployment object
contains information about a specific deployment, including the chain ID, chain name, contract address, and graph name.

For example:

```json
{
"5": {
"chainId": 5,
"chainName": "goerli",
"contractAddress": "0x822F17A9A5EeCFd66dBAFf7946a8071C265D1d07",
"graphName": "hypercerts-testnet"
}
}
```

### Client config properties

| \| Property | Type | Description |
| ------------------ | -------------------- | -------------------------------------- |
| `chainId` | `number` | The chain ID of the network to use. |
| `chainName` | `string` | The name of the network to use. |
| `contractAddress` | `string` | The address of the Hypercert contract. |
| `rpcUrl` | `string` | The URL of the RPC endpoint to use. |
| `graphName` | `string` | The name of the Gsubgraph to use. |
| `provider` | `providers.Provider` | A custom provider to use. |
| `signer` | `Signer` | A custom signer to use. |
| `nftStorageToken` | `string` | Your NFT.storage API key. |
| `web3StorageToken` | `string` | Your web3.storage API key. |

### Environment variables

To determine the missing configuration values the SDK defaults to the following environment variables:

| Environment Variable | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------------- |
| `DEFAULT_CHAIN_ID` | Specifies the default chain ID to use if no chain ID is specified. |
| `CONTRACT_ADDRESS` | Specifies the contract address to use for the Hypercert protocol. |
| `RPC_URL` | Specifies the RPC URL to use for the evm-compatible network. |
| `PRIVATE_KEY` | Specifies the private key to use for signing transactions. |
| `NFT_STORAGE_TOKEN` | Specifies the NFT.storage API token to use for storing Hypercert metadata. |
| `NEXT_PUBLIC_NFT_STORAGE_TOKEN` | Specifies the NFT.storage API token to use for storing Hypercert metadata in a Next.js application. |
| `WEB3_STORAGE_TOKEN` | Specifies the Web3.storage API token to use for storing Hypercert data. |
| `NEXT_PUBLIC_WEB3_STORAGE_TOKEN` | Specifies the Web3.storage API token to use for storing Hypercert data in a Next.js application. |

### Logging

The logger for the SDK uses the log level based on the value of the LOG_LEVEL environment variable. The log level
Expand All @@ -154,7 +110,7 @@ HypercertIndexer, and HypercertMinter classes, respectively.
```js
const {
client: { storage },
} = new HypercertClient({});
} = new HypercertClient({ chain: { id: 5 } });
```

The `storage` is a utility class that provides methods for storing and retrieving Hypercert metadata on IPFS and
Expand All @@ -163,7 +119,7 @@ NFT.storage. It is used by the HypercertClient to store metadata when creating n
```js
const {
client: { indexer },
} = new HypercertClient({});
} = new HypercertClient({ chain: { id: 5 } });
```

The `indexer` is a utility class that provides methods for indexing and searching Hypercerts based on various criteria.
Expand All @@ -172,7 +128,7 @@ It is used by the HypercertClient to retrieve event-based data via the subgraph
```js
const {
client: { contract },
} = new HypercertClient({});
} = new HypercertClient({ chain: { id: 5 } });
```

Finally we have a `contract` that provides methods for interacting with the HypercertMinter smart contract. It is used
Expand Down
10 changes: 7 additions & 3 deletions docs/docs/developer/api/sdk/classes/ClientError.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ An error that is caused by a problem with the client.

### constructor

• **new ClientError**(`message`, `payload?`)
• **new ClientError**(`message`, `payload?`): [`ClientError`](ClientError.md)

Creates a new instance of the ClientError class.

Expand All @@ -39,13 +39,17 @@ Creates a new instance of the ClientError class.
| `message` | `string` | The error message. |
| `payload?` | `Object` | Additional error payload. |

#### Returns

[`ClientError`](ClientError.md)

#### Overrides

Error.constructor

#### Defined in

[sdk/src/types/errors.ts:25](https://github.com/Network-Goods/hypercerts/blob/9677274/sdk/src/types/errors.ts#L25)
sdk/src/types/errors.ts:25

## Properties

Expand All @@ -65,4 +69,4 @@ Additional error payload.

#### Defined in

[sdk/src/types/errors.ts:18](https://github.com/Network-Goods/hypercerts/blob/9677274/sdk/src/types/errors.ts#L18)
sdk/src/types/errors.ts:18
10 changes: 7 additions & 3 deletions docs/docs/developer/api/sdk/classes/ConfigurationError.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The configuration was invalid

### constructor

• **new ConfigurationError**(`message`, `payload?`)
• **new ConfigurationError**(`message`, `payload?`): [`ConfigurationError`](ConfigurationError.md)

#### Parameters

Expand All @@ -37,13 +37,17 @@ The configuration was invalid
| `message` | `string` |
| `payload?` | `Object` |

#### Returns

[`ConfigurationError`](ConfigurationError.md)

#### Overrides

Error.constructor

#### Defined in

[sdk/src/types/errors.ts:166](https://github.com/Network-Goods/hypercerts/blob/9677274/sdk/src/types/errors.ts#L166)
sdk/src/types/errors.ts:166

## Properties

Expand All @@ -63,4 +67,4 @@ Additional error payload.

#### Defined in

[sdk/src/types/errors.ts:165](https://github.com/Network-Goods/hypercerts/blob/9677274/sdk/src/types/errors.ts#L165)
sdk/src/types/errors.ts:165
10 changes: 7 additions & 3 deletions docs/docs/developer/api/sdk/classes/FetchError.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Fails fetching a remote resource

### constructor

• **new FetchError**(`message`, `payload?`)
• **new FetchError**(`message`, `payload?`): [`FetchError`](FetchError.md)

Creates a new instance of the FetchError class.

Expand All @@ -39,13 +39,17 @@ Creates a new instance of the FetchError class.
| `message` | `string` | The error message. |
| `payload?` | `Object` | Additional error payload. |

#### Returns

[`FetchError`](FetchError.md)

#### Overrides

Error.constructor

#### Defined in

[sdk/src/types/errors.ts:43](https://github.com/Network-Goods/hypercerts/blob/9677274/sdk/src/types/errors.ts#L43)
sdk/src/types/errors.ts:43

## Properties

Expand All @@ -65,4 +69,4 @@ Additional error payload.

#### Defined in

[sdk/src/types/errors.ts:36](https://github.com/Network-Goods/hypercerts/blob/9677274/sdk/src/types/errors.ts#L36)
sdk/src/types/errors.ts:36
Loading
Loading