@hypercerts-org/marketplace-sdk 0.4.0 → 0.4.1

package/{LICENSE → LICENSE.md}

@@ -1,4 +1,5 @@
 This project is dual licensed under MIT and Apache-2.0.
 
 MIT: https://www.opensource.org/licenses/mit
+
 Apache-2.0: https://www.apache.org/licenses/license-2.0

package/README.md

@@ -1,101 +1,133 @@
-# @looksrare/sdk-v2
+# @hypercerts-org/marketplace-sdk
 
-![GitHub package.json version](https://img.shields.io/github/package-json/v/LooksRare/sdk-v2) ![GitHub](https://img.shields.io/github/license/LooksRare/sdk-v2) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/LooksRare/sdk-v2/build.yml) ![npm](https://img.shields.io/npm/dt/@looksrare/sdk-v2)
+![GitHub package.json version](https://img.shields.io/github/package-json/v/hypercerts-org/marketplace-sdk) ![GitHub](https://img.shields.io/github/license/hypercerts-org/marketplace-sdk) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/hypercerts-org/marketplace-sdk/build.yml) ![npm](https://img.shields.io/npm/dt/@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, enabling users to sell and buy Hypercerts on the marketplace.
 
-## Install
+## SDK usage
 
-This package has a peer dependency on [etherjs V5](https://docs.ethers.io/v5/).
+<!-- TODO: Check if links still work on deployment -->
 
-```bash
-yarn add @looksrare/sdk-v2 ethers
-```
+Read the [guides](./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 or run tests on the SDK.
 
-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 install && pnpm run build
+cd ../your-project
+pnpm link <path to marketplace sdk on you local filesystem>
 ```
 
-: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
+
+## Architecture
+
+### 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 by API
+1. If verified correctly, 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 might render it being invalid. A user can invalidate their own orders on request. There are more possible reasons, see the `OrderValidatorCode` enum located in [src/types.ts](./src/types.ts#L266) and the guide on [order validation](./guides/orderValidation.md).
+   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`, found in the marketplace SDK
+   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. If the transaction rendered the order invalid for any further sales, the error codes and validity get updated in the DB.
+1. Once a 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 visible to other users as long as it's valid]
+        C3[Order validity can be updated]
+        C4[Order can become invalid due to various reasons]
+        C5[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/sdk-v2@0.9.2`](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/sdk-v2@1.0.0`.
-
-## 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
-
-🔗 [Developer documentation](https://docs.looksrare.org/developers/welcome)
-
-🔗 [Public API documentation](https://looksrare.dev/reference/important-information)
-
-🔗 [Developer discord](https://discord.gg/jJA4qM5dXz)

package/dist/HypercertExchangeClient.d.ts

@@ -1,5 +1,5 @@
 import { BigNumberish, ContractTransactionResponse, Overrides, Provider, Signer, TypedDataDomain } from "ethers";
-import { Addresses, BatchTransferItem, ChainId, ContractMethods, CreateMakerAskOutput, CreateMakerBidOutput, CreateMakerCollectionOfferInput, CreateMakerCollectionOfferWithProofInput, CreateMakerInput, Currencies, Maker, MerkleTree, Order, OrderValidatorCode, SignMerkleTreeOrdersOutput, StrategyInfo, StrategyType, Taker } from "./types";
+import { Addresses, ChainId, ContractMethods, CreateDirectFractionsSaleMakerAskInput, CreateFractionalSaleMakerAskInput, CreateMakerAskOutput, CreateMakerBidOutput, CreateMakerInput, Currencies, Maker, MerkleTree, Order, OrderValidatorCode, SignMerkleTreeOrdersOutput, StrategyInfo, StrategyType, Taker } from "./types";
 import { ApiClient } from "./utils/api";
 /**
  * HypercertExchange
@@ -26,10 +26,10 @@ export declare class HypercertExchangeClient {
     readonly provider: Provider;
     /**
      * HypercertExchange protocol main class
-     * @param chainId Current app chain id
+     * @param chainId Chain id for contract interactions
      * @param provider Ethers provider
      * @param signer Ethers signer
-     * @param overrides Override contract addresses or api endpoint used
+     * @param overrides Override contract addresses or API endpoint used
      */
     constructor(chainId: ChainId, provider: Provider, signer?: Signer, overrides?: {
         addresses: Addresses;
@@ -57,27 +57,13 @@ export declare class HypercertExchangeClient {
      * @param CreateMakerInput
      * @returns the maker object, isTransferManagerApproved, and isTransferManagerApproved
      */
-    createMakerAsk({ collection, strategyId, collectionType, subsetNonce, orderNonce, endTime, price, itemIds, amounts, currency, startTime, additionalParameters, }: CreateMakerInput): Promise<CreateMakerAskOutput>;
+    createMakerAsk({ collection, strategyId, collectionType, subsetNonce, orderNonce, endTime, price, itemIds, currency, startTime, additionalParameters, }: CreateMakerInput): Promise<CreateMakerAskOutput>;
     /**
      * Create a maker bid object ready to be signed
      * @param CreateMakerInput
      * @returns the maker object, isCurrencyApproved, and isBalanceSufficient
      */
-    createMakerBid({ collection, strategyId, collectionType, subsetNonce, orderNonce, endTime, price, itemIds, amounts, currency, startTime, additionalParameters, }: CreateMakerInput): Promise<CreateMakerBidOutput>;
-    /**
-     * Create a maker bid for collection offer.
-     * @see this.createMakerBid
-     * @param orderInputs Order data
-     * @returns CreateMakerBidOutput
-     */
-    createMakerCollectionOffer(orderInputs: CreateMakerCollectionOfferInput): Promise<CreateMakerBidOutput>;
-    /**
-     * Create a maker bid for collection, with a list of item id that can be used for the taker order
-     * @see this.createMakerBid
-     * @param orderInputs Order data
-     * @returns CreateMakerBidOutput
-     */
-    createMakerCollectionOfferWithProof(orderInputs: CreateMakerCollectionOfferWithProofInput): Promise<CreateMakerBidOutput>;
+    createMakerBid({ collection, strategyId, collectionType, subsetNonce, orderNonce, endTime, price, itemIds, currency, startTime, additionalParameters, }: CreateMakerInput): Promise<CreateMakerBidOutput>;
     /**
      * Create a taker ask ready to be executed against a maker bid
      * @param maker Maker order that will be used as counterparty for the taker
@@ -86,27 +72,6 @@ export declare class HypercertExchangeClient {
      * @returns Taker object
      */
     createTaker(maker: Maker, recipient?: string, additionalParameters?: any[]): Taker;
-    /**
-     * Create a taker ask order for collection order.
-     * @see this.createTaker
-     * @see this.createMakerCollectionOffer
-     * @param maker Maker bid that will be used as counterparty for the taker
-     * @param itemId Token id to use as a counterparty for the collection order
-     * @param recipient Recipient address of the taker (if none, it will use the sender)
-     * @returns Taker object
-     */
-    createTakerCollectionOffer(maker: Maker, itemId: BigNumberish, recipient?: string): Taker;
-    /**
-     * Create a taker ask to fulfill a collection order (maker bid) created with a whitelist of item ids
-     * @see this.createTaker
-     * @see this.createMakerCollectionOfferWithMerkleTree
-     * @param maker Maker bid that will be used as counterparty for the taker
-     * @param itemId Token id to use as a counterparty for the collection order
-     * @param itemIds List of token ids used during the maker creation
-     * @param recipient Recipient address of the taker (if none, it will use the sender)
-     * @returns Taker object
-     */
-    createTakerCollectionOfferWithProof(maker: Maker, itemId: BigNumberish, itemIds: BigNumberish[], recipient?: string): Taker;
     /**
      * Sign a maker order using the signer provided in the constructor
      * @param maker Order to be signed by the user
@@ -125,7 +90,7 @@ export declare class HypercertExchangeClient {
      * @param maker Maker order
      * @param taker Taker order
      * @param signature Signature of the maker order
-     * @param merkleTree If the maker has been signed with a merkle tree
+     * @param merkleTree Optional merkle tree
      * @returns ContractMethods
      */
     executeOrder(maker: Maker, taker: Taker, signature: string, merkleTree?: MerkleTree, overrides?: Overrides): ContractMethods;
@@ -154,19 +119,13 @@ export declare class HypercertExchangeClient {
      */
     cancelAllOrders(bid: boolean, ask: boolean, overrides?: Overrides): ContractMethods;
     /**
-     * Cancel a list of specific orders
+     * Cancel a list of orders by nonce
      * @param nonces List of nonces to be cancelled
      * @returns ContractMethods
      */
     cancelOrders(nonces: BigNumberish[], overrides?: Overrides): ContractMethods;
     /**
-     * Cancel a list of specific subset orders
-     * @param nonces List of nonces to be cancelled
-     * @returns ContractMethods
-     */
-    cancelSubsetOrders(nonces: BigNumberish[], overrides?: Overrides): ContractMethods;
-    /**
-     * Approve all the items of a collection, to eventually be traded on HypercertExchange
+     * Approve all the items of a collection, to eventually be traded on the Hypercert Exchange
      * The spender is the TransferManager.
      * @param collectionAddress Address of the collection to be approved.
      * @param approved true to approve, false to revoke the approval (default to true)
@@ -174,7 +133,7 @@ export declare class HypercertExchangeClient {
      */
     approveAllCollectionItems(collectionAddress: string, approved?: boolean, overrides?: Overrides): Promise<ContractTransactionResponse>;
     /**
-     * Approve an ERC20 to be used as a currency on HypercertExchange.
+     * Approve an ERC20 to be used as a currency on the Hypercert Exchange.
      * The spender is the HypercertExchangeProtocol contract.
      * @param tokenAddress Address of the ERC20 to approve
      * @param amount Amount to be approved (default to MaxUint256)
@@ -201,13 +160,6 @@ export declare class HypercertExchangeClient {
      * @returns ContractMethods
      */
     revokeTransferManagerApproval(operators?: string[], overrides?: Overrides): ContractMethods;
-    /**
-     * Transfer a list of items across different collections
-     * @param to Recipient address
-     * @param collectionItems Each object in the array represent a list of items for a specific collection
-     * @returns ContractMethods
-     */
-    transferItemsAcrossCollection(to: string, collectionItems: BatchTransferItem[], overrides?: Overrides): Promise<ContractMethods>;
     /**
      * Verify if a set of orders can be executed (i.e are valid)
      * @param makerOrders List of maker orders
@@ -235,36 +187,16 @@ export declare class HypercertExchangeClient {
     strategyInfo(strategyId: StrategyType, overrides?: Overrides): Promise<StrategyInfo>;
     /**
      * Create a maker ask for a collection or singular offer of fractions
-     * @param itemIds Token IDs of the fractions to be sold
-     * @param price Price of the fractions in wei
-     * @param startTime Timestamp in seconds when the order becomes valid
-     * @param endTime Timestamp in seconds when the order becomes invalid
-     * @param currency Currency used to buy the fractions (default to WETH)
-     * @param additionalParameters Additional parameters used to support complex orders
+     * @param CreateDirectFractionsSaleMakerAskInput
      */
-    createDirectFractionsSaleMakerAsk({ itemIds, price, startTime, endTime, currency, additionalParameters, }: Omit<CreateMakerInput, "strategyId" | "collectionType" | "collection" | "subsetNonce" | "orderNonce" | "amounts">): Promise<CreateMakerAskOutput>;
+    createDirectFractionsSaleMakerAsk({ itemIds, price, startTime, endTime, currency, additionalParameters, }: CreateDirectFractionsSaleMakerAskInput): Promise<CreateMakerAskOutput>;
     /**
-     * Create a maker ask to let the buyer decide how much of the fraction they want to buy
-     * @param itemIds Token IDs of the fractions to be sold
-     * @param price Price of one unit in wei
-     * @param startTime Timestamp in seconds when the order becomes valid
-     * @param endTime Timestamp in seconds when the order becomes invalid
-     * @param currency Currency used to buy the fractions (default to WETH)
-     * @param maxUnitAmount Maximum amount of units that can be bought in a single transaction
-     * @param minUnitAmount Minimum amount of units that can be bought in a single transaction
-     * @param minUnitsToKeep Minimum amount of units that the seller wants to keep
-     * @param sellLeftoverFraction Whether or not the seller wants to sell the leftover units
-     * @param root Merkle tree root (optional)
+     * Create a maker ask to let the buyer decide how much of a fraction they want to buy
+     * @param CreateFractionalSaleMakerInput
      */
-    createFractionalSaleMakerAsk({ itemIds, price, startTime, endTime, currency, maxUnitAmount, minUnitAmount, minUnitsToKeep, sellLeftoverFraction, root, }: Omit<CreateMakerInput, "strategyId" | "collectionType" | "collection" | "subsetNonce" | "orderNonce" | "amounts" | "additionalParameters"> & {
-        minUnitAmount: BigNumberish;
-        maxUnitAmount: BigNumberish;
-        minUnitsToKeep: BigNumberish;
-        sellLeftoverFraction: boolean;
-        root?: string;
-    }): Promise<CreateMakerAskOutput>;
+    createFractionalSaleMakerAsk({ itemIds, price, startTime, endTime, currency, maxUnitAmount, minUnitAmount, minUnitsToKeep, sellLeftoverFraction, root, }: CreateFractionalSaleMakerAskInput): Promise<CreateMakerAskOutput>;
     /**
-     * Create a taker bid for buying a fraction of an open fractional sale
+     * Create a taker bid for buying part of a fraction
      * @param maker Maker order
      * @param recipient Recipient address of the taker (if none, it will use the sender)
      * @param unitAmount Amount of units to buy
@@ -272,7 +204,7 @@ export declare class HypercertExchangeClient {
      */
     createFractionalSaleTakerBid(maker: Maker, recipient: string | undefined, unitAmount: BigNumberish, pricePerUnit: BigNumberish): Taker;
     /**
-     * Register the order with hypercerts marketplace API.
+     * Register the order with the hypercerts marketplace API
      * @param order Maker order
      * @param signature Signature of the maker order
      */
@@ -283,7 +215,7 @@ export declare class HypercertExchangeClient {
         success: boolean;
     }>;
     /**
-     * Delete the order
+     * Delete the order from the hypercerts marketplace API
      * @param orderId Order ID
      */
     deleteOrder(orderId: string): Promise<boolean>;