@explorins/pers-signer SDK

A lightweight SDK for blockchain transaction signing with PERS integration. Uses existing services and environment-based configuration.

Installation

npm install @explorins/pers-signer

Quick Start

The SDK uses environment variables for configuration, so no complex setup is needed:

import { PersSignerSDK } from '@explorins/pers-signer';

// Simple initialization - uses environment config
const sdk = new PersSignerSDK();

// Authenticate user
const user = await sdk.authenticateUser('[email protected]');

// Sign PERS transaction
const result = await sdk.signPersTransaction(user, 'transaction-123');

if (result.success) {
  console.log('Transaction hash:', result.transactionHash);
}

Environment Variables

The SDK automatically uses these environment variables from your .env file:

• VITE_EXPRESS_API_URL - Signer backend API URL
• VITE_PERS_API_URL - PERS API URL
• VITE_PASSKEY_RELYING_PARTY_* - WebAuthn configuration
• VITE_ETHERS_PROVIDER - Blockchain provider URL

Configuration

Optional configuration can be provided:

import { PersSignerSDK, PersSignerConfig } from '@explorins/pers-signer';

const config: PersSignerConfig = {
  tenantId: 'my-tenant',                    // Multi-tenant identifier
  ethersProviderUrl: 'https://my-rpc.com'  // Custom blockchain provider
};

const sdk = new PersSignerSDK(config);

API Reference

High-Level Methods

authenticateUser(identifier: string): Promise<SignerUser>

Complete user onboarding flow - handles registration or login automatically.

signPersTransaction(user: SignerUser, transactionId: string): Promise<SigningResult>

Complete PERS transaction signing flow - same as the web project.

Granular Methods (For Custom Integrations)

registerUser(identifier: string): Promise<{authToken: string}>

loginUser(identifier: string): Promise<string>

addWalletToPersUser(signerAuthToken: string): Promise<string>

retrieveTransactionData(transactionId: string, persAccessToken: string): Promise<any>

signTransactionData(signerAuthToken: string, transactionData: any): Promise<string>

submitTransaction(transactionId: string, signature: string, persAccessToken: string): Promise<{transactionHash?: string; success: boolean}>

Utility Methods

checkUserExists(identifier: string): Promise<boolean>

getUserWallets(signerAuthToken: string): Promise<any>

getTransactionStatus(transactionId: string, persAccessToken: string): Promise<{status: string; transactionHash?: string}>

Examples

See /examples/basic-usage.ts for comprehensive examples including:

• Gaming platform integration
• E-commerce loyalty transactions
• Batch operations
• Custom blockchain providers
• Environment-based configuration

Types

interface PersSignerConfig {
  tenantId?: string;
  ethersProviderUrl?: string;
}

interface SignerUser {
  identifier: string;
  signerAuthToken?: string;
  persAccessToken?: string;
}

interface SigningResult {
  success: boolean;
  transactionHash?: string;
  error?: string;
}

Architecture

This SDK is a simple orchestrator that uses existing services:

• AuthenticationService - WebAuthn authentication
• WalletService - Wallet management
• SigningService - Transaction signing
• PersService - PERS integration
• TransactionSigningService - High-level transaction flow

No complex initialization or platform providers needed - everything is pre-configured.