System Components

This document provides detailed specifications for each component in the GRIPLOCK system.

Dashboard Application

The web-based dashboard is built with React and serves as the primary user interface.

Technology Stack

Technology	Version	Purpose
React	18.x	UI framework
TypeScript	5.x	Type safety
Wouter	3.x	Client-side routing
TanStack Query	5.x	Server state management
Tailwind CSS	4.x	Styling
Shadcn UI	Latest	Component library

Key Modules

Crypto Engine
Solana Client
WebRTC Hook
Wallet Context

File: client/src/lib/crypto.tsProvides all cryptographic operations:

// Key generation
export function generateKeyPair(): KeyPair

// Key exchange
export function deriveSharedSecret(
  privateKey: Uint8Array, 
  peerPublicKey: Uint8Array
): Uint8Array

// Encryption/Decryption
export function encryptPayload(data, sharedSecret): EncryptedPayload
export function decryptPayload(encrypted, sharedSecret): DecryptedWalletData

// Wallet derivation
export function deriveSolanaAddress(nfcId: string, pin: string): string

// Session storage encryption
export function encryptForStorage(data, sessionId, ttlMinutes): EncryptedStorageData
export function decryptFromStorage(encrypted, sessionId): StoredWalletData | null

Dependencies:

@noble/curves — Ed25519 and X25519 implementations
@noble/hashes — SHA-256 and HKDF
@noble/ciphers — AES-GCM encryption

File: client/src/lib/solana.tsDirect JSON-RPC communication with Solana mainnet:

// Balance queries
export async function getSolBalance(address: string): Promise<SolanaBalance>
export async function getTokenAccounts(address: string): Promise<TokenBalance[]>

// Transaction history
export async function getRecentTransactions(
  address: string, 
  limit?: number
): Promise<SolanaTransaction[]>

// Formatting utilities
export function formatAddress(address: string): string
export function formatTimestamp(timestamp: number | null): string

RPC Endpoint: https://api.mainnet-beta.solana.com

File: client/src/hooks/useWebRTC.tsManages the WebRTC lifecycle:

interface WebRTCState {
  status: 'idle' | 'generating' | 'ready' | 'connected' | 'received' | 'error';
  offer: string | null;
  error: string | null;
  walletCredentials: DecryptedWalletData | null;
  sessionId: string | null;
}

export function useWebRTC(): {
  state: WebRTCState;
  startConnection: () => Promise<void>;
  handleAnswer: (compressedAnswer: string) => Promise<boolean>;
  sendMessage: (message: object) => boolean;
  cleanup: () => void;
}

File: client/src/context/WalletContext.tsxGlobal wallet state management:

interface WalletContextType {
  // State
  walletData: { nfcId: string; pin: string; sessionId: string } | null;
  solAddress: string | null;
  sessionExpiresAt: number | null;
  isSessionValid: boolean;
  
  // Actions
  setWalletData: (data) => void;
  clearWallet: () => void;
  resetSessionTimer: () => void;
}

Session Features:

15-minute TTL with activity-based reset
Encrypted browser storage persistence
Automatic cleanup on expiration

Page Components

Page	Route	Purpose
Login	`/`	QR code display and connection handling
Dashboard	`/dashboard`	Wallet information display
Not Found	`*`	404 error page

Signaling Server

The Express.js backend provides WebSocket signaling for WebRTC connection establishment.

Architecture

// server/routes.ts

const sessions = new Map<string, {
  dashboard: WebSocket | null;
  mobile: WebSocket | null;
}>();

// WebSocket message types
type MessageType = 
  | 'register_dashboard'   // Dashboard joins session
  | 'register_mobile'      // Mobile joins session
  | 'mobile_connected'     // Notify dashboard of mobile presence
  | 'answer'               // WebRTC answer from mobile
  | 'ice_candidate'        // ICE candidate exchange
  | 'encrypted_credentials'; // Encrypted wallet data

Message Flow

Session Management

Sessions stored in-memory Map
Automatic cleanup on WebSocket disconnect
No persistent storage of session data

Mobile Application

The mobile app (iOS/Android) handles NFC reading and secure credential transmission.

Responsibilities

QR Scanning — Parse compressed connection payload
NFC Reading — Extract card UID via ISO 14443
PIN Collection — Secure numeric input
Encryption — Encrypt credentials with shared secret
Transmission — Send via WebRTC DataChannel

Security Measures

Memory-Only Processing

Credentials never written to storage

Secure Enclave

Cryptographic operations in secure hardware when available

App Transport Security

TLS 1.3 for all network communication

Certificate Pinning

Prevents MITM attacks on signaling

Cryptographic Libraries

