AvaCloud SDK 类型脚本

AvaCloud SDK是一个强大而灵活的工具集,旨在简化与AvaCloud的套装区块链服务的集成. 目前,这个SDK专注于为数据API提供强大的支持.

SDK 安装

SDK可以安装其中之一 无, (中文(简体) ), 小时, (中文(简体) ), 包头 或者说 线条 软件包管理器.

国家预防机制

npm add @avalabs/avacloud-sdk

菲律宾

pnpm add @avalabs/avacloud-sdk

阿宝

bun add @avalabs/avacloud-sdk

雅伦

yarn add @avalabs/avacloud-sdk zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.

模式背景协议( MCP) 服务器

这个SDK也是可安装的MCP服务器,各种SDK方法都在这里 被曝光为AI应用程序可以引用的工具.

从 npm 运行 MCP 服务器需要node.js v20 或更多.

{
  "mcpServers": {
    "AvaCloudSDK": {
      "command": "npx",
      "args": [
        "-y", "--package", "@avalabs/avacloud-sdk",
        "--",
        "mcp", "start",
        "--server-url", "...",
        "--api-key", "...",
        "--chain-id", "...",
        "--network", "..."
      ]
    }
  }
}

{
  "mcpServers": {
    "AvaCloudSDK": {
      "command": "npx",
      "args": [
        "-y", "--package", "@avalabs/avacloud-sdk",
        "--",
        "mcp", "start",
        "--server-url", "...",
        "--api-key", "...",
        "--chain-id", "...",
        "--network", "..."
      ]
    }
  }
}

也可以作为独立的二进制运行MCP服务器,没有额外的依赖性. 你必须从现有的 Github 释放中提取这些二进制:

curl -L -o mcp-server \
    https://github.com/{org}/{repo}/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
chmod +x mcp-server

如果回购是私人回购, 您必须加入您的 Github PAT 才能下载发行 -H "Authorization: Bearer {GITHUB_PAT}"。 。 。 .

{
  "mcpServers": {
    "Todos": {
      "command": "./DOWNLOAD/PATH/mcp-server",
      "args": [
        "start"
      ]
    }
  }
}

服务器参数完整列表中, 运行 :

npx -y --package @avalabs/avacloud-sdk -- mcp start --help

所需资源

对于支持的 JavaScript 运行时间, 请参考 运行时间.md。 。 。 .

SDK 示例使用法

示例

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";

const avaCloudSDK = new AvaCloudSDK({
  serverURL: "https://api.example.com",
});

