跳到主要内容

详细指南

上文介绍了如何使用 web3infra.dev 永存文件。开发者可以使用 sdk 连接 permadao 官方部署的 web3infra 进行文件永存，也可以自行部署 arseeding 轻节点。

对比 web3infra 和个人节点​

web3infra

  • 无需配置 Arweave 钱包，无需持有 AR
  • 兼容以太坊地址和 Arweave 地址
  • 必须在 everPay 上有资产，使用 everPay 上的资产用于支付

个人节点

  • 需要配置 Arweave 钱包并持有 AR
  • 可以选择开启或关闭支付功能
  • 调用 ANS-104 接口将消耗配置的 Arweave 钱包中的 AR

部署个人节点参考： 轻节点部署指南

业务流程​

web3infra​

  1. 开发者将数据（文件）通过 ANS-104 的 Item 格式上传到 Arseeding 节点。
  2. Arseeding 节点将返回一个 everPay 订单
  3. 开发者使用 everPay 支付存储订单
  4. Arseeding 将收到支付记录，并更数据为待发送
  5. Arseeding 将数据通过 ANS-104 批量上传到 Arweave Network。

如下图所示：

注意：如果开发者没有支付订单，数据缓存将在一小时后从 Arseeding 节点删除。

个人节点​

个人节点的流程同 web3infra 类似，如果关闭了支付功能，流程如下：

  1. 开发者将数据（文件）通过 ANS-104 的 Item 格式上传到 Arseeding 节点。
  2. Arseeding 将数据通过 ANS-104 批量上传到 Arweave Network。

注意：关闭支付功能的 Arseeding 将接收任何用户的数据并自动完成 Arweave Network 数据上传。你可能需要额外实现接口鉴权功能，或者仅将接口提供给内部服务进行使用。

关于指南​

本指南将深入介绍三种不同方式与 web3infra 服务进行文件存储交互。分别为:

安装​

确保你已经具备前端或者 node.js 知识，在终端使用下面命令安装 arseeding-js：

npm i arseeding-js

数据上传并自动支付费用​

初始化钱包​

Web3 有两种钱包初始化方案，可以在网页端通过 Provider 注入 MetaMask 或者 ArConnect。也可以在本地 node-js 中直接注入密钥。

  1. 本地注入密钥

该方式适用于 node-js 开发。

以太坊钱包

import { genNodeAPI } from 'arseeding-js'
const instance = await genNodeAPI('<YOUR PRIVATE KEY>')

Arweave 钱包

TODO

2. Web3 Provider

该方式适用于 Browser 开发。

MetaMask

import { genAPI } from 'arseeding-js'
const instance = await genAPI(window.ethereum)

ArConnect

TODO

上传和自动支付​

只需要使用 instance.sendAndPay 方法就可以完成数据上传和费用支付。

const arseedUrl = '<https://arseed.web3infra.dev>'
const data = Buffer.from('need upload data ...')
const payCurrency = 'USDC' // everpay supported all tokens,like 'AR','ETH','USDT' and so on
const ops = {
    tags: [
        {name: "Content-Type",value:"data type"},
        {name: "aa",value:"aaa"}
    ]
}
const resp = await instance.sendAndPay(arseedUrl, data, payCurrency, ops)
  • arseedUrl: 可以使用 https://arseed.web3infra.dev ，或者替换成自己部署的 Arseeding node url。
  • payCurrency: 指定支付费用的 token, 支持使用 everPay 上的任意 token 进行支付。
  • tags: 对上传数据打标签，可以打任意多个标签。注: 数据必须要有 Content-Type 标签用于描述数据类型，这样通过浏览器获取数据就可以直接被渲染出来。什么是 tags。
  • tags 中的 Content-Type 需要基于你上传的内容进行配置，例如 上传的 png 格式的图片，则配置为 image/png，详细说明参考 Content-Type。

数据上传和费用支付解耦​

为了满足更多的存储应用场景，Arseeding-js 提供了数据上传和费用支付解耦的使用方式。这意味着开发者可以为用户代付存储，例如：国家图书管将文献数据上传到 Arseeding 节点，Arweave Org 检查到图书管的数据上传，为国家图书馆进行存储代付。

数据签名和上传​

  1. 上传数据签名方法

上传数据需要使用私钥对数据进行签名，Arseeding-js 支持以下三种签名 provider：

  • MetaMask 签名（适用于 Brower 开发）
  • ECC 私钥签名
  • RSA 私钥签名

1.1 MetaMask

此方式将使用 MetaMask 对数据进行签名。

import { providers } from 'ethers'
import getCurrency from 'bundlr-arseeding-client/build/web/currencies'

const provider = new providers.Web3Provider(windowEthereum)
await provider._ready()
const currencyConfig = getCurrency('ethereum', provider)
await currencyConfig.ready()
const signer = await currencyConfig.getSigner()

我们已经实现了 MetaMask 上传数据的 Demo：demo.web3infra.dev ，源代码：https://github.com/permadao/arseed-bundle-demo 。

