binance-api

Pacifica凭据管理服务

🎯 概述

专注于Pacifica平台的内部凭据管理系统，提供Ed25519签名服务供项目内部其他模块调用。

核心特性：

• ✅ 单一职责: 专注于凭据分类管理和签名服务
• ✅ 内部调用: 供项目内部模块使用，非HTTP API
• ✅ 高性能: Ed25519签名 <50ms 响应时间
• ✅ 热重载: 配置文件变化自动检测和重载
• ✅ 类型安全: 完整的TypeScript类型定义

📦 快速开始

1. 配置文件设置

创建 credentials.json 配置文件：

{
  "pacifica": [
    {
      "accountId": "pac-main-001",
      "alias": "Pacifica主账户",
      "privateKey": "your_base58_private_key_here",
      "environment": "production"
    },
    {
      "accountId": "pac-dev-001",
      "alias": "Pacifica开发账户",
      "privateKey": "your_development_private_key_here",
      "environment": "development"
    }
  ]
}

2. 基本使用

import { signPacifica, hasPacificaAccount } from './src/services/index.js';

// 检查账户是否存在
if (hasPacificaAccount('pac-main-001')) {

  // 执行签名
  const result = await signPacifica('pac-main-001', {
    instruction: {
      type: 'place_order',
      market: 'BTC-USD',
      side: 'bid',
      amount: '0.001',
      price: '65000'
    },
    nonce: Date.now()
  });

  console.log('签名:', result.signature);
  console.log('公钥:', result.publicKey);
}

🔧 API 参考

便捷函数

signPacifica(accountId, data)

执行单次Pacifica签名

import { signPacifica, PacificaSignData } from './src/services/index.js';

const signData: PacificaSignData = {
  instruction: {
    type: 'place_order',
    market: 'BTC-USD',
    side: 'bid',
    amount: '0.001',
    price: '65000'
  },
  nonce: Date.now()
};

const result = await signPacifica('pac-main-001', signData);

signPacificaBatch(requests)

执行批量Pacifica签名

import { signPacificaBatch } from './src/services/index.js';

const requests = [
  {
    accountId: 'pac-main-001',
    requestId: 'order_1',
    data: { instruction: { type: 'place_order' } }
  },
  {
    accountId: 'pac-main-002',
    requestId: 'order_2',
    data: { instruction: { type: 'cancel_order' } }
  }
];

const results = await signPacificaBatch(requests);

hasPacificaAccount(accountId)

检查账户是否存在

import { hasPacificaAccount } from './src/services/index.js';

if (hasPacificaAccount('pac-main-001')) {
  console.log('账户存在');
}

getPacificaPublicKey(accountId)

获取账户公钥

import { getPacificaPublicKey } from './src/services/index.js';

const publicKey = getPacificaPublicKey('pac-main-001');
console.log('公钥:', publicKey);

高级用法

直接使用服务实例

import { getCredentialService } from './src/services/index.js';

const service = getCredentialService();

// 获取服务状态
const status = service.getStatus();
console.log('Pacifica账户数:', status.pacificaAccounts);

// 获取所有账户
const accounts = service.getPacificaAccounts();

// 监听事件
service.on('signature:success', (event) => {
  console.log(`签名成功: ${event.accountId}`);
});

service.on('signature:error', (event) => {
  console.log(`签名失败: ${event.accountId} - ${event.error}`);
});

🏗️ 在交易模块中的集成

示例：交易模块

import { signPacifica, hasPacificaAccount } from './src/services/index.js';

class TradingModule {
  async placeOrder(accountId: string, market: string, side: 'bid' | 'ask', amount: string, price: string) {
    // 1. 检查账户
    if (!hasPacificaAccount(accountId)) {
      throw new Error(`账户 ${accountId} 不可用`);
    }

    // 2. 构建订单数据
    const orderData = {
      instruction: {
        type: 'place_order',
        market,
        side,
        amount,
        price
      },
      nonce: Date.now()
    };

    // 3. 执行签名
    const signatureResult = await signPacifica(accountId, orderData);

    // 4. 提交到Pacifica交易所
    return this.submitToPacifica(signatureResult);
  }
}

示例：对冲交易

import { signPacificaBatch } from './src/services/index.js';

async function hedgeTrade(account1: string, account2: string, market: string, amount: string) {
  const requests = [
    {
      accountId: account1,
      requestId: 'long_position',
      data: {
        instruction: {
          type: 'place_order',
          market,
          side: 'bid',
          amount
        }
      }
    },
    {
      accountId: account2,
      requestId: 'short_position',
      data: {
        instruction: {
          type: 'place_order',
          market,
          side: 'ask',
          amount
        }
      }
    }
  ];

  const results = await signPacificaBatch(requests);

  // 处理结果...
}

📋 支持的订单类型

Pacifica签名适配器支持以下订单类型：

• place_order - 下单
• cancel_order - 撤单
• modify_order - 修改订单
• close_position - 平仓

🧪 测试

# 运行单元测试
npx jest __tests__/unit/pacifica-signature.test.ts
npx jest __tests__/unit/internal-credential-service.test.ts

# 运行使用示例
npx tsx examples/credential-usage.ts

📄 文件结构

src/
├── services/
│   ├── index.ts                    # 统一导出
│   └── credential-service.ts       # 内部凭据服务
├── core/
│   ├── config-loader.ts           # 配置加载器
│   └── signature-adapters/
│       └── pacifica.ts            # Pacifica签名适配器
└── shared/
    ├── credential-types.ts        # 类型定义
    ├── credential-constants.ts    # 常量
    └── credential-utils.ts        # 工具函数

examples/
└── credential-usage.ts           # 使用示例

__tests__/
├── unit/
│   ├── pacifica-signature.test.ts
│   └── internal-credential-service.test.ts
└── fixtures/
    └── test-credentials.json     # 测试配置

🚀 性能特性

• ✅ 单次签名: <50ms 响应时间
• ✅ 批量签名: 平均每个签名 <50ms
• ✅ 内存管理: 自动清理敏感数据
• ✅ 热重载: <5秒配置重载时间
• ✅ 并发安全: 支持多线程并发调用

🔒 安全特性

• ✅ 私钥保护: 内存中加密存储，自动清理
• ✅ 日志脱敏: 敏感信息自动脱敏
• ✅ 类型验证: 严格的输入验证和类型检查
• ✅ 错误隔离: 详细的错误分类和处理

📝 注意事项

1. 配置文件: 请确保 credentials.json 存在且包含有效的Pacifica账户
2. 私钥格式: 必须是44字符的base58编码Ed25519私钥
3. 环境隔离: development和production环境账户分离管理
4. 性能监控: 建议监控签名执行时间，超过50ms时检查系统负载

🔗 相关文档

• Pacifica API文档
• 技术设计文档
• 数据模型说明