/** * 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; /** * 验证Pacifica签名 * @param request 验证请求 * @returns 验证结果 */ verifySignature(request: PacificaVerifyRequest): Promise; /** * 获取账户公钥 * @param accountId 账户ID * @returns base58编码的公钥 */ getPublicKey(accountId: string): Promise; /** * 批量签名(提高性能) * @param requests 批量签名请求 * @returns 批量签名结果 */ signBatch(requests: PacificaSignRequest[]): Promise; } // ============================================================================ // Pacifica请求/响应类型 // ============================================================================ export interface PacificaSignRequest extends Omit { /** * 订单类型,影响签名格式 */ 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; /** * 验证私钥格式 */ 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; }