# @amadeus-protocol/sdk 中文文档

规范地址：https://npmcn.com/package/%40amadeus-protocol/sdk/

版本：1\.7\.0
npm 元数据更新时间：2026-10-27T15:52:16.469Z
中文译文更新时间：2026-11-06T10:34:46.604Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amadeus-protocol/sdk
原文对照：https://npmcn.com/package/%40amadeus-protocol/sdk/?lang=original
项目主页：https://github.com/amadeusprotocol/amadeus-typescript-sdk#readme
源码仓库：https://github.com/amadeusprotocol/amadeus-typescript-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：787 kB，203 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：5 个
- 首次发布：2025-12-09T20:15:24.478Z
- 最新版本发布：2026-10-27T15:52:16.250Z
- 近 30 天下载量：3458（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

官方 TypeScript/JavaScript SDK for Amadeus Protocol - 用于序列化,密码化,交易构建和API客户端的核心工具

## 安装

```sh
npm install @amadeus-protocol/sdk
```

也可以使用：`pnpm add @amadeus-protocol/sdk`、`yarn add @amadeus-protocol/sdk`、`bun add @amadeus-protocol/sdk`

## README

# @amadeus-protocol/sdk (英语)

官方 TypeScript/JavaScript SDK for Amadeus Protocol - 用于序列化,密码化,交易构建,以及API客户端的核心公用设施.

