@cryptforge/core

Core TypeScript types and interfaces for the CryptForge SDK. This package provides shared type definitions used across all CryptForge packages.

Installation

npm install @cryptforge/core
# or
pnpm add @cryptforge/core
# or
yarn add @cryptforge/core

Overview

This package contains no runtime code - only TypeScript type definitions and interfaces. It's automatically installed as a dependency when you use any CryptForge package.

What's Included

Authentication Types (types/auth.ts)

Core types for authentication and key management:

• Identity - User identity metadata
• Keys - Derived cryptographic keys
• Keystore - Encrypted keystore structure
• AuthState - Authentication state machine
• AuthChangeEvent - Auth state change events
• CreateIdentityOptions - Identity creation parameters
• UnlockOptions - Wallet unlock parameters
• ExportOptions - Identity export options

Blockchain Types (types/blockchain.ts)

Types for blockchain adapters and operations:

• BlockchainAdapter - Interface for implementing blockchain adapters
• KeyData - Derived key information
• ChainData - Blockchain metadata
• Transaction - Transaction structure
• TokenBalance - Token balance information
• TokenTransfer - Token transfer details
• TransactionOptions - Transaction query options

Client Types (types/client.ts)

Types for client-side operations:

• Client configuration types
• Client state management types
• Event types for client operations

Application Types (types/app.ts)

Application-level types:

• App configuration
• App state management
• Plugin interfaces

Secrets Types (types/secrets.ts)

Types for secret management:

• Secret storage interfaces
• Encryption/decryption types
• Secret metadata

Presence Types (types/presence.ts)

Types for device presence and synchronization:

• Device presence information
• Peer discovery types
• Sync state management

Usage

This package is primarily used by library authors creating CryptForge-compatible packages. Most developers will use higher-level packages like @cryptforge/auth or @cryptforge/blockchain-evm.

Implementing a Custom Blockchain Adapter

import type {
  BlockchainAdapter,
  KeyData,
  ChainData,
} from '@cryptforge/core';

class MyCustomAdapter implements BlockchainAdapter {
  readonly chainData: ChainData = {
    name: 'My Chain',
    symbol: 'MYC',
    cmc_id: 12345,
    chainId: 1,
    decimals: 18,
  };

  async deriveKeys(mnemonic: string): Promise<KeyData> {
    // Implement key derivation
  }

  async deriveKeysAtIndex(mnemonic: string, index: number): Promise<KeyData> {
    // Implement indexed key derivation
  }

  async deriveKeysAtPath(mnemonic: string, path: string): Promise<KeyData> {
    // Implement path-based key derivation
  }

  async getAddressAtIndex(
    mnemonic: string,
    index: number
  ): Promise<{ address: string; publicKey: string; path: string }> {
    // Implement address generation
  }

  async getAddresses(
    mnemonic: string,
    startIndex: number,
    count: number
  ): Promise<Array<{ address: string; path: string; index: number }>> {
    // Implement multiple address generation
  }

  async signMessage(
    privateKey: Uint8Array,
    message: string | Uint8Array
  ): Promise<{ signature: string }> {
    // Implement message signing
  }

  async signTransaction(
    privateKey: Uint8Array,
    transaction: any
  ): Promise<{ signedTransaction: any; signature: string }> {
    // Implement transaction signing
  }

  async verifySignature(
    message: string | Uint8Array,
    signature: string,
    publicKey: string
  ): Promise<boolean> {
    // Implement signature verification
  }

  // Implement blockchain data query methods...
  async getNativeBalance(address: string): Promise<any> {
    // Get native token balance
  }

  async getTokenBalances(address: string): Promise<any[]> {
    // Get all token balances
  }

  async getTransactions(address: string, options?: any): Promise<any[]> {
    // Get transaction history
  }

  // ... other required methods
}

Using Types in Your Application

import type {
  Identity,
  Keys,
  ChainData,
  Transaction,
} from '@cryptforge/core';

