@gnosis.pm/safe-apps-sdk

中文文档
7.8.0发布于 2022/09/01MITTypeScriptCommonJS近 30 天下载 5.1万

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

中文使用文档
文档目录33 节
  1. 安装
  2. 用纱线或npm安装软件包 :
  3. 构建
  4. 文档
  5. 保险
  6. 获取安全信息
  7. 获取链条信息
  8. 获得安全平衡
  9. 发送 TXs
  10. 签名消息
  11. 获取交易状态
  12. 请求地址簿
  13. 管理权限
  14. RPC呼吁
  15. 默认块参数
  16. 获取布兰斯
  17. 获取代码
  18. 获取StorageAt
  19. 调用
  20. 获取路径日志
  21. 获取 BlockByHash
  22. 获得锁定比数
  23. 获取切换ByHash
  24. 获取交易检索
  25. 安全应用程序中的测试
  26. 声明
  27. (简体中文)
  28. 反应开发
  29. 正在装入安全应用程序
  30. 部署到森林小组
  31. 用此 SDK 构建的应用程序示例
  32. 许可证
  33. 贡献者

安全应用程序 SDK

Logo npm Build Status

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

安装

用纱线或npm安装软件包 :

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

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

构建

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 -布尔 如果启用, 它将登录发送/ 收到的信件 .

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()

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

获取链条信息

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

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 货币编码为字符串

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=值 (帮助) 类型声明文件

发送 TXs

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

// 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 - 合同的标准签字验证方法. 与Safe签署信息需要发送安全交易,需要安全所有人批准。 要潜入智能合同的执行,你可以从 图书馆测试 保险合同的回购.

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

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 (中文(简体) )。要计算散列,可以使用 sdk.safe.calculateMessageHash()。 。 。 .
如果有打出的消息,将按 EIP-712 标准。 要计算信件散列, 您可以使用 sdk.safe.calculateTypedMessageHash()数字 :

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

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

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

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

获取交易状态

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

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

它会回来 网关交易 如果后端尚未同步交易, 结构或抛出错误

请求地址簿

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

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

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

返回数组 地址簿项目

管理权限

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

然而,作为内部执行《公约》的一部分 EIP-2255 (英语) 您现在可以使用两种方法 wallet 在SDK的章节.

获取权限

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

返回数组 权限 给了dapp.

请求权限

对于请求权限,您应该拨打 requestPermissions 接受参数,其数组包括: 请求权限。 。 。 .

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

返回数组 权限 给了Dapp。 如果目前没有被授予权限,则会从Web UI(只是第一次)中催促用户给予相应的权限.

RPC呼吁

SDK揭露了伊特鲁姆的一些 JSON-RPC API (英语)即读取方法.

默认块参数

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

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

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

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

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

获取布兰斯

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

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

获取代码

在给定地址返回代码 .

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

获取StorageAt

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

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

调用

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

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

获取路径日志

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

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

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

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

获取 BlockByHash

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

const hash = '0x1955a9f306903669e295196752b11bc0dee33b48cabdf44b1103b7cea086cae7';

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

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

获得锁定比数

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

const number = 11054275;

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

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

获取切换ByHash

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

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

获取交易检索

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

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

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

安全应用程序中的测试

声明

您的应用程序必须显示 manifest.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.

我们正在跟踪 外观光谱 所以,你可以找到更多的信息 关于如何填充 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- 重联。使图书馆能够更新 scripts 节次 package.json数字 :

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

此外,还需要创建 config-overrides.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 节改为:


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

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

正在装入安全应用程序

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

Apps section button

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

Add custom Safe App form

部署到森林小组

这需要你拥有 ipfs 已安装(说明(中文(简体) )

yarn build
ipfs add -r build

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

许可证

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

贡献者

版本与发布记录

@gnosis.pm/safe-apps-sdk 共发布 64 个版本,首次发布于 2020/04/29;过去 12 个月发布了 0 个版本。

版本发布日期距今
7.8.0latest2022/09/014 年前
7.7.02022/08/254 年前
7.6.02022/07/284 年前
7.5.02022/07/064 年前
7.4.12022/06/304 年前
7.4.02022/06/204 年前

其他发布通道:beta → 2.0.0-beta.0,alpha → 3.1.0-alpha.0,next → 5.0.0-next.1。

关于 @gnosis.pm/safe-apps-sdk 的常见问题

@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 和提交记录判断。