Skip to main content

Deep Guide

The above article describes how to use web3infra.dev to permanently store files. Developers can use the sdk to connect to the official permadao deployment of web3infra for file storage, or they can deploy their own arseeding light nodes.

Compare web3infra and private nodes​

web3infra

  • No need to configure Arweave wallets, no need to hold AR
  • Compatible with Ethereum addresses and Arweave addresses
  • Must have assets on everPay and use assets on everPay for payments

Private Node

  • Need to configure Arweave wallet and hold AR
  • Option to turn payments on or off
  • Calling the ANS-104 interface will consume the AR in the configured Arweave wallet

Deploy Private node please reference:

Deploy Light Node

Workflow Logic​

web3infra​

  1. The developer uploads the data (file) to the Arseeding node via the Item format of ANS-104.
  2. Arseeding node will return an everPay order
  3. The developer pays for the stored order using everPay
  4. Arseeding will receive the payment record and change the data status to be sent
  5. Arseeding uploads the data to Arweave Network via ANS-104 batch.

As shown in the figure below:

Note: If the developer does not pay for the order, the data cache will be deleted from the Arseeding node after one hour.

Private Node​

The process for the private node is similar to web3infra, if the payment feature is turned off, the process is as follows:

  1. The developer uploads the data (files) to the Arseeding node via ANS-104 in Item format.
  2. Arseeding uploads the data to Arweave Network via ANS-104 in batch.

Note: Arseeding with payments turned off will receive data from any user and automatically complete the Arweave Network data upload. You may need to implement additional interface authentication functionality, or make the interface available only to internal services for use.

About Guide​

This guide will provide an in-depth look at three different ways to interact with the web3infra service for file storage. They are:

  • Data upload and automatic payment: just use one method to do data upload and payment of fees.
  • Decoupled data upload and fee payment: Handle the data upload and fee payment methods separately. This is suitable for application scenarios where the fee payment private key and the data signature private key are not the same.
  • Submit data directly using apiKey: Submit the original data directly using apikey authentication, This is suitable for scenarios that do not need to sign and pay for the data, but just want to use the simplest way to store the data forever .

Installation​

Make sure you already have knowledge of front-end or node.js, and install arseeding-js in the terminal using the following command:

npm i arseeding-js

Data Upload And Automatic Payment​

Wallet Initialization​

Web3 has two wallet initialization options, either injecting MetaMask or ArConnect on the web side via the Provider, or injecting the key directly in the local node-js.

1. Local key injection​

This method is available for node-js development.

Ethereum Wallet

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

Arweave Wallet

TODO

2. Web3 Provider​

This method is suitable for Browser development.

MetaMask

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

ArConnect

TODO

Data Uploading And Paying​

Simply use the instance.sendAndPay method to complete the data upload and fee payment.

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 supported all 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: You can use https://arseed.web3infra.dev or replace it with your own deployed Arseeding node url.
  • payCurrencyTag: Specify the token tag for payment, support using any token on everPay for payment.You can get all the tags of a symbol by using getTokenTagByEver('symbol').
  • tags: tag the uploaded data, you can tag it with many tags as you want. Note: The data must have a Content-Type tag to describe the data type, so that the data can be rendered directly by the browser. What are tags.
  • Content-Type in tags needs to be configured based on the content you upload. For example, if you upload an image in png format, configure it as image/png. For details, refer to Content-Type.

Decoupled Data Upload And Fee Payment​

To meet more storage application scenarios, Arseeding-js provides decoupled usage of data upload and fee payment. This means that developers can pay for storage on behalf of users, e.g., the national library uploads literature data to the Arseeding node, and Arweave Org checks for data uploads from the library and makes storage payments on behalf of the national library.

Data signing and uploading​

1.Signing for data uploading​

Uploading data requires signing the data with a private key. Arseeding-js supports the following three signature providers:

  • MetaMask signature (for Browser development)

  • ECC private key signature

  • RSA private key signature

    (1) MetaMask

This method will sign the data using 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()

We have implemented the MetaMask upload data Demo: demo.web3infra.dev , source code: https://github.com/permadao/arseed-bundle-demo.

(2) ECC private key

This approach is suitable for scenarios where the nodejs service is configured with a private key of type ecc specifically for signing.

import { EthereumSigner } from 'arseeding-js'

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

(3) RSA private key

This approach is suitable for scenarios where the nodejs service is configured with a private key of type rsa specifically for signing.

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. Signing and uploading​

Assemble the data into a bundle Item and sign the data using the signer generated above and upload it to 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 payTags = await getTokenTagByEver('symbol') // USDC, ETH,...
const payCurrencyTag = payTags[0] // everpay supported all token tag (chainType-symbol-id)
const config = {
  signer: signer,
  path: '',
  arseedUrl: arseedingUrl,
  tag: payCurrencyTag
}
const order = await createAndSubmitItem(data, options, config)
  • arseedUrl: You can use https://arseed.web3infra.dev or replace it with your own deployed Arseeding node url.
  • payCurrencyTag: Specify the token for payment. everPay supports any token on everPay for payment.You can get all the tags of a symbol by using getTokenTagByEver('symbol').
  • tags: tag the uploaded data, you can tag it as many times as you want. Note: The data must have a Content-Type tag to describe the data type, so that the data can be rendered directly by the browser. What are tags.

Example of order’s return value:

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

Fee Payment​

Arseeding only supports everpay payment channel, so you must ensure that the address has enough token balance on everPay Protocol to pay for the stored orders before paying for the uploaded orders. everPay asset top-up can be found here.

1. everPay supported signing method​

everPay supports the following three signing methods.

(1) MetaMask

This method generally involves signing the everPay transaction using a metamask on the client side.

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 private key injection

This method is suitable for nodejs services configured with an ecc type private key specifically to send everPay transactions for payment fees.

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

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

(3) RSA private key injection

This method is suitable for nodejs services configured with a private key of type rsa specifically for sending everPay transactions with payment fees.

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. Use everpay to pay for your order​

import { payOrder } from 'arseeding-js'
const everHash = await payOrder(everpay, order)
  • order: The order returned by the upload data, note: the order must contain a tag field, if it does not have a tag field, you can use getTokenTagByEver('symbol') to find out if everpay supports token tag. If the order is forgotten, you can use getOrders to find the payment order.
  • everHash: everPay tx hash for payment.

Code Example​

  1. Data uploaded but fee not payed: https://github.com/permadao/arseeding-js/blob/main/example/uploadFile.ts
  2. Pay for data order: https://github.com/permadao/arseeding-js/blob/main/example/payBill.ts

Submit data using apiKey​

Arseeding supports authorizing clients to submit data to the server via apikey, which has the advantage that the client does not need to sign the data with a private key. There is no need to use everPay to pay for the data.

The Arseeding node receives the data, assembles the signed bundle item with its own private key and sends it to the server.

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: Apply for apiKey.
  • symbol: must be the token contained in the apiKey, as viewed via apikey.web3infra.dev.
  • contentType: data type, used to get the data directly rendered in the browser.

Code Example​

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