JSPM

@settlemint/sdk-portal

2.2.0-pr3e5ba083
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 6319
  • Score
    100M100P100Q124130F
  • License FSL-1.1-MIT

Portal API client module for SettleMint SDK, providing access to smart contract portal services and APIs

Package Exports

  • @settlemint/sdk-portal
  • @settlemint/sdk-portal/package.json

Readme

SettleMint logo

SettleMint SDK

https://settlemint.com
Integrate SettleMint into your application with ease.

CI status License npm stars

Documentation   •   NPM   •   Issues

Table of Contents

About

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

Get pending transactions

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`);

Deploy contract

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);

Send transaction using hd wallet

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

Functions

createPortalClient()

createPortalClient<Setup>(options, clientOptions?): object

Defined in: sdk/portal/src/portal.ts:71

Creates a Portal GraphQL client with the provided configuration.

Type Parameters
Type Parameter
Setup extends AbstractSetupSchema
Parameters
Parameter Type Description
options { accessToken: string; cache?: "default" | "force-cache" | "no-cache" | "no-store" | "only-if-cached" | "reload"; instance: string; } Configuration options for the Portal client
options.accessToken string -
options.cache? "default" | "force-cache" | "no-cache" | "no-store" | "only-if-cached" | "reload" -
options.instance? string -
clientOptions? RequestConfig Additional GraphQL client configuration options
Returns

object

An object containing the configured GraphQL client and graphql helper function

Name Type Defined in
client GraphQLClient sdk/portal/src/portal.ts:75
graphql initGraphQLTada<Setup> sdk/portal/src/portal.ts:76
Throws

If the provided options fail validation

Example
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";

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);

handleWalletVerificationChallenge()

handleWalletVerificationChallenge<Setup>(options): Promise<{ challengeResponse: string; verificationId?: string; }>

Defined in: sdk/portal/src/utils/wallet-verification-challenge.ts:106

Handles a wallet verification challenge by generating an appropriate response

Type Parameters
Type Parameter
Setup extends AbstractSetupSchema
Parameters
Parameter Type Description
options 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
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<undefined | Transaction>

Defined in: sdk/portal/src/utils/wait-for-transaction-receipt.ts:70

Wait for the transaction receipt

Parameters
Parameter Type Description
transactionHash string transaction hash
options WaitForTransactionReceiptOptions options
Returns

Promise<undefined | Transaction>

receipt

Interfaces

HandleWalletVerificationChallengeOptions<Setup>

Defined in: sdk/portal/src/utils/wallet-verification-challenge.ts:73

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

Represents the structure of a blockchain transaction with its receipt


WaitForTransactionReceiptOptions

Defined in: sdk/portal/src/utils/wait-for-transaction-receipt.ts:58

Options for waiting for a transaction receipt

Type Aliases

ClientOptions

ClientOptions = object

Defined in: sdk/portal/src/portal.ts:24

Type representing the validated client options.

Type declaration
Name Type Default value Defined in
accessToken string ApplicationAccessTokenSchema sdk/portal/src/portal.ts:17
cache? "default" | "force-cache" | "no-cache" | "no-store" | "only-if-cached" | "reload" - sdk/portal/src/portal.ts:18
instance string UrlOrPathSchema sdk/portal/src/portal.ts:16

RequestConfig

RequestConfig = ConstructorParameters<*typeof* GraphQLClient>[1]

Defined in: sdk/portal/src/portal.ts:10

Configuration options for the GraphQL client, excluding 'url' and 'exchanges'.

Variables

ClientOptionsSchema

const ClientOptionsSchema: ZodObject<ClientOptions>

Defined in: sdk/portal/src/portal.ts:15

Schema for validating Portal client configuration options.

Contributing

We welcome contributions from the community! Please check out our Contributing guide to learn how you can help improve the SettleMint SDK through bug reports, feature requests, documentation updates, or code contributions.

License

The SettleMint SDK is released under the FSL Software License. See the LICENSE file for more details.