雪崩 SDK 客户端

一个TypeScript SDK用于通过JSON-RPC API与Avalanche网络互动. 这个SDK提供了一套全面的工具,可以与所有Avalanche链(P-Chain,X-Chain,C-Chain)和各种API交互,包括交易签名和管理的钱包功能.

安装

npm install @avalanche-sdk/client
# or
yarn add @avalanche-sdk/client
# or
pnpm add @avalanche-sdk/client

快速启动

使用雪崩客户端

import { createAvalancheClient } from '@avalanche-sdk/client'
import { avalanche } from '@avalanche-sdk/client/chains'

// Create an Avalanche client
const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "http",
  },
})

// Access different chain clients
const pChainClient = client.pChain
const xChainClient = client.xChain
const cChainClient = client.cChain

// Access API clients
const adminClient = client.admin
const infoClient = client.info
const healthClient = client.health
const indexPChainBlockClient = client.indexBlock.pChain  
const proposervmCChainClient = client.proposervm

// Example: Get the latest block number
const blockNumber = await pChainClient.getBlockNumber()

// Example: Get base fee
const baseFee = await client.getBaseFee()

钱包客户端使用

import { createAvalancheWalletClient, privateKeyToAvalancheAccount } from '@avalanche-sdk/client'
import { avalanche } from '@avalanche-sdk/client/chains'
import { avaxToNanoAvax } from '@avalanche-sdk/client/utils'

// Create an account from private key
const account = privateKeyToAvalancheAccount("0x1234567890123456789012345678901234567890123456789012345678901234")

// Get P chain Address and Evm Address
const evmAddress = account.getEVMAddress()
const pchainAddress = account.getXPAddress("P", "fuji")

// Create a wallet client
const walletClient = createAvalancheWalletClient({
  account,
  chain: avalanche,
  transport: {
    type: "http",
  },
})

// Prepare a txn request
const xChainExportTxnRequest = await walletClient.xChain.prepareExportTxn({
  exportedOutputs: [
    {
      addresses: [account.getXPAddress("X", "fuji")], // X-fuji19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz
      amount: avaxToNanoAvax(0.001),
    },
  ],
  destinationChain: "P",
});

// Send an XP transaction
const result = await walletClient.sendXPTransaction(xChainExportTxnRequest)

// Sign a message
const signedMessage = await walletClient.signXPMessage({
  message: "Hello Avalanche",
})

// Get account public key
const pubKey = await walletClient.getAccountPubKey()

// Wait for transaction confirmation
await walletClient.waitForTxn({
  txID: "2QouvMUbQ6oy7yQ9tLvL3L8tGQG2QK1wJ1q1wJ1q1wJ1q1wJ1q1wJ1q1wJ1",
  chainAlias: "X"
})

链状钱包操作

// P-Chain wallet operations
const pChainWallet = walletClient.pChain

