Skip to main content

WalletStamper

Introduction​

The @turnkey/wallet-stamper package provides a flexible mechanism for using your Solana or EVM wallet to stamp and approve activity requests for Turnkey's API. This stamping process leverages your wallet's signature key to authenticate requests securely.

Installing​

To get started, install the @turnkey/wallet-stamper client.

npm i @turnkey/wallet-stamper

Initializing​

The WalletStamper class implements the TStamper interface used by the TurnkeyClient in the @turnkey/http package. It encapsulates the logic necessary to sign activity requests using your wallet and generate the appropriate HTTP headers for authentication.

constructor(wallet: WalletInterface): TStamper​

Parameters​

walletWalletInterfacerequired

An object representing your wallet, either a Solana or EVM wallet.

.type"solana" | "evm"required

The type of wallet, either solana or evm.

.signMessagefunctionrequired

A function that signs a message using your wallet's private key.

.recoverPublicKeyfunctionrequired

A function that recovers the public key from the signed message (required for EVM wallets).

Types​

SolanaWalletInterface​
export interface SolanaWalletInterface extends BaseWalletInterface {
  recoverPublicKey: () => string;
  type: "solana";
}
EvmWalletInterface​
export interface EvmWalletInterface extends BaseWalletInterface {
  recoverPublicKey: (message: string, signature: string) => Promise<string>;
  type: "evm";
}
WalletInterface​
export type WalletInterface = SolanaWalletInterface | EvmWalletInterface;

Methods​

stamp: (input: string) => Promise<TStamp>​

Signs the payload using the wallet's private key and returns the stamp to be used in the HTTP headers for authenticating requests to Turnkey's API.

Parameters​

payloadstringrequired

The payload that to be stamped. This is the stringified JSON request body that you want to send to Turnkey's API.

Types​

TStamp​
type TStamp = {
  stampHeaderName: string;
  stampHeaderValue: string;
};
TStamper​
interface TStamper {
  stamp: (input: string) => Promise<TStamp>;
}

Example​

The example below shows how to initialize and use the WalletStamper with the TurnkeyClient to make a request to Turnkey's /public/v1/query/whoami endpoint:

// Import the dependencies for the Solana
import { Keypair } from "@solana/web3.js";
import { decodeUTF8 } from "tweetnacl-util";
import nacl from "tweetnacl";

import { TurnkeyClient } from "@turnkey/http";
import { WalletStamper, SolanaWalletInterface } from "@turnkey/wallet-stamper";

class SolanaWallet implements SolanaWalletInterface {
  keypair = Keypair.fromSecretKey(SOLANA_PRIVATE_KEY);
  type = "solana" as const;

  async signMessage(message: string): Promise<string> {
    const messageBytes = decodeUTF8(message);
    const signature = nacl.sign.detached(messageBytes, this.keypair.secretKey);
    return Buffer.from(signature).toString("hex");
  }

  recoverPublicKey(): string {
    // Convert the base24 encoded Solana wallet public key (the one displayed in the wallet)
    // into the ed25519 decoded public key
    const ed25519PublicKey = Buffer.from(
      this.keypair.publicKey.toBuffer(),
    ).toString("hex");
    return ed25519PublicKey;
  }
}

// Instantiate the WalletStamper with the SolanaWallet
const walletStamper = new WalletStamper(new SolanaWallet());

// Instantiate the TurnkeyClient with the WalletStamper
const client = new TurnkeyClient({ baseUrl: BASE_URL }, walletStamper);

// You're now ready to make requests to Turnkey's API 🎉

Conclusion​

The WalletStamper class provides a seamless integration with Turnkey's API, enabling you to leverage your existing wallet for secure, authenticated requests. By following this guide, you can quickly set up and start using WalletStamper in your projects.