Hyperkit SDK: Alignment proposal and implementation plan (MONTH 3)

## Executive summary

Current state: React UI component library with basic wallet connection (EVM-only, MetaMask-focused).

Target state: Multi-chain abstraction SDK supporting 100+ chains with modular adapters, capability routing, RPC pooling, and x402 payment integration.

Gap: Missing core infrastructure (network registry, adapters, routers, payment system).

---

## Architecture overview

### Current architecture (Phase 0)

```
React Application
    ↓
HyperkitProvider (React Context)
    ↓
window.ethereum (MetaMask only)
    ↓
EVM Networks (hardcoded config)
```

Limitations:
- EVM-only (no Solana, SUI, Cosmos)
- Single RPC endpoint (no failover)
- Hardcoded network configs
- No adapter abstraction
- No payment routing
- React-specific (not framework-agnostic)

### Target architecture (Post-alignment)

```
Application Layer (React/Vue/Vanilla)
    ↓
HyperkitClient (Core SDK - Framework Agnostic)
    ↓
┌─────────────────────────────────────────┐
│  SDK Orchestration Layer                │
│  ├─ TransactionManager                  │
│  ├─ ContractManager                     │
│  ├─ WalletManager                       │
│  └─ BridgeManager                       │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Capability Router                      │
│  ├─ Network Registry (100+ chains)      │
│  ├─ Adapter Selection Logic             │
│  └─ Capability Mapping                  │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Adapter Layer                          │
│  ├─ EVM Adapter (ethers.js)             │
│  ├─ Solana Adapter (@solana/web3.js)    │
│  ├─ SUI Adapter (@mysten/sui.js)       │
│  └─ RPC Pool (Failover + Health Check)  │
└─────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────┐
│  Payment Layer (x402 Router)            │
│  ├─ Thirdweb x402                       │
│  ├─ LazAI Settlement                    │
│  ├─ Socket Payment                      │
│  └─ Direct Transfer                     │
└─────────────────────────────────────────┘
    ↓
Blockchains (100+)
```

---

## Implementation phases

### Phase 1: Foundation — Network registry and core infrastructure

Goal: Build the network registry and core SDK foundation.

What changes:

1. New package structure
   ```
   packages/
   ├── core/                    # NEW: Core SDK (framework-agnostic)
   │   ├── src/
   │   │   ├── registry/
   │   │   │   └── network-registry.ts
   │   │   ├── client/
   │   │   │   └── HyperkitClient.ts
   │   │   ├── errors/
   │   │   │   └── BaseError.ts
   │   │   └── types/
   │   │       └── Chain.ts
   │   └── package.json
   │
   └── react/                    # RENAME: Current src/ → react adapter
       └── src/
           └── ... (existing React components)
   ```

2. Network registry implementation
   - Centralized chain configuration
   - Runtime chain addition
   - Capability metadata (account, payment, DA)
   - Lazy loading

3. Core client
   - Framework-agnostic entry point
   - Adapter registry
   - Error hierarchy
   - Logger

Impact:
- Breaking: React components move to `@hyperkit/react`
- New: Core SDK usable without React
- Enables: Multi-chain support foundation
- Migration: Existing apps import from `@hyperkit/react` instead of `hyperkit`

Files created:
- `packages/core/src/registry/network-registry.ts`
- `packages/core/src/client/HyperkitClient.ts`
- `packages/core/src/errors/BaseError.ts`
- `packages/core/src/types/Chain.ts`

Files modified:
- `package.json` (monorepo structure)
- `src/index.ts` (re-export from react package)

---

### Phase 2: Adapter layer — Multi-chain support

Goal: Implement chain adapters (EVM, Solana, SUI) with unified interface.

What changes:

1. Adapter package structure
   ```
   packages/
   ├── adapters/
   │   ├── evm/                  # NEW
   │   │   ├── src/
   │   │   │   ├── EVMAdapter.ts
   │   │   │   └── handlers/
   │   │   └── package.json
   │   │
   │   ├── solana/               # NEW
   │   │   ├── src/
   │   │   │   ├── SolanaAdapter.ts
   │   │   │   └── handlers/
   │   │   └── package.json
   │   │
   │   └── sui/                  # NEW
   │       ├── src/
   │       │   ├── SuiAdapter.ts
   │       │   └── handlers/
   │       └── package.json
   ```

2. Unified adapter interface
   ```typescript
   interface IChainAdapter {
     chainId: string;
     chainName: string;
     nativeToken: string;
     
     deploy(bytecode: string, abi: any[], args: any[]): Promise<DeployResult>;
     call(address: string, method: string, args: any[]): Promise<any>;
     estimateGas(method: string, args: any[]): Promise<bigint>;
     getBalance(address: string): Promise<bigint>;
     sendTransaction(tx: Transaction): Promise<TransactionReceipt>;
   }
   ```