// Prepare add validator transaction
const validatorTx = await pChainWallet.prepareAddPermissionlessValidatorTxn({
  nodeId: "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
  stakeInAvax: avaxToNanoAvax(1),
  end: 1716441600,
  rewardAddresses: ["P-fuji19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
  threshold: 1,
  publicKey: "0x1234567890123456789012345678901234567890",
  signature: "0x1234567890123456789012345678901234567890",
  locktime: 1716441600,
  delegatorRewardPercentage: 2.5,
  delegatorRewardAddresses: ["P-fuji19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
})

// X-Chain wallet operations
const xChainWallet = walletClient.xChain

// Prepare base transaction
const baseTx = await xChainWallet.prepareBaseTxn({
  outputs: [{
    addresses: ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
    amount: avaxToNanoAvax(1), // 1 AVAX
  }],
})

// C-Chain wallet operations
const cChainWallet = walletClient.cChain

// Prepare export transaction
const exportTx = await cChainWallet.prepareExportTxn({
  to: "P-fuji1j2zllfqv4mgg7ytn9m2u2x0q3h3jqkzq8q8q8q8",
  amount: avaxToNanoAvax(1), // 1 AVAX = 1_000_000_000 nAvax
  destinationChain: "X"
})

特征

• 多钱支持: 与所有雪崩链相互作用:
  • P-Chain(平面链)
  • X-Chain(交换链)
  • C-Chain(合同链)
• 钱包功能: 完成钱包操作,包括:
  • 交易签名和发送
  • 信件签名
  • 账户管理
  • 特定交易链的准备
• API 客户端数字 :
  • 管理 API
  • 信息 API
  • 卫生协会
  • 索引 API
• 类型脚本支持: 带有类型定义的完整类型脚本支持
• 模块设计: 通过专用客户端访问特定功能

可用的客户端

链式客户端

• P- Chain 客户端: 平台链操作
• X-Chain 客户端: 交换链业务
• C-Chain 客户端: 合同链业务

API 客户端

• 管理客户端行政业务
• 信息客户端: 网络信息
• 保健客户: 健康检查终点
• 索引客户端数字 :
  • 索引 P- Chain 块
  • 指数 C- Chain 块
  • 索引 X- Chain 块
  • 索引 X-Chain 交易
• 提议客户端: 提案人 VM 信息

钱包客户端

• 雪崩钱包客户端: 一般钱包操作
• P- 钱钱包客户端: P-Chain 特定钱包操作
• X-Chain 钱包客户端: X- Chain 特定钱包操作
• C-Chain 钱包客户端: C-Chain 特定钱包操作

配置

SDK可以配置各种选项:

const client = createAvalancheClient({
  chain: avalanche, // Chain configuration
  transport: {
    type: "<transportType>", // Transport type
    url: "<url>",
    config: {
      // Transport-specific configuration
    }
  },
  apiKey: "", // Optional API key
  rlToken: "", // Optional rate limit token
})

运输配置

SDK支持多种运输类型连接到Avalanche节点. 每个传输类型都有特定的配置选项:

HTTP 运输(建议)

const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "http",
    url: "https://api.avax.network/ext/bc/C/rpc", // Optional custom RPC URL
    config: {
      // HTTP-specific configuration
      fetchOptions: {
        headers: {
          "Custom-Header": "value"
        },
      }
      retryCount: 3,
      retryDelay: 1000,
      timeout: 5000
    }
  }
})

HTTP 传输特性 :

• 自动 URL 分辨率: 如果没有提供URL,请使用链条默认的 RPC 端点
• 自定义信头: 支持自定义 HTTP 信头通过 fetchOptions.headers
• API 密钥支持: 自动添加 x-glacier-api-key 当标题 apiKey 提供
• 费率限制支持: 自动添加 rlToken 当标题 rlToken 提供

WebSocket 运输

const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "ws",
    url: "wss://api.avax.network/ext/bc/C/ws", // Optional custom WebSocket URL
    config: {
      // WebSocket-specific configuration
      retryCount: 3,
      retryDelay: 1000
    }
  }
})

WebSocket 运输特性 :

• 实时更新: 支持用于实时数据的 WebSocket 连接
• 自动重接: 内置重试逻辑, 并带有可配置重试计数和延迟
• 事件驱动: 签署屏蔽链事件和实时更新的理想

自定义运输

const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "custom",
    provider: window.avalanche, // Custom provider implementation
    config: {
      // Custom transport configuration
    }
  }
})

自定义运输特性 :

• 供应商一体化: 与自定义 RPC 供应商或中间软件整合
• 弹性配置:全面控制运输行为
• 钱包支持: 钱包客户端的特殊处理

后退运输

const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "fallback",
    transports: [
      { type: "http", url: "https://primary-rpc.com" },
      { type: "http", url: "https://backup-rpc.com" }
    ],
    config: {
      // Fallback configuration
      retryCount: 3,
      retryDelay: 1000
    }
  }
})

退后运输特性 :

• 高可用性: 多个 RPC 端点之间自动失效

高级配置示例

自定义 HTTP 信头和超时

