@zoralabs/protocol-sdk 0.3.2 → 0.3.3

package/.turbo/turbo-build.log

@@ -7,9 +7,9 @@ $ tsup
 CLI Cleaning output folder
 CJS Build start
 ESM Build start
-CJS dist/index.cjs     35.89 KB
-CJS dist/index.cjs.map 65.52 KB
-CJS ⚡️ Build success in 25ms
-ESM dist/index.js     33.30 KB
-ESM dist/index.js.map 65.40 KB
-ESM ⚡️ Build success in 25ms
+CJS dist/index.cjs     39.15 KB
+CJS dist/index.cjs.map 73.49 KB
+CJS ⚡️ Build success in 24ms
+ESM dist/index.js     36.55 KB
+ESM dist/index.js.map 73.48 KB
+ESM ⚡️ Build success in 23ms

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @zoralabs/protocol-sdk
 
+## 0.3.3
+
+### Patch Changes
+
+- 97f58b3: `MintAPIClient` is now a class, that takes a chain id and httpClient in the constructor, enabling the httpClient methods `fetch`, `post`, and `retries` to be overridden.
+
+  new methods on `MintAPIClient`:
+
+  `getMintableForToken` - takes a token id and token contract address and returns the mintable for it. Easier to use for fetching specific tokens than `getMintable`.
+
+  `MintClient` now takes the optional `PublicClient` in the constructor instead of in each function, and stores it or creates a default one if none is provided in the constructor. It also takes an optional `httpClient` param in the constructor, allowing the `fetch`, `post`, and `retries` methods to be overridden when using the api. It now internally creates the MintAPIClient.
+
+  `MintClient.makePrepareMintTokenParams` has the following changes:
+
+  - returns a `SimulateContractParams`, instead of an object containing it indexed by key
+  - no longer takes a `PublicClient` as an argument (it should be specified in the constructor instead)
+
+  new function `MintClient.getMintCosts` takes a mintable and quantity to mint and returns the mintFee, paidMintPrice, and totalCost.
+
+- d02484e: premintClient can have http methods overridable via DI, and now takes publicClient and http overrides in `createPremintClient` function. it no longer takes `publicClient` as an argument in functions, and rather uses them from the constructor. `executePremint` has been renamed ot `makeMintParameters`
+
 ## 0.3.2
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
-# Premint SDK
+# Zora Protocol SDK
 
-Protocol SDK allows users to manage zora mints and collects.
+Protocol SDK allows users to create tokens using the Zora Protocol, and mint them.
 
 ## Installing
 
@@ -11,28 +11,175 @@ Protocol SDK allows users to manage zora mints and collects.
 
 ### Creating a mint from an on-chain contract:
 
+#### Using viem
+
 ```ts
-import { createMintClient } from "@zoralabs/protocol-sdk";
-import type { Address, WalletClient } from "viem";
+import {createMintClient} from "@zoralabs/protocol-sdk";
+import type {Address, PublicClient, WalletClient} from "viem";
 
-async function mintNFT(
-  walletClient: WalletClient,
-  address: Address,
-  tokenId: bigint,
-) {
-  const mintAPI = createMintClient({ chain: walletClient.chain });
-  await mintAPI.mintNFT({
-    walletClient,
-    address,
+async function mintNFT({
+  walletClient,
+  publicClient,
+  tokenContract,
+  tokenId,
+  mintToAddress,
+  quantityToMint,
+  mintReferral,
+}: {
+  // wallet client that will submit the transaction
+  walletClient: WalletClient;
+  // public client that will simulate the transaction
+  publicClient: PublicClient;
+  // address of the token contract
+  tokenContract: Address;
+  // id of the token to mint
+  tokenId: bigint;
+  // address that will receive the minted token
+  mintToAddress: Address;
+  // quantity of tokens to mint
+  quantityToMint: number;
+  // optional address that will receive a mint referral reward
+  mintReferral?: Address;
+}) {
+  const mintClient = createMintClient({chain: walletClient.chain!});
+
+  // get mintable information about the token.
+  const mintable = await mintClient.getMintable({
+    tokenContract,
     tokenId,
+  });
+
+  // prepare the mint transaction, which can be simulated via an rpc with the public client.
+  const prepared = await mintClient.makePrepareMintTokenParams({
+    // token to mint
+    mintable,
     mintArguments: {
-      quantityToMint: 23,
-      mintComment: "Helo",
+      // address that will receive the token
+      mintToAddress,
+      // quantity of tokens to mint
+      quantityToMint,
+      // comment to include with the mint
+      mintComment: "My comment",
+      // optional address that will receive a mint referral reward
+      mintReferral,
     },
+    // account that is to invoke the mint transaction
+    minterAccount: walletClient.account!.address,
   });
+
+  // simulate the transaction and get any validation errors
+  const { request } = await publicClient.simulateContract(prepared);
+
+  // submit the transaction to the network
+  const txHash = await walletClient.writeContract(request);
+
+  // wait for the transaction to be complete
+  await publicClient.waitForTransactionReceipt({hash: txHash});
 }
 ```
 
