@sip-protocol/sdk 0.7.3 → 0.8.0

package/src/fees/near-contract.ts

@@ -0,0 +1,429 @@
+/**
+ * NEAR Fee Contract Interface
+ *
+ * Interface for interacting with the SIP Protocol fee contract on NEAR.
+ * The fee contract collects protocol fees from private intents.
+ *
+ * @module fees/near-contract
+ */
+
+import type { ChainId } from '@sip-protocol/types'
+import type {
+  ChainFeeConfig,
+  FeeCalculationInput,
+  FeeCalculationResult,
+  FeeContractState,
+  FeeStats,
+  TreasuryConfig,
+} from './types'
+import { FeeCalculator, DEFAULT_CHAIN_FEES } from './calculator'
+
+// ─── Contract Configuration ──────────────────────────────────────────────────
+
+/**
+ * NEAR fee contract addresses
+ */
+export const NEAR_FEE_CONTRACTS = {
+  /** Mainnet fee contract */
+  mainnet: 'fee.sip-protocol.near',
+  /** Testnet fee contract (for development) */
+  testnet: 'fee.sip-protocol.testnet',
+} as const
+
+/**
+ * Default treasury configuration
+ */
+export const DEFAULT_TREASURY: TreasuryConfig = {
+  nearAccount: 'treasury.sip-protocol.near',
+  evmAddress: '0x0000000000000000000000000000000000000000', // TBD
+  solanaAddress: '11111111111111111111111111111111', // TBD
+  multiSigThreshold: 2,
+  multiSigSigners: [],
+}
+
+// ─── Contract Interface ──────────────────────────────────────────────────────
+
+/**
+ * NEAR fee contract client options
+ */
+export interface NEARFeeContractOptions {
+  /** Contract account ID */
+  contractId?: string
+  /** Network (mainnet/testnet) */
+  network?: 'mainnet' | 'testnet'
+  /** NEAR RPC URL */
+  rpcUrl?: string
+  /** Fee calculator instance */
+  calculator?: FeeCalculator
+  /** Treasury configuration */
+  treasury?: TreasuryConfig
+}
+
+/**
+ * Fee collection parameters
+ */
+export interface FeeCollectionParams {
+  /** Transaction amount */
+  amount: bigint
+  /** Amount in USD */
+  amountUsd: number
+  /** Source chain */
+  sourceChain: ChainId
+  /** Destination chain */
+  destinationChain: ChainId
+  /** Transaction hash (for reference) */
+  txHash?: string
+  /** Viewing key disclosed */
+  viewingKeyDisclosed?: boolean
+  /** Intent ID (for tracking) */
+  intentId?: string
+}
+
+/**
+ * Fee collection result
+ */
+export interface FeeCollectionResult {
+  /** Fee amount collected */
+  feeAmount: bigint
+  /** Fee in USD */
+  feeUsd: number
+  /** Collection transaction hash */
+  collectionTxHash?: string
+  /** Treasury account */
+  treasuryAccount: string
+  /** Timestamp */
+  timestamp: number
+}
+
+/**
+ * NEAR Fee Contract Client
+ *
+ * Provides interface for fee calculation and collection on NEAR.
+ *
+ * @example
+ * ```typescript
+ * const feeContract = new NEARFeeContract({
+ *   network: 'mainnet',
+ * })
+ *
+ * // Calculate fee
+ * const fee = await feeContract.calculateFee({
+ *   amount: 1000000000000000000000000n, // 1 NEAR
+ *   amountUsd: 5.00,
+ *   sourceChain: 'near',
+ *   destinationChain: 'ethereum',
+ * })
+ *
+ * console.log(`Fee: ${fee.protocolFeeUsd} USD`)
+ * ```
+ */
+export class NEARFeeContract {
+  private readonly contractId: string
+  private readonly network: 'mainnet' | 'testnet'
+  private readonly rpcUrl: string
+  private readonly calculator: FeeCalculator
+  private readonly treasury: TreasuryConfig
+
+  // Simulated state (would be on-chain in production)
+  private state: FeeContractState
+
+  constructor(options: NEARFeeContractOptions = {}) {
+    this.network = options.network ?? 'mainnet'
+    this.contractId =
+      options.contractId ?? NEAR_FEE_CONTRACTS[this.network]
+    this.rpcUrl =
+      options.rpcUrl ??
+      (this.network === 'mainnet'
+        ? 'https://rpc.mainnet.near.org'
+        : 'https://rpc.testnet.near.org')
+    this.calculator = options.calculator ?? new FeeCalculator()
+    this.treasury = options.treasury ?? DEFAULT_TREASURY
+
+    // Initialize state
+    this.state = {
+      owner: this.treasury.nearAccount,
+      treasury: this.treasury.nearAccount,
+      config: DEFAULT_CHAIN_FEES.near,
+      totalCollected: 0n,
+      paused: false,
+    }
+  }
+
+  // ─── Fee Calculation ─────────────────────────────────────────────────────────
+
+  /**
+   * Calculate fee for a transaction
+   */
+  async calculateFee(params: FeeCollectionParams): Promise<FeeCalculationResult> {
+    if (this.state.paused) {
+      // Return zero fee if paused
+      return {
+        protocolFee: 0n,
+        protocolFeeUsd: 0,
+        appliedBps: 0,
+        discountBps: 0,
+        originalFee: 0n,
+        breakdown: {
+          baseFee: 0n,
+          networkFee: 0n,
+          totalFee: 0n,
+          components: [],
+        },
+      }
+    }
+
+    const input: FeeCalculationInput = {
+      amount: params.amount,
+      amountUsd: params.amountUsd,
+      sourceChain: params.sourceChain,
+      destinationChain: params.destinationChain,
+      viewingKeyDisclosed: params.viewingKeyDisclosed ?? false,
+    }
+
+    return this.calculator.calculate(input)
+  }
+
+  /**
+   * Get fee estimate for UI display
+   */
+  async estimateFee(
+    amountUsd: number,
+    sourceChain: ChainId = 'near'
+  ): Promise<{ feeUsd: number; bps: number; tierName?: string }> {
+    const result = await this.calculateFee({
+      amount: BigInt(Math.floor(amountUsd * 1e24)), // NEAR decimals
+      amountUsd,
+      sourceChain,
+      destinationChain: sourceChain,
+    })
+
+    return {
+      feeUsd: result.protocolFeeUsd,
+      bps: result.appliedBps,
+      tierName: result.tierName,
+    }
+  }
+
+  // ─── Fee Collection ──────────────────────────────────────────────────────────
+
+  /**
+   * Collect fee for a transaction
+   *
+   * In production, this would create a NEAR transaction to transfer
+   * the fee to the treasury. For now, it simulates the collection.
+   */
+  async collectFee(params: FeeCollectionParams): Promise<FeeCollectionResult> {
+    if (this.state.paused) {
+      throw new Error('Fee collection is paused')
+    }
+
+    // Calculate fee
+    const feeResult = await this.calculateFee(params)
+
+    // Simulate collection (would be on-chain in production)
+    this.state.totalCollected += feeResult.protocolFee
+
+    return {
+      feeAmount: feeResult.protocolFee,
+      feeUsd: feeResult.protocolFeeUsd,
+      collectionTxHash: undefined, // Would be set after on-chain tx
+      treasuryAccount: this.treasury.nearAccount,
+      timestamp: Date.now(),
+    }
+  }
+
+  /**
+   * Batch collect fees for multiple transactions
+   */
+  async batchCollectFees(
+    params: FeeCollectionParams[]
+  ): Promise<FeeCollectionResult[]> {
+    const results: FeeCollectionResult[] = []
+
+    for (const p of params) {
+      const result = await this.collectFee(p)
+      results.push(result)
+    }
+
+    return results
+  }
+
+  // ─── State Management ────────────────────────────────────────────────────────
+
+  /**
+   * Get contract state
+   */
+  async getState(): Promise<FeeContractState> {
+    return { ...this.state }
+  }
+
+  /**
+   * Get fee configuration
+   */
+  async getConfig(): Promise<ChainFeeConfig> {
+    return { ...this.state.config }
+  }
+
+  /**
+   * Update fee configuration (owner only)
+   */
+  async updateConfig(config: Partial<ChainFeeConfig>): Promise<void> {
+    this.state.config = { ...this.state.config, ...config }
+    this.calculator.updateChainConfig('near', config)
+  }
+
+  /**
+   * Get treasury configuration
+   */
+  async getTreasury(): Promise<TreasuryConfig> {
+    return { ...this.treasury }
+  }
+
+  /**
+   * Get fee statistics
+   */
+  async getStats(
+    startTime?: number,
+    endTime?: number
+  ): Promise<FeeStats> {
+    // In production, this would query historical data
+    const now = Date.now()
+    return {
+      totalCollectedUsd: Number(this.state.totalCollected) / 1e24 * 5, // Assume $5/NEAR
+      byChain: {
+        near: this.state.totalCollected,
+      } as Record<ChainId, bigint>,
+      totalTransactions: 0, // Would be tracked
+      avgFeeUsd: 0,
+      periodStart: startTime ?? now - 86400000,
+      periodEnd: endTime ?? now,
+    }
+  }
+
+  // ─── Admin Functions ─────────────────────────────────────────────────────────
+
+  /**
+   * Pause fee collection (emergency)
+   */
+  async pause(): Promise<void> {
+    this.state.paused = true
+  }
+
+  /**
+   * Resume fee collection
+   */
+  async resume(): Promise<void> {
+    this.state.paused = false
+  }
+
+  /**
+   * Check if fee collection is paused
+   */
+  async isPaused(): Promise<boolean> {
+    return this.state.paused
+  }
+
+  /**
+   * Withdraw fees to treasury
+   *
+   * In production, this would create a NEAR transaction.
+   */
+  async withdrawToTreasury(amount?: bigint): Promise<string> {
+    const withdrawAmount = amount ?? this.state.totalCollected
+
+    if (withdrawAmount > this.state.totalCollected) {
+      throw new Error('Insufficient balance')
+    }
+
+    // Simulate withdrawal
+    this.state.totalCollected -= withdrawAmount
+
+    // Return mock transaction hash
+    return `withdraw_${Date.now()}_${withdrawAmount.toString()}`
+  }
+
+  // ─── Contract Info ───────────────────────────────────────────────────────────
+
+  /**
+   * Get contract ID
+   */
+  getContractId(): string {
+    return this.contractId
+  }
+
+  /**
+   * Get network
+   */
+  getNetwork(): 'mainnet' | 'testnet' {
+    return this.network
+  }
+
+  /**
+   * Get RPC URL
+   */
+  getRpcUrl(): string {
+    return this.rpcUrl
+  }
+}
+
+// ─── Factory Functions ───────────────────────────────────────────────────────
+
+/**
+ * Create NEAR fee contract client
+ */
+export function createNEARFeeContract(
+  options?: NEARFeeContractOptions
+): NEARFeeContract {
+  return new NEARFeeContract(options)
+}
+
+/**
+ * Create mainnet fee contract client
+ */
+export function createMainnetFeeContract(): NEARFeeContract {
+  return new NEARFeeContract({ network: 'mainnet' })
+}
+
+/**
+ * Create testnet fee contract client
+ */
+export function createTestnetFeeContract(): NEARFeeContract {
+  return new NEARFeeContract({ network: 'testnet' })
+}
+
+// ─── Integration Helpers ─────────────────────────────────────────────────────
+
+/**
+ * Calculate fee and add to transaction
+ *
+ * Helper for integrating fee collection into swap flows.
+ */
+export async function calculateFeeForSwap(
+  contract: NEARFeeContract,
+  swapAmount: bigint,
+  swapAmountUsd: number,
+  sourceChain: ChainId,
+  destChain: ChainId,
+  viewingKeyDisclosed = false
+): Promise<{
+  fee: FeeCalculationResult
+  netAmount: bigint
+  netAmountUsd: number
+}> {
+  const fee = await contract.calculateFee({
+    amount: swapAmount,
+    amountUsd: swapAmountUsd,
+    sourceChain,
+    destinationChain: destChain,
+    viewingKeyDisclosed,
+  })
+
+  const netAmount = swapAmount - fee.protocolFee
+  const netAmountUsd = swapAmountUsd - fee.protocolFeeUsd
+
+  return {
+    fee,
+    netAmount,
+    netAmountUsd,
+  }
+}