const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "http",
    config: {
      fetchOptions: {
        headers: {
          "X-Custom-Header": "custom-value"
        },
      }
    }
  }
})

多个倒计时终点

const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "fallback",
    transports: [
      { type: "http", url: "https://api.avax.network/ext/bc/C/rpc" },
      { type: "http", url: "https://rpc.ankr.com/avalanche" },
      { type: "http", url: "https://avalanche.public-rpc.com" }
    ],
    config: {
      retryCount: 5,
      retryDelay: 2000
    }
  }
})

带有自定义配置的 WebSocket

const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "ws",
    config: {
      retryCount: 5,
      retryDelay: 2000,
      maxRetryDelay: 30000
    }
  }
})

运输选择准则

• HTTP 运输: 最适合大多数使用的大小写, 简单配置, 宽相容性
• WebSocket 运输: 实时应用程序的理想,事件订阅,实时更新
• 自定义运输: 与特定提供者或中间软件集成时使用
• 后退运输: 建议用于需要大量供应的生产应用

环境考虑因素

• 浏览器: HTTP 和 WebSocket 传输已完全支持
• 节点.js: 所有运输类型都得到支持
• 移动: 建议移动应用的HTTP运输
• 生产: 考虑使用具有多个RPC端点的倒置运输实现可靠性

输出模块和公用事业

主要出口

SDK输出出所有viem的公用设施和类型,加上Avalanche特有的功能:

import { 
  createAvalancheClient,
  createAvalancheWalletClient,
  // All viem exports
  createClient,
  createPublicClient,
  createWalletClient,
  // ... and many more
} from '@avalanche-sdk/client'

账户管理

import { 
  privateKeyToAvalancheAccount,
  mnemonicsToAvalancheAccount,
  hdKeyToAvalancheAccount,
  privateKeyToXPAddress,
  publicKeyToXPAddress,
  // ... and more
} from '@avalanche-sdk/client/accounts'

链式配置

import { 
  avalanche,
  avalancheFuji,
  // ... and more
} from '@avalanche-sdk/client/chains'

方法

访问特定方法类别:

// P-Chain methods
import { /* P-Chain methods */ } from '@avalanche-sdk/client/methods/pChain'

// X-Chain methods  
import { /* X-Chain methods */ } from '@avalanche-sdk/client/methods/xChain'

// C-Chain methods
import { /* C-Chain methods */ } from '@avalanche-sdk/client/methods/cChain'

// Wallet methods
import { /* Wallet methods */ } from '@avalanche-sdk/client/methods/wallet'

// Public methods
import { /* Public methods */ } from '@avalanche-sdk/client/methods/public'

// Admin methods
import { /* Admin methods */ } from '@avalanche-sdk/client/methods/admin'

// Info methods
import { /* Info methods */ } from '@avalanche-sdk/client/methods/info'

// Health methods
import { /* Health methods */ } from '@avalanche-sdk/client/methods/health'

// Index methods
import { /* Index methods */ } from '@avalanche-sdk/client/methods/index'

// proposervm methods
import { /* proposervm methods */ } from '@avalanche-sdk/client/methods/proposervm'

公用事业

import { 
  CB58ToHex,
  hexToCB58,
  getTxFromBytes,
  getUnsignedTxFromBytes,
  getUtxoFromBytes,
  getUtxosForAddress,
  // All viem utilities
  formatEther,
  parseEther,
  keccak256,
  // ... and many more
} from '@avalanche-sdk/client/utils'

额外模块

// Node utilities
import { /* Node utilities */ } from '@avalanche-sdk/client/node'

// Nonce management
import { /* Nonce utilities */ } from '@avalanche-sdk/client/nonce'

// Serializable utilities
import { /* Serializable utilities */ } from '@avalanche-sdk/client/serializable'

// SIWE (Sign-In with Ethereum)
import { /* SIWE utilities */ } from '@avalanche-sdk/client/siwe'

// Window utilities
import { /* Window utilities */ } from '@avalanche-sdk/client/window'