3. EVM adapter
   - ethers.js integration
   - Contract deployment
   - Transaction sending
   - Gas estimation
   - Tested on Mantle, Metis, Hyperion

4. Solana adapter
   - @solana/web3.js integration
   - Anchor program deployment
   - PDA management
   - Compute unit estimation

5. SUI adapter
   - @mysten/sui.js integration
   - Move package deployment
   - moveCall execution
   - Dry-run gas estimation

Impact:
- New: Deploy to Solana and SUI
- New: Unified API across chains
- Breaking: Component APIs may change to use adapters
- Enables: True multi-chain dApps

Dependencies:
- `ethers@^6.15.0` (existing)
- `@solana/web3.js@^1.95.0` (new)
- `@coral-xyz/anchor` (new)
- `@mysten/sui.js@^1.0.0` (new)

---

### Phase 3: Capability router — Intelligent adapter selection

Goal: Build capability router that selects the correct adapter based on chain and action.

What changes:

1. Router implementation
   ```
   packages/
   └── core/
       └── src/
           └── router/
               └── capability-router.ts  # NEW
   ```

2. Routing logic
   - Action → capability mapping (deploy → DA, call → account, bridge → payment)
   - Chain → adapter mapping
   - Fallback handling
   - Zero hardcoded chain checks

3. Integration with network registry
   - Reads capabilities from registry
   - Dynamic adapter selection
   - Runtime chain addition support

Impact:
- New: Automatic adapter selection
- New: No manual chain checks
- Improved: Developer experience (single API)
- Enables: Runtime chain addition

How it works:
```typescript
// Developer writes:
const result = await client.deploy(bytecode, abi, args, 'mantle');

// Router automatically:
// 1. Checks network registry for 'mantle'
// 2. Identifies capability needed (deploy → DA)
// 3. Selects EVM adapter (mantle is EVM)
// 4. Routes to correct adapter
// 5. Returns normalized result
```

---

### Phase 4: RPC pool and failover — Reliability layer

Goal: Implement RPC pooling with automatic failover and health checks.

What changes:

1. RPC pool implementation
   ```
   packages/
   └── core/
       └── src/
           └── router/
               └── rpc-pool.ts  # NEW
   ```

2. Features
   - Multiple RPC endpoints per chain
   - Health check (30s interval)
   - Automatic failover
   - Latency tracking
   - Recovery when endpoint restored

3. Integration
   - Adapters use RPC pool
   - Transparent to developers
   - Configurable per chain

Impact:
- Improved: Reliability (no single point of failure)
- Improved: Performance (latency-based selection)
- Improved: Uptime (automatic failover)
- New: Health monitoring

How it works:
```typescript
// Network registry defines multiple RPCs:
mantle: {
  rpc: [
    'https://rpc.mantle.xyz',
    'https://mantle-rpc.mantle.xyz',
    'https://mantle-rpc.publicnode.com'
  ]
}

// RPC pool automatically:
// 1. Tracks health of each endpoint
// 2. Routes requests to healthy endpoints
// 3. Falls back if primary fails
// 4. Recovers when endpoint restored
```

---

### Phase 5: x402 payment router — Monetization layer

Goal: Implement x402 multi-network payment routing for monetization.

What changes:

1. Payment router implementation
   ```
   packages/
   └── payments/                 # NEW
       └── src/
           ├── x402-router.ts
           ├── thirdweb-x402.ts
           ├── lazai-settlement.ts
           ├── socket-payment.ts
           └── direct-transfer.ts
   ```

2. Payment facilitators
   - Thirdweb x402 (ERC-4337 payment intents)
   - LazAI settlement (Metis/Hyperion)
   - Socket payment (cross-chain)
   - Direct transfer (fallback)

3. Integration with network registry
   - Payment capability per chain
   - Automatic facilitator selection
   - Payment intent creation
   - Expiration handling

Impact:
- New: Monetization capability
- New: Payment processing
- New: Revenue stream
- Enables: Pay-per-use model

How it works:
```typescript
// Network registry defines payment facilitator:
mantle: {
  capabilities: {
    payment: {
      facilitator: 'thirdweb_x402',
      metering: true,
      creditsPerRun: 3
    }
  }
}

// Developer creates payment:
const intent = await client.payments.createIntent({
  amount: 1000000n,  // 1 USDC
  chain: 'mantle',
  action: 'agent_run'
});

// Router automatically:
// 1. Checks network registry for payment capability
// 2. Selects facilitator (thirdweb_x402)
// 3. Creates payment intent via Thirdweb API
// 4. Returns payment URL and expiration
```