async function run() {
  await avaCloudSDK.sendAddressActivityWebhook({
    webhookId: "401da7d9-d6d7-46c8-b431-72ff1e1543f4",
    eventType: "address_activity",
    messageId: "bc9732db-2430-4296-afc3-c51267beb14a",
    event: {
      transaction: {
        blockHash:
          "0x2a47bebed93db4a21cc8339980f004cc67f17d0dff4a368001e450e7be2edaa0",
        blockNumber: "45396106",
        from: "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
        gas: "80000",
        gasPrice: "52000000000",
        maxFeePerGas: "52000000000",
        maxPriorityFeePerGas: "2000000000",
        txHash:
          "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
        txStatus: "1",
        input:
          "0xa9059cbb00000000000000000000000040e832c3df9562dfae5a86a4849f27f687a9b46b00000000000000000000000000000000000000000000000000000000c68b2a69",
        nonce: "0",
        to: "0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7",
        transactionIndex: 1,
        value: "0",
        type: 2,
        chainId: "43114",
        receiptCumulativeGasUsed: "668508",
        receiptGasUsed: "44038",
        receiptEffectiveGasPrice: "27000000000",
        receiptRoot:
          "0xe5b018c29a77c8a92c4ea2f2d7e58820283041a52e14a0620d90d13b881e1ee3",
        blockTimestamp: 1715621840,
        contractAddress: "0x0000000000000000000000000000000000000000",
        erc20Transfers: [
          {
            transactionHash:
              "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
            type: "ERC20",
            from: "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
            to: "0x40E832C3Df9562DfaE5A86A4849F27F687A9B46B",
            value: "3331009129",
            tokenId: "2",
            blockTimestamp: 1640995200,
            logIndex: 5,
            erc20Token: {
              address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
              name: "TetherToken",
              symbol: "USDt",
              decimals: 6,
              valueWithDecimals: "3331.009129",
            },
            erc721Token: {
              address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
              name: "TetherToken",
              symbol: "USDt",
              decimals: 6,
              valueWithDecimals: "3331.009129",
            },
            erc1155Token: {
              address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
              name: "TetherToken",
              symbol: "USDt",
              decimals: 6,
              valueWithDecimals: "3331.009129",
            },
          },
          {
            transactionHash:
              "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
            type: "ERC20",
            from: "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
            to: "0x40E832C3Df9562DfaE5A86A4849F27F687A9B46B",
            value: "3331009129",
            tokenId: "2",
            blockTimestamp: 1640995200,
            logIndex: 5,
            erc20Token: {
              address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
              name: "TetherToken",
              symbol: "USDt",
              decimals: 6,
              valueWithDecimals: "3331.009129",
            },
            erc721Token: {
              address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
              name: "TetherToken",
              symbol: "USDt",
              decimals: 6,
              valueWithDecimals: "3331.009129",
            },
            erc1155Token: {
              address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
              name: "TetherToken",
              symbol: "USDt",
              decimals: 6,
              valueWithDecimals: "3331.009129",
            },
          },
        ],
        erc721Transfers: [],
        erc1155Transfers: [],
        internalTransactions: [
          {
            from: "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
            to: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            internalTxType: "call",
            value: "50000000000000000",
            gasUsed: "44038",
            gasLimit: "50000",
            transactionHash:
              "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
          },
          {
            from: "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
            to: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            internalTxType: "call",
            value: "50000000000000000",
            gasUsed: "44038",
            gasLimit: "50000",
            transactionHash:
              "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
          },
          {
            from: "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
            to: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            internalTxType: "call",
            value: "50000000000000000",
            gasUsed: "44038",
            gasLimit: "50000",
            transactionHash:
              "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
          },
        ],
        accessList: [
          {
            accessAddresses: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            storageKeys: [
              "<value 1>",
              "<value 2>",
            ],
          },
          {
            accessAddresses: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            storageKeys: [
              "<value 1>",
              "<value 2>",
            ],
          },
          {
            accessAddresses: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            storageKeys: [
              "<value 1>",
              "<value 2>",
            ],
          },
        ],
        networkToken: {
          tokenName: "TetherToken",
          tokenSymbol: "USDt",
          tokenDecimals: 6,
          valueWithDecimals: "3331.009129",
        },
      },
      logs: [
        {
          address: "0x54C800d2331E10467143911aabCa092d68bF4166",
          topic0:
            "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
          topic1:
            "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
          topic2:
            "0x0000000000000000000000000000000000000000000000000000000000000000",
          topic3:
            "0x0000000000000000000000000000000000000000000000000000000000001350",
          data: "0x",
          transactionIndex: 2,
          logIndex: 10,
          removed: false,
        },
        {
          address: "0x54C800d2331E10467143911aabCa092d68bF4166",
          topic0:
            "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
          topic1:
            "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
          topic2:
            "0x0000000000000000000000000000000000000000000000000000000000000000",
          topic3:
            "0x0000000000000000000000000000000000000000000000000000000000001350",
          data: "0x",
          transactionIndex: 2,
          logIndex: 10,
          removed: false,
        },
        {
          address: "0x54C800d2331E10467143911aabCa092d68bF4166",
          topic0:
            "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
          topic1:
            "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
          topic2:
            "0x0000000000000000000000000000000000000000000000000000000000000000",
          topic3:
            "0x0000000000000000000000000000000000000000000000000000000000001350",
          data: "0x",
          transactionIndex: 2,
          logIndex: 10,
          removed: false,
        },
      ],
    },
  });
}

run();

现有资源和业务

独立职能

上述所有方法都作为独立功能提供。 这些 函数是用于在浏览器中运行的应用程序的理想功能,没有服务器 运行时间或应用程序捆绑大小为主的其他环境 关心。 当使用捆绑器构建您的应用程序时, 全部未使用 功能将被从最后的捆绑中排除,或者被树切除.

要了解更多独立函数, 请检查 职能.md。 。 。 .

全球参数