+#### Using wagmi
+
+```tsx
+import {createMintClient, Mintable} from "@zoralabs/protocol-sdk";
+import {useEffect, useMemo, useState} from "react";
+import {BaseError, SimulateContractParameters, stringify} from "viem";
+import {Address, useAccount, useContractWrite, useNetwork, usePrepareContractWrite, usePublicClient, useWaitForTransaction} from "wagmi";
+
+// custom hook that gets the mintClient for the current chain
+const useMintClient = () => {
+  const publicClient = usePublicClient();
+
+  const {chain} = useNetwork();
+
+  const mintClient = useMemo(() => chain && createMintClient({chain, publicClient}), [chain, publicClient]);
+
+  return mintClient;
+};
+
+export const Mint = ({tokenId, tokenContract}: {tokenId: string; tokenContract: Address}) => {
+  // call custom hook to get the mintClient
+  const mintClient = useMintClient();
+
+  // value will be set by the form
+  const [quantityToMint, setQuantityToMint] = useState<number>(1);
+
+  // fetched mintable info from the sdk
+  const [mintable, setMintable] = useState<Mintable>();
+
+  useEffect(() => {
+    // fetch the mintable token info
+    const fetchMintable = async () => {
+      if (mintClient) {
+        const mintable = await mintClient.getMintable({tokenId, tokenContract});
+        setMintable(mintable);
+      }
+    };
+
+    fetchMintable();
+  }, [mintClient, tokenId, tokenContract]);
+
+  // params for the prepare contract write hook
+  const [params, setParams] = useState<SimulateContractParameters>();
+
+  const {address} = useAccount();
+
+  useEffect(() => {
+    if (!mintable || !mintClient || !address) return;
+
+    const makeParams = async () => {
+      // make the params for the prepare contract write hook
+      const params = await mintClient.makePrepareMintTokenParams({
+        mintable,
+        minterAccount: address,
+        mintArguments: {
+          mintToAddress: address,
+          quantityToMint,
+        },
+      });
+      setParams(params);
+    };
+
+    makeParams();
+  }, [mintable, mintClient, address, quantityToMint]);
+
+  const {config} = usePrepareContractWrite(params);
+
+  const {write, data, error, isLoading, isError} = useContractWrite(config);
+  const {data: receipt, isLoading: isPending, isSuccess} = useWaitForTransaction({hash: data?.hash});
+
+  return (
+    <>
+      <h3>Mint a token</h3>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          write?.();
+        }}
+      >
+        {/* input for quantity to mint: */}
+        <input placeholder="quantity to mint" onChange={(e) => setQuantityToMint(Number(e.target.value))} />
+        <button disabled={!write} type="submit">
+          Mint
+        </button>
+      </form>
+
+      {isLoading && <div>Check wallet...</div>}
+      {isPending && <div>Transaction pending...</div>}
+      {isSuccess && (
+        <>
+          <div>Transaction Hash: {data?.hash}</div>
+          <div>
+            Transaction Receipt: <pre>{stringify(receipt, null, 2)}</pre>
+          </div>
+        </>
+      )}
+      {isError && <div>{(error as BaseError)?.shortMessage}</div>}
+    </>
+  );
+};
+```
+
 ### Creating an 1155 contract:
 
 If an object with {name, uri} is passed in to this helper, it uses the creatorAccount and those values to either 1) create or 2) mint to that existing contract.