---

## Detailed change matrix

### Package structure changes

| Current | Target | Type | Impact |
|---------|--------|------|--------|
| `src/` (React components) | `packages/react/src/` | Move | Breaking: Import path changes |
| N/A | `packages/core/` | New | New: Core SDK foundation |
| N/A | `packages/adapters/evm/` | New | New: EVM chain support |
| N/A | `packages/adapters/solana/` | New | New: Solana support |
| N/A | `packages/adapters/sui/` | New | New: SUI support |
| N/A | `packages/payments/` | New | New: Payment routing |
| `package.json` (single) | Monorepo with workspaces | Restructure | Breaking: Install process changes |

### API changes

| Current API | Target API | Breaking? | Migration |
|-------------|------------|-----------|-----------|
| `HyperkitProvider` (React) | `HyperkitClient` (agnostic) | Yes | Wrap React components with client |
| `useWallet()` hook | `client.wallet.getBalance()` | Yes | Use client methods instead of hooks |
| `NETWORKS` (hardcoded) | `NetworkRegistry` (dynamic) | Yes | Use registry methods |
| N/A | `client.deploy()` | New | New capability |
| N/A | `client.call()` | New | New capability |
| N/A | `client.payments.createIntent()` | New | New capability |

### Component changes

| Component | Current | Target | Impact |
|-----------|---------|--------|--------|
| `ConnectWallet` | window.ethereum only | Multi-chain support | Enhanced: Works with all chains |
| `Bridge` | Hardcoded logic | Uses BridgeManager | Enhanced: Better routing |
| `Swap` | Hardcoded logic | Uses ContractManager | Enhanced: Multi-chain swaps |
| `Staking` | Hardcoded logic | Uses ContractManager | Enhanced: Multi-chain staking |
| `Faucet` | Hardcoded logic | Uses TransactionManager | Enhanced: Multi-chain faucets |

---

## Impact analysis

### Developer experience

Before:
- React-only
- EVM-only
- Hardcoded networks
- Manual chain checks

After:
- Framework-agnostic core
- 100+ chains
- Runtime chain addition
- Automatic adapter selection

### Technical capabilities

Before:
- Single RPC endpoint
- No failover
- No payment system
- Limited to EVM

After:
- RPC pooling with failover
- Health monitoring
- x402 payment routing
- Multi-chain (EVM, Solana, SUI)

### Business impact

Before:
- Limited to EVM chains
- No monetization
- Single point of failure

After:
- 100+ chain support
- Payment processing
- Revenue stream
- High reliability

### Migration impact

Breaking changes:
1. Package structure (monorepo)
2. Import paths (`hyperkit` → `@hyperkit/react`)
3. API surface (hooks → client methods)
4. Network configuration (hardcoded → registry)

Migration effort:
- Small apps: 1-2 hours
- Medium apps: 4-8 hours
- Large apps: 1-2 days

---

## Implementation dependencies

### Task dependency graph

```
TASK-M3-SDK-001 (Network Registry)
    ↓
TASK-M3-SDK-002 (Capability Router)
    ↓
├─→ TASK-M3-SDK-003 (EVM Adapter)
├─→ TASK-M3-SDK-004 (Solana Adapter)
└─→ TASK-M3-SDK-005 (SUI Adapter)
    ↓
TASK-M3-SDK-006 (RPC Pool)
    ↓
TASK-M3-SDK-007 (x402 Router)
```

### External dependencies

| Dependency | Purpose | Phase |
|------------|---------|-------|
| `ethers@^6.15.0` | EVM operations | Phase 2 |
| `@solana/web3.js@^1.95.0` | Solana operations | Phase 2 |
| `@coral-xyz/anchor` | Solana programs | Phase 2 |
| `@mysten/sui.js@^1.0.0` | SUI operations | Phase 2 |
| Thirdweb x402 API | Payment processing | Phase 5 |
| LazAI API | Settlement | Phase 5 |
| Socket API | Cross-chain payments | Phase 5 |

---

## Success metrics

### Phase 1: Foundation
- [ ] Network registry supports 100+ chains
- [ ] Core client framework-agnostic
- [ ] Error hierarchy implemented
- [ ] Zero breaking changes to React components

### Phase 2: Adapters
- [ ] EVM adapter tested on 3+ chains
- [ ] Solana adapter deploys Anchor programs
- [ ] SUI adapter deploys Move packages
- [ ] All adapters implement unified interface