1.2 ECC 私钥

此方式适合 nodejs 服务配置 ecc 类型的私钥专门用于签名的场景

import EthereumSigner from 'arseeding-arbundles/src/signing/chains/ethereumSigner'

const privateKey = '<your ecc private key>'
const signer = new EthereumSigner(privateKey)

1.3 RSA 私钥

此方式适合 nodejs 服务配置 rsa 类型的私钥专门用于签名的场景

import ArweaveSigner from "arseeding-arbundles/src/signing/chains/ArweaveSigner"

const wallet = JSON.parse(
    readFileSync(path.join(__dirname, "test_key.json")).toString(),
);
const signer = new ArweaveSigner(wallet)

2. 签名并上传

数据组装成 bundle Item，并使用上面生成的 signer 签名数据并上传到 Arseeding

const data = Buffer.from('<need upload data>')
const ops = {
    tags: [
        { name: 'key01', value: 'val01' },
        { name: 'Content-Type', value: 'imag/png' } // you should set the data type tag
    ]
}
const arseedingUrl = '<https://arseed.web3infra.dev>'
const payCurrency = 'USDC' // everpay supported all tokens, like 'AR','ETH','USDT' and so on
const order = await createAndSubmitItem(arseedingUrl, signer, data, ops, payCurrency)
  • arseedUrl: 可以使用 https://arseed.web3infra.dev ，或者替换成自己部署的 Arseeding node url。
  • payCurrency: 指定支付费用的 token, 支持使用 everPay 上的任意 token 进行支付。
  • tags: 对上传数据打标签，可以打任意多个标签。注: 数据必须要有 Content-Type 标签用于描述数据类型，这样通过浏览器获取数据就可以直接被渲染出来。什么是 tags。

order 返回值示例：

{
  itemId: 'XTnZ26gmangoxn7BBXXXabZhxf-BQgnI-x8p1xNUDdA',
  bundler: 'uDA8ZblC-lyEFfsYXKewpwaX-kkNDDw8az3IW9bDL68',
  currency: 'USDC',
  decimals: 6,
  fee: '28029',
  paymentExpiredTime: 1658827438,
  expectedBlock: 982398
}

费用支付​

Arseeding 只支持 everpay 支付通道，所以在支付上传订单费用之前，必须保证地址在 everPay Protocol 上有足够的资产用于支付存储订单费用，everPay 资产充值可以参考这里。

1. everPay 支持的签名方式

everPay 支持以下三种签名方式：

1.1 MetaMask

此方式一般是用户端使用 metamask 对everPay 交易进行签名

import { providers } from 'ethers'
import Everpay from 'everpay'

const provider = new providers.Web3Provider(windowEthereum)
await provider._ready()
const accounts = await provider.listAccounts()
const account = accounts[0] ?? ''
const everpay = new Everpay({
  debug: debug,
  account: account,
  ethConnectedSigner: provider.getSigner(),
  chainType: 'ethereum' as any
})

1.2 ECC 私钥注入

此方式适合 nodejs 服务配置 ecc 类型的私钥专门发送支付费用的 everPay 交易

import { newEverpayByEcc } from 'arseeding-js'

const eccPrivate = '<your ecc private key>'
const everpay = newEverpayByEcc(eccPrivate)

1.3 RSA 私钥注入

此方式适合 nodejs 服务配置 rsa 类型的私钥专门发送支付费用的 everPay 交易

import { newEverpayByRSA } from 'arseeding-js'

const arJWK = '<your arweave wallet keyFile>'
const arAddress = '<your arweave wallet address>'
const everpay = newEverpayByRSA(arJWK, arAddress)

2. 使用 everpay 支付订单

import { payOrder } from 'arseeding-js'
const everHash = await payOrder(everpay, order)
  • order: 为上传数据返回的 order
  • everHash: 用于支付费用的 everPay tx hash

代码实例​

  1. 上传数据但是未进行支付：https://github.com/permadao/arseeding-js/blob/main/example/uploadFile.ts
  2. 对存储订单进行支付：https://github.com/permadao/arseeding-js/blob/main/example/payBill.ts

使用 apiKey 直接提交数据​

Arseeding 支持通过 apikey 授权客户端直接提交 data 到服务端，这样的好处是客户端不需要使用私钥对 data 进行签名。也不需要使用 everPay 进行费用支付。 Arseeding 节点收到 data 之后会使用自有的私钥组装签名 bundle item 并发送上链。

使用apikey​

const arseedingUrl = '<https://arseed.web3infra.dev>'
const apikey = '<your arseeding apiKey>'
const data = '<need upload data, such as a picture>'
const contentType = 'image/png'
const tags = {'a':'aa','b':'bb'}
const res = await submitByApikey(arseedingUrl,apikey,data,contentType, tags)
  • apiKey: 申请 apiKey
  • contentType: data 数据类型，用于在浏览器中获取数据时能直接被渲染出来。

代码实例​

https://github.com/permadao/arseeding-js/blob/main/example/apiKey.ts