package/src/fees/types.ts

@@ -0,0 +1,268 @@
+/**
+ * Fee Types for SIP Protocol
+ *
+ * Defines fee structure, tiers, and configuration for protocol revenue.
+ *
+ * @module fees/types
+ */
+
+import type { ChainId, HexString } from '@sip-protocol/types'
+
+// ─── Fee Models ──────────────────────────────────────────────────────────────
+
+/**
+ * Fee model type
+ */
+export type FeeModel =
+  | 'flat' // Fixed fee per transaction
+  | 'percentage' // Percentage of volume (basis points)
+  | 'tiered' // Tiered based on volume
+  | 'dynamic' // Dynamic based on network conditions
+
+/**
+ * Fee tier configuration
+ */
+export interface FeeTier {
+  /** Tier name for display */
+  name: string
+  /** Minimum volume (USD) for this tier */
+  minVolume: number
+  /** Maximum volume (USD) for this tier (Infinity for unlimited) */
+  maxVolume: number
+  /** Fee rate in basis points (100 = 1%) */
+  basisPoints: number
+}
+
+/**
+ * Fee configuration for a chain
+ */
+export interface ChainFeeConfig {
+  /** Chain identifier */
+  chain: ChainId
+  /** Fee model */
+  model: FeeModel
+  /** Base fee in basis points (for percentage model) */
+  baseBps: number
+  /** Flat fee in native token smallest unit (for flat model) */
+  flatFee?: bigint
+  /** Fee tiers (for tiered model) */
+  tiers?: FeeTier[]
+  /** Minimum fee in USD */
+  minFeeUsd: number
+  /** Maximum fee in USD (cap) */
+  maxFeeUsd: number
+  /** Fee discount for viewing key disclosure (basis points reduction) */
+  viewingKeyDiscountBps: number
+}
+
+// ─── Fee Calculation ─────────────────────────────────────────────────────────
+
+/**
+ * Fee calculation input
+ */
+export interface FeeCalculationInput {
+  /** Transaction amount in smallest units */
+  amount: bigint
+  /** Amount in USD for tier calculation */
+  amountUsd: number
+  /** Source chain */
+  sourceChain: ChainId
+  /** Destination chain */
+  destinationChain: ChainId
+  /** Whether viewing key is disclosed */
+  viewingKeyDisclosed: boolean
+  /** Custom fee override (for governance) */
+  customBps?: number
+}
+
+/**
+ * Fee calculation result
+ */
+export interface FeeCalculationResult {
+  /** Protocol fee in source token smallest units */
+  protocolFee: bigint
+  /** Protocol fee in USD */
+  protocolFeeUsd: number
+  /** Fee rate applied (basis points) */
+  appliedBps: number
+  /** Fee tier used (if tiered model) */
+  tierName?: string
+  /** Discount applied (if viewing key disclosed) */
+  discountBps: number
+  /** Original fee before discount */
+  originalFee: bigint
+  /** Fee breakdown for display */
+  breakdown: FeeBreakdown
+}
+
+/**
+ * Fee breakdown for transparency
+ */
+export interface FeeBreakdown {
+  /** Base protocol fee */
+  baseFee: bigint
+  /** Network/gas fee estimate */
+  networkFee: bigint
+  /** Total fee */
+  totalFee: bigint
+  /** Fee components */
+  components: Array<{
+    name: string
+    amount: bigint
+    description: string
+  }>
+}
+
+// ─── Treasury Management ─────────────────────────────────────────────────────
+
+/**
+ * Treasury address configuration
+ */
+export interface TreasuryConfig {
+  /** NEAR treasury account */
+  nearAccount: string
+  /** Ethereum treasury address */
+  evmAddress: HexString
+  /** Solana treasury address */
+  solanaAddress: string
+  /** Multi-sig threshold (if applicable) */
+  multiSigThreshold?: number
+  /** Multi-sig signers */
+  multiSigSigners?: string[]
+}
+
+/**
+ * Fee collection event
+ */
+export interface FeeCollectionEvent {
+  /** Event ID */
+  id: string
+  /** Timestamp */
+  timestamp: number
+  /** Chain where fee was collected */
+  chain: ChainId
+  /** Transaction hash */
+  txHash: string
+  /** Fee amount in native token */
+  amount: bigint
+  /** Fee amount in USD */
+  amountUsd: number
+  /** Source transaction (swap/intent) */
+  sourceTransaction?: string
+  /** Treasury account that received fee */
+  treasuryAccount: string
+}
+
+/**
+ * Fee statistics
+ */
+export interface FeeStats {
+  /** Total fees collected (USD) */
+  totalCollectedUsd: number
+  /** Total fees collected by chain */
+  byChain: Record<ChainId, bigint>
+  /** Total transactions */
+  totalTransactions: number
+  /** Average fee per transaction (USD) */
+  avgFeeUsd: number
+  /** Period start */
+  periodStart: number
+  /** Period end */
+  periodEnd: number
+}
+
+// ─── Fee Contract Interface ──────────────────────────────────────────────────
+
+/**
+ * Fee contract state
+ */
+export interface FeeContractState {
+  /** Contract owner (can update config) */
+  owner: string
+  /** Treasury account */
+  treasury: string
+  /** Current fee configuration */
+  config: ChainFeeConfig
+  /** Total fees collected */
+  totalCollected: bigint
+  /** Paused state */
+  paused: boolean
+  /** Governance contract (if applicable) */
+  governanceContract?: string
+}
+
+/**
+ * Fee contract methods
+ */
+export interface FeeContractMethods {
+  /** Calculate fee for a transaction */
+  calculateFee(input: FeeCalculationInput): Promise<FeeCalculationResult>
+  /** Collect fee (called during swap) */
+  collectFee(amount: bigint, txHash: string): Promise<string>
+  /** Update fee configuration (owner only) */
+  updateConfig(config: Partial<ChainFeeConfig>): Promise<void>
+  /** Withdraw fees to treasury (owner only) */
+  withdrawToTreasury(amount?: bigint): Promise<string>
+  /** Get contract state */
+  getState(): Promise<FeeContractState>
+  /** Pause fee collection (emergency) */
+  pause(): Promise<void>
+  /** Resume fee collection */
+  resume(): Promise<void>
+}
+
+// ─── Fee Waiver ──────────────────────────────────────────────────────────────
+
+/**
+ * Fee waiver type
+ */
+export type FeeWaiverType =
+  | 'viewing_key' // Viewing key disclosure
+  | 'governance' // Governance holder
+  | 'volume' // High volume tier
+  | 'promotional' // Promotional period
+  | 'partner' // Partner integration
+
+/**
+ * Fee waiver configuration
+ */
+export interface FeeWaiver {
+  /** Waiver type */
+  type: FeeWaiverType
+  /** Discount in basis points (100 = 1% off) */
+  discountBps: number
+  /** Waiver expiry (0 for permanent) */
+  expiresAt?: number
+  /** Maximum uses (0 for unlimited) */
+  maxUses?: number
+  /** Current uses */
+  currentUses: number
+  /** Waiver code (for promotional) */
+  code?: string
+}
+
+// ─── Governance ──────────────────────────────────────────────────────────────
+
+/**
+ * Fee governance proposal
+ */
+export interface FeeGovernanceProposal {
+  /** Proposal ID */
+  id: string
+  /** Proposal type */
+  type: 'update_config' | 'update_treasury' | 'pause' | 'resume'
+  /** Proposed changes */
+  changes: Partial<ChainFeeConfig> | Partial<TreasuryConfig>
+  /** Proposer */
+  proposer: string
+  /** Votes for */
+  votesFor: bigint
+  /** Votes against */
+  votesAgainst: bigint
+  /** Voting end time */
+  votingEndsAt: number
+  /** Execution time (after voting) */
+  executionTime: number
+  /** Status */
+  status: 'pending' | 'passed' | 'rejected' | 'executed'
+}