@t402/streaming-payments 1.0.0-beta.1

package/README.md

@@ -0,0 +1,422 @@
+# @t402-internal/streaming-payments
+
+Streaming payments with payment channels for T402 Protocol.
+
+## Overview
+
+This package provides per-second settlement using payment channel technology. It enables continuous value transfer with off-chain state updates and on-chain settlement, similar to Lightning Network concepts adapted for stablecoin HTTP payments.
+
+## Installation
+
+```bash
+pnpm add @t402-internal/streaming-payments
+```
+
+## Quick Start
+
+```typescript
+import {
+  ChannelOpener,
+  ChannelStateMachine,
+  FlowController,
+  CheckpointManager,
+  FinalSettlementManager,
+} from '@t402-internal/streaming-payments';
+
+// Create a payment channel
+const opener = new ChannelOpener();
+const { channel, stateMachine, fundingRequired } = opener.create({
+  chain: 'eip155:8453',
+  asset: '0xUSDT',
+  payerAddress: '0xPayer',
+  payeeAddress: '0xPayee',
+  depositAmount: '1000000000', // 1000 USDT
+  ratePerSecond: '1000',       // 0.001 USDT per second
+});
+
+// Fund the channel
+opener.processFunding(stateMachine, '0xTxHash', '1000000000');
+opener.confirmFunding(stateMachine, { /* confirmation */ });
+
+// Start streaming
+const flow = new FlowController(channel.id, channel.ratePerSecond);
+flow.start();
+
+// Get current streamed amount
+const currentAmount = flow.getCurrentAmount();
+
+// Pause/resume
+flow.pause();
+flow.resume();
+
+// Stop and get final amount
+const { finalAmount } = flow.stop();
+```
+
+## Modules
+
+### Channels
+
+Payment channel lifecycle management with state machine.
+
+```typescript
+import {
+  ChannelOpener,
+  ChannelCloser,
+  ChannelStateMachine,
+  ChannelRecovery,
+  isChannelActive,
+  isChannelTerminal,
+} from '@t402-internal/streaming-payments/channels';
+
+// Open channel
+const opener = new ChannelOpener({
+  fundingTimeout: 3600000, // 1 hour
+  confirmations: 3,
+});
+
+const result = opener.create({
+  chain: 'eip155:8453',
+  asset: '0xUSDT',
+  payerAddress: '0xPayer',
+  payeeAddress: '0xPayee',
+  depositAmount: '1000000000',
+  ratePerSecond: '1000',
+});
+
+// Process state transitions
+const stateMachine = result.stateMachine;
+stateMachine.process({ type: 'FUND', txHash: '0x...', amount: '1000000000' });
+stateMachine.process({ type: 'CONFIRM_FUNDING' });
+
+// Close channel
+const closer = new ChannelCloser({
+  challengePeriod: 86400, // 24 hours
+});
+
+closer.initiateClose(stateMachine, '0xPayer', '0xSignature');
+closer.finalize(stateMachine);
+
+// Recovery
+const recovery = new ChannelRecovery();
+const recoveryResult = recovery.recoverFromCheckpoints(channel, checkpoints);
+```
+
+### Channel States
+
+| State | Description |
+|-------|-------------|
+| `created` | Channel created, awaiting funding |
+| `funding` | Funding transaction submitted |
+| `open` | Channel active and streaming |
+| `paused` | Temporarily paused |
+| `closing` | Close initiated, in challenge period |
+| `disputing` | Dispute in progress |
+| `closed` | Fully settled |
+| `expired` | Timed out |
+
+### Streaming
+
+Continuous flow control with metering and billing.
+
+```typescript
+import {
+  FlowController,
+  createFixedRateFlow,
+  createTieredRateFlow,
+  RateController,
+  MeteringManager,
+  BillingManager,
+} from '@t402-internal/streaming-payments/streaming';
+
+// Fixed rate streaming
+const flow = createFixedRateFlow('ch_123', '1000');
+flow.start();
+
+// Get current amount
+console.log(flow.getCurrentAmount());
+
+// Tiered rate streaming
+const tieredFlow = createTieredRateFlow(
+  'ch_123',
+  '1000', // Base rate
+  [
+    { threshold: '1000000', rate: '800' },  // Discount after 1M
+    { threshold: '5000000', rate: '600' },  // Further discount after 5M
+  ],
+);
+
+// Rate adjustment
+const rateController = new RateController({
+  type: 'fixed',
+  baseRate: '1000',
+  minRate: '500',
+  maxRate: '2000',
+});
+
+rateController.adjustRate({
+  sessionId: 'ss_123',
+  newRate: '1200',
+  reason: 'Peak demand',
+});
+
+// Metering
+const metering = new MeteringManager('ss_123');
+metering.record(60, '60000', '1000'); // 60 seconds at 1000/s
+
+const metrics = metering.getMetrics();
+console.log(metrics.totalAmount);
+console.log(metrics.averageRate);
+
+// Billing
+const billing = new BillingManager(
+  'ch_123',
+  '0xPayer',
+  '0xPayee',
+  { period: 'hour', minimumCharge: '100000' },
+);
+
+const invoice = billing.generateInvoice(
+  metering.getRecords(),
+  startTime,
+  endTime,
+);
+```
+
+### Streaming Events
+
+```typescript
+flow.onEvent(event => {
+  switch (event.type) {
+    case 'started':
+      console.log('Stream started at rate:', event.rate);
+      break;
+    case 'paused':
+      console.log('Stream paused, total:', event.totalStreamed);
+      break;
+    case 'checkpoint':
+      console.log('Checkpoint created:', event.checkpointId);
+      break;
+    case 'completed':
+      console.log('Stream completed:', event.totalAmount);
+      break;
+  }
+});
+```
+
+### Settlement
+
+Checkpoint-based settlement with dispute resolution.
+
+```typescript
+import {
+  CheckpointManager,
+  FinalSettlementManager,
+  DisputeManager,
+  signCheckpoint,
+  createCheckpointEvidence,
+} from '@t402-internal/streaming-payments/settlement';
+
+// Checkpoint management
+const checkpointMgr = new CheckpointManager(settlementConfig, {
+  autoCheckpoint: true,
+  intervalSeconds: 3600,
+});
+
+const checkpoint = checkpointMgr.create({
+  channelId: 'ch_123',
+  sequence: 0,
+  payerBalance: '900000000',
+  payeeBalance: '100000000',
+  totalStreamed: '100000000',
+  payerSignature: '0xsig',
+});
+
+// Validate checkpoint chain
+const validation = checkpointMgr.verifyCheckpointChain(checkpoints);
+
+// Final settlement
+const settlementMgr = new FinalSettlementManager(
+  checkpointMgr,
+  settlementConfig,
+);
+
+// Initiate settlement
+settlementMgr.initiate({
+  channelId: 'ch_123',
+  initiator: '0xPayer',
+  finalCheckpoint: checkpoint,
+  reason: 'unilateral',
+  signature: '0xsig',
+});
+
+// Mutual close (instant, no challenge period)
+settlementMgr.processMutual(
+  'ch_123',
+  payerSignature,
+  payeeSignature,
+  finalCheckpoint,
+);
+
+// Finalize after challenge period
+const { canFinalize, timeRemaining } = settlementMgr.canFinalize('ch_123');
+if (canFinalize) {
+  settlementMgr.finalize('ch_123');
+}
+
+// Dispute handling
+const disputeMgr = new DisputeManager(checkpointMgr, settlementConfig);
+
+// Raise dispute
+disputeMgr.raise({
+  channelId: 'ch_123',
+  initiator: '0xPayee',
+  respondent: '0xPayer',
+  reason: 'stale_state',
+  description: 'Payer submitted old checkpoint',
+  claimedPayerBalance: '800000000',
+  claimedPayeeBalance: '200000000',
+  claimedCheckpoint: newerCheckpoint,
+  evidence: [
+    createCheckpointEvidence(newerCheckpoint, 'Newer signed checkpoint'),
+  ],
+});
+
+// Respond to dispute
+disputeMgr.respond({
+  disputeId: 'dsp_123',
+  responder: '0xPayer',
+  evidence: [...],
+  signature: '0xsig',
+});
+
+// Resolve dispute
+disputeMgr.resolve(
+  'dsp_123',
+  '0xPayee',          // Winner
+  '800000000',        // Final payer balance
+  '200000000',        // Final payee balance
+  'Challenger had newer checkpoint',
+);
+```
+
+## Settlement Flow
+
+```
+1. Channel Open
+   - Payer deposits funds
+   - Channel enters 'open' state
+
+2. Streaming
+   - Continuous per-second billing
+   - Periodic checkpoints
+   - Off-chain state updates
+
+3. Close Initiation
+   - Either party can initiate
+   - Submit final checkpoint
+
+4. Challenge Period (24h default)
+   - Counter-party can dispute
+   - Submit newer checkpoint to win
+
+5. Finalization
+   - After challenge period
+   - On-chain settlement
+   - Funds distributed
+```
+
+## API Reference
+
+### ChannelOpener
+
+- `create(request)` - Create new channel
+- `processFunding(stateMachine, txHash, amount)` - Process funding tx
+- `confirmFunding(stateMachine, confirmation)` - Confirm funding
+
+### ChannelStateMachine
+
+- `getChannel()` - Get current channel state
+- `getState()` - Get channel state enum
+- `process(event)` - Process state transition
+- `canTransition(state)` - Check if transition allowed
+- `updateBalance(payer, payee)` - Update balances
+- `addCheckpoint(checkpoint)` - Add checkpoint
+- `onStateChange(state, callback)` - Subscribe to changes
+
+### FlowController
+
+- `start()` - Start streaming
+- `pause()` - Pause streaming
+- `resume()` - Resume streaming
+- `stop()` - Stop and get final amount
+- `cancel(reason)` - Cancel streaming
+- `getCurrentAmount()` - Get current streamed amount
+- `getCurrentRate()` - Get effective rate
+- `createCheckpoint()` - Create manual checkpoint
+- `onEvent(callback)` - Subscribe to events
+
+### CheckpointManager
+
+- `create(request)` - Create checkpoint
+- `getLatest(channelId)` - Get latest checkpoint
+- `validate(checkpoint)` - Validate checkpoint
+- `verifyCheckpointChain(checkpoints)` - Verify integrity
+- `needsCheckpoint(channelId, balance)` - Check if needed
+
+### FinalSettlementManager
+
+- `initiate(request)` - Start settlement
+- `processMutual(...)` - Mutual (instant) close
+- `canFinalize(channelId)` - Check if can finalize
+- `finalize(channelId)` - Complete settlement
+
+### DisputeManager
+
+- `raise(request)` - Raise dispute
+- `respond(response)` - Respond to dispute
+- `resolve(...)` - Resolve dispute
+- `addEvidence(...)` - Add evidence
+- `evaluateEvidence(disputeId)` - Evaluate evidence
+
+## Dispute Reasons
+
+| Reason | Description |
+|--------|-------------|
+| `invalid_checkpoint` | Checkpoint signature/data invalid |
+| `stale_state` | Challenger has newer valid state |
+| `balance_mismatch` | Balance doesn't match expected |
+| `unauthorized_close` | Unauthorized party initiated close |
+| `fraud` | Fraudulent activity detected |
+
+## Configuration
+
+### Settlement Config
+
+```typescript
+const settlementConfig = {
+  challengePeriod: 86400,      // 24 hours
+  disputeResponsePeriod: 43200, // 12 hours
+  disputeResolutionPeriod: 172800, // 48 hours
+  minCheckpointInterval: 60,   // 60 seconds
+  maxCheckpointsStored: 100,
+  settlementFee: '0',
+  disputeBond: '0',
+};
+```
+
+### Billing Config
+
+```typescript
+const billingConfig = {
+  period: 'realtime', // 'second' | 'minute' | 'hour' | 'day'
+  minimumCharge: '0',
+  roundingMode: 'floor', // 'ceil' | 'round'
+  gracePeriod: 0,
+  invoiceInterval: 86400, // Generate invoice daily
+};
+```
+
+## License
+
+Internal use only - T402 Protocol