c1ph3r_c01n

A TypeScript package for cryptographic proof generation and verification with settlement support.

Installation

npm install c1ph3r_c01n

Basic Usage

import { C1ph3rSDK } from 'c1ph3r_c01n';

// Initialize SDK with optional settlement API URL
const apiKey = 'secret-verifier';
const requireHmacAuth = true;
const cipher = new C1ph3rSDK('https://settlement-api.example.com', apiKey, requireHmacAuth);

// Example private key (for demonstration only)
const privateKey = '0xb06bbba13c2ce93621525d166e286f212de43f2fb87853aa19025751932d9cbd';

async function example() {
    // Start new authentication session
    const auth = await cipher.startNewAuth(
        privateKey,
        'myPassword123',  // password (4-100 chars)
        'RDUL'           // sequence (exactly 4 chars: U, D, L, R) for RGBY so U -> Red, D -> Yellow, L -> Blue, R -> Green
    );

    // Solve rounds one by one
    cipher.solveCurrentRound('U');
    const nextRound = cipher.getCurrentRound();
    cipher.solveCurrentRound('D');
    // ... continue for all rounds
    // if it's not the last round then solveCurrentRound will return the next round, so the response will be like this 
    {
        success: true, // true means that solutions was accepted (doesn't mean it's correct or wrong)
        verificationResponse: null // this means that it's not the last round
    }

    // if it's the last round then solveCurrentRound will return the verificationResponse, so the response will be like this 
    {
        success: true, // true means that solutions was accepted (doesn't mean it's correct or wrong)
        verificationResponse: Promise<VerificationResponse> // this is the response from the verifier, so it will contain if the rwp is correct or not (verificationResponse.response.rwp_result)
    }
    
    // Check settlement status if using aRPC
    const settlementStatus = await verification.settlementPromise;
}

API Reference

C1ph3rSDK

Constructor

constructor(arpcSettlementApiUrl?: string)

• arpcSettlementApiUrl: Optional URL for settlement verification
• Throws: Error if URL is invalid

Methods

startNewAuth(privateKey: string, password?: string, directions?: string)

Initializes a new proof session.

Parameters:

• privateKey: Ethereum private key (hex string with '0x' prefix)
• password: Optional if previously set, 4-100 characters
• directions: Optional if previously set, exactly 4 characters (U, D, L, R)

Returns: Promise<{ proverState: any, currentRound: number, colorAssignments: any }>

Throws:

• If authentication already in progress
• If password/directions not provided and no stored data
• If inputs are invalid
• If prover initialization fails

solveCurrentRound(solution: string)

Submits solution for current round.

Parameters:

• solution: Single character (U, D, L, R)

Returns: { success: boolean, message?: string, verificationResponse: Promise | null }

Throws:

• If no authentication in progress
• If invalid solution
• If no more rounds available

verifyAuth(solution: string)

Verifies complete authentication attempt.

Parameters:

• solution: String of U, D, L, R characters

Returns: Promise<{ verificationResult: boolean, responses: any, settlementPromise?: Promise }>

Throws:

• If invalid solution format
• If prover state not found

getCurrentRound()

Retrieves current round's color assignments.

Returns: { success: boolean, colorAssignment: any, message?: string }

Throws:

• If no authentication in progress

getLastSettlementStatus()

Retrieves status of last settlement attempt.

Returns: Promise<SettlementResponse | null>

Data Persistence

• Browser: Encrypted credentials stored in localStorage
• Node.js: Must provide credentials each time

Error Handling

The SDK throws descriptive errors for:

• Invalid inputs
• Authentication state issues
• Encryption/decryption failures
• Network errors
• Settlement verification failures

Settlement Integration

When initialized with an aRPC settlement API URL:

• Non-blocking settlement verification
• Access settlement status via verification.settlementPromise
• Query last settlement via getLastSettlementStatus()

Performance Benchmarks

• Authentication: ~6.10s
• Verification: ~0.08s
• Settlement: ~4.69s

Version History

1.2.7

• Added non-blocking aRPC settlement
• Settlement status accessible via settlementPromise

1.2.6

• Added blocking aRPC settlement

1.1.5

• Added localhost development support
• Improved error handling
• Added browser storage support