[![npm version](https://img.shields.io/npm/v/@amadeus-protocol/sdk)](https://www.npmjs.com/package/@amadeus-protocol/sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@amadeus-protocol/sdk)](https://bundlephobia.com/package/@amadeus-protocol/sdk)

## 安装

```bash
npm install @amadeus-protocol/sdk
# or
yarn add @amadeus-protocol/sdk
# or
pnpm add @amadeus-protocol/sdk
# or
bun add @amadeus-protocol/sdk
```

> **仅限无害环境管理**:本包作为纯无害环境管理发布(`"type": "module"`。使用节点20+ `"type": "module"` 在你身边 `package.json`,或者任何现代的捆绑工(Vite,webpack,esbuilt,Metro). 对于普通JS的消费者,通过 [`tsx`](https://github.com/privatenumber/tsx)。见 [解决问题](https://docs.ama.one/sdk/9.-troubleshooting.md) 联 合 国 `1.0.x` `ERR_MODULE_NOT_FOUND` 发布和升级路径.

## 1.7.0中的新情况

-   **页 次 `get_prefix`** - 因为节点 `78b5e9c` 结尾答案 `{rows, cursor}` 页面. `decodeContractState()` 读出页和旧的形状 `contract.getPrefixEntries()` (因此,每个 `staking.*` 读取)跟随光标。 让你自己 HTTP电话? 使用 `readAllPrefixPages()` 与 `prefixPagePath()`
-   同时提出的一项请求 `AmadeusClient` 不再互相终止

## 1.6.0中有什么新鲜事

-   **双衍生导入** —— 说 `resolveMnemonicImport()` 生成两个账户中的短语 打开,检查每个历史 `addressHasActivity()`,并告诉你要打开的 或用户必须选择。 见 [将短语导入钱包](https://npmcn.com/package/%40amadeus-protocol/sdk/#readme-importing-a-phrase-into-a-wallet)
-   **`resolveCandidateForAddress()`** 找到一个打开已知地址的短语的出处
-   **`derivationForSeed()`** 找到哪一种衍生物产生了被储存的种子
-   `validateMnemonic()` 函数现在接受带有额外空白的短语,或者 换行符
-   `SDK_VERSION` 现在报告真实的软件包版本( 它被卡在 `1.2.0`(中文(简体) )

## 1.5.0中有什么新鲜事

-   **每个短语的两个衍生词** - 自1.4.0起,同一恢复短语可以打开两个 不同的地址,取决于哪个SDK版本得出它. 1.5.0 增加: `mnemonicToCandidateKeypairs()` 因此钱包也可以恢复。 见 [行为和账户衍生](https://npmcn.com/package/%40amadeus-protocol/sdk/#readme-mnemonics-and-account-derivation)
-   **`secretKeyToSeedBase58()`** ——导入一个生的32字节 BLS 密钥(如中枢导出)

见 [变化](https://npmcn.com/package/%40amadeus-protocol/sdk/CHANGELOG.md) 完全释放历史.

## 1.4.0中弹: `mnemonicToSeedBase58` 返回不同的账户

`mnemonicToSeedBase58()` 保留它的名字,但从生的BIP39种子中切换出来(BIP39种子)`legacy`改为: EIP-2333 路径 `m/12381'/36969'/0'/0'/0'` (单位:千美元)`eip2333`),与中枢共享的标准,Prime Hub 和克利华莱特。 重新使用 1. 4.0+ 打开一个短语 **不同地址** 超过1.3.0和 对 储存在保险库里的种子不会受到影响。 见 [变化](https://npmcn.com/package/%40amadeus-protocol/sdk/CHANGELOG.md)。 。 。 .

## 在1.2.0中有什么新东西

-   **摄取( E)`LockupVault`(中文(简体) )** 在一次通话中读取一个账户的占有权: `sdk.staking.getPosition(publicKey)` 返回每个金库外加滚动总数 (计总计分,累计收成,计分计分的APY,到期/解锁状态,每名验证人计分)
-   **`contract.getPrefixEntries()`** - 前缀读取返回为原始 `[key, value]` 字节对. `/api/contract/get_prefix` 用 VecPack 回答 _二进制_ 身体,哪个 `getPrefix()` 管理器 通过解析为文本
-   **`client.postBinary()`** —— POST 返回生字节,用于二进制终点
-   **`decodeContractState()` 修补** – 匹配无物的前缀作为空 VecPack 返回 _列表_,不是空地图。 曾经投出;现在解码为 `[]`。这是常见的情况 任何从未涉入的账户
-   **`ChainStats`** 添加实际返回的节点字段 : `total_locked`, (中文(简体) ), `total_supply`, (中文(简体) ), `supply_computed_at_height`,以及 `validators` (每名验证人) `commission_bps` 和赌注)

见 [变化](https://npmcn.com/package/%40amadeus-protocol/sdk/CHANGELOG.md) 完全释放历史.

## 1.1.0中有什么新鲜事

-   **`contract.view()`** ——只读合同执行
-   **`chain.getByFilter()`** 编号 : **`chain.getKpi()`** ——过滤tx查询+协议KPI
-   **`proof.getContractStateProof()`** 合同状态的墨克尔证明
-   **`submitAndWait(txPacked, { finalized: true })`** 等待最终结果而不是确认
-   **NFT合同** —— 说 `NFT_ABI`, (中文(简体) ), `buildNftTransfer/Mint/CreateCollection`, (中文(简体) ), `TransactionBuilder.nftTransfer/nftMint/nftCreateCollection`
-   **无害环境管理的固定** ——已出版 `dist/*.js` 现在在原始状态下正确解决 `node` (单位:千美元) `1.0.x` `ERR_MODULE_NOT_FOUND` 错误)

见 [变化](https://npmcn.com/package/%40amadeus-protocol/sdk/CHANGELOG.md) 完全释放历史.

## 特征

-   **巨型序列化( VecPack)**: 加密操作的定型编码/解码
-   **密码操作**: BLS12-381 密钥生成,签名和校验
-   **基于密码的加密**: 为钱包数据使用 PBKDF2 密钥加密安全 AES- GCM
-   **交易大楼**: 创建并签名 Amadeus 协议交易
-   **托肯转换**: 原子单位和可读量之间的转换
-   **编码公用事业**: Base58和Base64 地址、密钥和二进制数据的编码/解码
-   **摄取**: 读取锁舱位置——总数、每舱细节和计分的APY
-   **API 客户端**: 与 Amadeus 节点互动的全功能 HTTP 客户端
-   **类型安全**: 所有 API 的完整类型脚本定义
-   **无依赖**: 使用本地获取( 无轴或其他 HTTP 库)

## 快速启动

### 使用 SDK

```typescript
import { AmadeusSDK } from '@amadeus-protocol/sdk'

// Initialize SDK (uses default node URL if not specified)
const sdk = new AmadeusSDK({
    baseUrl: 'https://mainnet-rpc.ama.one/api'
})

// Query chain
const tip = await sdk.chain.getTip()
console.log('Current height:', tip.entry.header.height)

// Query wallet balance
const balance = await sdk.wallet.getBalance('5Kd3N...', 'AMA')
console.log('Balance:', balance.balance.float)

// Submit transaction
const result = await sdk.transaction.submit(txPacked)
```

## 使用量

### API 客户端

```typescript
import { AmadeusSDK } from '@amadeus-protocol/sdk'

const sdk = new AmadeusSDK({
    baseUrl: 'https://mainnet-rpc.ama.one/api',
    timeout: 30000 // Optional: custom timeout
})

// Chain API
const stats = await sdk.chain.getStats()
const tip = await sdk.chain.getTip()
const entry = await sdk.chain.getByHash('5Kd3N...')
const { txs, cursor } = await sdk.chain.getByFilter({ contract: 'Coin', function: 'transfer' })
const { kpi } = await sdk.chain.getKpi()

// Wallet API
const balance = await sdk.wallet.getBalance('5Kd3N...', 'AMA')
const allBalances = await sdk.wallet.getAllBalances('5Kd3N...')

// Transaction API
const result = await sdk.transaction.submit(txPacked)
const confirmed = await sdk.transaction.submitAndWait(txPacked)
const finalized = await sdk.transaction.submitAndWait(txPacked, { finalized: true })
const tx = await sdk.transaction.get('5Kd3N...')

// Contract API
const contractData = await sdk.contract.get(key)
const richlist = await sdk.contract.getRichlist()
const { success, result } = await sdk.contract.view({
    contract: 'LockupPrime',
    function: 'view_balance',
    args: ['my_vault']
})

// Epoch API
const scores = await sdk.epoch.getScore()
const emission = await sdk.epoch.getEmissionAddress('5Kd3N...')

// Peer API
const nodes = await sdk.peer.getNodes()
const trainers = await sdk.peer.getTrainers()

// Proof API
const validatorProof = await sdk.proof.getValidators(entryHash)
const stateProof = await sdk.proof.getContractStateProof(stateKey)
```

### 密钥生成

```typescript
import { generateKeypair, derivePublicKeyFromSeedBase58 } from '@amadeus-protocol/sdk'

// Generate a new keypair
const keypair = generateKeypair()
console.log(keypair.publicKey) // Base58 public key
console.log(keypair.privateKey) // Base58 private key (seed)

// Derive public key from existing seed
const publicKey = derivePublicKeyFromSeedBase58(keypair.privateKey)
```

### 交易大楼

#### 使用交易构建器类( 建议)

```typescript
import { TransactionBuilder, fromBase58, toAtomicAma } from '@amadeus-protocol/sdk'

// Instance-based usage (convenient for multiple transactions)
const builder = new TransactionBuilder('5Kd3N...') // Base58 encoded seed

// Option 1: Build and sign in one step (convenience)
const { txHash, txPacked } = builder.transfer({
    recipient: '5Kd3N...', // Base58 encoded recipient address
    amount: 10.5, // Amount in human-readable format
    symbol: 'AMA' // Token symbol
})

// Option 2: Build unsigned, then sign (more control)
const unsignedTx = builder.buildTransfer({
    recipient: '5Kd3N...',
    amount: 10.5,
    symbol: 'AMA'
})
// Can inspect or modify unsignedTx before signing
const { txHash, txPacked } = builder.sign(unsignedTx)

// Option 3: Build custom transaction and sign
const unsignedTx = builder.build('Coin', 'transfer', [
    fromBase58('5Kd3N...'), // Recipient bytes
    toAtomicAma(10.5).toString(), // Amount in atomic units
    'AMA'
])
const { txHash, txPacked } = builder.sign(unsignedTx)

// Option 4: Build and sign custom transaction (convenience)
const { txHash, txPacked } = builder.buildAndSign('Coin', 'transfer', [
    fromBase58('5Kd3N...'),
    toAtomicAma(10.5).toString(),
    'AMA'
])
```

#### ABI- Driven( 锁起、 锁起等)

内部合同的建议模式。 通过任何 ABI 到 `builder.contract(abi)` 并获得全类型函数调用 :

```typescript
import {
    TransactionBuilder,
    LOCKUP_PRIME_ABI,
    LOCKUP_ABI,
    toAtomicAma
} from '@amadeus-protocol/sdk'

const builder = new TransactionBuilder('5Kd3N...')

// LockupPrime — auto-typed methods derived from the ABI
builder.contract(LOCKUP_PRIME_ABI).lock({ amount: toAtomicAma(100).toString(), tier: '30d' })
builder.contract(LOCKUP_PRIME_ABI).unlock({ vaultIndex: '3' })
builder.contract(LOCKUP_PRIME_ABI).daily_checkin({ vaultIndex: '7' })

// Lockup
builder.contract(LOCKUP_ABI).unlock({ vaultIndex: '5' })
```

#### NFT( 转让、 薄荷、 创建- 收集)

这个 `Nft` 内建合同有专用的建造方法。 NFT金额是整数, **没有** AMA原子单位.

```typescript
const builder = new TransactionBuilder(privateKey)

// Create a collection (caller becomes owner)
builder.nftCreateCollection({ collection: 'AGENTIC', soulbound: false })

// Mint tokens (collection owner only)
builder.nftMint({ recipient: '5Kd3N...', amount: 10, collection: 'AGENTIC', token: '1' })

// Transfer
builder.nftTransfer({ recipient: '5Kd3N...', amount: 1, collection: 'AGENTIC', token: '1' })
```

静态变种: `TransactionBuilder.buildSignedNftTransfer/Mint/CreateCollection(input)` ——各取同出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出 `senderPrivkey`。 。 。 .

### 签名交易

SDK支持两种模式. 选择适合你工作流程的哪个.

#### 图案1——自动签名(高级别,建议)

这个 `TransactionBuilder` 实例方法构建 **财务报告和审定财务报表** 在一个呼叫中签名。 最好的应用代码,那里有私人钥匙.

```typescript
import { TransactionBuilder, LOCKUP_PRIME_ABI, toAtomicAma } from '@amadeus-protocol/sdk'

const builder = new TransactionBuilder('5Kd3N...') // Base58 seed

// Coin transfer
const a = builder.transfer({ recipient: '5Kd3N...', amount: 10.5, symbol: 'AMA' })

// ABI-driven (any contract)
const b = builder.contract(LOCKUP_PRIME_ABI).lock({
    amount: toAtomicAma(100).toString(),
    tier: '30d'
})

// NFT
const c = builder.nftTransfer({
    recipient: '5Kd3N...',
    amount: 1,
    collection: 'AGENTIC',
    token: '1'
})

// All return { txHash, txPacked } ready for sdk.transaction.submit(txPacked)
```

#### 模式2——手册:建立 `ContractCall`,单独签名

构建一个 `ContractCall` 拥有独立的助手或 `createContract(ABI)`,然后用 `TransactionBuilder.signCall(privkey, call)`。当:

-   您想要在签名前检查或登录电话
-   签名密钥生活在其它地方( HSM, 单独进程, 单独机器)
-   您想要批量建造并在结尾签名

```typescript
import {
    TransactionBuilder,
    createContract,
    LOCKUP_PRIME_ABI,
    buildCoinTransfer,
    buildNftTransfer,
    toAtomicAma
} from '@amadeus-protocol/sdk'

// Build a ContractCall — three ways:

// A. Standalone helper (Coin)
const callA = buildCoinTransfer({ recipient: '5Kd3N...', amount: 10.5, symbol: 'AMA' })

// B. Standalone helper (NFT)
const callB = buildNftTransfer({
    recipient: '5Kd3N...',
    amount: 1,
    collection: 'AGENTIC',
    token: '1'
})

// C. ABI-driven, any contract
const lockupPrime = createContract(LOCKUP_PRIME_ABI)
const callC = lockupPrime.lock({ amount: toAtomicAma(100).toString(), tier: '30d' })

// Inspect if you want
console.log('Will call:', callC.contract, callC.method, callC.args)

// Sign with any private key (no builder instance needed)
const { txHash, txPacked } = TransactionBuilder.signCall('5Kd3N...', callC)
```

#### 构建- 无签名时的设计( 调试)

如果您在签署前需要检查全部未签名的交易(nice, signer, action) :

```typescript
const builder = new TransactionBuilder('5Kd3N...')

const unsigned = builder.buildTransfer({ recipient: '5Kd3N...', amount: 10.5, symbol: 'AMA' })
console.log('Nonce:', unsigned.tx.nonce)
console.log('Action:', unsigned.tx.action)

const { txHash, txPacked } = builder.sign(unsigned)
```

#### 使用静态方法

```typescript
import {
    TransactionBuilder,
    fromBase58,
    toAtomicAma,
    getPublicKey,
    deriveSkAndSeed64FromBase58Seed
} from '@amadeus-protocol/sdk'

// Option 1: Build and sign transfer in one step (convenience)
const { txHash, txPacked } = TransactionBuilder.buildSignedTransfer({
    senderPrivkey: '5Kd3N...', // Base58 encoded seed
    recipient: '5Kd3N...', // Base58 encoded recipient address
    amount: 10.5, // Amount in human-readable format
    symbol: 'AMA' // Token symbol
})

// Option 2: Build unsigned transfer, then sign
const { seed64 } = deriveSkAndSeed64FromBase58Seed('5Kd3N...')
const signerPubKey = getPublicKey(seed64)

const unsignedTx = TransactionBuilder.buildTransfer(
    { recipient: '5Kd3N...', amount: 10.5, symbol: 'AMA' },
    signerPubKey
)
const { txHash, txPacked } = TransactionBuilder.sign(unsignedTx, '5Kd3N...')

// Option 3: Build custom unsigned transaction, then sign
const unsignedTx = TransactionBuilder.build(
    signerPubKey,
    'Coin', // Contract name
    'transfer', // Method name
    [fromBase58('5Kd3N...'), toAtomicAma(10.5).toString(), 'AMA']
)
const { txHash, txPacked } = TransactionBuilder.sign(unsignedTx, '5Kd3N...')

// Option 4: Build and sign custom transaction (convenience)
const { seed64, sk } = deriveSkAndSeed64FromBase58Seed('5Kd3N...')
const signerPubKey = getPublicKey(seed64)

const { txHash, txPacked } = TransactionBuilder.buildAndSign(signerPubKey, sk, 'Coin', 'transfer', [
    fromBase58('5Kd3N...'),
    toAtomicAma(10.5).toString(),
    'AMA'
])
```

### 序列化

```typescript
import { encode, decode } from '@amadeus-protocol/sdk'

// Encode data to canonical format
const data = {
    foo: 'bar',
    count: 42,
    items: [1, 2, 3]
}
const encoded = encode(data)

// Decode data from canonical format
const decoded = decode(encoded)
```

### 托肯转换

```typescript
import { toAtomicAma, fromAtomicAma } from '@amadeus-protocol/sdk'

// Convert to atomic units
const atomic = toAtomicAma(1.5) // Returns 1500000000

// Convert from atomic units
const ama = fromAtomicAma(1500000000) // Returns 1.5
```

### 行为和账户衍生

```typescript
import { generateMnemonic, validateMnemonic, mnemonicToSeedBase58 } from '@amadeus-protocol/sdk'

// Generate a 12-word mnemonic
const mnemonic = generateMnemonic()

// Validate a mnemonic
if (validateMnemonic(mnemonic)) {
    // Derive a Base58 seed (compatible with TransactionBuilder)
    const seedBase58 = mnemonicToSeedBase58(mnemonic)
}
```

一个短语可以打开 **两个不同的账户**,视其来源而定:

| 衍生 | 种子是如何产生的 | 制作人: |
| --- | --- | --- |
| `eip2333` | EIP-2333 BLS12-381 沿途 `m/12381'/36969'/0'/0'/0'` | `mnemonicToSeedBase58` 在SDK 1.4.0+、中枢、主中枢、cli-wallet中 |
| `legacy` | 生的64字节BIP39种子,被直接用作阿玛德乌斯种子 | `mnemonicToSeedBase58` 在SDK 1.3.0及更早, 和钱包建在它上 |

`mnemonicToSeedBase58` 总是返回 `eip2333` 种子 。 找回一个钱包 两位候选人:

```typescript
import { mnemonicToCandidateKeypairs, validateMnemonic } from '@amadeus-protocol/sdk'

// Candidates do not check the checksum, so validate first: a typo still derives two
// plausible-looking but wrong accounts.
if (!validateMnemonic(mnemonic)) throw new Error('Invalid recovery phrase')

const [standard, legacy] = mnemonicToCandidateKeypairs(mnemonic)
// standard.derivation === 'eip2333', legacy.derivation === 'legacy'
// Each has { derivation, seed, publicKey }. To pick one on import, see resolveMnemonicImport below.
```

当您已经知道地址( 例如, 从钱包复制) 时, 解析 直接匹配候选人。 它修剪地址并扔出一个无效的短语:

```typescript
import { TransactionBuilder, resolveCandidateForAddress } from '@amadeus-protocol/sdk'

const candidate = resolveCandidateForAddress(mnemonic, walletAddress)
if (!candidate) throw new Error('This phrase does not open that address')

// candidate.seed signs as walletAddress, whichever derivation created it
const builder = new TransactionBuilder(candidate.seed)
```

#### 将短语导入钱包

`resolveMnemonicImport` 调查两个候选人 并且只有在有历史和 其他被确认为空,或两者被确认为空(标准胜出)。 否则(两者都有: 历史,或任何探测器未知)它报告说用户必须选择. 总是显示另一个 地址也一样. `addressHasActivity` 是默认的探测器:它可以调节当前平衡(包括 发送或收到的交易和答复 `'unknown'` 而不是说 `'inactive'` 何时 请求失败或超时( 默认为8 s) 。 在您的应用中通过相同的 API 基础 URL 使用; 保留任何路径前缀.

```typescript
import { addressHasActivity, resolveMnemonicImport, validateMnemonic } from '@amadeus-protocol/sdk'

if (!validateMnemonic(mnemonic)) throw new Error('Invalid recovery phrase')

const apiBaseUrl = 'https://mainnet-rpc.ama.one/api'
const result = await resolveMnemonicImport(mnemonic, (address) =>
    addressHasActivity(apiBaseUrl, address)
)

if (result.needsChoice) {
    // reason is 'both-active' or 'check-failed': let the user pick from result.candidates
} else {
    // reason is 'single-active' or 'none-active': open result.chosen, still showing the other
}
```

标签一个账户,该账户用其短语保存,但没有记录衍生词,使用 `derivationForSeed(mnemonic, seed)`返回时返回 `'eip2333'`, (中文(简体) ), `'legacy'` 或者说 `null` (亦为 错误的短语,所以它不会扔出.

### 编码公用事业

```typescript
import { toBase58, fromBase58, uint8ArrayToBase64, base64ToUint8Array } from '@amadeus-protocol/sdk'

// Base58 encoding
const encoded = toBase58(new Uint8Array([1, 2, 3]))
const decoded = fromBase58('5Kd3N...')

// Base64 encoding
const base64 = uint8ArrayToBase64(new Uint8Array([1, 2, 3]))
const bytes = base64ToUint8Array(base64)
```

### 基于密码的加密

```typescript
import { encryptWithPassword, decryptWithPassword } from '@amadeus-protocol/sdk'

// Encrypt sensitive data (e.g., private keys)
const encrypted = await encryptWithPassword('sensitive wallet data', 'my-password')
// Returns: { encryptedData, iv, salt } (all Base64 encoded)

// Decrypt the data
const decrypted = await decryptWithPassword(encrypted, 'my-password')
// Returns: 'sensitive wallet data'
```

## API 参考

### 常数

-   `AMADEUS_PUBLIC_KEY_BYTE_LENGTH`:公钥字节长度(48)
-   `AMADEUS_SEED_BYTE_LENGTH`:种子的字节长度(64个)
-   `AMA_TOKEN_DECIMALS`: 小数位数(9)
-   `AMA_TOKEN_DECIMALS_MULTIPLIER`: 转换乘以 (10^9)
-   `AMA_TRANSFER_FEE`: 网络传输费(0.02)
-   `EXPLORER_URL`: 默认探索器 URL
-   `NODE_API_URL`: 默认节点 API URL

### 序列化

-   `encode(term: SerializableValue): Uint8Array` - 编码值为条形格式
-   `decode(bytes: Uint8Array | number[]): DecodedValue` - 从犬科格式解码

### 密码

-   `generateKeypair(): KeyPair` - 生成一个新的键盘
-   `generatePrivateKey(): Uint8Array` - 随机生成64字节种子
-   `getPublicKey(seed64: Uint8Array): Uint8Array` - 种子的衍生公用钥匙
-   `derivePublicKeyFromSeedBase58(base58Seed: string): string` - 来自Base58种子的衍生公用钥匙
-   `deriveSkAndSeed64FromBase58Seed(base58Seed64: string)` - 衍生密钥和种子

### 仪式(BIP39)

-   `generateMnemonic(): string` - 生成12个字的BIP39元音
-   `validateMnemonic(mnemonic: string): boolean` - 验证BIP39元音
-   `normalizeMnemonic(mnemonic: string): string` - 缩写、 小写和折叠的白空; 存储和比较短语的窗体
-   `mnemonicToSeedBase58(mnemonic: string): string` - 制定标准(`eip2333`) Base58种子出自一门元. 归还了 `legacy` 1.4.0之前的种子
-   `mnemonicToCandidateKeypairs(mnemonic: string): MnemonicCandidate[]` - 推荐两位候选人, `eip2333` 首页和 `legacy` 再来 不验证元音
-   `resolveCandidateForAddress(mnemonic: string, address: string): MnemonicCandidate | null` - 验证元音,并将打开的候选人交还 `address`,或 `null`
-   `derivationForSeed(mnemonic: string, seed: string): HdDerivation | null` - 产生的元音的衍生物 `seed`,或 `null`
-   `resolveMnemonicImport(mnemonic: string, probeActivity: (address: string) => Promise<AddressActivity>): Promise<ResolvedMnemonicImport>` - 选择两个候选人,调查每个候选人的历史,选择开户,或报告用户必须选择
-   `addressHasActivity(apiBaseUrl: string, address: string, timeoutMs?: number): Promise<AddressActivity>` - 说吧 `'active'`, (中文(简体) ), `'inactive'` 或者说 `'unknown'` 从余额和交易历史。 别扔
-   `secretKeyToSeedBase58(secretKey: Uint8Array): string` - 将生的32字节BLS密钥包入64字节Base58种子
-   `encodeVaultSecret`, (中文(简体) ), `decodeVaultSecret`, (中文(简体) ), `detectInputType` - 跳楼帮手

### 编码

-   `toBase58(buf: Uint8Array): string` - 编码字节到Base58
-   `fromBase58(str: string): Uint8Array` - 解码 Base58 到字节
-   `uint8ArrayToBase64(bytes: Uint8Array): string` - 将字节转换为 Base64
-   `base64ToUint8Array(base64: string): Uint8Array` - 将 Base64 转换为字节
-   `arrayBufferToBase64(buffer: ArrayBuffer): string` - 将矩阵缓冲器转换为 Base64
-   `base64ToArrayBuffer(base64: string): ArrayBuffer` - 将 Base64 转换为矩阵缓冲器
-   `uint8ArrayToArrayBuffer(bytes: Uint8Array): ArrayBuffer` - 将 Uint8 箭头转换为箭头
-   `arrayBufferToUint8Array(buffer: ArrayBuffer): Uint8Array` - 将阵列缓冲器转换为 Uint8 阵列

### 改划

-   `toAtomicAma(ama: number): number` - 将AMA转换为原子单位
-   `fromAtomicAma(atomicAma: number | string): number` - 将原子单位转换为AMA

### 加密

-   `encryptWithPassword(plaintext: string, password: string): Promise<EncryptedPayload>` - 密码加密数据(AES-GCM + PBKDF2)
-   `decryptWithPassword(payload: EncryptedPayload, password: string): Promise<string>` - 用密码解密数据
-   `generateSalt(): Uint8Array` - 产生随机盐(16字节)
-   `generateIV(): Uint8Array` - 生成随机IV(12字节)
-   `deriveKey(password: string, salt: Uint8Array | ArrayBuffer): Promise<CryptoKey>` - 密码中的衍生AES-GCM密钥

### 交易大楼

-   `TransactionBuilder` - 建筑和签字交易类别
    -   **构造器 :** `new TransactionBuilder(privateKey?: string)` - 创建一个新建实例
    -   **ABI驱动(建议):**
        -   `contract(abi)` - 返回一个键入的、签入方合同界面;每个ABI功能成为一步中构建和签名的方法
    -   **一般实例方法 :**
        -   `build(contract, method, args, signerPk?): UnsignedTransactionWithHash`
        -   `sign(unsignedTx, signerSk?): BuildTransactionResult`
        -   `buildAndSign(contract, method, args, signerPk?, signerSk?): BuildTransactionResult`
        -   `buildFromCall(call): UnsignedTransactionWithHash`
        -   `buildAndSignCall(call): BuildTransactionResult`
    -   **硬币转移 :**
        -   `buildTransfer(input, signerPk?): UnsignedTransactionWithHash`
        -   `transfer(input): BuildTransactionResult`
    -   **NFT(Nft合同):**
        -   `nftTransfer({ recipient, amount, collection, token }): BuildTransactionResult`
        -   `nftMint({ recipient, amount, collection, token }): BuildTransactionResult`
        -   `nftCreateCollection({ collection, soulbound? }): BuildTransactionResult`
    -   **锁定/ 锁定Prime便利方法 :**
        -   `lockupUnlock({ vaultIndex }): BuildTransactionResult`
        -   `lockupPrimeLock({ amount, tier }): BuildTransactionResult`
        -   `lockupPrimeUnlock({ vaultIndex }): BuildTransactionResult`
        -   `lockupPrimeDailyCheckin({ vaultIndex }): BuildTransactionResult`
    -   **静态方法:** `signCall`, (中文(简体) ), `buildFromCall`, (中文(简体) ), `buildAndSignCall`, (中文(简体) ), `buildSignedTransfer`, (中文(简体) ), `buildSignedNft{Transfer,Mint,CreateCollection}`, (中文(简体) ), `buildSignedLockup{Unlock}`, (中文(简体) ), `buildSignedLockupPrime{Lock,Unlock,DailyCheckin}`

### 合同 ABIs

`as const` ABI对内置合同的定义。 通过任何 ABI 到 `createContract(abi)` 或者说 `builder.contract(abi)` 用于全类型函数调用.

-   `LOCKUP_ABI` - 说吧 `Lockup` (血压) - `unlock(vaultIndex)`
-   `LOCKUP_PRIME_ABI` - 说吧 `LockupPrime` —— 说 `lock(amount, tier)`, (中文(简体) ), `unlock(vaultIndex)`, (中文(简体) ), `daily_checkin(vaultIndex)`
-   `NFT_ABI` - 说吧 `Nft` —— 说 `transfer`, (中文(简体) ), `mint`, (中文(简体) ), `create_collection`

返回 a 的独立建筑者 `ContractCall`数字 :

-   `buildCoinTransfer({ recipient, amount, symbol })`
-   `buildNftTransfer({ recipient, amount, collection, token })`
-   `buildNftMint({ recipient, amount, collection, token })`
-   `buildNftCreateCollection({ collection, soulbound? })`
-   `createContract(abi).fn(params)` - 通用ABI驱动的构建器
-   `buildContractCall(abi, fn, params)` - 低级ABI驱动的建设器

### 拍摄( 洛克普瓦特)

阿玛德乌斯捕捉是 `LockupVault` 合同(`bic:lockup_vault:`: AMA 锁定一个分级持续时间, 支持验证员 赚一个锁定的APY。 不要被混淆 与 `Lockup` (血压)或 `LockupPrime` (分数.

```ts
const position = await sdk.staking.getPosition('5Kd3N...')

position.totalStaked // AMA staked = principal + yield compounded into the vaults
position.totalAccrued // yield compounded so far
position.weightedApyPercent // stake-weighted average APY
position.vaultCount // how many vaults
position.nextMatureEpoch // when the soonest lock expires
position.vaults // per-vault detail (tier, amount, APY, validator, maturity)
```

-   `sdk.staking.getPosition(pk, opts?)` ——金库加卷起总额
-   `sdk.staking.getVaults(pk, opts?)` - 只有金库
-   `sdk.staking.getAllVaults(opts?)` ——链上每个地库(勘探者风格视图)
-   `sdk.staking.getValidatorCommissions(opts?)` ——每个验证人委托,划时代解决
-   `sdk.staking.getCurrentEpoch()` ——从链条尖起的时代

过 `{ currentEpoch }` 数个电话,所以他们决意打击一个时代,跳过附加 来回旅行 对于拥有自己的HTTP层的呼叫者,这些构件也被输出: `buildOwnerVaultsKeyPrefix`, (中文(简体) ), `readAllPrefixPages`, (中文(简体) ), `prefixPagePath`, (中文(简体) ), `decodeContractStatePage`, (中文(简体) ), `decodeContractState`, (中文(简体) ), `parseLockupVaultEntries`, (中文(简体) ), `summarizeLockupVaults`, (中文(简体) ), `epochFromHeight`, (中文(简体) ), `flatToAma`。 。 。 .

`get_prefix` 答复页 `{ rows, cursor }` (每行最多1,000行);获取下一页 与 `?cursor=<cursor>` 直到光标 `null`。 。 。 . `readAllPrefixPages(fetchPage)` 做这个循环, 并抛出一个它不认得的形状,而不把它看成是空的.

数量是原子的 `bigint` (单位:千美元)`*Flat`因此,没有任何东西可以漂移到四舍五入——实际位置超过 `2^53` 原子单位. 使用 `flatToAma()` 或预计算 `number` 字段.

### 完整 API 参考

完整文档,包括请求/答复类型、错误处理和端到端实例,见 [文献.ama.one/sdk](https://docs.ama.one/sdk/1.-introduction.md)。 。 。 .

## 实例

见 [`examples/`](https://npmcn.com/package/%40amadeus-protocol/sdk/examples/) 综合使用示例目录:

-   **基本用途** - SDK初始化、密钥生成、查询
-   **交易流量** - 完成交易编制和提交流程
-   **API 使用量** - 显示所有API终点

```bash
# Run examples
npm run example:basic
npm run example:tx
npm run example:api
```

## 测试

SDK包括全面测试范围:

```bash
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

## 类型脚本支持

此软件包以 TypeScript 写成,包含完整类型定义. 所有出口品都有打字和记录.

## 处理错误

所有错误都抛出为 `AmadeusSDKError` 有描述性信息的实例 :

```typescript
import { AmadeusSDK, AmadeusSDKError } from '@amadeus-protocol/sdk'

try {
    const balance = await sdk.wallet.getBalance('invalid')
} catch (error) {
    if (error instanceof AmadeusSDKError) {
        console.error('SDK Error:', error.message)
        console.error('Status:', error.status)
        console.error('Response:', error.response)
    }
}
```

## 许可证

麻省理工学院

## 捐款

欢迎捐款! 请确保所有代码遵循现有的样式,并包括适当的测试.

## 常见问题

### @amadeus-protocol/sdk 是什么？

官方 TypeScript/JavaScript SDK for Amadeus Protocol - 用于序列化,密码化,交易构建和API客户端的核心工具

### 如何安装 @amadeus-protocol/sdk？

在项目目录运行 npm install @amadeus-protocol/sdk，或使用 pnpm add / yarn add / bun add。

### @amadeus-protocol/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amadeus-protocol/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @amadeus-protocol/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @amadeus-protocol/sdk 可以商用吗？

@amadeus-protocol/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @amadeus-protocol/sdk 的下载量有多少？

根据 npm 官方下载统计，@amadeus-protocol/sdk 在 2026/10/06 – 2026/11/04 这 30 天内被下载 3,458 次，日均约 115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amadeus-protocol/sdk 还在维护吗？

最新版本 1\.7\.0 发布于 2026/10/27（11 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2025/12/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。