@settlemint/sdk-portal 2.2.0 → 2.2.1

package/README.md

@@ -27,9 +27,19 @@
 ## Table of Contents
 
 - [About](#about)
+- [Examples](#examples)
+  - [Deploy contract](#deploy-contract)
+  - [Get pending transactions](#get-pending-transactions)
+  - [Send transaction using hd wallet](#send-transaction-using-hd-wallet)
 - [API Reference](#api-reference)
   - [Functions](#functions)
     - [createPortalClient()](#createportalclient)
+    - [handleWalletVerificationChallenge()](#handlewalletverificationchallenge)
+    - [waitForTransactionReceipt()](#waitfortransactionreceipt)
+  - [Interfaces](#interfaces)
+    - [HandleWalletVerificationChallengeOptions\<Setup\>](#handlewalletverificationchallengeoptionssetup)
+    - [Transaction](#transaction)
+    - [WaitForTransactionReceiptOptions](#waitfortransactionreceiptoptions)
   - [Type Aliases](#type-aliases)
     - [ClientOptions](#clientoptions)
     - [RequestConfig](#requestconfig)
@@ -43,8 +53,310 @@
 The SettleMint Smart Contract Portal SDK provides a seamless way to interact with the Smart Contract Portal Middleware API. It enables you to easily interact with your smart contracts using a REST or GraphQL API.
 
 The SDK offers a type-safe interface for all Portal API operations, with comprehensive error handling and validation. It integrates smoothly with modern TypeScript applications while providing a simple and intuitive developer experience.
+## Examples
 
-For detailed information about using the Smart Contract Portal Middleware, check out our [official documentation](https://console.settlemint.com/documentation).
+### Deploy contract
+
+```ts
+/**
+ * This example demonstrates how to deploy a contract.
+ *
+ * The process involves:
+ * 1. Creating a portal client
+ * 2. Deploying a forwarder contract
+ * 3. Waiting for the forwarder contract deployment to be finalized
+ * 4. Deploying a stablecoin factory contract
+ * 5. Getting all contracts and filtering by ABI name
+ *
+ * This pattern is useful for applications that need to deploy smart contracts
+ * in the SettleMint Portal, providing a way to track the progress of blockchain operations.
+ */
+import { loadEnv } from "@settlemint/sdk-utils/environment";
+import { createLogger, requestLogger } from "@settlemint/sdk-utils/logging";
+import { getAddress } from "viem";
+import { createPortalClient } from "../portal.js"; // Replace this path with "@settlemint/sdk-portal"
+import { waitForTransactionReceipt } from "../utils/wait-for-transaction-receipt.js";
+import type { introspection } from "./schemas/portal-env.d.ts"; // Replace this path with the generated introspection type
+
+const env = await loadEnv(false, false);
+const logger = createLogger();
+
+const { client: portalClient, graphql: portalGraphql } = createPortalClient<{
+  introspection: introspection;
+  disableMasking: true;
+  scalars: {
+    // Change unknown to the type you are using to store metadata
+    JSON: unknown;
+  };
+}>(
+  {
+    instance: env.SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT!,
+    accessToken: env.SETTLEMINT_ACCESS_TOKEN!,
+  },
+  {
+    fetch: requestLogger(logger, "portal", fetch) as typeof fetch,
+  },
+);
+
+// Replace with the address of your private key which you use to deploy smart contracts
+const FROM = getAddress("0x4B03331cF2db1497ec58CAa4AFD8b93611906960");
+
+/**
+ * Deploy a forwarder contract
+ */
+const deployForwarder = await portalClient.request(
+  portalGraphql(`
+    mutation DeployContractForwarder($from: String!) {
+      DeployContractForwarder(from: $from, gasLimit: "0x3d0900") {
+        transactionHash
+      }
+    }
+  `),
+  {
+    from: FROM,
+  },
+);
+
+/**
+ * Wait for the forwarder contract deployment to be finalized
+ */
+const transaction = await waitForTransactionReceipt(deployForwarder.DeployContractForwarder?.transactionHash!, {
+  portalGraphqlEndpoint: env.SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT!,
+  accessToken: env.SETTLEMINT_ACCESS_TOKEN!,
+});
+
+/**
+ * Deploy a stablecoin factory contract
+ */
+const deployStableCoinFactory = await portalClient.request(
+  portalGraphql(`
+    mutation DeployContractStableCoinFactory($from: String!, $constructorArguments: DeployContractStableCoinFactoryInput!) {
+      DeployContractStableCoinFactory(from: $from, constructorArguments: $constructorArguments, gasLimit: "0x3d0900") {
+        transactionHash
+      }
+    }
+  `),
+  {
+    from: FROM,
+    constructorArguments: {
+      forwarder: getAddress(transaction?.receipt.contractAddress!),
+    },
+  },
+);
+
+console.log(deployStableCoinFactory?.DeployContractStableCoinFactory?.transactionHash);
+
+const contractAddresses = await portalClient.request(
+  portalGraphql(`
+    query GetContracts {
+        getContracts {
+            count
+            records {
+                address
+                abiName
+                createdAt
+            }
+        }
+    }
+  `),
+);
+// Print total count
+console.log(`Total contracts: ${contractAddresses.getContracts?.count}`);
+
+// Contracts for StableCoinFactory
+console.log(contractAddresses.getContracts?.records.filter((record) => record.abiName === "StableCoinFactory"));
+
+```
+### Get pending transactions
+
+```ts
+/**
+ * This example demonstrates how to get the number of pending transactions.
+ *
+ * The process involves:
+ * 1. Creating a portal client
+ * 2. Making a GraphQL query to get the number of pending transactions
+ *
+ * This pattern is useful for applications that need to monitor the status of pending transactions
+ * in the SettleMint Portal, providing a way to track the progress of blockchain operations.
+ */
+import { loadEnv } from "@settlemint/sdk-utils/environment";
+import { createLogger, requestLogger } from "@settlemint/sdk-utils/logging";
+import { createPortalClient } from "../portal.js"; // Replace this path with "@settlemint/sdk-portal"
+import type { introspection } from "./schemas/portal-env.d.ts"; // Replace this path with the generated introspection type
+
+const env = await loadEnv(false, false);
+const logger = createLogger();
+
+const { client: portalClient, graphql: portalGraphql } = createPortalClient<{
+  introspection: introspection;
+  disableMasking: true;
+  scalars: {
+    // Change unknown to the type you are using to store metadata
+    JSON: unknown;
+  };
+}>(
+  {
+    instance: env.SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT!,
+    accessToken: env.SETTLEMINT_ACCESS_TOKEN!,
+  },
+  {
+    fetch: requestLogger(logger, "portal", fetch) as typeof fetch,
+  },
+);
+
+// Making GraphQL queries
+const query = portalGraphql(`
+  query GetPendingTransactions {
+    getPendingTransactions {
+      count
+    }
+  }
+`);
+
+const result = await portalClient.request(query);
+console.log(`There are ${result.getPendingTransactions?.count} pending transactions`);
+
+```
+### Send transaction using hd wallet
+
+```ts
+/**
+ * This example demonstrates how to send a transaction using an HD wallet.
+ *
+ * The process involves:
+ * 1. Creating a wallet for a user using the HD private key
+ * 2. Setting up a pincode for wallet verification
+ * 3. Handling the wallet verification challenge
+ * 4. Sending a transaction to the blockchain
+ *
+ * This pattern is useful for applications that need to manage multiple user wallets
+ * derived from a single HD wallet, providing a secure and scalable approach to
+ * blockchain interactions in enterprise applications.
+ */
+import { loadEnv } from "@settlemint/sdk-utils/environment";
+import { createLogger, requestLogger } from "@settlemint/sdk-utils/logging";
+import type { Address } from "viem";
+import { createPortalClient } from "../portal.js"; // Replace this path with "@settlemint/sdk-portal"
+import { handleWalletVerificationChallenge } from "../utils/wallet-verification-challenge.js"; // Replace this path with "@settlemint/sdk-portal"
+import type { introspection } from "./schemas/portal-env.js"; // Replace this path with the generated introspection type
+
+const env = await loadEnv(false, false);
+const logger = createLogger();
+
+const { client: portalClient, graphql: portalGraphql } = createPortalClient<{
+  introspection: introspection;
+  disableMasking: true;
+  scalars: {
+    // Change unknown to the type you are using to store metadata
+    JSON: unknown;
+  };
+}>(
+  {
+    instance: env.SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT!,
+    accessToken: env.SETTLEMINT_ACCESS_TOKEN!,
+  },
+  {
+    fetch: requestLogger(logger, "portal", fetch) as typeof fetch,
+  },
+);
+
+/**
+ * First create a wallet using the HD private key, this needs to be done for every user that is using your app
+ */
+const wallet = await portalClient.request(
+  portalGraphql(`
+    mutation createUserWallet($keyVaultId: String!, $name: String!) {
+      createWallet(keyVaultId: $keyVaultId, walletInfo: { name: $name }) {
+        address
+      }
+    }
+  `),
+  {
+    keyVaultId: env.SETTLEMINT_HD_PRIVATE_KEY!,
+    name: "My Wallet",
+  },
+);
+
+/**
+ * Set a pincode for the wallet, this is used to verify the wallet when the user is sending a transaction to the chain
+ */
+const pincodeVerification = await portalClient.request(
+  portalGraphql(`
+    mutation setPinCode($address: String!, $pincode: String!) {
+      createWalletVerification(
+        userWalletAddress: $address
+        verificationInfo: {pincode: {name: "PINCODE", pincode: $pincode}}
+      ) {
+        id
+        name
+        parameters
+        verificationType
+      }
+    }
+    `),
+  {
+    address: wallet.createWallet?.address!,
+    pincode: "123456",
+  },
+);
+
+/**
+ * Generate a challenge response for the pincode verification
+ */
+const challengeResponse = await handleWalletVerificationChallenge({
+  portalClient,
+  portalGraphql,
+  verificationId: pincodeVerification.createWalletVerification?.id!,
+  userWalletAddress: wallet.createWallet?.address! as Address,
+  code: "123456",
+  verificationType: "pincode",
+});
+
+/**
+ * Send a transaction to the chain
+ * This is a sample of how to send a transaction to the chain using the portal client and the asset tokenization kit
+ * The challenge response is generated using the handleWalletVerificationChallenge function, this is used to verifiy wallet access
+ * @see https://github.com/settlemint/asset-tokenization-kit
+ */
+const result = await portalClient.request(
+  portalGraphql(`
+    mutation StableCoinFactoryCreate(
+      $challengeResponse: String!
+      $verificationId: String
+      $address: String!
+      $from: String!
+      $input: StableCoinFactoryCreateInput!
+    ) {
+      StableCoinFactoryCreate(
+        challengeResponse: $challengeResponse
+        verificationId: $verificationId
+        address: $address
+        from: $from
+        input: $input
+      ) {
+        transactionHash
+      }
+    }
+  `),
+  {
+    challengeResponse: challengeResponse.challengeResponse,
+    verificationId: pincodeVerification.createWalletVerification?.id!,
+    address: "0x5e771e1417100000000000000000000000000004",
+    from: wallet.createWallet?.address!,
+    input: {
+      name: "Test Coin",
+      symbol: "TEST",
+      decimals: 18,
+      collateralLivenessSeconds: 3_600,
+    },
+  },
+);
+
+// Log the transaction hash
+console.log("Transaction hash:", result.StableCoinFactoryCreate?.transactionHash);
+
+```
 
 ## API Reference
 
@@ -54,7 +366,7 @@ For detailed information about using the Smart Contract Portal Middleware, check
 
 > **createPortalClient**\<`Setup`\>(`options`, `clientOptions?`): `object`
 
-Defined in: [sdk/portal/src/portal.ts:66](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L66)
+Defined in: [sdk/portal/src/portal.ts:71](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L71)
 
 Creates a Portal GraphQL client with the provided configuration.
 
@@ -82,8 +394,8 @@ An object containing the configured GraphQL client and graphql helper function
 
 | Name | Type | Defined in |
 | ------ | ------ | ------ |
-| `client` | `GraphQLClient` | [sdk/portal/src/portal.ts:70](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L70) |
-| `graphql` | `initGraphQLTada`\<`Setup`\> | [sdk/portal/src/portal.ts:71](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L71) |
+| `client` | `GraphQLClient` | [sdk/portal/src/portal.ts:75](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L75) |
+| `graphql` | `initGraphQLTada`\<`Setup`\> | [sdk/portal/src/portal.ts:76](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L76) |
 
 ##### Throws
 
@@ -92,28 +404,33 @@ If the provided options fail validation
 ##### Example
 
 ```ts
-import { createPortalClient } from '@settlemint/sdk-portal';
+import { createPortalClient } from "@settlemint/sdk-portal";
+import { loadEnv } from "@settlemint/sdk-utils/environment";
+import { createLogger, requestLogger } from "@settlemint/sdk-utils/logging";
 import type { introspection } from "@schemas/portal-env";
-import { createLogger, requestLogger } from '@settlemint/sdk-utils/logging';
 
+const env = await loadEnv(false, false);
 const logger = createLogger();
 
-export const { client: portalClient, graphql: portalGraphql } = createPortalClient<{
+const { client: portalClient, graphql: portalGraphql } = createPortalClient<{
   introspection: introspection;
   disableMasking: true;
   scalars: {
     // Change unknown to the type you are using to store metadata
     JSON: unknown;
   };
-}>({
-  instance: process.env.SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT,
-  accessToken: process.env.SETTLEMINT_ACCESS_TOKEN,
-}, {
-  fetch: requestLogger(logger, "portal", fetch) as typeof fetch,
-});
+}>(
+  {
+    instance: env.SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT!,
+    accessToken: env.SETTLEMINT_ACCESS_TOKEN!,
+  },
+  {
+    fetch: requestLogger(logger, "portal", fetch) as typeof fetch,
+  },
+);
 
 // Making GraphQL queries
-const query = graphql(`
+const query = portalGraphql(`
   query GetPendingTransactions {
     getPendingTransactions {
       count
@@ -121,16 +438,139 @@ const query = graphql(`
   }
 `);
 
-const result = await client.request(query);
+const result = await portalClient.request(query);
+```
+
+***
+
+#### handleWalletVerificationChallenge()
+
+> **handleWalletVerificationChallenge**\<`Setup`\>(`options`): `Promise`\<\{ `challengeResponse`: `string`; `verificationId?`: `string`; \}\>
+
+Defined in: [sdk/portal/src/utils/wallet-verification-challenge.ts:106](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/utils/wallet-verification-challenge.ts#L106)
+
+Handles a wallet verification challenge by generating an appropriate response
+
+##### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `Setup` *extends* `AbstractSetupSchema` |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options` | [`HandleWalletVerificationChallengeOptions`](#handlewalletverificationchallengeoptions)\<`Setup`\> | The options for handling the wallet verification challenge |
+
+##### Returns
+
+`Promise`\<\{ `challengeResponse`: `string`; `verificationId?`: `string`; \}\>
+
+Promise resolving to an object containing the challenge response and optionally the verification ID
+
+##### Throws
+
+If the challenge cannot be created or is invalid
+
+##### Example
+
+```ts
+import { createPortalClient } from "@settlemint/sdk-portal";
+import { handleWalletVerificationChallenge } from "@settlemint/sdk-portal";
+
+const { client, graphql } = createPortalClient({
+  instance: "https://portal.example.com/graphql",
+  accessToken: "your-access-token"
+});
+
+const result = await handleWalletVerificationChallenge({
+  portalClient: client,
+  portalGraphql: graphql,
+  verificationId: "verification-123",
+  userWalletAddress: "0x123...",
+  code: "123456",
+  verificationType: "otp"
+});
+```
+
+***
+
+#### waitForTransactionReceipt()
+
+> **waitForTransactionReceipt**(`transactionHash`, `options`): `Promise`\<[`Transaction`](#transaction)\>
+
+Defined in: [sdk/portal/src/utils/wait-for-transaction-receipt.ts:82](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/utils/wait-for-transaction-receipt.ts#L82)
+
+Waits for a blockchain transaction receipt by subscribing to transaction updates via GraphQL.
+This function polls until the transaction is confirmed or the timeout is reached.
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `transactionHash` | `string` | The hash of the transaction to wait for |
+| `options` | [`WaitForTransactionReceiptOptions`](#waitfortransactionreceiptoptions) | Configuration options for the waiting process |
+
+##### Returns
+
+`Promise`\<[`Transaction`](#transaction)\>
+
+The transaction details including receipt information when the transaction is confirmed
+
+##### Throws
+
+Error if the transaction receipt cannot be retrieved within the specified timeout
+
+##### Example
+
+```ts
+import { waitForTransactionReceipt } from "@settlemint/sdk-portal";
+
+const transaction = await waitForTransactionReceipt("0x123...", {
+  portalGraphqlEndpoint: "https://example.settlemint.com/graphql",
+  accessToken: "your-access-token",
+  timeout: 30000 // 30 seconds timeout
+});
 ```
 
+### Interfaces
+
+#### HandleWalletVerificationChallengeOptions\<Setup\>
+
+Defined in: [sdk/portal/src/utils/wallet-verification-challenge.ts:73](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/utils/wallet-verification-challenge.ts#L73)
+
+Options for handling a wallet verification challenge
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `Setup` *extends* `AbstractSetupSchema` | The GraphQL schema setup type |
+
+***
+
+#### Transaction
+
+Defined in: [sdk/portal/src/utils/wait-for-transaction-receipt.ts:25](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/utils/wait-for-transaction-receipt.ts#L25)
+
+Represents the structure of a blockchain transaction with its receipt
+
+***
+
+#### WaitForTransactionReceiptOptions
+
+Defined in: [sdk/portal/src/utils/wait-for-transaction-receipt.ts:58](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/utils/wait-for-transaction-receipt.ts#L58)
+
+Options for waiting for a transaction receipt
+
 ### Type Aliases
 
 #### ClientOptions
 
 > **ClientOptions** = `object`
 
-Defined in: [sdk/portal/src/portal.ts:24](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L24)
+Defined in: [sdk/portal/src/portal.ts:24](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L24)
 
 Type representing the validated client options.
 
@@ -138,9 +578,9 @@ Type representing the validated client options.
 
 | Name | Type | Default value | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="accesstoken"></a> `accessToken` | `string` | `ApplicationAccessTokenSchema` | [sdk/portal/src/portal.ts:17](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L17) |
-| <a id="cache"></a> `cache?` | `"default"` \| `"force-cache"` \| `"no-cache"` \| `"no-store"` \| `"only-if-cached"` \| `"reload"` | - | [sdk/portal/src/portal.ts:18](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L18) |
-| <a id="instance"></a> `instance` | `string` | `UrlOrPathSchema` | [sdk/portal/src/portal.ts:16](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L16) |
+| <a id="accesstoken"></a> `accessToken` | `string` | `ApplicationAccessTokenSchema` | [sdk/portal/src/portal.ts:17](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L17) |
+| <a id="cache"></a> `cache?` | `"default"` \| `"force-cache"` \| `"no-cache"` \| `"no-store"` \| `"only-if-cached"` \| `"reload"` | - | [sdk/portal/src/portal.ts:18](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L18) |
+| <a id="instance"></a> `instance` | `string` | `UrlOrPathSchema` | [sdk/portal/src/portal.ts:16](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L16) |
 
 ***
 
@@ -148,7 +588,7 @@ Type representing the validated client options.
 
 > **RequestConfig** = `ConstructorParameters`\<*typeof* `GraphQLClient`\>\[`1`\]
 
-Defined in: [sdk/portal/src/portal.ts:10](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L10)
+Defined in: [sdk/portal/src/portal.ts:10](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L10)
 
 Configuration options for the GraphQL client, excluding 'url' and 'exchanges'.
 
@@ -158,7 +598,7 @@ Configuration options for the GraphQL client, excluding 'url' and 'exchanges'.
 
 > `const` **ClientOptionsSchema**: `ZodObject`\<[`ClientOptions`](#clientoptions)\>
 
-Defined in: [sdk/portal/src/portal.ts:15](https://github.com/settlemint/sdk/blob/v2.2.0/sdk/portal/src/portal.ts#L15)
+Defined in: [sdk/portal/src/portal.ts:15](https://github.com/settlemint/sdk/blob/v2.2.1/sdk/portal/src/portal.ts#L15)
 
 Schema for validating Portal client configuration options.