可用方法

P-钱方法

• getBalance - 返回平台链上地址的余额,从 platform.getUTXOs。 。 。 . 文档
• getBlock - 得到一个街区的身份证. 文档
• getBlockByHeight - 得到一个街区的高度. 文档
• getBlockchainStatus - 返回块链状态. 文档
• getBlockchains - 堕落了 返回所有存在的块链(不包括P-Chain). 使用索引器, 如数据 API @avalanche-sdk/chainkit,转而. 文档
• getCurrentSupply - 返回当前系统中的AVAX供应. 文档
• getCurrentValidators - 返回给定子网的当前验证符. 文档
• getFeeConfig - 返回P-Chain的收费配置. 文档
• getFeeState - 返回 P-Chain 目前的收费状况. 文档
• getHeight - 返回最近块的高度. 文档
• getL1Validator - 返回关于L1验证器的信息. 文档
• getMinStake - 返回验证所请求的Subnet所需的最低nAVAX. 文档
• getProposedHeight - 返回最近区块的拟议高度. 文档
• getRewardUTXOs - 堕落了 返回交易的奖励 UTXOs 。 使用索引器, 如数据 API 在 @avalanche-sdk/chainkit,转而. 文档
• getStake - 堕落了 返回一组地址所显示的 nAVAX 值 。 AvalancheGo计划在即将发行的版本中移除. 计算赌注 getCurrentValidators 财务报告和审定财务报表 getTx 换句话说. 文档
• getStakingAssetID - 返回用于取用所请求的子网的资产识别. 文档
• getSubnet - 返回关于子网的信息. 文档
• getSubnets - 堕落了 返回所有子网。 使用 getSubnet 用于一个子网,或者一个索引器,例如: @avalanche-sdk/chainkit,为列表. 文档
• getTimestamp - 返回当前 P-Chan 的时间戳. 文档
• getTotalStake - 返回所请求的Subnet上标注的总金额. 文档
• getTx - 返回指定的交易. 文档
• getTxStatus - 返回指定交易的状况. 文档
• getUTXOs - 返回引用特定地址的UTXOs. 文档
• getValidatorsAt - 在指定高度返回子网的验证器及其重量. 文档
• issueTx - 向平台链发送交易. 文档
• sampleValidators - 特定子网的样本验证器. 文档
• validatedBy - 获取验证特定区块链的子网. 文档
• validates - 获得区块链的ID 一个子网验证. 文档
• getAllValidatorsAt - 获取所有L1的验证器及其重量 以及P-Chain高度的初级网络. 文档

X-Chain 方法

• buildGenesis - 为X-Chain建造一个起源区块. 文档
• getAllBalances - 堕落了 返回给定地址的所有余额。 AvalancheGo计划在即将发行的版本中移除. 使用 getUTXOs 并添加只有地址拥有的未解锁的传输输出量. 文档
• getAssetDescription - 归还资产信息. 文档
• getBalance - 堕落了 返回地址所持有资产的余额。 AvalancheGo计划在即将发行的版本中移除. 使用 getUTXOs 并添加只有地址拥有的未解锁的传输输出量. 文档
• getBlock - 得到一个街区的身份证. 文档
• getBlockByHeight - 得到一个街区的高度. 文档
• getHeight - 返回最近块的高度. 文档
• getTx - 返回指定的交易. 文档
• getTxFee - 退还特定交易的费用. 文档
• getTxStatus - 堕落了 返回指定交易的状态。 AvalancheGo计划在即将发行的版本中移除. 使用 getTx 相反:当 getTx 返回它. 文档
• getUTXOs - 返回引用特定地址的UTXOs. 文档
• issueTx - 给X -Chain开个交易. 文档

C-Chain 方法问题

• getAtomicTx - 返回指定的原子交易. 文档
• getAtomicTxStatus - 堕落了 返回指定的原子交易状态。 赫利孔升级后不可用. 使用 getAtomicTx 换句话说. 文档
• getUTXOs - 返回引用特定地址的UTXOs. 文档
• issueTx - 给C -Chain发个交易. 文档

