Merge branch 'main' into feature/automated-compliance-checks

Author: Mystery-CLI

GOVERNANCE_TOKEN.md

@@ -0,0 +1,212 @@
+import { ApiClient } from './client';
+import { Trade } from './models';
+
+export interface BridgeProvider {
+  name: string;
+  oracle_address: string;
+  is_active: boolean;
+  fee_bps: number;
+  supported_chains: string[];
+  max_trade_amount: string;
+  min_trade_amount: string;
+}
+
+export interface CrossChainTrade {
+  trade_id: number;
+  source_chain: string;
+  dest_chain: string;
+  source_tx_hash: string;
+  bridge_provider: string;
+  attestation_id: string;
+  attestation_status: 'pending' | 'confirmed' | 'failed' | 'expired';
+  attestation_timestamp: number;
+  retry_count: number;
+  current_confirmations: number;
+  bridge_fee: string;
+}
+
+export interface BridgeAttestation {
+  attestation_id: string;
+  trade_id: number;
+  source_chain: string;
+  source_tx_hash: string;
+  amount: string;
+  recipient: string;
+  timestamp: number;
+  signature: string;
+  provider: string;
+}
+
+export interface BridgeValidation {
+  valid: boolean;
+  error_code?: number;
+  error_message?: string;
+  confirmations: number;
+}
+
+export interface ProviderStatus {
+  provider: string;
+  healthy: boolean;
+  latency_ms: number;
+  last_check: number;
+  error?: string;
+}
+
+/**
+ * Bridge API for cross-chain trade operations
+ */
+export class BridgeApi {
+  constructor(private client: ApiClient) {}
+
+  /**
+   * Register a new bridge provider
+   */
+  async registerProvider(provider: Partial<BridgeProvider>): Promise<BridgeProvider> {
+    return this.client.post('/bridge/providers', provider);
+  }
+
+  /**
+   * Get all registered bridge providers
+   */
+  async getProviders(): Promise<BridgeProvider[]> {
+    return this.client.get('/bridge/providers');
+  }
+
+  /**
+   * Get a specific bridge provider
+   */
+  async getProvider(name: string): Promise<BridgeProvider> {
+    return this.client.get(`/bridge/providers/${name}`);
+  }
+
+  /**
+   * Deactivate a bridge provider
+   */
+  async deactivateProvider(name: string): Promise<void> {
+    return this.client.delete(`/bridge/providers/${name}`);
+  }
+
+  /**
+   * Create a cross-chain trade
+   */
+  async createCrossChainTrade(
+    tradeId: number,
+    sourceChain: string,
+    sourceTxHash: string,
+    bridgeProvider: string,
+    attestationId: string,
+    bridgeFee: string
+  ): Promise<CrossChainTrade> {
+    return this.client.post('/bridge/trades', {
+      trade_id: tradeId,
+      source_chain: sourceChain,
+      source_tx_hash: sourceTxHash,
+      bridge_provider: bridgeProvider,
+      attestation_id: attestationId,
+      bridge_fee: bridgeFee,
+    });
+  }
+
+  /**
+   * Get cross-chain trade info
+   */
+  async getCrossChainTrade(tradeId: number): Promise<CrossChainTrade> {
+    return this.client.get(`/bridge/trades/${tradeId}`);
+  }
+
+  /**
+   * Submit bridge attestation
+   */
+  async submitAttestation(attestation: BridgeAttestation): Promise<BridgeValidation> {
+    return this.client.post('/bridge/attestations', attestation);
+  }
+
+  /**
+   * Get attestation status
+   */
+  async getAttestationStatus(attestationId: string): Promise<BridgeValidation> {
+    return this.client.get(`/bridge/attestations/${attestationId}`);
+  }
+
+  /**
+   * Retry failed attestation
+   */
+  async retryAttestation(tradeId: number): Promise<void> {
+    return this.client.post(`/bridge/trades/${tradeId}/retry`, {});
+  }
+
+  /**
+   * Rollback failed cross-chain trade
+   */
+  async rollbackTrade(tradeId: number, reason: string): Promise<CrossChainTrade> {
+    return this.client.post(`/bridge/trades/${tradeId}/rollback`, { reason });
+  }
+
+  /**
+   * Get bridge provider health status
+   */
+  async getProviderStatus(provider: string): Promise<ProviderStatus> {
+    return this.client.get(`/bridge/providers/${provider}/status`);
+  }
+
+  /**
+   * Get all provider statuses
+   */
+  async getAllProviderStatuses(): Promise<ProviderStatus[]> {
+    return this.client.get('/bridge/providers/status/all');
+  }
+
+  /**
+   * Pause bridge operations
+   */
+  async pauseBridge(): Promise<void> {
+    return this.client.post('/bridge/pause', {});
+  }
+
+  /**
+   * Resume bridge operations
+   */
+  async resumeBridge(): Promise<void> {
+    return this.client.post('/bridge/resume', {});
+  }
+
+  /**
+   * Get bridge operational status
+   */
+  async getBridgeStatus(): Promise<{ paused: boolean; providers_active: number }> {
+    return this.client.get('/bridge/status');
+  }
+
+  /**
+   * Query cross-chain trades with filters
+   */
+  async queryCrossChainTrades(filters: {
+    source_chain?: string;
+    bridge_provider?: string;
+    attestation_status?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<{ items: CrossChainTrade[]; total: number; has_more: boolean }> {
+    const params = new URLSearchParams();
+    if (filters.source_chain) params.append('source_chain', filters.source_chain);
+    if (filters.bridge_provider) params.append('bridge_provider', filters.bridge_provider);
+    if (filters.attestation_status) params.append('attestation_status', filters.attestation_status);
+    if (filters.limit) params.append('limit', filters.limit.toString());
+    if (filters.offset) params.append('offset', filters.offset.toString());
+
+    return this.client.get(`/bridge/trades?${params}`);
+  }
+
+  /**
+   * Get bridge statistics
+   */
+  async getBridgeStats(): Promise<{
+    total_cross_chain_trades: number;
+    successful_attestations: number;
+    failed_attestations: number;
+    total_bridge_volume: string;
+    average_confirmation_time_secs: number;
+  }> {
+    return this.client.get('/bridge/stats');
+  }
+}

api/src/bridge.ts

@@ -38,11 +38,18 @@ export function isTrade(value: unknown): value is Trade {
   );
 }
 
+const EVENT_CATEGORIES = new Set<string>([
+  'trade', 'arb', 'fee', 'tmpl', 'sub', 'gov', 'sys', 'ins', 'oracle',
+]);
+
 export function isEvent(value: unknown): value is Event {
   return (
     isRecord(value) &&
     typeof value.id === 'string' &&
     typeof value.type === 'string' &&
+    typeof value.category === 'string' &&
+    EVENT_CATEGORIES.has(value.category) &&
+    typeof value.schemaVersion === 'number' &&
     typeof value.tradeId === 'string' &&
     typeof value.timestamp === 'string' &&
     isRecord(value.data)

api/src/contracts.ts

@@ -8,10 +8,41 @@ export interface Trade {
   timestamp: string;
 }
 
+/** High-level event categories matching the contract's topic layout. */
+export type EventCategory =
+  | 'trade'
+  | 'arb'
+  | 'fee'
+  | 'tmpl'
+  | 'sub'
+  | 'gov'
+  | 'sys'
+  | 'ins'
+  | 'oracle';
+
 export interface Event {
   id: string;
+  /** Canonical snake_case event name, e.g. "trade_created" */
   type: string;
+  /** High-level category for client-side filtering */
+  category: EventCategory;
+  /** Schema version from the contract payload (v field) */
+  schemaVersion: number;
   tradeId: string;
   timestamp: string;
-  data: Record<string, any>;
+  data: Record<string, unknown>;
+}
+
+/** Query parameters accepted by GET /events */
+export interface EventFilterParams {
+  limit?: number;
+  offset?: number;
+  event_type?: string;
+  category?: EventCategory;
+  trade_id?: string;
+  from_ledger?: number;
+  to_ledger?: number;
+  from_time?: string;
+  to_time?: string;
+  contract_id?: string;
 }

api/src/models.ts

@@ -1,5 +1,5 @@
 import { ApiClient } from './client';
-import { Event, Trade } from './models';
+import { Event, EventCategory, EventFilterParams, Trade } from './models';
 
 export class TradesApi {
   constructor(private client: ApiClient) {}
@@ -28,16 +28,29 @@ export class TradesApi {
 export class EventsApi {
   constructor(private client: ApiClient) {}
 
-  async getEvents(limit = 100, tradeId?: string): Promise<Event[]> {
-    const params = new URLSearchParams({ limit: limit.toString() });
-    if (tradeId) params.append('tradeId', tradeId);
+  async getEvents(filters: EventFilterParams = {}): Promise<Event[]> {
+    const params = new URLSearchParams();
+    if (filters.limit !== undefined) params.set('limit', filters.limit.toString());
+    if (filters.offset !== undefined) params.set('offset', filters.offset.toString());
+    if (filters.event_type) params.set('event_type', filters.event_type);
+    if (filters.category) params.set('category', filters.category);
+    if (filters.trade_id) params.set('trade_id', filters.trade_id);
+    if (filters.from_ledger !== undefined) params.set('from_ledger', filters.from_ledger.toString());
+    if (filters.to_ledger !== undefined) params.set('to_ledger', filters.to_ledger.toString());
+    if (filters.from_time) params.set('from_time', filters.from_time);
+    if (filters.to_time) params.set('to_time', filters.to_time);
+    if (filters.contract_id) params.set('contract_id', filters.contract_id);
     return this.client.get(`/events?${params}`);
   }
 
   async getEventsByTrade(tradeId: string): Promise<Event[]> {
     return this.client.get(`/events/trade/${tradeId}`);
   }
 
+  async getEventsByCategory(category: EventCategory, limit = 50): Promise<Event[]> {
+    return this.getEvents({ category, limit });
+  }
+
   async getEvent(id: string): Promise<Event> {
     return this.client.get(`/events/${id}`);
   }