@@ -67,53 +214,71 @@ export async function createContract({
 }
 ```
 
-### Creating a premint:
+### Creating a token for free (gasless creation):
 
 ```ts
-import { PremintAPI } from "@zoralabs/protocol-sdk";
-import type { Address, WalletClient } from "viem";
+import {createPremintClient} from "@zoralabs/protocol-sdk";
+import type {Address, PublicClient, WalletClient} from "viem";
 
-async function makePremint(walletClient: WalletClient) {
-  // Create premint
-  const premint = await createPremintAPI(walletClient.chain).createPremint({
-    // Extra step to check the signature on-chain before attempting to sign
+async function createForFree({
+  walletClient,
+  creatorAccount,
+}: {
+  // wallet client that will submit the transaction
+  walletClient: WalletClient;
+  // address of the token contract
+  creatorAccount: Address;
+}) {
+  const premintClient = createPremintClient({ chain: walletClient.chain! });
+
+  // create and sign a free token creation.
+  const createdPremint = await premintClient.createPremint({
+    walletClient,
+    account: creatorAccount,
+    // if true, will validate that the creator is authorized to create premints on the contract.
     checkSignature: true,
-    // Collection information that this premint NFT will exist in once minted.
+    // collection info of collection to create
     collection: {
-      contractAdmin: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
+      contractAdmin: creatorAccount,
       contractName: "Testing Contract",
       contractURI:
         "ipfs://bafkreiainxen4b4wz4ubylvbhons6rembxdet4a262nf2lziclqvv7au3e",
     },
-    // WalletClient doing the signature
-    walletClient,
-    // Token information, falls back to defaults set in DefaultMintArguments.
+    // token info of token to create
     token: {
       tokenURI:
         "ipfs://bafkreice23maski3x52tsfqgxstx3kbiifnt5jotg3a5ynvve53c4soi2u",
     },
   });
 
-  console.log(`created ZORA premint, link: ${premint.url}`);
-  return premint;
-}
+  const premintUid = createdPremint.uid;
+  const premintCollectionAddress = createdPremint.verifyingContract;
+
+  return {
+    // unique id of created premint, which can be used later to 
+    // update or delete the premint
+    uid: premintUid,
+    tokenContract: premintCollectionAddress, 
+  }
+} 
 ```
 
-### Updating a premint:
+### Updating a token that was created for free (before it was brought onchain):
+
+Before a token that was created for free is brought onchain, it can be updated by the original creator of that token, by having that creator sign a message indicating the update. This is useful for updating the tokenURI, other metadata, or token sale configuration (price, duration, limits, etc.):
 
 ```ts
-import { PremintAPI } from "@zoralabs/premint-sdk";
-import type { Address, WalletClient } from "viem";
+import {createPremintClient} from "@zoralabs/protocol-sdk";
+import type {Address, PublicClient, WalletClient} from "viem";
 
-async function updatePremint(walletClient: WalletClient) {
+async function updateCreatedForFreeToken(walletClient: WalletClient, premintUid: number) {
   // Create premint API object passing in the current wallet chain (only zora and zora testnet are supported currently).
-  const premintAPI = createPremintAPI(walletClient.chain);
+  const premintClient = createPremintClient({ chain: walletClient.chain! });
 
-  // Create premint
-  const premint = await premintAPI.updatePremint({
-    // Extra step to check the signature on-chain before attempting to sign
+  // sign a message to update the created for free token, and store the update
+  await premintClient.updatePremint({
     collection: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
-    uid: 23,
+    uid: premintUid,
     // WalletClient doing the signature
     walletClient,
     // Token information, falls back to defaults set in DefaultMintArguments.
@@ -122,73 +287,72 @@ async function updatePremint(walletClient: WalletClient) {
         "ipfs://bafkreice23maski3x52tsfqgxstx3kbiifnt5jotg3a5ynvve53c4soi2u",
     },
   });
-
-  console.log(`updated ZORA premint, link: ${premint.url}`);
-  return premint;
 }
 ```
 
-### Deleting a premint:
+### Deleting a token that was created for free (before it was brought onchain):
+
+Before a token that was created for free is brought onchain, it can be deleted by the original creator of that token, by having that creator sign a message indicating the deletion:
 
 ```ts
-import { PremintAPI } from "@zoralabs/premint-sdk";
-import type { Address, WalletClient } from "viem";
+import {createPremintClient} from "@zoralabs/protocol-sdk";
+import type {Address, PublicClient, WalletClient} from "viem";
 
-async function deletePremint(walletClient: WalletClient) {
-  // Create premint API object passing in the current wallet chain (only zora and zora testnet are supported currently).
-  const premintAPI = createPremintClient({ chain: walletClient.chain });
+async function deleteCreatedForFreeToken(walletClient: WalletClient) {
+  const premintClient = createPremintClient({ chain: walletClient.chain! });
 
-  // Create premint
-  const premint = await premintAPI.deletePremint({
+  // sign a message to delete the premint, and store the deletion
+  await premintClient.deletePremint({
     // Extra step to check the signature on-chain before attempting to sign
     collection: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
     uid: 23,
     // WalletClient doing the signature
     walletClient,
   });
-
-  console.log(`updated ZORA premint, link: ${premint.url}`);
-  return premint;
 }
 ```
 
-### Executing a premint:
+### Minting a token that was created for free (and bringing it onchain):
 
 ```ts
-import { PremintAPI } from "@zoralabs/premint-sdk";
-import type { Address, WalletClient } from "viem";
+import {createPremintClient} from "@zoralabs/protocol-sdk";
+import type {Address, PublicClient, WalletClient} from "viem";
 
-async function executePremint(
+async function mintCreatedForFreeToken(
   walletClient: WalletClient,
-  premintAddress: Address,
-  premintUID: number,
+  publicClient: PublicClient,
+  minterAccount: Address,
 ) {
-  const premintAPI = createPremintClient({ chain: walletClient.chain });
-
-  return await premintAPI.executePremintWithWallet({
-    data: premintAPI.getPremintData(premintAddress, premintUID),
-    walletClient,
+  const premintClient = createPremintClient({ chain: walletClient.chain! });
+
+  const simulateContractParameters = await premintClient.makeMintParameters({
+    account: minterAccount,
+    data: await premintClient.getPremintData({
+      address: "0xf8dA7f53c283d898818af7FB9d98103F559bDac2",
+      uid: 3,
+    }),
     mintArguments: {
       quantityToMint: 1,
+      mintComment: "",
     },
   });
-}
-```
 
-### Deleting a premint:
+  // simulate the transaction and get any validation errors
+  const { request } = await publicClient.simulateContract(simulateContractParameters);
 
-```ts
-import {PremintAPI} from '@zoralabs/premint-sdk';
-import type {Address, WalletClient} from 'viem';
+  // submit the transaction to the network
+  const txHash = await walletClient.writeContract(request);
 
-async function deletePremint(walletClient: WalletClient, collection: Address, uid: number) {
-    const premintAPI = createPremintClient({chain: walletClient.chain});
+  // wait for the transaction to be complete
+  const receipt = await publicClient.waitForTransactionReceipt({hash: txHash});
 
-    return await premintAPI.deletePremint({
-        walletClient,
-        uid,
-        collection
-    });
-}
+  const { urls } = await premintClient.getDataFromPremintReceipt(receipt);
 
-```
+  // block explorer url:
+  console.log(urls.explorer);
+  // collect url:
+  console.log(urls.zoraCollect);
+  // manage url:
+  console.log(urls.zoraManage);
+}
+```

package/dist/apis/http-api-base.d.ts

@@ -23,4 +23,10 @@ export declare const get: <T>(url: string) => Promise<T>;
  */
 export declare const post: <T>(url: string, data: any) => Promise<T>;
 export declare const retries: <T>(tryFn: () => T, maxTries?: number, atTry?: number, linearBackoffMS?: number) => Promise<T>;
+export interface IHttpClient {
+    get: typeof get;
+    post: typeof post;
+    retries: typeof retries;
+}
+export declare const httpClient: IHttpClient;
 //# sourceMappingURL=http-api-base.d.ts.map

package/dist/apis/http-api-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-api-base.d.ts","sourceRoot":"","sources":["../../src/apis/http-api-base.ts"],"names":[],"mappings":"AAAA,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,KAAK;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;gBACI,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG;CAMvD;AAQD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,WAAkB,MAAM,eAcvC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,WAAkB,MAAM,QAAQ,GAAG,eAqBnD,CAAC;AAEF,eAAO,MAAM,OAAO,iCAER,MAAM,UACT,MAAM,oBACI,MAAM,eAexB,CAAC"}
+{"version":3,"file":"http-api-base.d.ts","sourceRoot":"","sources":["../../src/apis/http-api-base.ts"],"names":[],"mappings":"AAAA,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,KAAK;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;gBACI,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG;CAMvD;AAQD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,WAAkB,MAAM,eAcvC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,WAAkB,MAAM,QAAQ,GAAG,eAqBnD,CAAC;AAEF,eAAO,MAAM,OAAO,iCAER,MAAM,UACT,MAAM,oBACI,MAAM,eAexB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,OAAO,GAAG,CAAC;IAChB,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,OAAO,EAAE,OAAO,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,UAAU,EAAE,WAIxB,CAAC"}