# @gnosis\.pm/safe-apps-sdk 中文文档

规范地址：https://npmcn.com/package/%40gnosis.pm/safe-apps-sdk/

版本：7\.8\.0
npm 元数据更新时间：2022-09-01T09:39:16.771Z
中文译文更新时间：2026-11-16T17:20:33.795Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：147 kB，90 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2020-04-28T16:56:20.460Z
- 最新版本发布：2022-09-01T09:39:16.648Z
- 近 30 天下载量：50668（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：64（近 12 个月 0 个）

## 中文简介

SDK开发将第三方应用与Safe应用集成.

## 安装

```sh
npm install @gnosis.pm/safe-apps-sdk
```

也可以使用：`pnpm add @gnosis.pm/safe-apps-sdk`、`yarn add @gnosis.pm/safe-apps-sdk`、`bun add @gnosis.pm/safe-apps-sdk`

## README

# 安全应用程序 SDK

[![Logo](https://raw.githubusercontent.com/gnosis/safe-apps-sdk/master/assets/logo.png)](https://gnosis-safe.io/) [![npm](https://img.shields.io/npm/v/@gnosis.pm/safe-apps-sdk)](https://www.npmjs.com/package/@gnosis.pm/safe-apps-sdk) [![Build Status](https://travis-ci.org/gnosis/safe-apps-sdk.svg?branch=master)](https://travis-ci.org/gnosis/pm-contracts)

将第三方应用程序(Safe Apps)与Safe(安全软件)集成的软件开发包[https://gnosis-safe.io/app/ (英语)](https://gnosis-safe.io/app/)) (中文(简体) ).

## 安装

### 用纱线或npm安装软件包 :

```bash
yarn add @gnosis.pm/safe-apps-sdk

npm install @gnosis.pm/safe-apps-sdk
```

## 构建

```bash
yarn install
yarn build

npm install
npm build
```

关于 `sed` macOS 和 Linux 上的 unix 工具 : 对于MacOS来说,应该:

```
  "format-dist": "sed -i '' 's/\"files\":/\"_files\":/' dist/package.json"
```

对于Linux:

```
  "format-dist": "sed -i 's/\"files\":/\"_files\":/' dist/package.json",
```

## 文档

由Safe Apps SDK所制造的Apps,本意是在Safe Web UI内部的iframe中运行. 此库将一个类作为默认导出 。 它接受一个选项对象:  
`allowedDomains` - 用于接受来源信息的正则表达式组。 如果没有通过,接受 来自所有域的信息  
`debug` -布尔 如果启用, 它将登录发送/ 收到的信件 .

```ts
import SafeAppsSDK from '@gnosis.pm/safe-apps-sdk';

type Opts = {
  allowedDomains?: RegExp[];
  debug?: boolean;
};

const opts: Opts = {
  allowedDomains: [/gnosis-safe.io/],
  debug: false
};

const appsSdk = new SafeAppsSDK(opts);
```

这个实例允许您与“安全”应用程序互动.

## 保险

### 获取安全信息

安全信息可以通过电话获取 `.safe.getInfo()`

```js
const safe = await appsSdk.safe.getInfo();
// {
//   "safeAddress": "0x2fC97b3c7324EFc0BeC094bf75d5dCdFEb082C53",
//   "chainId": 4
// }
```

### 获取链条信息

链条信息可以通过呼叫获取 `.safe.getChainInfo()`

```js
const chain = await appsSdk.safe.getChainInfo();
// {
//   chainName: "Rinkeby",
//   chainId: "4",
//   shortName: "rin",
//   nativeCurrency: {
//     name: "Ether",
//     symbol: "ETH",
//     decimals: 18,
//     logoUri:
//       "https://safe-transaction-assets.gnosis-safe.io/chains/4/currency_logo.png",
//   },
//   blockExplorerUriTemplate: {
//     address: "https://rinkeby.etherscan.io/address/{{address}}",
//     txHash: "https://rinkeby.etherscan.io/tx/{{txHash}}",
//     api: "https://api-rinkeby.etherscan.io/api?module={{module}}&action={{action}}&address={{address}}&apiKey={{apiKey}}",
//   },
// }
```

### 获得安全平衡

安全平衡可以通过拨打 `.safe.experimental_getBalances()`。该方法具有实验性,可被更改为返回已粘合结果.

它接受一个可选对象参数,使用 `currency` 属性. `currency` - 说吧 [国际标准化组织 4217](https://en.wikipedia.org/wiki/ISO_4217) 货币编码为字符串

```js
const safe = await appsSdk.safe.experimental_getBalances({ currency: 'rub' });
// {
//   "fiatTotal": "0",
//   "items": [
//     {
//     "tokenInfo": {
//       "type": "ETHER",
//       "address": "0x0000000000000000000000000000000000000000",
//       "decimals": 18,
//       "symbol": "ETH",
//       "name": "Ether",
//       "logoUri": null
//     },
//     "balance": "0",
//     "fiatBalance": "0",
//     "fiatConversion": "222297.29"
//     }
//   ]
// }
```

请检查url=值 (帮助) [类型声明文件](https://npmcn.com/packages/safe-apps-sdk/src/types.ts#L203-L227)

### 发送 TXs

通过保险箱发送一个 TX 和引用一样简单 `.txs.send()`

```js
// Create a web3 instance
const web3 = new Web3('https://rinkeby.infura.io/v3/token');
const contract = new web3.eth.Contract(abi, contractAddress);

const txs = [
  {
    to: someAddress,
    value: 0,
    data: contract.methods.someMethod().encodeABI(),
  },
  {
    to: someAddress2,
    value: 0,
    data: contract.methods.someOtherMethod().encodeABI(),
  },
];

const params = {
  safeTxGas: 500000,
};

try {
  const txs = await appsSdk.txs.send({ txs, params });
  // { safeTxHash: '0x...' }
} catch (err) {
  console.error(err.message);
}
```

> 说明: `value` 接受数字或字符串作为小数或六进制数字.

### 签名消息

由于"保险箱"是一个智能合同钱包,它没有钱包可以用来签名消息的私钥. 相反,我们有一个库 签署消息, 验证逻辑遵循 [EIP-1271 - 合同的标准签字验证方法](https://eips.ethereum.org/EIPS/eip-1271). 与Safe签署信息需要发送安全交易,需要安全所有人批准。 要潜入智能合同的执行,你可以从 [图书馆测试](https://github.com/gnosis/safe-contracts/blob/main/test/libraries/SignMessageLib.spec.ts) 保险合同的回购.

要触发交易以签名信件, 您可以使用 `sdk.txs.signMessage()` 或者说 `sdk.txs.signTypedMessage()`。 。 。 .

```js
const message = "I'm the owner of wallet 0x000000";
const tx = await sdk.txs.signMessage(message);
// { safeTxHash: '0x...' }

const typedMessage = {
    ...
}
const typedTx = await sdk.txs.signTypedMessage(typedMessage);
// { safeTxHash: '0x...' }
```

非类型信件将使用散列 [EIP-191 (中文(简体) )](https://eips.ethereum.org/EIPS/eip-191)。要计算散列,可以使用 `sdk.safe.calculateMessageHash()`。 。 。 .  
如果有打出的消息,将按 [EIP-712](https://eips.ethereum.org/EIPS/eip-712) 标准。 要计算信件散列, 您可以使用 `sdk.safe.calculateTypedMessageHash()`数字 :

```js
const messageHash = sdk.safe.calculateMessageHash(message);

const typedMessageHash = sdk.safe.calculateTypedMessageHash(typedMessage);
```

要验证信件是否签名, 请使用 `sdk.safe.isMessageSigned()`

```js
const message = "I'm the owner of wallet 0x000000";
const messageIsSigned = await sdk.safe.isMessageSigned(message);
```

### 获取交易状态

一旦您收到安全交易散列, 您可能想要获得交易状态( 是否执行 ) ? 有多少确认书

```js
const tx = await sdk.txs.getBySafeTxHash(safeTxHash);
```

它会回来 [网关交易](https://npmcn.com/package/%40gnosis.pm/safe-apps-sdk/src/types/gateway.ts#L222-L230) 如果后端尚未同步交易, 结构或抛出错误

### 请求地址簿

地址簿可以拨打 `.safe.requestAddressBook()`。此方法受到限制,因此如果呼叫者没有给予许可,需要当前连接的安全所有者批准.

制作请求的所有流程由SDK处理,所以开发人员只需要使用这种方法,其余的则由SDK和Web UI处理.

```js
const addressBook = await appsSdk.safe.requestAddressBook();
// [
//   {
//     address: '0x0',
//     chainId: '4',
//     name: 'Entry 1',
//   },
//   {
//     address: '0x1',
//     chainId: '4',
//     name: 'Entry 2',
//   },
// ];
```

返回数组 [地址簿项目](https://npmcn.com/package/%40gnosis.pm/safe-apps-sdk/src/types/sdk.ts#L55-L59)

### 管理权限

通常你不会使用这些方法,因为限制性方法 `requestAddressBook` 处理您的逻辑.

然而,作为内部执行《公约》的一部分 [EIP-2255 (英语)](https://eips.ethereum.org/EIPS/eip-2255) 您现在可以使用两种方法 `wallet` 在SDK的章节.

**获取权限**

```js
await appsSdk.wallet.getPermissions();
// [
//   {
//     parentCapability: "requestAddressBook",
//     invoker: "https://invoker-dapp.eth",
//     date: 1658499292741,
//     caveats: [],
//   }
// ]
```

返回数组 [权限](https://npmcn.com/package/%40gnosis.pm/safe-apps-sdk/src/types/permissions.ts#L1-L6) 给了dapp.

**请求权限**

对于请求权限,您应该拨打 `requestPermissions` 接受参数,其数组包括: [请求权限](https://npmcn.com/package/%40gnosis.pm/safe-apps-sdk/src/types/permissions.ts#L8-L10)。 。 。 .

```js
await appsSdk.wallet.requestPermissions([{ requestAddressBook: {} }]);
// [
//   {
//     parentCapability: "requestAddressBook",
//     invoker: "https://invoker-dapp.eth",
//     date: 1658499292741,
//     caveats: [],
//   }
// ]
```

返回数组 [权限](https://npmcn.com/package/%40gnosis.pm/safe-apps-sdk/src/types/permissions.ts#L1-L6) 给了Dapp。 如果目前没有被授予权限,则会从Web UI(只是第一次)中催促用户给予相应的权限.

## RPC呼吁

SDK揭露了伊特鲁姆的一些 [JSON-RPC API (英语)](https://eth.wiki/json-rpc/API)即读取方法.

### 默认块参数

以下方法具有额外的默认块参数:

-   获取布兰斯
-   获取代码
-   获取StorageAt
-   调用

当在乙醚状态下提出请求时,最后一个默认块参数决定了块的高度.

默认Block 参数的下列选项是可能的:

`HEX String` - 整数块数  
`String "earliest"` 用于最早/起源区块  
`String "latest"` - 最新的被布雷区块(默认)  
`String "pending"` - 有待处理的国家/交易

### 获取布兰斯

返回给定地址账户的余额.

```js
const balance = await appsSdk.eth.getBalance(['0x...']);
```

### 获取代码

在给定地址返回代码 .

```js
const code = await appsSdk.eth.getCode(['0x...']);
```

### 获取StorageAt

从给定地址的存储位置返回值.

```js
const value = await appsSdk.eth.getStorageAt(['0x...', 0]);
```

### 调用

立即执行新信件呼叫,而不在区块链上创建交易.

```js
const config = {
  from: '0x0000000000000000000000000000000000000000',
  to: '0x0000000000000000000000000000000000000000',
};

const result = await appsSdk.eth.call([config]);
```

交易调用对象 :  
`from` - (可选) 交易地址是寄来的 .  
`to` 20 字节 - 交易的地址是指定的.  
`gas` - (可选)交易执行所需的气体整数。 eth call消耗了零气体,但一些处决可能需要这个参数.  
`gasPrice` - (可选)每种有薪气体所用的气价整数  
`value` - (可选) 与此交易一起发送的值的整数  
`data` - (可选)方法签名和编码参数的散列. 详情见 [团结文件中的Ethereum Contract ABI](https://docs.soliditylang.org/en/latest/abi-spec.html)

### 获取路径日志

返回匹配指定过滤对象的所有日志的数组.

```js
const params = [
  {
    fromBlock: 11054275,
    toBlock: 'latest',
  },
];

const logs = await appsSdk.eth.getPastLogs([params]);
```

过滤选项 :  
`fromBlock` - 整数区块编号,或最后一个被开采区块的“最晚”或尚未被开采的交易的“待定”或“最远”的“最晚”.  
`toBlock` - 整数区块编号,或最后一个被开采区块的“最晚”或尚未被开采的交易的“待定”或“最远”的“最晚”.  
`address` - (可选)合同地址或记录来源地址清单.  
`topics` -(可选)32字节DATA主题的矩阵. 主题取决于秩序。 每个专题也可以是一系列带有“或”选项的DATA.

### 获取 BlockByHash

通过散列返回关于块的信息.

```js
const hash = '0x1955a9f306903669e295196752b11bc0dee33b48cabdf44b1103b7cea086cae7';

const block = await appsSdk.eth.getBlockByHash([hash, true]);
```

参数  
`DATA` -一个街区的草地.  
`Boolean` (默认:虚假) - 如果真实, 它会返回全部交易对象, 如果只假冒交易的散列 .

### 获得锁定比数

按块号返回关于块的信息.

```js
const number = 11054275;

const block = await appsSdk.eth.getBlockByNumber([number]);
```

参数  
`QUANTITY|TAG` - 区块数的整数,或字符串“最早”、“最晚”或“待定”,如默认区块参数. `Boolean` (默认:虚假) - 如果真实, 它会返回全部交易对象, 如果只假冒交易的散列 .

### 获取切换ByHash

返回交易散列要求的交易信息.

```js
const tx = await appsSdk.eth.getTransactionByHash([
  '0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b',
]);
```

### 获取交易检索

按交易散列返回交易的收讫.

> 说明: 尚未处理的交易没有收据.

```js
const tx = await appsSdk.eth.getTransactionReceipt([
  '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238',
]);
```

## 安全应用程序中的测试

### 声明

您的应用程序必须显示 `manifest.json` 此结构的文件 :

```json
{
  "name": "YourAppName",
  "description": "A description of what your app do",
  "icons": [
    {
      "src": "/myAppIcon.svg",
      "type": "image/svg+xml",
      "sizes": "any"
    }
  ]
}
```

> 注:图标\[n\]. src是公用相对路径,Safe将尝试加载您的应用程序图标. 例如,应当使用https://yourAppUrl/myAppIcon.svg.

我们正在跟踪 [外观光谱](https://developer.mozilla.org/en-US/docs/Web/Manifest) 所以,你可以找到更多的信息 关于如何填充 `icons` 现场.

### (简体中文)

由于安全应用软件通过iframe被纳入安全应用软件,因此需要启用 **跨站点请求** 通过设置 **(简体中文)** 服务安全应用程序时头条.

所需标题为:

```
"Access-Control-Allow-Origin": "\*",
"Access-Control-Allow-Methods": "GET",
"Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization"
```

### 反应开发

可以使用本地 React 开发服务器. 为此,你需要设置 **(简体中文)** 信头,并确保使用与安全接口相同的协议(https或https).

#### (简体中文)

为此,我们建议使用 [反应- app- 重联](https://www.npmjs.com/package/react-app-rewired)。使图书馆能够更新 `scripts` 节次 `package.json`数字 :

```json
"scripts": {
  "start": "react-app-rewired start",
  "build": "react-app-rewired build",
  "test": "react-app-rewired test"
},
```

此外,还需要创建 `config-overrides.js` 在工程的根中为配置 **(简体中文)** 头. 文件内容应为:

```js
/* config-overrides.js */

module.exports = {
  // The function to use to create a webpack dev server configuration when running the development
  // server with 'npm run start' or 'yarn start'.
  // Example: set the dev server to use a specific certificate in https.
  devServer: function (configFunction) {
    // Return the replacement function for create-react-app to use to generate the Webpack
    // Development Server config. "configFunction" is the function that would normally have
    // been used to generate the Webpack Development server config - you can use it to create
    // a starting configuration to then modify instead of having to create a config from scratch.
    return function (proxy, allowedHost) {
      // Create the default config by calling configFunction with the proxy/allowedHost parameters
      const config = configFunction(proxy, allowedHost);

      config.headers = {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'GET',
        'Access-Control-Allow-Headers': 'X-Requested-With, content-type, Authorization',
      };

      // Return your customised Webpack Development Server config.
      return config;
    };
  },
};
```

#### SSL 服务器

启用 SSL 与 `react-scripts` 有必要确定 `HTTPS` 环境变量改为 `true`。可以在 `package.json` 通过调整文件 `scripts` 节改为:

```json

"scripts": {
  "start": "HTTPS=true react-app-rewired start",
},
```

在大多数情况下,由 `react-scripts` 无效,它需要在浏览器中将其标记为信任。 对于此操作, 在单独的标签( 不在安全界面) 中打开 Safe App 并接受证书/ 忽略警告 .

### 正在装入安全应用程序

开发您的安全应用程序时, 您可以直接使用 [我们的制作界面](https://gnosis-safe.io/app) 为了测试它。 一些像林克比这样的测试网也在那里提供. 一旦您的应用程序被激活,即使您正在本地运行,也可以将它导入安全应用程序作为自定义的应用程序. 为此,您应当选择“ Apps” 标签 :

![Apps section button](https://raw.githubusercontent.com/gnosis/safe-apps-sdk/master/assets/safe-tab-apps.png "Safe: Apps tab")

使用 `Add custom app` 按钮并使用链接添加您的应用程序 :

![Add custom Safe App form](https://raw.githubusercontent.com/gnosis/safe-apps-sdk/master/assets/third-pary-app-modal.png "Safe: Add Safe App")

## 部署到森林小组

这需要你拥有 `ipfs` 已安装([说明](https://gist.github.com/MiguelBel/b3b5f711aa8d9362afa5f16e4e972461)(中文(简体) )

```bash
yarn build
ipfs add -r build
```

## 用此 SDK 构建的应用程序示例

-   [https://github.com/gnosis/ safe-react-apps 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/gnosis/safe-react-apps)
-   [https://github.com/Uxio0/安全反应-收集](https://github.com/Uxio0/safe-react-collectibles)
-   [https://docs.gnosis-safe.io/building/sdks/saf-apps#已存在-安全应用程序](https://docs.gnosis-safe.io/build/sdks/safe-apps#existing-safe-apps)

## 许可证

这个库在麻省理工学院下发行.

## 贡献者

-   尼古拉斯·多明格斯(签名)[尼可桑普勒语name](https://github.com/nicosampler)(中文(简体) )
-   理查德·迈斯纳(Richard Meissner)[卢迈斯纳](https://github.com/rmeissner)(中文(简体) )

## 常见问题

### @gnosis\.pm/safe-apps-sdk 是什么？

SDK开发将第三方应用与Safe应用集成\.

### 如何安装 @gnosis\.pm/safe-apps-sdk？

在项目目录运行 npm install @gnosis\.pm/safe-apps-sdk，或使用 pnpm add / yarn add / bun add。

### @gnosis\.pm/safe-apps-sdk 支持 TypeScript 吗？

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

### @gnosis\.pm/safe-apps-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gnosis\.pm/safe-apps-sdk 可以商用吗？

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

### @gnosis\.pm/safe-apps-sdk 的下载量有多少？

根据 npm 官方下载统计，@gnosis\.pm/safe-apps-sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 50,668 次，日均约 1,689 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gnosis\.pm/safe-apps-sdk 还在维护吗？

最新版本 7\.8\.0 发布于 2022/09/01（4 年前）；至今共发布 64 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/04/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

