详细指南
上文介绍了如何使用 web3infra.dev 永存文件。开发者可以使用 sdk 连接 permadao 官方部署的 web3infra 进行文件永存,也可以自行部署 arseeding 轻节点。
对比 web3infra 和个人节点
web3infra
- 无需配置 Arweave 钱包,无需持有 AR
- 兼容以太坊地址和 Arweave 地址
- 必须在 everPay 上有资产,使用 everPay 上的资产用于支付
个人节点
- 需要配置 Arweave 钱包并持有 AR
- 可以选择开启或关闭支付功能
- 调用 ANS-104 接口将消耗配置的 Arweave 钱包中的 AR
部署个人节点参考: 轻节点部署指南
业务流程
web3infra
- 开发者将数据(文件)通过 ANS-104 的 Item 格式上传到 Arseeding 节点。
- Arseeding 节点将返回一个 everPay 订单
- 开发者使用 everPay 支付存储订单
- Arseeding 将收到支付记录,并更数据为待发送
- Arseeding 将数据通过 ANS-104 批量上传到 Arweave Network。
如下图所示:
注意:如果开发者没有支付订单,数据缓存将在一小时后从 Arseeding 节点删除。
个人节点
个人节点的流程同 web3infra 类似,如果关闭了支付功能,流程如下:
- 开发者将数据(文件)通过 ANS-104 的 Item 格式上传到 Arseeding 节点。
- Arseeding 将数据通过 ANS-104 批量上传到 Arweave Network。
注意:关闭支付功能的 Arseeding 将接收任何用户的数据并自动完成 Arweave Network 数据上传。你可能需要额外实现接口鉴权功能,或者仅将接口提供给内部服务进行使用。
关于指南
本指南将深入介绍三种不同方式与 web3infra 服务进行文件存储交互。分别为:
- 数据上传并自动支付: 一个方法就可以完成数据上传和费用支付。
- 数据上传和费用支付解耦: 分别操作上传数据和支付费用方法,适用于费用支付私钥和数据签名私钥不相同的应用场景。
- 使用 apiKey 直接提交数据: 使用 apikey 鉴权直接提交原数据,适用于不需要对数据进行签名和支付费用,只想使用最简单的方式永存数据的场景。
安装
确保你已经具备前端或者 node.js 知识,在终端使用下面命令安装 arseeding-js:
npm i arseeding-js
数据上传并自动支付费用
初始化钱包
Web3 有两种钱包初始化方案,可以在网页端通过 Provider 注入 MetaMask 或者 ArConnect。也可以在本地 node-js 中直接注入密钥。
- 本地注入密钥
该方式适用于 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 检查到图书管的数据上传,为国家图书馆进行存储代付。
数据签名和上传
- 上传数据签名方法
上传数据需要使用私钥对数据进行签名,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
: 为上传数据返回的 ordereverHash
: 用于支付费用的 everPay tx hash
代码实例
- 上传数据但是未进行支付:https://github.com/permadao/arseeding-js/blob/main/example/uploadFile.ts
- 对存储订单进行支付: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
: 申请 apiKeycontentType
: data 数据类型,用于在浏览器中获取数据时能直接被渲染出来。
代码实例
https://github.com/permadao/arseeding-js/blob/main/example/apiKey.ts