钱包方法

• getAccountPubKey - 获取经常账户的公用钥匙. 文档
• send - 用钱包发送交易. 文档
• sendXPTransaction - 在X-Chain或P-Chain上签名并发送交易. 文档
• signXPMessage - 在X-Chain或P-Chain上签名. 文档
• signXPTransaction - 在X-Chain或P-Chain上签个字. 文档
• waitForTxn - 等待交易被接受. 文档

P-Chain钱包方法

• prepareAddAutoRenewedValidatorTxn - 准备增加自动更新验证器交易. 非加太国家-236
• prepareAddPermissionlessDelegatorTx - 准备一个没有授权的委托人交易. 文档
• prepareAddPermissionlessValidatorTxn - 准备额外无授权的验证交易. 文档
• prepareAddSubnetValidatorTxn - 准备添加子网验证器交易. 文档
• prepareBaseTxn - 准备基础交易. 文档
• prepareConvertSubnetToL1Txn - 准备将子网转换为L1交易. 文档
• prepareCreateChainTxn - 准备一个创建链交易. 文档
• prepareCreateSubnetTxn - 准备一个创建子网交易. 文档
• prepareDisableL1ValidatorTxn - 准备禁用 L1 验证器交易 . 文档
• prepareExportTxn - 准备出口交易. 文档
• prepareImportTxn - 准备进口交易. 文档
• prepareIncreaseL1ValidatorBalanceTxn - 准备增加L1验证器余额交易. 文档
• prepareRegisterL1ValidatorTxn - 编制登记册L1验证器交易. 文档
• prepareRemoveSubnetValidatorTxn - 准备删除子网验证器交易. 文档
• prepareSetAutoRenewedValidatorConfigTxn - 准备一套自动更新的验证器配置交易. 非加太国家-236
• prepareSetL1ValidatorWeightTxn - 准备一套L1验证器重量交易. 文档

X-钱钱包方法

• prepareBaseTxn - 为X-Chain准备基础交易. 文档
• prepareExportTxn - 准备X-Chain的出口交易. 文档
• prepareImportTxn - 准备X-Chain的进口交易. 文档

C-钱钱包方法

• prepareExportTxn - 准备从C-Chan到另一链的出口交易. 文档
• prepareImportTxn - 准备从另一条链子到C -Chain的进口交易. 文档

公共方法

• baseFee - 返回下一个区块的基准费. 文档
• getChainConfig - 返回链式配置. 文档
• maxPriorityFeePerGas - 退还每根气体的最高优先费. 文档
• feeConfig - 返回指定块的收费配置. 文档
• getActiveRulesAt - 在指定的时间戳返回活动规则. 文档

管理方法

• alias - 指定一个API端点 一个别名. 文档
• aliasChain -给块链一个别名. 文档
• getChainAliases - 返回链的别名. 文档
• getLoggerLevel - 返回日志和显示日志的级别. 文档
• loadVMs - 动态加载节点上安装的任何虚拟机器作为插件. 文档
• lockProfile - 写一个mutex统计图 锁定.profile. 文档
• memoryProfile - 给Mem.profile写一个记忆简介. 文档
• setLoggerLevel - 设置日志和显示日志的级别. 文档
• startCPUProfiler - 开始剖析节点的CPU利用情况. 文档
• stopCPUProfiler - 停止先前启动的CPU配置文件. 文档

信息方法

• acps - 回归阿瓦兰切社区提案的同伴偏好. 文档
• getBlockchainID - 鉴于块链的别名, 获取其身份. 文档
• getNetworkID - 获取这个节点参与的网络的ID. 文档
• getNetworkName - 获取这个节点参与的网络名称. 文档
• getNodeID - 拿到身份证 BLS钥匙 和这个节点的持有证明. 文档
• getNodeIP - 获取这个节点的IP. 文档
• getNodeVersion - 获取这个节点的版本. 文档
• getTxFee - 为指定的交易类型收取交易费. 文档
• getVMs - 得到这个节点支持的虚拟机. 文档
• isBootstrapped - 检查一个链条是否完成了拖带. 文档
• peers - 描述一下对等关系. 文档
• uptime - 返回网络观察到的这个节点的恢复时间. 文档
• upgrades - 返回网络的升级历史和配置. 文档

