Arweave

Skill based on Arweave (official Erlang node/gateway), generated 2026-02-24. Docs from sources/arweave/ (README, http_iface_docs, http_post_unsigned_tx_docs, doc/).

Arweave is a distributed, cryptographically verified permanent archive. Data is stored in a decentralised peer-to-peer Blockweave; amounts are in winston (1 AR = 10^12 winston). The node exposes an HTTP API for transactions, blocks, wallets, price, and peers; gateways serve content by domain with optional path manifests and custom domains.

Core References

Features

HTTP and Internal API

Gateway and Data

Best Practices

External Links

• arweave.org
• Yellow paper
• ArweaveTeam/arweave GitHub
• HTTP API Postman

Generation Info

• Source: sources/arweave
• Git SHA: 1d0ca29335062a1b348bf9486103ef6e192a5c1d
• Generated: 2026-02-24

Doc Paths Used

• sources/arweave/README.md
• sources/arweave/http_iface_docs.md
• sources/arweave/http_post_unsigned_tx_docs.md
• sources/arweave/doc/ar-ipfs-howto.md
• sources/arweave/doc/gateway_setup_guide.md
• sources/arweave/doc/path-manifest-schema.md

Units and Encoding

Correct handling of units and encoding avoids interoperability and precision bugs.

Winston and AR

• 1 AR = 1,000,000,000,000 winston. All on-chain and API amounts (balance, reward, quantity, price) are in winston.
• Use strings for amounts in JSON. JavaScript and other environments cannot safely represent full winston range as numbers; the API uses decimal strings for quantity, reward, balance, and price.
• When displaying to users, convert winston to AR by dividing by 1e12; when sending, convert AR to winston and send as string.

Base64url

• Transaction IDs, block hashes (indep_hash), wallet addresses, and binary fields (owner, signature, data) use base64url encoding (RFC 4648, URL-safe base64 without padding in URLs).
• Do not use raw base64; ensure no +// (use -/_) and handle padding as per gateway/node expectations.

Content-Type and Tags

• Path manifest transactions MUST be tagged Content-Type: application/x.arweave-manifest+json.
• Other tags are optional and application-defined; use tags for indexing and filtering (e.g. App-Name, Content-Type for non-manifest data).

Key Points

• Never send or parse winston as JSON number in agent or client code; use string and a bignum library if doing arithmetic.
• Always use base64url for IDs and binary fields when calling the HTTP API or building POST bodies.
• Tag manifest tx with Content-Type: application/x.arweave-manifest+json so gateways recognize path manifests.

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (http_iface_docs.md, doc/path-manifest-schema.md)

-->

Arweave Blocks

Blocks contain the blockweave metadata and transaction lists. Use indep_hash (not hash) when requesting a block by ID.

Block Fields (JSON)

Usage

By block ID (use indep_hash):

GET /block/hash/{block_id}

By height:

GET /block/height/{block_height}

Current block (network head):

GET /current_block

Key Points

• Requesting by hash must use indep_hash from block JSON; hash is internal.
• Block height is numeric; use /block/height/{n} for historical queries.

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (http_iface_docs.md)

-->

Arweave Protocol Overview

Arweave is a distributed, cryptographically verified permanent archive backed by a cryptocurrency. Data is stored in a decentralised, peer-to-peer manner with miners incentivised to store rare data.

Key Concepts

• Blockweave: Datastructure linking blocks; miners store and replicate data.
• AR: Native token; smallest unit is winston (1 AR = 1,000,000,000,000 winston). All API amounts (balance, reward, quantity, price) are in winston; use string type for interoperability (e.g. JavaScript cannot safely represent full winston range as number).
• Node: Participates in the network (sync, mine, serve HTTP API). Default HTTP port often 1984.
• Gateway: Node configured to serve content by domain (e.g. permaweb apps, custom domains).

Usage

When implementing clients or agents:

• Treat monetary and size-related values as strings in winston.
• Use base64url for transaction IDs, block hashes, wallet addresses, and binary fields (owner, signature, data) in the HTTP API.
• Distinguish indep_hash (block identifier for requests) from hash (internal); use indep_hash for /block/hash/{block_id}.

Key Points

• Permanent storage: data in transactions is stored on the weave and can be retrieved by transaction ID.
• Financial transactions: set target and quantity (winston string), leave data empty.
• Data transactions: set data (base64url), leave target and quantity empty or zero.
• Price endpoint is pessimistic (reports as if difficulty were one step lower) to account for possible retarget.

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (README.md)
• https://yellow-paper.arweave.dev

