详细指南

上文介绍了如何使用 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 中直接注入密钥。

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 payTags = await getTokenTagByEver('symbol') // USDC,ETH,...
const payCurrencyTag = payTags[0] // everPay 支持的 token tag (chainType-symbol-id)
const options = {
  tags: [
    { name: 'Content-Type', value: 'data type' },
    { name: 'aa', value: 'aaa' }
  ]
}
const resp = await instance.sendAndPay(arseedUrl, data, payCurrencyTag, options)

arseedUrl: 可以使用 https://arseed.web3infra.dev ，或者替换成自己部署的 Arseeding node url。
payCurrencyTag: 指定支付费用的 token tag, 支持使用 everPay 上的任意 token 进行支付, 可通过 getTokenTagByEver('symbol'),获取 symbol 的 tag，。
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) MetaMask

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

npm i ethers bundlr-arseeding-client

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

const provider = new providers.Web3Provider(window.ethereum)
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 。

(2) ECC 私钥

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

import { EthereumSigner } from 'arseeding-js'

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

(3) RSA 私钥

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

import { ArweaveSigner } from 'arseeding-js'
import { readFileSync } from 'fs'
import path from 'path'
import { fileURLToPath } from 'url'

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const privateKeyJSON = '<arweave key file json>'
const arJWK = JSON.parse(
  readFileSync(path.join(__dirname, privateKeyJSON)).toString()
)
const arAddress = '<your arweave wallet address>'
const signer = new ArweaveSigner(arJWK)

2. 签名并上传

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

const data = Buffer.from('<need upload data>')
const options = {
  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 payTags = await getTokenTagByEver('symbol') // USDC, ETH,...
const payCurrencyTag = payTags[0] // everPay 支持的 token tag (chainType-symbol-id)
const config = {
  signer: signer,
  path: '',
  arseedUrl: arseedingUrl,
  tag: payCurrencyTag
}
const order = await createAndSubmitItem(data, options, config)

arseedUrl: 可以使用 https://arseed.web3infra.dev ，或者替换成自己部署的 Arseeding node url。
payCurrencyTag: 指定支付费用的 token tag, 支持使用 everPay 上的任意 token 进行支付, 可通过 getTokenTagByEver('symbol'),获取 symbol 的 tag。
tags: 对上传数据打标签，可以打任意多个标签。注: 数据必须要有 Content-Type 标签用于描述数据类型，这样通过浏览器获取数据就可以直接被渲染出来。什么是 tags。

order 返回值示例：

{
  itemId: 'VoPNz4JVdWw5hDUfzmYlBWDm9ZLt7otBZ8yJbWTAG1E',
  size: 201,
  bundler: 'uDA8ZblC-lyEFfsYXKewpwaX-kkNDDw8az3IW9bDL68',
  currency: 'USDC',
  decimals: 6,
  fee: '1244',
  paymentExpiredTime: 1690970459,
  expectedBlock: 1212405,
  tag: 'ethereum-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
}

费用支付

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

1. everPay 支持的签名方式

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

(1) MetaMask

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

import { providers } from 'ethers'
import Everpay,{ ChainType } 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 ChainType
})

(2) ECC 私钥注入

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

import { newEverpayByEcc } from 'arseeding-js/cjs/payOrder'

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

(3) RSA 私钥注入

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

import { newEverpayByRSA } from 'arseeding-js/cjs/payOrder'
import { readFileSync } from 'fs'
import path from 'path'
import { fileURLToPath } from 'url'

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const privateKeyJSON = '<arweave key file json>'
const arJWK = JSON.parse(
  readFileSync(path.join(__dirname, privateKeyJSON)).toString()
)
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, 注意: order 中必需包含 tag 字段，若没有 tag 字段，可通过 getTokenTagByEver('symbol') 查询 everpay 支持 token tag。若 order 遗忘, 可通过 getOrders 查询该笔支付订单。
everHash: 用于支付费用的 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 tokenTags = await getTokenTagByEver('symbol')
const data = '<need upload data, such as a picture>'
const contentType = 'image/png'
const tags = { 'Content-Type': 'image/png', a: 'aa', b: 'bb' }
const res = await submitByApikey(
  arseedingUrl,
  apikey,
  tokenTags[0],
  data,
  contentType,
  tags
)
console.log(res)

apiKey: 申请 apiKey
symbol: 必需是 apiKey 中所包含的代币，可通过 apikey.web3infra.dev查看。
contentType: data 数据类型，用于在浏览器中获取数据时能直接被渲染出来。

代码实例

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

详细指南

对比 web3infra 和个人节点​

业务流程​

web3infra​

个人节点​

关于指南​

安装​

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

初始化钱包​

1. 本地注入密钥​

2. Web3 Provider​

上传和自动支付​

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

数据签名和上传​

1. 上传数据签名方法​

2. 签名并上传​

费用支付​

代码实例​

使用 apiKey 直接提交数据​

使用 apikey​

代码实例​

对比 web3infra 和个人节点

业务流程

web3infra

个人节点

关于指南

安装

数据上传并自动支付费用

初始化钱包

1. 本地注入密钥

2. Web3 Provider

上传和自动支付

数据上传和费用支付解耦

数据签名和上传

1. 上传数据签名方法

2. 签名并上传

费用支付

代码实例

使用 apiKey 直接提交数据

使用 apikey

代码实例