卫生方法

• health - 返回最后一套健康检查结果. 文档
• liveness - 一旦有终点,返回健康. 文档
• readiness - 节点完成初始化后返回健康. 文档

指数方法

• getContainerByID -通过身份证取出集装箱. 文档
• getContainerByIndex -按指数算. 文档
• getContainerRange - 按指数范围取出容器. 文档
• getIndex - 获取一个容器的索引. 文档
• getLastAccepted - 拿到最后一个接受的容器. 文档
• isAccepted - 如果容器在此索引中, 返回真实性 . 文档

建议的方法

• getCurrentEpoch - 返回当前时代信息. 文档
• getProposedHeight - 返回此节点目前的提议者 VM 高度 . 文档

实例

说明: 确保创建自己的 .env 通过复制 .env.example 文档并更新值。 你还需要修改 config.ts 要指向您的文件 .env 文件路径。 默认情况下,示例使用来自 .env.example,以及示例中提及的作为注释的测试地址(如 0x76Dd3d7b2f635c2547B861e55aE8A374E587742D 财务报告和审定财务报表 X-fuji19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz)来自该文件中的私钥值.

看看这个 实例 用于综合使用的文件夹示例 :

基本实例

• sendAvax.ts - 使用SDK发送AVAX的基本实例

主网络交易示例

这个 prepare-primary-network-txns 文件夹中包含准备各类交易的示例 :

跨海峡传输示例

• transfer-avax-from-x-chain-to-p-chain.ts - 将AVAX从X-Chain转移到P-Chain
• transfer-avax-from-p-chain-to-x-chain.ts - 将AVAX从P-Chan转移到X-Chan
• transfer-avax-from-x-chain-to-c-chain.ts - 把AVAX从X-Chan转到C-Chan
• transfer-avax-from-c-chain-to-x-chain.ts - 把AVAX从C-Chan转到X-Chan
• transfer-avax-from-p-chain-to-c-chain.ts - 将AVAX从P-Chain转移到C-Chain
• transfer-avax-from-c-chain-to-p-chain.ts - 把AVAX从C-Chan转到P-Chan

X-Chain 交易实例

• exportTx.ts - 准备X-Chain出口交易
• importTx.ts - 准备X-Chain进口交易

P-Chain 交易实例

• addAutoRenewedValidatorTx.ts - 添加自动更新的验证器交易
• addSubnetValidatorTx.ts - 添加子网验证器交易
• baseTx.ts - 基础交易实例
• convertSubnetToL1Tx.ts - 将子网转换为L1交易
• createChainTx.ts - 创建链式交易
• createSubnetTx.ts - 创建子网交易
• exportTx.ts - 准备P-Chain出口交易
• importTx.ts - 准备P-Chain进口交易
• removeSubnetValidatorTx.ts - 删除子网验证交易
• setAutoRenewedValidatorConfigTx.ts - 设置自动更新的验证器配置交易

C-Chain 交易实例

• exportTx.ts - 准备C-Chain出口交易
• importTx.ts - 准备C-Chain进口交易

有关每个实例的更详细资料,请参见: 实例。 。 。 .

捐款

欢迎捐款! 请随意提交拉力请求 对于重大变动,请先开出一个问题来讨论你想要改变什么.

许可证

这个项目根据BSD 3-Clause许可证获得许可——详情见[LICENSE]./(LICENSE)文件.

支助

如果遇到问题或有问题,请:

1. 检查 文档
2. 打开一个 问题
3. 加入我们的社区求助渠道

链接

• GitHub 仓库
• 文档
• 问题跟踪器