docs update Sequence Pay (#197)

* docs update * updated documentation for kit-checkout * better paragraph * fix docs * docs fix * more params * explanation about decimals
0xsequence · Dec 16, 2024 · 0e4e389 · 0e4e389
1 parent 37d0c64
commit 0e4e389
Show file tree

Hide file tree

Showing 4 changed files with 186 additions and 78 deletions.
diff --git a/packages/checkout/README.md b/packages/checkout/README.md
@@ -1,10 +1,12 @@
 # Sequence Kit Checkout
 
-<div align="center">
-  <img src="../../public/docs/checkout-modal.png">
-</div>
+Sequence Checkout provides a seamless and flexible payment experience for interacting with NFTs, cryptocurrencies, and fiat currencies. It supports multiple payment options, including cryptocurrency transfers, currency swaps, and even credit card payments for whitelisted contracts.
 
-Checkout modal for Sequence Kit. Displays a list a summary of collectibles to be purchased
+## Key Features
+
+- **NFT Checkout**: Buy NFTs using either the main currency (e.g., ETH), a swapped currency, or a credit card.
+- **Currency Swap**: Swap one token for another before completing the transaction.
+- **Fiat Onramp**: Onboard users with fiat currency to interact with the blockchain.
 
 # Installing the module
 
@@ -34,115 +36,221 @@ const App = () => {
 }
 ```
 
-## Open the checkout modal
+# NFT Checkout (Sequence Pay)
+
+<div align="center">
+  <img src="../../public/docs/checkout-modal.png">
+</div>
+
+Sequence Pay Checkout allows users to purchase NFTs using various payment methods. Users can pay with the main currency (e.g., ETH), swap tokens for payment, or use a credit card provided the smart contract is whitelisted (contact a member of the Sequence team to whitelist your contract for credit card payments).
 
-The `useCheckoutModal` hook must be used to open the modal.
-Furthermore, it is necessary to pass a settings object.
+## Basic Usage
+
+To enable this functionality in your app, use the `useSelectPaymentModal` hook from the `@0xsequence/kit-checkout` package. The following code demonstrates how to set up the checkout modal and trigger it on a button click:
 
 ```js
-  import { useCheckoutModal } from '@0xsequence/kit-checkout'
+import { useSelectPaymentModal, type SelectPaymentSettings } from '@0xsequence/kit-checkout'
 
+const MyComponent = () => {
+  const { openSelectPaymentModal } = useSelectPaymentModal()
 
-  const MyComponent = () => {
-    const { triggerCheckout } = useCheckoutModal()
+  const onClick = () => {
+    const erc1155SalesContractAbi = [
+      {
+        type: 'function',
+        name: 'mint',
+        inputs: [
+          { name: 'to', type: 'address', internalType: 'address' },
+          { name: 'tokenIds', type: 'uint256[]', internalType: 'uint256[]' },
+          { name: 'amounts', type: 'uint256[]', internalType: 'uint256[]' },
+          { name: 'data', type: 'bytes', internalType: 'bytes' },
+          { name: 'expectedPaymentToken', type: 'address', internalType: 'address' },
+          { name: 'maxTotal', type: 'uint256', internalType: 'uint256' },
+          { name: 'proof', type: 'bytes32[]', internalType: 'bytes32[]' }
+        ],
+        outputs: [],
+        stateMutability: 'payable'
+      }
+    ]
+
+    const purchaseTransactionData = encodeFunctionData({
+      abi: erc1155SalesContractAbi,
+      functionName: 'mint',
+      args: [
+        recipientAddress,
+        collectibles.map(c => BigInt(c.tokenId)),
+        collectibles.map(c => BigInt(c.quantity)),
+        toHex(0),
+        currencyAddress,
+        price,
+        [toHex(0, { size: 32 })]
+      ]
+    })
 
-    const onClick = () => {
-      const checkoutSettings = {...}
-      triggerCheckout(checkoutSettings)
+    const settings: SelectPaymentSettings = {
+      collectibles: [
+        {
+          tokenId: '1',
+          quantity: '1'
+        }
+      ],
+      chain: chainId,
+      price,
+      targetContractAddress: salesContractAddress,
+      recipientAddress: address,
+      currencyAddress,
+      collectionAddress,
+      creditCardProviders: ['sardine'],
+      copyrightText: 'ⓒ2024 Sequence',
+      onSuccess: (txnHash: string) => {
+        console.log('success!', txnHash)
+      },
+      onError: (error: Error) => {
+        console.error(error)
+      },
+      txData: purchaseTransactionData,
     }
 
-    return (
-      <button onClick={onClick}>checkout</button>
-    )
+    openSelectPaymentModal(settings)
   }
 
+  return <button onClick={onClick}>Purchase collectible</button>
+}
 ```
 
-## Configuration
+## Parameters
+
+- **collectibles**: List of NFT collectibles, including their token IDs and quantities.
+- **chain**: The blockchain network ID.
+- **price**: Total price for the transaction in the selected currency. This value should not contain decimals.
+- **currencyAddress**: The address of the currency used for executing the transaction on the target contract.
+- **targetContractAddress**: The address of the smart contract handling the minting function.
+  creditCardProviders: Providers like sardine for credit card payments.
+- **collectionAddress**: The contract address of the collectible such as an ERC-1155 or ERC-721
+- **creditCardProviders**: The list of credit card providers to execute a payment with. It is up to the developer to make sure that the region, currency and network is compatible.
+- **txData**: Encoded transaction data to interact with the mint function.
+- **copyrightText**: The copyright text shown at the bottom of the modal.
+- **onSuccess**: Callback function triggered once the transaction has been confirmed on the blockchain
+- **onError**: Callback function triggered if an error has occurred before or after sending the transaction.
 
-The react example has an example configuration for setting up the checkout.
+## Utility functions
 
-Example [settings](../../examples/react/src/utils/settings.ts)
+The `@0xsequence/kit-checkout` library indeed simplifies the integration of Web3 payment solutions by providing utility functions. One such function, `useERC1155SaleContractPaymentModal`, is tailored for use cases involving the minting of ERC-1155 tokens. This function works in conjunction with Sequence's wallet ecosystem and its deployable smart contract infrastructure, such as the ERC-1155 sale contract available through the [Sequence Builder](https://sequence.build).
 
 ```js
-const checkoutSettings = {
-  creditCardCheckout: {...},
-  cryptoCheckout: {...},
-  orderSummaryItems: {...}
-}
-```
+import { useERC1155SaleContractPaymentModal } from '@0xsequence/kit-checkout'
 
-### cryptoCheckout
+const MyComponent = () => {
+  const { openERC1155SaleContractPaymentModal } = useERC1155SaleContractPaymentModal()
 
-The `cryptoCheckout` specifies settings regarding checking out with crypto.
-An example usecase might be interacting with a minting contract.
 
-The actual cryptoTransaction must be passed down to `triggerCheckout`.
+  const onClick = () => {
+    if (!address) {
+      return
+    }
+    // // ERC-20 contract
+    const currencyAddress = '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
+    const salesContractAddress = '0xe65b75eb7c58ffc0bf0e671d64d0e1c6cd0d3e5b'
+    const collectionAddress = '0xdeb398f41ccd290ee5114df7e498cf04fac916cb'
+    const price = '20000'
+
+    const chainId = 137
+
+    openERC1155SaleContractPaymentModal({
+      collectibles: [
+        {
+          tokenId: '1',
+          quantity: '1'
+        }
+      ],
+      chain: chainId,
+      price,
+      targetContractAddress: salesContractAddress,
+      recipientAddress: address,
+      currencyAddress,
+      collectionAddress,
+      creditCardProviders: ['sardine'],
+      isDev: true,
+      copyrightText: 'ⓒ2024 Sequence',
+      onSuccess: (txnHash: string) => {
+        console.log('success!', txnHash)
+      },
+      onError: (error: Error) => {
+        console.error(error)
+      }
+    })
+  }
 
-```js
-const checkoutConfig = {
-  {...},
-  cryptoCheckout: {
-    chainId: 137,
-    triggerTransaction: async () => { console.log('triggered transaction') },
-    coinQuantity: {
-      contractAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
-      amountRequiredRaw: '10000000000'
-    },
-  },
+  return <button onClick={onClick}>Buy ERC-1155 collectble!</button>
 }
 ```
 
-### creditCardCheckout
+# Swap
+
+<div align="center">
+  <img src="../../public/docs/swap-modal.png">
+</div>
+
+The **Swap Modal** allows users to swap one currency for another (e.g., ETH to USDC) before completing a transaction. This feature is useful when users need to convert their tokens into the correct currency for payment.
 
-The `creditCardCheckout` field specifies settings regarding checking out with credit card.
+## Basic Usage
 
-`triggerCheckout` must be called in order to open the checkout modal.
+Here’s an example of how to use the Swap Modal with the `useSwapModal` hook:
 
 ```js
-const creditCardCheckout = {
-  {...},
-  cryptoCheckout: {
-      defaultPaymentMethodType: 'us_debit',
-      onSuccess: (hash) => { console.log('credit card checkout success', hash) },
-      onError: (e) => { console.log('credit card checkout error', e) },
+import { useSwapModal, type SwapModalSettings } from '@0xsequence/kit-checkout'
+
+const MyComponent = () => {
+  const { openSwapModal } = useSwapModal()
+
+  const onClick = () => {
+    const chainId = 137
+    const currencyAddress = '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
+    const currencyAmount = '20000'
+
+    const contractAbiInterface = new ethers.Interface(['function demo()'])
+
+    const data = contractAbiInterface.encodeFunctionData('demo', []) as `0x${string}`
+
+    const swapModalSettings: SwapModalSettings = {
+      onSuccess: () => {
+        console.log('swap successful!')
+      },
       chainId,
-      contractAddress: orderbookAddress,
-      recipientAddress,
-      currencyQuantity: '100000',
-      currencySymbol: 'USDC',
-      currencyAddress: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
-      currencyDecimals: '6',
-      nftId: checkoutTokenId,
-      nftAddress: checkoutTokenContractAddress,
-      nftQuantity,
-      isDev: true,
-      calldata: getOrderbookCalldata({
-        orderId: checkoutOrderId,
-        quantity: nftQuantity,
-        recipient: recipientAddress
-      })
-  },
+      currencyAddress,
+      currencyAmount,
+      postSwapTransactions: [
+        {
+          to: '0x37470dac8a0255141745906c972e414b1409b470',
+          data
+        }
+      ],
+      title: 'Swap and Pay',
+      description: 'Select a token in your wallet to swap to 0.2 USDC.'
+    }
+
+    openSwapModal(swapModalSettings)
+  }
+
+  return <button onClick={onClick}>Swap and Pay</button>
 }
 ```
 
-### orderSummaryItems
+## Key Parameters
 
-This field specific the list of collectibles that will show up in the order summary.
+- **currencyAddress**: The address of the token to swap from (e.g., USDC).
+- **currencyAmount**: The amount to swap.
+- **postSwapTransactions**: An optional array of transactions to be executed after the swap, using the swapped tokens.
+- **title**: The modal’s title.
+- **description**: A description of the swap and payment process.
 
-```js
-orderSummaryItems: [
-  {
-    contractAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e',
-    tokenId: '66597',
-    quantityRaw: '100'
-  }
-]
-```
+# Fiat Onramp
 
-## Open the Add Funds by Credit Card Modal
+<div align="center">
+  <img src="../../public/docs/fiat-onramp.png">
+</div>
 
-Kit allows users to buy cryptocurrencies using credit card. Calling the `triggerAddFunds` function will cause a modal to appear.
+The Fiat Onramp feature allows users to convert traditional fiat currencies (e.g., USD) into cryptocurrencies. This feature makes it easier for non-crypto users to interact with decentralized applications (dApps) by onboarding them directly through fiat payments.
 
 ```js
 import { useAddFundsModal } from '@0xsequence/kit-checkout'

diff --git a/public/docs/checkout-modal.png b/public/docs/checkout-modal.png
diff --git a/public/docs/fiat-onramp.png b/public/docs/fiat-onramp.png
diff --git a/public/docs/swap-modal.png b/public/docs/swap-modal.png