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

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

wallet

WalletInterface

required

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

type

string

required

The type of wallet, either solana or evm.

signMessage

function

required

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

recoverPublicKey

function

required

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

payload

string

required

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.