// Type-safe identity handling
const handleIdentity = (identity: Identity) => {
  console.log('Identity ID:', identity.id);
  console.log('Label:', identity.label);
  console.log('Created:', identity.createdAt);
};

// Type-safe key handling
const handleKeys = (keys: Keys) => {
  console.log('Address:', keys.address);
  console.log('Chain:', keys.chain.name);
  console.log('Expires:', keys.expiresAt);
};

// Type-safe chain data
const displayChainInfo = (chain: ChainData) => {
  console.log(`${chain.name} (${chain.symbol})`);
};

Key Interfaces

BlockchainAdapter

The BlockchainAdapter interface defines the contract that all blockchain adapters must implement:

interface BlockchainAdapter {
  // Chain metadata
  readonly chainData: ChainData;

  // Key derivation
  deriveKeys(mnemonic: string): Promise<KeyData>;
  deriveKeysAtIndex(mnemonic: string, index: number): Promise<KeyData>;
  deriveKeysAtPath(mnemonic: string, path: string): Promise<KeyData>;

  // Address generation
  getAddressAtIndex(
    mnemonic: string,
    index: number
  ): Promise<{ address: string; publicKey: string; path: string }>;
  getAddresses(
    mnemonic: string,
    startIndex: number,
    count: number
  ): Promise<Array<{ address: string; path: string; index: number }>>;

  // Cryptographic operations
  signMessage(
    privateKey: Uint8Array,
    message: string | Uint8Array
  ): Promise<{ signature: string }>;
  signTransaction(
    privateKey: Uint8Array,
    transaction: any
  ): Promise<{ signedTransaction: any; signature: string }>;
  verifySignature(
    message: string | Uint8Array,
    signature: string,
    publicKey: string
  ): Promise<boolean>;

  // Blockchain data queries
  getNativeBalance(address: string): Promise<any>;
  getTokenBalances(address: string): Promise<any[]>;
  getTokenBalance(address: string, tokenAddress: string): Promise<string>;
  getTransactions(address: string, options?: any): Promise<any[]>;
  getTokenTransfers(address: string, options?: any): Promise<any[]>;

  // Transaction operations
  sendNativeToken(params: {
    privateKey: Uint8Array;
    to: string;
    amount: string;
  }): Promise<any>;
  sendToken(params: {
    privateKey: Uint8Array;
    to: string;
    tokenAddress: string;
    amount: string;
  }): Promise<any>;
  getTransactionStatus(hash: string): Promise<any>;
}

ChainData

interface ChainData {
  name: string; // Display name (e.g., "Ethereum")
  symbol: string; // Token symbol (e.g., "ETH")
  cmc_id: number; // CoinMarketCap ID
  chainId?: number; // Chain ID for EVM chains
  decimals?: number; // Token decimals (default: 18)
}

KeyData

interface KeyData {
  mnemonic: string; // BIP39 mnemonic phrase
  seed: Uint8Array; // BIP39 seed (512 bits)
  privateKey: Uint8Array; // Private key bytes
  privateKeyHex: string; // Private key as hex string
  publicKey: Uint8Array; // Public key bytes
  publicKeyHex: string; // Public key as hex string
  address: string; // Blockchain address
  path: string; // BIP44 derivation path
}

Related Packages

• @cryptforge/auth - Authentication and key management using these types
• @cryptforge/blockchain-evm - EVM blockchain adapter implementation
• @cryptforge/blockchain-btc - Bitcoin blockchain adapter implementation
• @cryptforge/key-exchange - Device synchronization using presence types
• @cryptforge/client-vue - Vue.js UI components using client types

TypeScript Configuration

For best results, use these TypeScript compiler options:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

Contributing

When adding new types to this package:

1. Add types to the appropriate file in src/types/
2. Export from src/index.ts
3. Update this README with documentation
4. Ensure all types are well-documented with JSDoc comments
5. Keep types browser-compatible (no Node.js-specific types)

License

MIT