@courierprotocol/sdk

Official SDK for interacting with the Courier Protocol on Solana. This SDK provides a simple and powerful interface for creating, managing, and consuming one-time action codes on the Solana blockchain.

Installation

npm install @courierprotocol/sdk
# or
yarn add @courierprotocol/sdk
# or
pnpm add @courierprotocol/sdk

Quick Start

import { Client } from '@courierprotocol/sdk';
import { Connection, clusterApiUrl } from '@solana/web3.js';
import { Wallet } from '@coral-xyz/anchor';

// Initialize the SDK with a Solana connection
const connection = new Connection(clusterApiUrl('devnet'));
const wallet = new Wallet(Keypair.generate()); // Your wallet implementation

const client = new Client({
  connection,
  wallet,
});

// Use the carrier service to create and manage codes
const code = await client.carrier.claimCode({
  type: 'solanaPay',
  amount: 1.0,
  recipient: 'H7fubezu5B76NMjsQGNcEdaZWXgXRDtTd7NQjAeTY6W3',
});

Features

Carrier Service

The carrier service handles the creation and management of one-time action codes:

• Code Management

  • Claim codes
  • Resolve codes
  • Consume codes
  • Update transaction hashes
  • Get active codes

• Payload Creation

  • Solana Pay payloads
  • Solana Action payloads
  • Custom Transaction payloads

Protocol Services

The SDK provides two protocol services for different use cases:

1. User Protocol

   • Register users
   • Hash user codes
   • Manage user-specific operations

2. Entity Protocol

   • Register entities
   • Hash entity codes
   • Manage entity-specific operations

Usage Examples

Creating a Solana Pay Code

// Create a Solana Pay payload
const payload = client.carrier.createSolanaPayPayload(
  'H7fubezu5B76NMjsQGNcEdaZWXgXRDtTd7NQjAeTY6W3',
  1.0,
  'Payment for services'
);

// Claim the code
const code = await client.carrier.claimCode({
  type: 'solanaPay',
  amount: 1.0,
  recipient: 'H7fubezu5B76NMjsQGNcEdaZWXgXRDtTd7NQjAeTY6W3',
  memo: 'Payment for services',
});

Creating a Custom Transaction Code

// Create a custom transaction payload
const instructions = [
  new TransactionInstruction({
    programId: new PublicKey('Stake11111111111111111111111111111111111111'),
    keys: [
      {
        pubkey: wallet.publicKey,
        isSigner: true,
        isWritable: true,
      },
      {
        pubkey: new PublicKey('H7fubezu5B76NMjsQGNcEdaZWXgXRDtTd7NQjAeTY6W3'),
        isSigner: false,
        isWritable: true,
      },
    ],
    data: Buffer.from([0]), // Stake instruction
  }),
];

const payload = client.carrier.createCustomTransactionPayload(
  instructions,
  { memo: 'Staking 1 SOL' },
  [wallet.publicKey.toBase58()]
);

// Claim the code
const code = await client.carrier.claimCode({
  type: 'customTransaction',
  instructions,
  parameters: { memo: 'Staking 1 SOL' },
  signers: [wallet.publicKey.toBase58()],
});

Consuming a Code

// Resolve the code first
const resolved = await client.carrier.resolveCode('12345678');

// Consume the code with an action
const result = await client.carrier.consumeCode('12345678', {
  action: {
    type: 'solanaPay',
    chain: 'solana',
    payload: resolved.payload,
  },
  consumer: wallet.publicKey.toBase58(),
});

Error Handling

The SDK provides comprehensive error handling with specific error codes and messages:

try {
  await client.carrier.claimCode({ /* ... */ });
} catch (error) {
  if (error instanceof Error) {
    console.error(`Failed to claim code: ${error.message}`);
  }
}

API Reference

Client

The main entry point for the SDK.

interface ClientOptions {
  connection: Connection;
  wallet?: Wallet;
  opts?: ConfirmOptions;
}

class Client {
  constructor(options: ClientOptions);
  get carrier(): CarrierService;
  get entityProtocol(): EntityCourierProtocolSDK;
  get userProtocol(): UserCourierProtocolSDK;
  updateWallet(wallet: Wallet): void;
}

CarrierService

Handles code management and payload creation.

class CarrierService {
  createSolanaPayPayload(recipient: string, amount: number, memo?: string, splToken?: string): Payload;
  createSolanaActionPayload(title: string, description: string, recipient: string, amount: number, icon?: string): Payload;
  createCustomTransactionPayload(instructions: TransactionInstruction[], parameters?: Record<string, any>, signers?: string[]): Payload;
  parseToUnifiedUIPayload(payload: Payload): UnifiedUIPayload;
  toWalletTx(payload: Payload): Promise<Transaction>;
  signAndSend(payload: Payload): Promise<string>;
  claimCode(opts: ClaimRequest): Promise<ClaimResponse>;
  getActiveCode(): Promise<ClaimResponse>;
  resolveCode(code: string): Promise<ResolveResponse>;
  consumeCode(code: string, opts: ConsumeRequest): Promise<ConsumeResponse>;
  updateTransactionHash(code: string, transactionHash: string): Promise<ResolveResponse>;
}

Payload Helpers

The SDK provides several payload helper methods to create different types of transaction payloads:

1. Solana Pay Payload

Used for simple SOL or SPL token transfers.

const payload = client.carrier.createSolanaPayPayload(
  recipient: string,      // Recipient's public key
  amount: number,         // Amount to transfer
  memo?: string,          // Optional memo
  splToken?: string       // Optional SPL token mint address
);

2. Solana Action Payload

Used for creating interactive actions with custom UI elements.

const payload = client.carrier.createSolanaActionPayload(
  title: string,          // Action title
  description: string,    // Action description
  recipient: string,      // Recipient's public key
  amount: number,         // Amount involved
  icon?: string          // Optional icon URL
);

3. Custom Transaction Payload

Used for complex transactions with custom instructions.

const payload = client.carrier.createCustomTransactionPayload(
  instructions: TransactionInstruction[],  // Array of transaction instructions
  parameters?: Record<string, any>,        // Optional parameters
  signers?: string[]                       // Optional array of signer public keys
);

4. Unified UI Payload

Converts any payload type into a standardized format for UI display.

const unifiedPayload = client.carrier.parseToUnifiedUIPayload(payload);

5. Transaction Conversion

Convert a payload to a Solana transaction for signing and sending.

const transaction = await client.carrier.toWalletTx(payload);
const signature = await client.carrier.signAndSend(payload);