### Phase 3: Router
- [ ] Router selects correct adapter 100% of time
- [ ] Zero hardcoded chain checks
- [ ] Fallback logic functional
- [ ] Runtime chain addition works

### Phase 4: RPC Pool
- [ ] Failover tested (endpoint down scenario)
- [ ] Health check runs every 30s
- [ ] Recovery works when endpoint restored
- [ ] Latency tracking per endpoint

### Phase 5: Payments
- [ ] All 4 facilitators implemented
- [ ] Payment intents created successfully
- [ ] Expiration handling works
- [ ] Tested on each network

---

## Risk mitigation

### Technical risks

| Risk | Mitigation |
|------|------------|
| Breaking changes | Provide migration guide and backward compatibility layer |
| Performance degradation | Benchmark before/after, optimize critical paths |
| Complexity increase | Maintain clear documentation, code reviews |
| Third-party API failures | Implement retry logic, fallback facilitators |

### Business risks

| Risk | Mitigation |
|------|------------|
| Developer adoption | Maintain React compatibility, provide examples |
| Revenue impact | Test payment system thoroughly before launch |
| Support burden | Comprehensive documentation, clear error messages |

---


This plan transforms the current React UI library into a production-ready multi-chain SDK while maintaining backward compatibility where possible. Each phase builds on the previous one, enabling incremental development and testing.

Current	Target	Type	Impact
`src/` (React components)	`packages/react/src/`	Move	Breaking: Import path changes
N/A	`packages/core/`	New	New: Core SDK foundation
N/A	`packages/adapters/evm/`	New	New: EVM chain support
N/A	`packages/adapters/solana/`	New	New: Solana support
N/A	`packages/adapters/sui/`	New	New: SUI support
N/A	`packages/payments/`	New	New: Payment routing
`package.json` (single)	Monorepo with workspaces	Restructure	Breaking: Install process changes

Current API	Target API	Breaking?	Migration
`HyperkitProvider` (React)	`HyperkitClient` (agnostic)	Yes	Wrap React components with client
`useWallet()` hook	`client.wallet.getBalance()`	Yes	Use client methods instead of hooks
`NETWORKS` (hardcoded)	`NetworkRegistry` (dynamic)	Yes	Use registry methods
N/A	`client.deploy()`	New	New capability
N/A	`client.call()`	New	New capability
N/A	`client.payments.createIntent()`	New	New capability

Component	Current	Target	Impact
`ConnectWallet`	window.ethereum only	Multi-chain support	Enhanced: Works with all chains
`Bridge`	Hardcoded logic	Uses BridgeManager	Enhanced: Better routing
`Swap`	Hardcoded logic	Uses ContractManager	Enhanced: Multi-chain swaps
`Staking`	Hardcoded logic	Uses ContractManager	Enhanced: Multi-chain staking
`Faucet`	Hardcoded logic	Uses TransactionManager	Enhanced: Multi-chain faucets

Dependency	Purpose	Phase
`ethers@^6.15.0`	EVM operations	Phase 2
`@solana/web3.js@^1.95.0`	Solana operations	Phase 2
`@coral-xyz/anchor`	Solana programs	Phase 2
`@mysten/sui.js@^1.0.0`	SUI operations	Phase 2
Thirdweb x402 API	Payment processing	Phase 5
LazAI API	Settlement	Phase 5
Socket API	Cross-chain payments	Phase 5

Risk	Mitigation
Breaking changes	Provide migration guide and backward compatibility layer
Performance degradation	Benchmark before/after, optimize critical paths
Complexity increase	Maintain clear documentation, code reviews
Third-party API failures	Implement retry logic, fallback facilitators

Risk	Mitigation
Developer adoption	Maintain React compatibility, provide examples
Revenue impact	Test payment system thoroughly before launch
Support burden	Comprehensive documentation, clear error messages

Hyperkit SDK: Alignment proposal and implementation plan (MONTH 3) #2

Description

Executive summary

Architecture overview

Current architecture (Phase 0)

Target architecture (Post-alignment)

Implementation phases

Phase 1: Foundation — Network registry and core infrastructure

Phase 2: Adapter layer — Multi-chain support

Phase 3: Capability router — Intelligent adapter selection

Phase 4: RPC pool and failover — Reliability layer

Phase 5: x402 payment router — Monetization layer

Detailed change matrix

Package structure changes

API changes

Component changes

Impact analysis

Developer experience

Technical capabilities

Business impact

Migration impact

Implementation dependencies

Task dependency graph

External dependencies

Success metrics

Phase 1: Foundation

Phase 2: Adapters

Phase 3: Router

Phase 4: RPC Pool

Phase 5: Payments

Risk mitigation

Technical risks

Business risks

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions