binance-api/specs/001-credential-manager/contracts/pacifica-signer.ts

/**
 * Pacifica平台签名器契约
 *
 * 定义Pacifica平台特定的签名接口和数据结构
 * 使用Ed25519算法进行签名操作
 */

import { Platform, SignRequest, SignResponse, VerifyRequest, VerifyResponse } from './credential-manager';

// ============================================================================
// Pacifica特定接口
// ============================================================================

/**
 * Pacifica平台签名器接口
 */
export interface IPacificaSigner {
  readonly platform: Platform.PACIFICA;

  /**
   * 对Pacifica订单进行签名
   * @param request Pacifica签名请求
   * @returns 签名结果，包含base64编码的Ed25519签名
   */
  signOrder(request: PacificaSignRequest): Promise<PacificaSignResponse>;

  /**
   * 验证Pacifica签名
   * @param request 验证请求
   * @returns 验证结果
   */
  verifySignature(request: PacificaVerifyRequest): Promise<PacificaVerifyResponse>;

  /**
   * 获取账户公钥
   * @param accountId 账户ID
   * @returns base58编码的公钥
   */
  getPublicKey(accountId: string): Promise<string>;

  /**
   * 批量签名（提高性能）
   * @param requests 批量签名请求
   * @returns 批量签名结果
   */
  signBatch(requests: PacificaSignRequest[]): Promise<PacificaSignResponse[]>;
}

// ============================================================================
// Pacifica请求/响应类型
// ============================================================================

export interface PacificaSignRequest extends Omit<SignRequest, 'options'> {
  /**
   * 订单类型，影响签名格式
   */
  orderType: PacificaOrderType;

  /**
   * Pacifica特定选项
   */
  options?: PacificaSignOptions;
}

export interface PacificaSignOptions {
  /**
   * 签名超时时间（毫秒）
   * @default 30000
   */
  timeout?: number;

  /**
   * 是否包含时间戳
   * @default true
   */
  includeTimestamp?: boolean;

  /**
   * 签名编码格式
   * @default 'base64'
   */
  encoding?: 'base64' | 'base58' | 'hex';

  /**
   * 是否启用批量优化
   * @default false
   */
  enableBatchOptimization?: boolean;
}

export interface PacificaSignResponse extends SignResponse {
  /**
   * Pacifica签名格式，base64编码
   */
  signature: string;

  /**
   * 固定为'ed25519'
   */
  algorithm: 'ed25519';

  /**
   * 用于Pacifica API的公钥
   */
  publicKey: string;

  /**
   * 订单类型
   */
  orderType: PacificaOrderType;
}

export interface PacificaVerifyRequest extends VerifyRequest {
  /**
   * Pacifica公钥，base58编码
   */
  publicKey: string;

  /**
   * 订单类型
   */
  orderType?: PacificaOrderType;
}

export interface PacificaVerifyResponse extends VerifyResponse {
  /**
   * 固定为'ed25519'
   */
  algorithm: 'ed25519';

  /**
   * 验证的公钥
   */
  publicKey: string;
}

// ============================================================================
// Pacifica特定枚举和常量
// ============================================================================

export enum PacificaOrderType {
  MARKET = 'market',
  LIMIT = 'limit',
  STOP_LOSS = 'stop_loss',
  TAKE_PROFIT = 'take_profit',
  CANCEL = 'cancel',
  CANCEL_ALL = 'cancel_all'
}

/**
 * Pacifica API常量
 */
export const PACIFICA_CONSTANTS = {
  /**
   * Ed25519私钥长度（字节）
   */
  PRIVATE_KEY_LENGTH: 32,

  /**
   * Ed25519公钥长度（字节）
   */
  PUBLIC_KEY_LENGTH: 32,

  /**
   * Ed25519签名长度（字节）
   */
  SIGNATURE_LENGTH: 64,

  /**
   * 私钥十六进制字符串长度
   */
  PRIVATE_KEY_HEX_LENGTH: 64,

  /**
   * 公钥base58字符串典型长度
   */
  PUBLIC_KEY_BASE58_LENGTH: 44,

  /**
   * 签名base64字符串长度
   */
  SIGNATURE_BASE64_LENGTH: 88,

  /**
   * 最大消息大小（字节）
   */
  MAX_MESSAGE_SIZE: 1024 * 1024, // 1MB

  /**
   * 默认签名超时（毫秒）
   */
  DEFAULT_SIGN_TIMEOUT: 30000,

  /**
   * 最大批量签名数量
   */
  MAX_BATCH_SIZE: 100
} as const;

