@cryptforge/core

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

Installation

``bash
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

$3

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

$3

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

$3

Types for client-side operations:

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

$3

Application-level types:

- App configuration
- App state management
- Plugin interfaces

$3

Types for secret management:

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

$3

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.

$3

`typescript
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 {
// Implement key derivation
}

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

async deriveKeysAtPath(mnemonic: string, path: string): Promise {
// 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> {
// 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 {
// Implement signature verification
}

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

async getTokenBalances(address: string): Promise {
// Get all token balances
}

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

// ... other required methods
}
`

$3

`typescript
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

$3

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

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

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

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

// 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;

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

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

$3

`typescript
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)
}
`

$3

`typescript
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:

`json
{
"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