GRIPLOCK uses the Noble cryptography suite for all security-critical operations:

Library	Usage
`@noble/curves/ed25519`	Ed25519 signatures, X25519 key exchange
`@noble/hashes/sha2`	SHA-256 hashing
`@noble/hashes/hkdf`	HKDF key derivation
`@noble/ciphers/aes`	AES-256-GCM encryption

Why Noble?

Audited — Security-reviewed by third parties
Pure JavaScript — No native dependencies, works everywhere
Constant-time — Resistant to timing attacks
Modern — Uses latest cryptographic best practices

Payment Integrations

Moonpay (On/Off-Ramp)

Handles fiat-to-crypto and crypto-to-fiat conversions:

// Moonpay integration endpoints
interface MoonpayConfig {
  apiKey: string;
  environment: 'sandbox' | 'production';
  defaultCurrency: 'SOL' | 'USDC';
}

// On-ramp: Buy crypto with fiat
export function initiateBuy(params: {
  amount: number;
  currency: string;
  walletAddress: string;
}): Promise<MoonpayTransaction>;

// Off-ramp: Sell crypto for fiat
export function initiateSell(params: {
  amount: number;
  cryptoCurrency: string;
  bankAccount: string;
}): Promise<MoonpayTransaction>;

Features:

160+ countries supported
Apple Pay, Google Pay, credit/debit cards
Built-in KYC verification
Direct bank transfers

x402 Protocol (Micropayments)

HTTP-native payment protocol for pay-per-use transactions:

// x402 payment handler
interface X402Config {
  facilitator: 'coinbase' | 'custom';
  network: 'solana' | 'base';
  currency: 'USDC';
}

// Handle 402 Payment Required responses
export async function handlePaymentRequired(
  response: Response,
  wallet: Wallet
): Promise<PaymentResult>;

// Create payment middleware
export function createPaymentMiddleware(
  endpoints: Record<string, { price: string }>
): Middleware;

Use Cases:

API access payments
AI agent transactions
Content micropayments
Pay-per-use services

Virtual Cards

Generate and manage virtual Visa cards:

interface VirtualCard {
  id: string;
  last4: string;
  expiryMonth: number;
  expiryYear: number;
  balance: number;
  status: 'active' | 'frozen' | 'cancelled';
}

// Card operations
export function createCard(walletAddress: string): Promise<VirtualCard>;
export function topUpCard(cardId: string, amount: number): Promise<Transaction>;
export function freezeCard(cardId: string): Promise<void>;

Supported:

Apple Pay integration
Google Pay integration
Online transactions worldwide

Blockchain Integration

Solana RPC Methods

Method	Usage
`getBalance`	Query SOL balance
`getTokenAccountsByOwner`	List SPL token holdings
`getSignaturesForAddress`	Fetch transaction history

Known Token Registry

const knownTokens: Record<string, string> = {
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v': 'USDC',
  'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB': 'USDT',
  'So11111111111111111111111111111111111111112': 'wSOL',
};

Getting Started

Architecture

Security

Features

Components

System Components

Dashboard Application

Technology Stack

Key Modules

Page Components

Signaling Server

Architecture

Message Flow

Session Management

Mobile Application

Responsibilities

Security Measures

Memory-Only Processing

Secure Enclave

App Transport Security

Certificate Pinning

Cryptographic Libraries

Why Noble?

Payment Integrations

Moonpay (On/Off-Ramp)

x402 Protocol (Micropayments)

Virtual Cards

Blockchain Integration

Solana RPC Methods

Known Token Registry

Next Steps

Key Derivation

Encryption

Getting Started

Architecture

Security

Features

​System Components

​Dashboard Application

​Technology Stack

​Key Modules

​Page Components

​Signaling Server

​Architecture

​Message Flow

​Session Management

​Mobile Application

​Responsibilities

​Security Measures

Memory-Only Processing

Secure Enclave

App Transport Security

Certificate Pinning

​Cryptographic Libraries

​Why Noble?

​Payment Integrations

​Moonpay (On/Off-Ramp)

​x402 Protocol (Micropayments)

​Virtual Cards

​Blockchain Integration

​Solana RPC Methods

​Known Token Registry

​Next Steps

Key Derivation

Encryption

System Components

Dashboard Application

Technology Stack

Key Modules

Page Components

Signaling Server

Architecture

Message Flow

Session Management

Mobile Application

Responsibilities

Security Measures

Cryptographic Libraries

Why Noble?

Payment Integrations

Moonpay (On/Off-Ramp)

x402 Protocol (Micropayments)

Virtual Cards

Blockchain Integration

Solana RPC Methods

Known Token Registry

Next Steps