// ============================================================================
// Pacifica消息格式
// ============================================================================

/**
 * Pacifica订单消息结构
 */
export interface PacificaOrderMessage {
  /**
   * 订单类型
   */
  order_type: PacificaOrderType;

  /**
   * 交易对
   */
  symbol: string;

  /**
   * 订单方向
   */
  side: 'buy' | 'sell';

  /**
   * 数量
   */
  size: string;

  /**
   * 价格（限价单）
   */
  price?: string;

  /**
   * 客户端订单ID
   */
  client_id?: string;

  /**
   * 时间戳
   */
  timestamp: number;

  /**
   * 过期时间
   */
  expiry?: number;
}

/**
 * Pacifica取消订单消息
 */
export interface PacificaCancelMessage {
  /**
   * 订单类型
   */
  order_type: 'cancel' | 'cancel_all';

  /**
   * 要取消的订单ID（单个取消）
   */
  order_id?: string;

  /**
   * 交易对（取消所有）
   */
  symbol?: string;

  /**
   * 时间戳
   */
  timestamp: number;
}

// ============================================================================
// 辅助函数接口
// ============================================================================

/**
 * Pacifica消息序列化器
 */
export interface IPacificaMessageSerializer {
  /**
   * 序列化订单消息为签名用的字节数组
   */
  serializeOrder(message: PacificaOrderMessage): Uint8Array;

  /**
   * 序列化取消消息为签名用的字节数组
   */
  serializeCancel(message: PacificaCancelMessage): Uint8Array;

  /**
   * 验证消息格式
   */
  validateMessage(message: PacificaOrderMessage | PacificaCancelMessage): boolean;
}

/**
 * Pacifica密钥工具
 */
export interface IPacificaKeyUtils {
  /**
   * 从十六进制私钥生成公钥
   */
  derivePublicKey(privateKeyHex: string): Promise<string>;

  /**
   * 验证私钥格式
   */
  validatePrivateKey(privateKeyHex: string): boolean;

  /**
   * 验证公钥格式
   */
  validatePublicKey(publicKeyBase58: string): boolean;

  /**
   * 转换密钥格式
   */
  convertKeyFormat(
    key: string,
    from: 'hex' | 'base58' | 'base64',
    to: 'hex' | 'base58' | 'base64'
  ): string;
}

// ============================================================================
// 错误类型
// ============================================================================

export class PacificaSignerError extends Error {
  constructor(
    message: string,
    public readonly code: PacificaErrorCode,
    public readonly details?: any
  ) {
    super(message);
    this.name = 'PacificaSignerError';
  }
}

export enum PacificaErrorCode {
  INVALID_PRIVATE_KEY = 'INVALID_PRIVATE_KEY',
  INVALID_PUBLIC_KEY = 'INVALID_PUBLIC_KEY',
  INVALID_MESSAGE = 'INVALID_MESSAGE',
  SIGNATURE_FAILED = 'SIGNATURE_FAILED',
  VERIFICATION_FAILED = 'VERIFICATION_FAILED',
  ACCOUNT_NOT_FOUND = 'ACCOUNT_NOT_FOUND',
  TIMEOUT = 'TIMEOUT',
  BATCH_SIZE_EXCEEDED = 'BATCH_SIZE_EXCEEDED',
  MESSAGE_TOO_LARGE = 'MESSAGE_TOO_LARGE'
}

// ============================================================================
// 性能监控接口
// ============================================================================

export interface PacificaSignerMetrics {
  /**
   * 总签名次数
   */
  totalSignatures: number;

  /**
   * 成功签名次数
   */
  successfulSignatures: number;

  /**
   * 失败签名次数
   */
  failedSignatures: number;

  /**
   * 平均签名时间（毫秒）
   */
  averageSignTime: number;

  /**
   * 最大签名时间（毫秒）
   */
  maxSignTime: number;

  /**
   * 最小签名时间（毫秒）
   */
  minSignTime: number;

  /**
   * 批量签名次数
   */
  batchSignatures: number;

  /**
   * 平均批量大小
   */
  averageBatchSize: number;

  /**
   * 上次重置时间
   */
  lastResetAt: Date;
}