@zoralabs/coins-sdk 0.0.2-sdkalpha.3 → 0.0.2-sdkalpha.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @zoralabs/coins-sdk
 
+## 0.0.2-sdkalpha.4
+
+### Patch Changes
+
+- d8cbf6ea: Update coin sdk structure and offchain functions
+
 ## 0.0.2-sdkalpha.3
 
 ### Patch Changes

package/README.md

@@ -6,25 +6,34 @@ This SDK is based off of viem v2 and exposes both functions to get the viem call
 
 Devs can input their addresses in `platformReferrer` and `traderReferrer` fields to earn trade and create referral fees for their platform.
 
-This prerelease SDK has 3 core features: `createCoin`, `tradeCoin`, and `getCoinDetails`.
+This prerelease SDK has two main categories of functionality: Onchain Actions and Queries.
 
-1. `getCoinDetails`: Gets details for the given coin. This function retrieves the current state of a coin for a user, including balance, pool address, pool state, owners, and payout recipient.
+All the SDK functions are accessible from the main export (for example: `import {createCoin, getCoin} from "@zoralabs/coins-sdk"`).
 
-   **Key Parameters:**
-   - `coin`: The coin contract address.
-   - `user`: The user address to check balance for. (Optional)
-   - `publicClient`: The viem public client instance.
+## Table of Contents
 