某些参数是在全球配置的。 在初始化过程中,这些参数可能设定在SDK客户端实例上. 当在 SDK 初始化期间配置为选项时, 这些全局值将被用作使用它们的操作的默认值 。 当这种业务被调用时,如果需要,每个业务都有一个地方可以推翻全球价值.

例如,你可以设定 chainId 改为 "43114" 在 SDK 初始化时, 您无需将相同的值传递给操作 list。但如果您想要这样做,则您可以这样做,这将会在本地覆盖全球环境。 演示请参看下面的示例代码.

可用的全局

以下全球参数可供查阅.

示例

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";

const avaCloudSDK = new AvaCloudSDK({
  serverURL: "https://api.example.com",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await avaCloudSDK.metrics.chains.list({
    network: "mainnet",
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

倾斜

此 SDK 中的一些端点支持 pagination. 要用帕吉恩语,你 使您的 SDK 调用如常, 但返回的响应对象也将是 可使用下列设备消耗的同步可执行性: for await...of 语法.

举个例子说

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";

const avaCloudSDK = new AvaCloudSDK({
  serverURL: "https://api.example.com",
});

async function run() {
  const result = await avaCloudSDK.metrics.chains.list({
    network: "mainnet",
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

检索

此 SDK 中的一些端点支持重试. 如果在没有任何配置的情况下使用SDK,则会回落到API提供的默认重试策略. 然而,默认的重试策略可以在一次操作的基础上被推翻,或者在整个SDK中被推翻.

更改单个 API 调用默认重试策略, 只需为调用提供重试 Config 对象 :

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";

const avaCloudSDK = new AvaCloudSDK({
  serverURL: "https://api.example.com",
});

async function run() {
  const result = await avaCloudSDK.metrics.healthCheck({
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  console.log(result);
}

run();

如果您想要覆盖所有支持重试的操作的默认重试策略, 您可以在 SDK 初始化时提供重试Config :

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";

const avaCloudSDK = new AvaCloudSDK({
  serverURL: "https://api.example.com",
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

async function run() {
  const result = await avaCloudSDK.metrics.healthCheck();

  console.log(result);
}

run();

处理错误

AvaCloudSDKError 是所有 HTTP 错误响应的基础类。 其属性如下:

示例

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";
import * as errors from "@avalabs/avacloud-sdk/models/errors";

const avaCloudSDK = new AvaCloudSDK({
  serverURL: "https://api.example.com",
  chainId: "43114",
});

async function run() {
  try {
    await avaCloudSDK.data.nfts.reindex({
      address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      tokenId: "145",
    });
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.AvaCloudSDKError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof errors.BadRequest) {
        console.log(error.data$.message); // errors.Message
        console.log(error.data$.statusCode); // number
        console.log(error.data$.error); // string
      }
    }
  }
}

run();

错误分类

主错误 :

• AvaCloudSDKError: HTTP 错误响应的基础类.
  • BadRequest:不良请求一般指客户端通过无效或畸形参数. 回复中的错误信息可能有助于评价错误. 状态代码 400。 。 。 .
  • Unauthorized:当客户端试图访问需要授权证书但客户端在请求中缺乏适当认证的资源时,服务器以401回复. 状态代码 401。 。 。 .
  • Forbidden:当客户端试图以有效资质访问资源但无权执行此动作时,服务器以403响应. 状态代码 403。 。 。 .
  • NotFound:当客户端请求使用错误的URL,或者通过的资源被移动或删除,或者资源不存在时,错误大多被返回. 状态代码 404。 。 。 .
  • TooManyRequests: 当客户端发送过多, 并且达到了速率限制时, 此错误会被返回 。 状态代码 429。 。 。 .
  • InternalServerError: 错误是一个通用的服务器侧错误, 对于服务器侧的任何未发现和出乎意料的问题都会被返回. 这应该非常罕见,如果问题持续了更长的时间,你可能会向我们伸出援手。 状态代码 500。 。 。 .
  • BadGateway: 这是一个内部错误, 表示客户端的代理服务器或网关从上游服务器收到的响应无效 。 状态代码 502。 。 。 .
  • ServiceUnavailable: 返回特定Subnet上某些路线的错误。 这表明我们的子网节点存在内部问题,可能并不一定意味着子网已经下架或受到影响. 状态代码 503。 。 。 .

自定义 HTTP 客户端

TypeScript SDK 使用一个 HTTPClient 将本地人包裹起来 获取 API这个 客户端是薄薄的包装 fetch 并且提供连接钩子的能力 围绕可用于修改请求或处理的请求生命周期 错误和反应.

这个 HTTPClient 构造器使用可选 fetcher 参数可以是 用于整合第三方 HTTP 客户端或用于编写测试以嘲弄 hTTP 客户端并输入固定设备.

以下示例说明如何使用 "beforeRequest" 要添加的钩子 自定义标题和请求的超时及如何使用 "requestError" 钩子 记录错误 :

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";
import { HTTPClient } from "@avalabs/avacloud-sdk/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new AvaCloudSDK({ httpClient });

认证

常客安全计划

这个SDK在全球支持以下安全计划:

用 API 认证 apiKey 初始化 SDK 客户端实例时必须设置参数 。 例如:

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";

const avaCloudSDK = new AvaCloudSDK({
  serverURL: "https://api.example.com",
  apiKey: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await avaCloudSDK.metrics.healthCheck();

  console.log(result);
}

run();

调试

您可以为 SDK 请求和响应设置 SDK 以发送调试日志 .

你可以通过一个匹配的日志 console'作为 SDK 选项的接口.

[尖叫声] 注意调试日志会揭示一些秘密, 如标题中的 API 令牌, 打印到控制台或文件中的日志信息 。 建议只在本地开发期间使用这一特征,而不能用于生产.

import { AvaCloudSDK } from "@avalabs/avacloud-sdk";

const sdk = new AvaCloudSDK({ debugLogger: console });

内容提要

Data API:Data API为Web3应用程序开发者提供与Avalanche主网,Avalanche子网和Ethereum相关的多链数据. 通过Data API,您可以轻松地构建出能够利用实时和历史交易以及传输历史,本土和象征余额,以及各类象征元数据的产品. API位于Beta,可能会被更改.

如果您对 API 有反馈或功能请求, 请提交 这里。错误报告可以提交 这里,可以报告任何潜在的安全问题 这里。 。 。 .

目录

• SDK 安装
• 所需资源
• SDK 示例使用法
• 现有资源和业务
• 独立职能
• 全球参数
• 倾斜
• 检索
• 处理错误
• 自定义 HTTP 客户端
• 认证
• 调试
• 校验 Webhook 签名
• 发展
  • 成熟度
  • 捐款

校验 Webhook 签名

ValidSignature函数是Avalanche SDK中的一种功能,它验证了AvaCloud收到的webhook请求的真实性和完整性. 该功能通过验证请求头中提供的HMAC SHA-256签名,确保请求来自可信任的来源. 使用量

导入和使用 isValidSignature 函数 :

import { isValidSignature } from '@avalabs/avacloud-sdk/utils';
import express from 'express';

const app = express();
app.use(express.json());

const signingSecret = 'your-signing-secret'; // Replace with your signing secret

app.post('/webhook', (req, res) => {
    const signature = req.headers['x-signature'];
    const payload = req.body;

    if (isValidSignature(signingSecret, signature, payload)) {
        console.log('Valid signature');
        // Process the request
    } else {
        console.log('Invalid signature');
    }

    res.json({ received: true });
});

app.listen(8000, () => console.log('Server running on port 8000'));

参数

• signingSecret:签名的秘密密钥.
• signature: HMAC SHA-256 从请求头签名.
• payload请求的JSON载荷.

更多信息

3⁄4 ̄ ̧漯B.

详情请访问 AvaCloud 开发者 文档.

发展

成熟度

这个SDK是在β中,在版本之间可能会有断裂的更改,而没有主要的版本更新. 因此,我们建议使用 到特定软件包版本。 这样,您可以每次安装同一版本而不中断更改,除非您是故意的 正在寻找最新版本.

捐款

虽然我们重视对SDK的开源贡献,但这个库是程序生成的. 任何加入内部文件的手动修改都会被覆盖到下一代上. 我们期待着听到你的反馈。 随便你开个公关 或一个有概念证明的问题 我们会尽力把它纳入未来的发行.