forked from LooksRare/sdk-v2
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
(chore): update developer documentation
Updates developer documentation for contributing to the sdk. Updates developer documentation for consuming the SDK. Removes redundant references to env vars. Removes redundant references to outdated package manager yarn. Updates typedoc version and configuration to include handwritten guides in the generated docs. Removes outdated github templates. Updates JSDoc annotations.
- Loading branch information
Showing
99 changed files
with
14,332 additions
and
10,487 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| { | ||
| "npm.packageManager": "pnpm" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,101 +1,138 @@ | ||
| # @looksrare/sdk-v2 | ||
| # @hypercerts-org/marketplace-sdk | ||
|
|
||
|     | ||
|     | ||
|
|
||
| A collection of typescript tools to interact with LooksRare protocol V2 smart contracts 👀💎 | ||
| A collection of typescript tools to interact with HypercertsExchange smart contracts, enable users to sell and buy Hypercerts on the marketplace. | ||
|
|
||
| ## Install | ||
|
|
||
| This package has a peer dependency on [etherjs V5](https://docs.ethers.io/v5/). | ||
| ## SDK usage | ||
|
|
||
| ```bash | ||
| yarn add @looksrare/sdk-v2 ethers | ||
| ``` | ||
| Read the [guides](./docs/guides) if you need help with the implementation. | ||
|
|
||
| ```bash | ||
| npm install @looksrare/sdk-v2 ethers --save | ||
| ``` | ||
| You can also read the detailed [api documentation](./doc). | ||
|
|
||
| ## Getting Started | ||
| ## SDK development | ||
|
|
||
| The SDK expose a main class used to perform all the onchain operations: | ||
| ### Environment variables | ||
|
|
||
| ```ts | ||
| import { ChainId } from "@looksrare/sdk-v2"; | ||
| const looksrare = new LooksRare(ChainId.MAINNET, provider, signer); | ||
| ``` | ||
| No environment variables are required to run build the SDK or run the tests. | ||
|
|
||
| The signer is optional if you need access to read only data (:warning: Calls to function that need a signer will throw a `Signer is undefined` exception): | ||
| ### Local development | ||
|
|
||
| ```ts | ||
| import { ChainId } from "@looksrare/sdk-v2"; | ||
| const looksrare = new LooksRare(ChainId.MAINNET, provider); | ||
| ``` | ||
| The `HypercertExchangeClient()` allows you to override the api endpoint. This can be useful for developing against a local instance of the API. | ||
|
|
||
| If you work on a hardhat setup, you can override the addresses as follow: | ||
| To use a locally built version of the SDK in another project, you can use `pnpm link`: | ||
|
|
||
| ```ts | ||
| import { Addresses } from "@looksrare/sdk-v2"; | ||
| const addresses: Addresses = {...}; | ||
| const looksrare = new LooksRare(ChainId.HARDHAT, provider, signer, addresses); | ||
| ```bash | ||
| cd marketplace-sdk | ||
| pnpm link | ||
| cd ../your-project | ||
| pnpm link @hypercerts-org/marketplace-sdk | ||
| ``` | ||
|
|
||
| :information_source: Use [`JsonRpcProvider`](https://docs.ethers.org/v6/api/providers/jsonrpc/#JsonRpcApiProviderOptions) from `ethers v6` if you want to make batched RPC calls. | ||
|
|
||
| ```ts | ||
| import { JsonRpcProvider, Network } from "ethers"; | ||
|
|
||
| // Create a HTTP/HTTPS batch call provider | ||
| const provider = new JsonRpcProvider(RPC_URL, CHAIN_ID, { staticNetwork: Network.from(CHAIN_ID) }); | ||
|
|
||
| // Create LooksRare instance using this provider | ||
| const looksrare = new LooksRare(ChainId.HARDHAT, provider, signer, addresses); | ||
| ## Scripts | ||
|
|
||
| - `dev` - Run the SDK in development mode | ||
| - `build` - Build the SDK | ||
| - `test` - Run the tests | ||
| - `docs` - Generate the documentation into the `doc` folder | ||
| - `supabase:types:hypercerts` - Generate types for the `data-staging` database | ||
|
|
||
| ## Lifecycle of an order | ||
|
|
||
| 1. User A creates maker order and signs it | ||
| 1. User A registers maker order with API | ||
| 1. Signature on maker order gets verified | ||
| 1. Order gets stored in data postgres DB | ||
| 1. Order will live in DB until deleted | ||
| 1. Order will be visible to other users as long as it's valid. | ||
| 1. An order being executed or canceled (or many other reasons) might render it being invalid. | ||
| 1. User B fetches order from API | ||
| 1. User B creates taker order for maker order | ||
| 1. User B signs taker order against maker order using the `HypercertExchangeClient` | ||
| 1. User B calls the `executeOrder` method on the `HypercertExchangeClient` with the taker order, which calls the `HypercertExchange` contract in turn. | ||
| 1. The `HypercertExchange` contract verifies the signature and executes the order | ||
| 1. The `HypercertExchange` contract will emit an event that the order has been executed, which is picked up by the indexer which revalidates the order and updates the errors codes and validity in the DB. | ||
| 1. Once an maker order is invalidated it's only visible to User A. | ||
| 1. Maker order can be deleted or permanently rendered invalid by declaring the nonce invalid by User A at any time. | ||
|
|
||
| > [!WARNING] | ||
| > | ||
| > The indexer is not listing to the OrderExecuted event yet, so the order will not be updated in the DB, unless reverified manually. | ||
| ```mermaid | ||
| graph TD | ||
| subgraph User A | ||
| A1[Creates maker order and signs it] | ||
| A2[Registers maker order with API] | ||
| end | ||
| subgraph API | ||
| B1[Receives maker order] | ||
| B2[Verifies signature on maker order] | ||
| B3[Stores order in Postgres DB] | ||
| end | ||
| subgraph Postgres DB | ||
| C1[Stores order] | ||
| C2[Order lives in DB until deleted] | ||
| C3[Order visible to other users as long as it's valid] | ||
| C4[Order validity can be updated] | ||
| C5[Order can become invalid due to various reasons] | ||
| C6[Marks order as invalid and stores error codes] | ||
| end | ||
| subgraph User B | ||
| D1[Fetches order from API] | ||
| D2[Creates taker order for maker order] | ||
| D3[Signs taker order against maker order using HypercertExchangeClient] | ||
| D4[Calls executeOrder method on HypercertExchangeClient] | ||
| end | ||
| subgraph HypercertExchange Contract | ||
| E1[Verifies signature] | ||
| E2[Executes order] | ||
| E3[Emits OrderExecuted event] | ||
| end | ||
| subgraph Indexer | ||
| F1[Picks up OrderExecuted event] | ||
| F2[Revalidates order] | ||
| F3[Updates error codes and validity in DB] | ||
| end | ||
| subgraph User A | ||
| G1[Invalid order is only visible to User A] | ||
| G2[Can delete or render order permanently invalid] | ||
| end | ||
| A1 --> A2 | ||
| A2 --> B1 | ||
| B1 --> B2 | ||
| B2 --> B3 | ||
| B3 --> C1 | ||
| C1 --> C2 | ||
| C2 --> C3 | ||
| C3 --> D1 | ||
| C3 --> C4 | ||
| C4 --> C5 | ||
| C5 --> C6 | ||
| D1 --> D2 | ||
| D2 --> D3 | ||
| D3 --> D4 | ||
| D4 --> E1 | ||
| E1 --> E2 | ||
| E2 --> E3 | ||
| E3 --> F1 | ||
| F1 --> F2 | ||
| F2 --> F3 | ||
| C6 --> G1 | ||
| G1 --> G2 | ||
| ``` | ||
|
|
||
| Prior to [`@looksrare/[email protected]`](https://www.npmjs.com/package/@looksrare/sdk-v2/v/0.9.2?activeTab=readme), LooksRareSDK was making batched calls using `0xsequence/multicall`. But this is not natively supported since `@looksrare/[email protected]`. | ||
|
|
||
| ## Documentation | ||
|
|
||
| Read the [guides](./guides) if you need help with the implementation. | ||
|
|
||
| You can also read the detailed [api documentation](./doc). | ||
|
|
||
| ## FAQ | ||
|
|
||
| ### ❓ How to use ABIs | ||
|
|
||
| The SDK exposes most of the LooksRare contract [ABIs](https://github.com/LooksRare/sdk-v2/tree/master/src/abis). For convenience, some commonly used ABIs are also exported. | ||
|
|
||
| ```js | ||
| import LooksRareProtocolABI from "@looksrare/sdk-v2/dist/abis/LooksRareProtocol.json"; | ||
| ``` | ||
|
|
||
| ### ❓ How to retrieve order nonce ? | ||
|
|
||
| Call the public api endpoint [/orders/nonce](https://looksrare.dev/reference/getordernonce), and use this nonce directly. | ||
|
|
||
| ### ❓ What to do when the order is created and signed ? | ||
|
|
||
| Use the public api endpoint [/orders](https://looksrare.dev/reference/createorder) to push the order to the database. After that, the order will be visible by everyone using the API (looksrare.org, aggregators, etc..). | ||
|
|
||
| ### ❓ When should I use merkle tree orders ? | ||
|
|
||
| Merkle tree orders are used to create several orders with a single signature. You shouldn't use them when using a bot. Their main purpose is to facilitate orders creation using a user interface. | ||
|
|
||
| ### ❓ Why do I need to call grantTransferManagerApproval ? | ||
|
|
||
| When you approve a collection to be traded on LooksRare, you approve the TransferManager instead of the exchange. Calling `grantTransferManagerApproval` gives the exchange contract the right to call the transfer function on the TransferManager. You need to call this function only once, the first time you use the V2. | ||
|
|
||
| ### ❓ What are subset nonces and how to use them ? | ||
|
|
||
| tl;dr subset nonces allow you to cancel all the orders sharing the same subset nonce. | ||
| Subset nonces allow you to group some orders together according to arbitrary rules (for example all your orders for a specific collection, all your orders above a certain threshold, etc). You can then cancel them all with a single call to `cancelSubsetOrders`. | ||
| :information_source: Unlike order nonces, executing an order with a specific subset nonce doesn't invalidate other orders sharing the same subset nonce. | ||
|
|
||
| ## Resources | ||
| ## Data | ||
|
|
||
| 🔗 [Developer documentation](https://docs.looksrare.org/developers/welcome) | ||
| Order information and nonces live in the `data-staging` and `data-production` database. Nonces are invalidated on-chain, but keeping track of the current nonce for a user happens off-chain in the DB. Orders do not live on-chain, but as they are signed they can be verified. | ||
|
|
||
| 🔗 [Public API documentation](https://looksrare.dev/reference/important-information) | ||
| ## Architecture | ||
|
|
||
| 🔗 [Developer discord](https://discord.gg/jJA4qM5dXz) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,14 @@ | ||
| **@hypercerts-org/marketplace-sdk** | ||
|
|
||
| *** | ||
|
|
||
| # @hypercerts-org/marketplace-sdk | ||
|
|
||
| ## Documents | ||
|
|
||
| - [Developer guide](documents/Developer-guide.md) | ||
|
|
||
| ## Modules | ||
|
|
||
| - [HypercertExchangeClient](modules/HypercertExchangeClient.md) | ||
| - [types](modules/types.md) | ||
| - [src/HypercertExchangeClient](src/HypercertExchangeClient/README.md) | ||
| - [src/types](src/types/README.md) |
Oops, something went wrong.