-   **Return Value:**
-   - `balance`: The user's balance of the coin.
-   - `marketCap`: The market cap of the coin.
-   - `liquidity`: The liquidity of the coin.
-   - `pool`: Pool address.
-   - `poolState`: Current state of the UniswapV3 pool.
-   - `owners`: List of owners for the coin.
-   - `payoutRecipient`: The payout recipient address.
+### Onchain Actions
+- [createCoin](#1-createcoin-creates-a-new-coin-with-the-given-parameters-to-trade)
+- [tradeCoin](#2-tradecoin-buys-or-sells-an-existing-coin)
+- [updateCoinURI](#3-updatecoinuri-updates-the-uri-for-an-existing-coin)
+
+### Queries
+- [getOnchainCoinDetails](#1-getonchaincoindetails-gets-details-for-the-given-coin-from-the-blockchain)
+- [API Key](#2-api-key)
+- [Cursor Pagination](#cursor-pagination)
+- [API Queries](#3-api-queries)
+  - [Explore Queries](#4-explore-queries)
+  - [getCoin](#getcoin-get-details-for-a-specific-coin)
+  - [getCoins](#getcoins-get-details-for-multiple-coins)
+  - [getCoinComments](#getcoincomments-get-comments-for-a-coin)
+  - [getProfile](#getprofile-get-profile-information)
+  - [getProfileOwned](#getprofileowned-get-coins-owned-by-a-profile)
+
+## Onchain Actions
+
+These are functions that interact directly with the blockchain and require transaction signing.
 
-2. `createCoin`: Creates a new coin with the given parameters to trade.
+### 1. `createCoin`: Creates a new coin with the given parameters to trade.
 
    **Key Parameters:**
    - `name`: The name of the new coin.
@@ -66,7 +75,7 @@ This prerelease SDK has 3 core features: `createCoin`, `tradeCoin`, and `getCoin
    // the receipt can be parsed from `getCoinCreateFromLogs(receipt.logs)`
    ```
 
-3. `tradeCoin`: Buys or sells an existing coin.
+### 2. `tradeCoin`: Buys or sells an existing coin.
 
    **Key Parameters:**
    - `direction`: The trade direction, either 'buy' or 'sell'.
@@ -94,7 +103,7 @@ This prerelease SDK has 3 core features: `createCoin`, `tradeCoin`, and `getCoin
    ```
 
    **Lower Level Call Method with WAGMI:**
-   Use the `tradeCoinCall` function to get the contract call parameters and then use WAGMI's `useContractWrite` hook. Also, use WAGMI's `useWaitForTransaction` hook to get the transaction receipt.
+   Use the `tradeCoinCall` function to get the contract call parameters and then use WAGMI's `useContractWrite` hook.
 
    ```typescript
    const tradeParams = {
@@ -107,6 +116,427 @@ This prerelease SDK has 3 core features: `createCoin`, `tradeCoin`, and `getCoin
    };
 
    const { config } = tradeCoinCall(tradeParams);
-   const { write, data } = useContractWrite(config);
+   const { write } = useContractWrite(config);
+
+   write(); // Execute the contract write
    // the receipt can be parsed from `getTradeFromLogs(receipt.logs)`
    ```
+
+### 3. `updateCoinURI`: Updates the URI for an existing coin.
+
+   **Key Parameters:**
+   - `coin`: The coin contract address.
+   - `newURI`: The new URI for the coin metadata (must start with "ipfs://").
+
+   **Usage:**
+   ```typescript
+   const updateParams = {
+     coin: "0xCoinAddress",
+     newURI: "ipfs://new-metadata-uri",
+   };
+
+   const result = await updateCoinURI(updateParams, walletClient, publicClient);
+   console.log(result);
+   ```
+
+   **Lower Level Call Method with WAGMI:**
+   ```typescript
+   const updateParams = {
+     coin: "0xCoinAddress",
+     newURI: "ipfs://new-metadata-uri",
+   };
+
+   const { config } = updateCoinURICall(updateParams);
+   const { write } = useContractWrite(config);
+
+   write(); // Execute the contract write
+   ```
+
+## Onchain Queries
+
+These are functions that read data from the blockchain or API without requiring transaction signing.
+
+### 1. `getOnchainCoinDetails`: Gets details for the given coin from the blockchain.
+
+This query retrieves the most up-to-date coin information directly from the blockchain.
+It is strongly recommended to use the other API queries to fetch this information if possible.
+
+   **Key Parameters:**
+   - `coin`: The coin contract address.
+   - `user`: The user address to check balance for. (Optional)
+   - `publicClient`: The viem public client instance.
+
+   **Return Value:**
+   - `balance`: The user's balance of the coin.
+   - `marketCap`: The market cap of the coin.
+   - `liquidity`: The liquidity of the coin.
+   - `pool`: Pool address.
+   - `poolState`: Current state of the UniswapV3 pool.
+   - `owners`: List of owners for the coin.
+   - `payoutRecipient`: The payout recipient address.
+
+### 2. API Queries
+
+   These functions interact with the Zora API to fetch additional data:
+
+   #### API Key
+
+   To get a higher rate limit and fully use the zora API, an API key is required.
+
+   To set the API key, you can use the `setApiKey` function which will apply your API key to all requests.
+
+   ```typescript
+   setApiKey("your-api-key");
+   ```
+
+   Please DM the Zora team to get the API key.
+
+   These queries allow non-api-key access for reasonable development usage.
+
+   #### Cursor Pagination
+
+   Many queries support cursor-based pagination using the `after` parameter. To paginate through results:
+
+   1. Make your initial query without an `after` parameter
+   2. From the response, get the `endCursor` from the `pageInfo` object
+   3. Pass this `endCursor` as the `after` parameter in your next query
+
+   **Example:**
+   ```typescript
+   // First page
+   const firstPage = await getTopGainers({
+     count: 10
+   });
+   
+   // Get the cursor for the next page
+   const nextCursor = firstPage.exploreList?.pageInfo?.endCursor;
+   
+   // Fetch next page using the cursor
+   if (nextCursor) {
+     const nextPage = await getTopGainers({
+       count: 10,
+       after: nextCursor
+     });
+   }
+   ```
+
+   **Complete Pagination Example:**
+   ```typescript
+   async function fetchAllTopGainers() {
+     const allResults = [];
+     let hasNextPage = true;
+     let cursor: string | undefined;
+     
+     while (hasNextPage) {
+       const response = await getTopGainers({
+         count: 10,
+         after: cursor
+       });
+       
+       const { edges, pageInfo } = response.exploreList || {};
+       
+       if (edges) {
+         allResults.push(...edges.map(edge => edge.node));
+       }
+       
+       hasNextPage = pageInfo?.hasNextPage || false;
+       cursor = pageInfo?.endCursor;
+     }
+     
+     return allResults;
+   }
+   ```
+
+   This pagination pattern works for all queries that return `pageInfo` with `endCursor` and `hasNextPage`, including:
+   - All explore queries
+   - `getCoinComments`
+   - `getProfileOwned`
+
+   #### `getCoin`: Get details for a specific coin
+   **Parameters:**
+   - `address`: The coin contract address
+   - `chain`: (Optional) The chain ID
+
+   **Returns:**
+   ```typescript
+   {
+     zora20Token?: {
+       id?: string;
+       name?: string;
+       description?: string;
+       address?: string;
+       symbol?: string;
+       totalSupply?: string;
+       totalVolume?: string;
+       volume24h?: string;
+       createdAt?: string;
+       creatorAddress?: string;
+       creatorEarnings?: Array<{
+         amount?: {
+           currency?: { address?: string };
+           amountRaw?: string;
+           amountDecimal?: number;
+         };
+         amountUsd?: string;
+       }>;
+       marketCap?: string;
+       marketCapDelta24h?: string;
+       chainId?: number;
+       creatorProfile?: string;
+       handle?: string;
+       avatar?: {
+         previewImage?: string;
+         blurhash?: string;
+         small?: string;
+       };
+       media?: {
+         mimeType?: string;
+         originalUri?: string;
+         format?: string;
+         previewImage?: string;
+         medium?: string;
+         blurhash?: string;
+       };
+       transfers?: { count?: number };
+       uniqueHolders?: number;
+     }
+   }
+   ```
+
+   #### `getCoins`: Get details for multiple coins
+   **Parameters:**
+   - `coins`: Array of coin objects with:
+     - `chainId`: (Optional) The chain ID
+     - `collectionAddress`: The coin contract address
+
+   **Returns:** Array of coin details in the same format as `getCoin`
+
+   #### `getCoinComments`: Get comments for a coin
+   **Parameters:**
+   - `address`: The coin contract address
+   - `chain`: (Optional) The chain ID
+   - `after`: (Optional) Pagination cursor
+   - `count`: (Optional) Number of comments to return
+
+   **Returns:**
+   ```typescript
+   {
+     zora20Token?: {
+       zoraComments?: {
+         pageInfo?: {
+           endCursor?: string;
+           hasNextPage?: boolean;
+         };
+         count?: number;
+         edges?: Array<{
+           node?: string;
+           txHash?: string;
+           comment?: string;
+           userAddress?: string;
+           timestamp?: number;
+           userProfile?: string;
+           id?: string;
+           handle?: string;
+           avatar?: {
+             previewImage?: string;
+             blurhash?: string;
+             small?: string;
+           };
+           replies?: {
+             count?: number;
+             edges?: Array<{
+               node?: {
+                 txHash?: string;
+                 comment?: string;
+                 userAddress?: string;
+                 timestamp?: number;
+                 userProfile?: string;
+                 id?: string;
+                 handle?: string;
+                 avatar?: {
+                   previewImage?: string;
+                   blurhash?: string;
+                   small?: string;
+                 };
+               };
+             }>;
+           };
+         }>;
+       };
+     }
+   }
+   ```
+
+   #### `getProfile`: Get profile information
+   **Parameters:**
+   - `identifier`: The profile identifier (username, handle, or address)
+
+   **Returns:**
+   ```typescript
+   {
+     profile?: string;
+     id?: string;
+     handle?: string;
+     avatar?: {
+       small?: string;
+       medium?: string;
+       blurhash?: string;
+     };
+     username?: string;
+     displayName?: string;
+     bio?: string;
+     website?: string;
+     publicWallet?: {
+       walletAddress?: string;
+     };
+     linkedWallets?: {
+       edges?: Array<{
+         node?: {
+           walletType?: "PRIVY" | "EXTERNAL" | "SMART_WALLET";
+           walletAddress?: string;
+         };
+       }>;
+     };
+   }
+   ```
+
+   #### `getProfileOwned`: Get coins owned by a profile
+   **Parameters:**
+   - `identifier`: The profile identifier (username, handle, or address)
+   - `count`: (Optional) Number of items to return
+   - `after`: (Optional) Pagination cursor
+   - `chainIds`: (Optional) Array of chain IDs to filter by
+
+   **Returns:**
+   ```typescript
+   {
+     profile?: string;
+     id?: string;
+     handle?: string;
+     avatar?: {
+       previewImage?: string;
+       blurhash?: string;
+       small?: string;
+     };
+     coinBalances?: {
+       count?: number;
+       edges?: Array<{
+         node?: {
+           balance?: string;
+           id?: string;
+           coin?: {
+             // Same coin details as getCoin
+           };
+         };
+       }>;
+       pageInfo?: {
+         hasNextPage?: boolean;
+         endCursor?: string;
+       };
+     };
+   }
+   ```
+
+### 3. Explore Queries
+
+   These functions fetch curated lists of coins. All explore queries share the same parameters and return type:
+
+   **Parameters:**
+   - `count`: (Optional) Number of items to return
+   - `after`: (Optional) Pagination cursor
+
+   **Returns:**
+   ```typescript
+   {
+     exploreList?: {
+       edges?: Array<{
+         node?: {
+           // Same coin details as getCoin
+         };
+         cursor?: string;
+       }>;
+       pageInfo?: {
+         endCursor?: string;
+         hasNextPage?: boolean;
+       };
+     }
+   }
+   ```
+
+   Available explore queries:
+   - `getTopGainers`: Get top gaining coins
+   - `getTopVolume24h`: Get coins with highest 24h volume
+   - `getMostValuable`: Get most valuable coins
+   - `getNew`: Get newly created coins
+   - `getLastTraded`: Get recently traded coins
+   - `getLastTradedUnique`: Get recently traded unique coins
+
+   **Usage Example:**
+   ```typescript
+   const topGainers = await getTopGainers({
+     count: 10,
+     after: "cursor"
+   });
+   const newCoins = await getNew({
+     count: 20
+   });
+   ```
+
+### 4. Cursor Pagination
+
+   Many queries support cursor-based pagination using the `after` parameter. To paginate through results:
+
+   1. Make your initial query without an `after` parameter
+   2. From the response, get the `endCursor` from the `pageInfo` object
+   3. Pass this `endCursor` as the `after` parameter in your next query
+
+   **Example:**
+   ```typescript
+   // First page
+   const firstPage = await getTopGainers({
+     count: 10
+   });
+   
+   // Get the cursor for the next page
+   const nextCursor = firstPage.exploreList?.pageInfo?.endCursor;
+   
+   // Fetch next page using the cursor
+   if (nextCursor) {
+     const nextPage = await getTopGainers({
+       count: 10,
+       after: nextCursor
+     });
+   }
+   ```
+
+   **Complete Pagination Example:**
+   ```typescript
+   async function fetchAllTopGainers() {
+     const allResults = [];
+     let hasNextPage = true;
+     let cursor: string | undefined;
+     
+     while (hasNextPage) {
+       const response = await getTopGainers({
+         count: 10,
+         after: cursor
+       });
+       
+       const { edges, pageInfo } = response.exploreList || {};
+       
+       if (edges) {
+         allResults.push(...edges.map(edge => edge.node));
+       }
+       
+       hasNextPage = pageInfo?.hasNextPage || false;
+       cursor = pageInfo?.endCursor;
+     }
+     
+     return allResults;
+   }
+   ```
+
+   This pagination pattern works for all queries that return `pageInfo` with `endCursor` and `hasNextPage`, including:
+   - All explore queries
+   - `getCoinComments`
+   - `getProfileOwned`

package/dist/actions/getOnchainCoinDetails.d.ts

@@ -1,4 +1,5 @@
-import { Address, PublicClient } from "viem";
+import { GenericPublicClient } from "src/utils/genericPublicClient";
+import { Address } from "viem";
 type Slot0Result = {
     sqrtPriceX96: bigint;
     tick: number;
@@ -45,7 +46,7 @@ export type OnchainCoinDetails = {
 export declare function getOnchainCoinDetails({ coin, user, publicClient, }: {
     coin: Address;
     user?: Address;
-    publicClient: PublicClient;
+    publicClient: GenericPublicClient;
 }): Promise<OnchainCoinDetails>;
 export {};
 //# sourceMappingURL=getOnchainCoinDetails.d.ts.map

package/dist/actions/getOnchainCoinDetails.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getOnchainCoinDetails.d.ts","sourceRoot":"","sources":["../../src/actions/getOnchainCoinDetails.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,OAAO,EAIP,YAAY,EAEb,MAAM,MAAM,CAAC;AAEd,KAAK,WAAW,GAAG;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,0BAA0B,EAAE,MAAM,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,WAAW,CAAC;IACvB,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,IAAI,EACJ,IAAkB,EAClB,YAAY,GACb,EAAE;IACD,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,YAAY,CAAC;CAC5B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmH9B"}
+{"version":3,"file":"getOnchainCoinDetails.d.ts","sourceRoot":"","sources":["../../src/actions/getOnchainCoinDetails.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,EACL,OAAO,EAKR,MAAM,MAAM,CAAC;AAEd,KAAK,WAAW,GAAG;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,0BAA0B,EAAE,MAAM,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,WAAW,CAAC;IACvB,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,IAAI,EACJ,IAAkB,EAClB,YAAY,GACb,EAAE;IACD,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,mBAAmB,CAAC;CACnC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmH9B"}

package/dist/api/api-key.d.ts

@@ -0,0 +1,9 @@
+export declare function setApiKey(key: string): void;
+export declare function getApiKeyMeta(): {
+    headers?: undefined;
+} | {
+    headers: {
+        "api-key": string;
+    };
+};
+//# sourceMappingURL=api-key.d.ts.map

package/dist/api/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../../src/api/api-key.ts"],"names":[],"mappings":"AACA,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,QAEpC;AAED,wBAAgB,aAAa;;;;;;EAS5B"}