-->

Arweave Transactions

Transactions are the unit of data and value transfer. IDs and hashes are base64url-encoded.

Transaction Fields

Usage

Get full transaction:

GET /tx/{transaction_id}

Get single field: id, last_tx, owner, target, quantity, data, reward, signature

GET /tx/{transaction_id}/{field}

Get decoded data as HTML (e.g. archived page):

GET /tx/{transaction_id}/data.html

Get confirmation status:

GET /tx/{transaction_id}/status

Response example: {"block_indep_hash":"...","block_height":10,"number_of_confirmations":3}

Post signed transaction:

POST /tx
Content-Type: application/json
Body: { "last_tx", "owner", "target", "quantity", "data", "reward", "signature" }

All winston fields (quantity, reward) must be decimal strings for interoperability.

Key Points

• Wallet address = base64url SHA256 of the raw RSA modulus (public key).
• Always fetch last_tx for a wallet before submitting a new tx from that wallet.
• Use /price/{byte_size} to estimate reward (byte_size = 0 for transfer-only).

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (http_iface_docs.md)

-->

Wallets and Balances

Wallet address is the base64url-encoded SHA256 hash of the raw RSA modulus (public key). Balances and amounts are in winston (string in API).

Usage

Balance (winston string):

GET /wallet/{wallet_address}/balance

Last transaction ID from wallet:

GET /wallet/{wallet_address}/last_tx

Transaction IDs made by wallet (optional from earliest_tx):

GET /wallet/{wallet_address}/txs
GET /wallet/{wallet_address}/txs/{earliest_tx}

Deposits to wallet (transfer tx IDs; index may be partial per node):

GET /wallet/{wallet_address}/deposits
GET /wallet/{wallet_address}/deposits/{earliest_deposit}

Key Points

• Before posting a new transaction, get last_tx for the owner wallet and set it in the transaction body.
• Balance and reward/quantity values are strings to support arbitrary-precision; do not use JSON number for winston.
• Deposits endpoint returns only transfers to the given address; coverage depends on the node.

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (http_iface_docs.md)

-->

Gateway Setup

A gateway node serves content by domain. It requires TLS certificates and optional custom-domain support.

Certificate Files

• Main domain (e.g. gateway.example): certificate and key at:
• apps/arweave/priv/tls/cert.pem
• apps/arweave/priv/tls/key.pem
• Certificate must be valid for the main domain and wildcard *.gateway.example.
• Custom domain (e.g. custom.domain.example): per-domain cert/key at:
• apps/arweave/priv/tls/custom.domain.example/cert.pem
• apps/arweave/priv/tls/custom.domain.example/key.pem

Custom Domain DNS

To point a custom domain at a specific transaction, create a TXT record:

• Name: _arweave.{custom.domain.example}
• Value: the transaction ID (e.g. 1H0jHTlM6bYFdnrwZ4yMx92EgJITDRakse2YP_sDkBc)

Startup

Command line:

./arweave-server gateway gateway.example

With custom domains:

./arweave-server gateway gateway.example custom_domain custom1.domain.example custom_domain custom2.domain.example

Configuration:

{
  "gateway": "gateway.example",
  "custom_domains": ["custom1.domain.example", "custom2.domain.example"]
}

Custom domains are in addition to the main gateway domain.

Key Points

• Gateway mode is enabled by the gateway flag or config field with the main domain name.
• Custom domains require both TLS files and DNS TXT _arweave.{domain} → tx id.
• Use path manifests so one tx ID can serve an entire app with multiple paths.

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (doc/gateway_setup_guide.md)

-->

Arweave HTTP API

The node exposes an HTTP interface (default port often 1984). All IDs and binary fields use base64url.

Network and Peers

Transactions

Blocks

Wallet

Usage

Base URL example: http://127.0.0.1:1984. POST body for /tx:

{
  "last_tx": "",
  "owner": "",
  "target": "",
  "quantity": "",
  "data": "",
  "reward": "",
  "signature": ""
}

Use string values for quantity and reward. Empty last_tx for first tx from wallet.

Key Points

• All monetary and size-related values in responses are winston strings.
• Use indep_hash from block JSON when calling /block/hash/{block_id}.
• Price endpoint is pessimistic (accounts for possible difficulty change).

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (http_iface_docs.md)
• https://documenter.getpostman.com/view/5500657/RWgm2g1r

-->

Internal HTTP API (Wallet and Unsigned Tx)

