Arweave JS is the JavaScript/TypeScript SDK for interacting with the Arweave network and uploading data to the permaweb. It works in latest browsers and Node JS.
Notes: 1. If you are planning to upload large batches of data transactions to the Arweave network, it is strongly advised that you use @DHA-Team/ArBundles instead of transactions with Arweave.js. You can read about bundles and their advantages on the Arwiki. 2. When working with NodeJS a minimum version of 18+ is required. Bun/Deno not currently working.
npm install --save arweave
Single bundle file (web only - use the NPM method if using Node).
<script src="https://unpkg.com/arweave/bundles/web.bundle.js"></script>
<script src="https://unpkg.com/arweave/bundles/web.bundle.min.js"></script>
<script src="https://unpkg.com/arweave@1.2.0/bundles/web.bundle.js"></script>
<script src="https://unpkg.com/arweave@1.2.0/bundles/web.bundle.min.js"></script>
const Arweave = require('arweave');
// If you want to connect directly to a node
const arweave = Arweave.init({
host: '127.0.0.1',
port: 1984,
protocol: 'http'
});
// Or to specify a gateway when running from NodeJS you might use
const arweave = Arweave.init({
host: 'arweave.net',
port: 443,
protocol: 'https'
});
import Arweave from 'arweave';
// Since v1.5.1 you're now able to call the init function for the web version without options. The current URL path will be used by default. This is recommended when running from a gateway.
const arweave = Arweave.init({});
// Or manually specify a host
const arweave = Arweave.init({
host: '127.0.0.1',
port: 1984,
protocol: 'http'
});
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Hello world</title>
<script src="https://unpkg.com/arweave/bundles/web.bundle.js"></script>
<script>
const arweave = Arweave.init({});
arweave.network.getInfo().then(console.log);
</script>
</head>
<body>
</body>
</html>
{
host: 'arweave.net',// Hostname or IP address for a Arweave host
port: 443, // Port
protocol: 'https', // Network protocol http or https
timeout: 20000, // Network request timeouts in milliseconds
logging: false, // Enable network request logging
}
Here you can generate a new wallet address and private key (JWK), don't expose private keys or make them public as anyone with the key can use the corresponding wallet.
Make sure they're stored securely as they can never be recovered if lost.
Once AR has been sent to the address for a new wallet, the key can then be used to sign outgoing transactions.
arweave.wallets.generate().then((key) => {
console.log(key);
// {
// "kty": "RSA",
// "n": "3WquzP5IVTIsv3XYJjfw5L-t4X34WoWHwOuxb9V8w...",
// "e": ...
});
arweave.wallets.jwkToAddress(key).then((address) => {
console.log(address);
//1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY
});
Get the balance of a wallet address, all amounts by default are returned in winston.
arweave.wallets.getBalance('1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY').then((balance) => {
let winston = balance;
let ar = arweave.ar.winstonToAr(balance);
console.log(winston);
//125213858712
console.log(ar);
//0.125213858712
});
arweave.wallets.getLastTransactionID('1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY').then((transactionId) => {
console.log(transactionId);
//3pXpj43Tk8QzDAoERjHE3ED7oEKLKephjnVakvkiHF8
});
Transactions are the building blocks of the Arweave permaweb. They can send AR between wallet addresses or store data on the Arweave network.
The create transaction methods create and return an unsigned transaction object. You must sign the transaction and submit it separately using the transactions.sign and transactions.submit methods.
If you don't pass in a key argument when creating a transaction, Arweave.js will attempt to use a browser-based wallet extension, such as ArConnect or Arweave.app, to sign the transaction.
Modifying a transaction object after signing it will invalidate the signature, causing it to be rejected by the network if submitted in that state. Transaction prices are based on the size of the data field, so modifying the data field after a transaction has been created isn't recommended as you'll need to manually update the price.
The transaction ID is a hash of the transaction signature, so a transaction ID can't be known until its contents are finalised and it has been signed.
Note: If you are planning to upload large batches of data transactions to the Arweave network, it is strongly advised that you use ArBundles instead of transactions with Arweave.js. You can read about bundles and their advantages on the Arwiki.
Data transactions are used to store data on the Arweave permaweb. They can contain HTML or any arbitrary data and are served like webpages.
let key = await arweave.wallets.generate();
// Plain text
let transactionA = await arweave.createTransaction({
data: '<html><head><meta charset="UTF-8"><title>Hello world!</title></head><body></body></html>'
}, key);
// Buffer
let transactionB = await arweave.createTransaction({
data: Buffer.from('Some data', 'utf8')
}, key);
console.log(transactionA);
// Transaction {
// format: 2,
// id: 'ReUohI9tEmXQ6EN9H9IkRjY9bSdgql_OdLUCOeMEte0',
// last_tx: 'Tk-0c7260Ya5zjfjzl4f6-W-vRO94qiqZMAScKBcYXc68v1Pd8bYfTbKWi7pepUF',
// owner: 'kmM4O08BJB85RbxfQ2nkka9VNO6Czm2Tc_IGQNYCTSXRzO...',
// tags: [],
// target: '',
// quantity: '0',
// data: 'c29tZSBkYXRh',
// data_size: '9',
// data_root: 'qwKZUl7qWpCEmB3cpONKTYOcSmnmhb-_s8ggMTZwCU4',
// data_tree: [],
// reward: '7489274',
// signature: 'JYdFPblDuT95ky7_wVss3Ax9e4Qygcd_lEcB07sDPUD_wNslOk...'
// }
Wallet to wallet transactions can facilitate payments from one wallet to another, given a target wallet and AR token quantity in Winston.
let key = await arweave.wallets.generate();
// Send 10.5 AR to 1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY
let transaction = await arweave.createTransaction({
target: '1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY',
quantity: arweave.ar.arToWinston('10.5')
}, key);
console.log(transaction);
// Transaction {
// format: 2,
// id: 'v-n7hAc7cubeXSClh0beaOs1RjYFagyvpl2TkUOfbRg',
// last_tx: 'Tk-0c7260Ya5zjfjzl4f6-W-vRO94qiqZMAScKBcYXc68v1Pd8bYfTbKWi7pepUF',
// owner: 'kmM4O08BJB85RbxfQ2nkka9VNO6Czm2Tc_IGQNYCTSXRzOc6W9b...',
// tags: [],
// target: '1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY',
// quantity: '10500000000000',
// data: '',
// data_size: '0',
// data_root: '',
// data_tree: [],
// reward: '7468335',
// signature: 'DnUOYbRSkhI4ZXg5fpYDCwPv8yvM5toAneSx4Jlg0zjIocqPs8giPP...'
// }
Metadata can be added to transactions through tags, these are simple key/value attributes that can be used to document the contents of a transaction or provide related data.
GraphQL uses tags when searching for transactions.
The Content-Type is a reserved tag and is used to set the data content type. For example, a transaction with HTML data and a content type tag of text/html will be served as a HTML page and render correctly in browsers,
if the content type is set to text/plain then it will be served as a plain text document and not render in browsers.
let key = await arweave.wallets.generate();
let transaction = await arweave.createTransaction({
data: '<html><head><meta charset="UTF-8"><title>Hello world!</title></head><body></body></html>',
}, key);
transaction.addTag('Content-Type', 'text/html');
transaction.addTag('key2', 'value2');
console.log(transaction);
// Transaction {
// format: 2,
// id: '',
// last_tx: 'Tk-0c7260Ya5zjfjzl4f6-W-vRO94qiqZMAScKBcYXc68v1Pd8bYfTbKWi7pepUF',
// owner: 'kmM4O08BJB85RbxfQ2nkka9VNO6Czm2Tc_IGQNYC...',
// tags: [
// Tag { name: 'Q29udGVudC1UeXBl', value: 'dGV4dC9odG1s' },
// Tag { name: 'a2V5Mg', value: 'dmFsdWUy' }
// ],
// target: '',
// quantity: '0',
// data: 'PGh0bWw-PGhlYWQ-PG1ldGEgY2hhcnNldD0iVVRGLTgiPjx0aXRsZT5IZWxsbyB3b3JsZCE8L3RpdGxlPjwvaGVhZD48Ym9keT48L2JvZHk-PC9odG1sPg',
// data_size: '88',
// data_root: 'GQunzmbwk2_JPU7oJOmLrTMvj8v_7BJaF0weyjVn5Nc',
// data_tree: [],
// reward: '7673074',
// signature: ''
// }
let key = await arweave.wallets.generate();
let transaction = await arweave.createTransaction({
target: '1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY',
quantity: arweave.ar.arToWinston('10.5')
}, key);
await arweave.transactions.sign(transaction, key);
console.log(transaction);
// Transaction {
// format: 2,
// id: 'v-n7hAc7cubeXSClh0beaOs1RjYFagyvpl2TkUOfbRg',
// last_tx: 'Tk-0c7260Ya5zjfjzl4f6-W-vRO94qiqZMAScKBcYXc68v1Pd8bYfTbKWi7pepUF',
// owner: 'kmM4O08BJB85RbxfQ2nkka9VNO6Czm2Tc_IGQNYCTSXRzOc6W9b...',
// tags: [],
// target: '1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY',
// quantity: '10500000000000',
// data: '',
// data_size: '0',
// data_root: '',
// data_tree: [],
// reward: '7468335',
// signature: 'DnUOYbRSkhI4ZXg5fpYDCwPv8yvM5toAneSx4Jlg0zjIocqPs8giPP...'
// }
The preferred method of submitting a data transaction is to use chunk uploading. This method will allow larger transaction sizes, resuming a transaction upload if it's interrupted and give progress updates while uploading.
Simple example:
let data = fs.readFileSync('path/to/file.pdf');
let transaction = await arweave.createTransaction({ data: data }, key);
transaction.addTag('Content-Type', 'application/pdf');
await arweave.transactions.sign(transaction, key);
let uploader = await arweave.transactions.getUploader(transaction);
while (!uploader.isComplete) {
await uploader.uploadChunk();
console.log(`${uploader.pctComplete}% complete, ${uploader.uploadedChunks}/${uploader.totalChunks}`);
}
N.B. The above code has been simplified and ignores potential errors.
You can also submit transactions using transactions.post() which is suitable for small transactions or token transfers:
let key = await arweave.wallets.generate();
let transaction = await arweave.createTransaction({
target: '1seRanklLU_1VTGkEk7P0xAwMJfA7owA1JHW5KyZKlY',
quantity: arweave.ar.arToWinston('10.5')
}, key);
await arweave.transactions.sign(transaction, key);
const response = await arweave.transactions.post(transaction);
console.log(response.status);
// 200 : not to be confused with getStatus === 200, see note below**
// HTTP response codes (200 - server received the transaction, 4XX - invalid transaction, 5XX - error)
N.B.
This 200 response does not mean that the transaction has mined & confirmed, and that a txid can be used as if it's immutable. It just means that a node has received your transaction. See Get a transaction status for more detail on how to correctly determine that your transaction has been mined & confirmed. This also applies to the uploader method.
You can resume an upload from a saved uploader object, that you have persisted in storage some using
JSON.stringify(uploader) at any stage of the upload. To resume, parse it back int
$ claude mcp add arweave-js \
-- python -m otcore.mcp_server <graph>