Warning: Only use when you know what you are doing. Endpoints are available only when arweave-server is started with internal_api_secret set.

Authentication

Send header on every request:

X-Internal-Api-Secret: <value of internal_api_secret>

Endpoints

Generate wallet and get access code

POST /wallet
X-Internal-Api-Secret: <secret>

Response: {"wallet_access_code":"<base64url>"}. Use this code to sign and submit transactions via /unsigned_tx.

Post unsigned transaction

POST /unsigned_tx
X-Internal-Api-Secret: <secret>
Content-Type: application/json

Body (no owner or signature; server signs with wallet from access code):

{
  "last_tx": "",
  "target": "",
  "quantity": "",
  "data": "",
  "reward": "",
  "wallet_access_code": ""
}

Response: {"id": "<transaction_id>"} (base64url hash of the signature).

Usage

1. POST /wallet to obtain wallet_access_code. 2. Build unsigned tx: last_tx, target, quantity, data, reward (all as for public API; winston as strings). 3. POST to /unsigned_tx with wallet_access_code; server signs and broadcasts, returns tx id.

Key Points

• Do not expose internal_api_secret or wallet_access_code; treat as sensitive.
• last_tx must be the last transaction ID for the wallet that owns the access code.
• Use for server-side signing when the client must not hold the private key.

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (http_post_unsigned_tx_docs.md)

-->

Arweave and IPFS Pinning

When running arweave-server with IPFS pinning, the server can pin transaction data to a local IPFS node when transactions include the IPFS_Add tag with the corresponding hash.

Prerequisites

• Go-IPFS installed and in PATH (e.g. from https://dist.ipfs.io/#go-ipfs).
• IPFS daemon running (ipfs daemon) before starting the Arweave server with pinning.

Enabling Pinning

Command line:

arweave-server peer ... ipfs_pin

In Erlang shell (after starting server):

app_ipfs:start_pinning().

Behavior

• Server listens for incoming transactions that have data and a tag {"IPFS_Add", Hash}.
• It runs ipfs add for that data and pins it to the local IPFS node, associating the hash with the transaction.

Monitoring

Server state:

app_ipfs:report(app_ipfs).
% or
app_ipfs:report(IPFSPid).

Returns a proplist including adt_pid, queue, wallet, ipfs_name, ipfs_key, blocks, txs, ipfs_hashes.

Hash status:

app_ipfs:ipfs_hash_status(Hash).

Returns [{pinned, true|false}, {tx, list()}] (tx = list of tx IDs containing that IPFS hash and data).

Key Points

• Pinning is optional and requires a running IPFS daemon and ipfs_pin (or start_pinning()).
• Only transactions with data and the appropriate IPFS tag trigger pinning.
• Use ipfs_hash_status/1 to check whether a hash is pinned and which tx(s) reference it.

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (doc/ar-ipfs-howto.md)

-->

Path Manifests

Path manifests are JSON documents stored in a single transaction. They map URL subpaths to transaction IDs so one root TX can represent a multi-file app or site. Gateways use them to serve paths like /{tx_id}/path/to/file.

Schema

The manifest transaction MUST contain only this JSON (no other data). Tag with Content-Type: application/x.arweave-manifest+json.

Example

{
  "manifest": "arweave/paths",
  "version": "0.1.0",
  "index": {
    "path": "index.html"
  },
  "paths": {
    "index.html": { "id": "cG7Hdi_iTQPoEYgQJFqJ8NMpN4KoZ-vH_j7pG4iP7NI" },
    "css/style.css": { "id": "fZ4d7bkCAUiXSfo3zFsPiQvpLVKVtXUKB6kiLNt2XVQ" },
    "assets/img/logo.png": { "id": "QYWh-QsozsYu2wor0ZygI5Zoa_fRYFc8_X1RkYmw_fU" }
  }
}

When index is omitted, gateways typically serve a listing of all paths.

Usage

• Upload each asset as its own transaction; collect tx IDs.
• Create one transaction whose body is only the manifest JSON; add tag Content-Type: application/x.arweave-manifest+json.
• Reference the manifest tx ID as the app root; gateways resolve /{manifest_tx_id}/path to the tx in paths[path].id.

Key Points

• index.path must reference a key in paths, not a raw transaction ID.
• Path keys are subpaths (e.g. js/app.js, index.html).
• One manifest tx = one deployable app/site with many underlying data tx IDs.

<!-- Source references:

• https://github.com/ArweaveTeam/arweave (doc/path-manifest-schema.md)

-->