Connecting to the Permaweb

The Permaweb is a platform for hosting permanent and decentralized websites and applications. Arweave is the storage of the Permaweb, as it allows uploading arbitrary data when submitting a transaction (TX) and ensures that this data is immutable and perpetually stored with hundreds of replicas worldwide. Users can read this data with a browser by connecting to an Arweave gateway, which distributes TX data via HTTP and provides caching and indexing to ensure low-latency access.

This article will explain how to read and write data on the Permaweb, first from a user's perspective and then from an app creator's perspective.

If you want to stay updated on Arweave news, follow @onlyarweave on Twitter!

How to Open Permaweb Apps in the Browser?

To view a Permaweb app, you need a URL that consists of an Arweave gateway's hostname and the app's Arweave TX ID.

Popular gateways are:

A TX ID that contains a simple HTML page is:

yRj4a5KMctX_uOmKWCFJIjmY8DeJcusVk6-HzLiM_t8

To view this page, choose a gateway and append the TX ID:

https://arweave.dev/yRj4a5KMctX_uOmKWCFJIjmY8DeJcusVk6-HzLiM_t8

Copy it into your browser's navigation bar, and you connected to the Permaweb!

If a gateway goes offline, choose another one and use the same TX ID. Since gateways all use Arweave as their data source, you can be sure to receive the same data. Figure 1 shows how nodes, gateway, and users are connected in Arweave.

Figure 1: Arweave network architecture

This URL responds with the same HTML page:

https://g8way.io/yRj4a5KMctX_uOmKWCFJIjmY8DeJcusVk6-HzLiM_t8

Why do Gateways Redirect TX ID URLs to Subdomains?

You might have noticed that gateways redirect TX ID URLs to a subdomain with a cryptic name. This subdomain redirect is a security measure called sandboxing. Gateways serve data of each TX under a subdomain that acts as a sandbox for the JavaScript it might contain. This way, a Permaweb app can’t access the browser data of another Permaweb app.

Instead of this URL:

https://g8way.io/yRj4a5KMctX_uOmKWCFJIjmY8DeJcusVk6-HzLiM_t8

You will see this sandbox URL in your browser:

https://zempq24srrznl75y5gffqikjei4zr4bxrfzowfmtv6d4zoem73pq.g8way.io/yRj4a5KMctX_uOmKWCFJIjmY8DeJcusVk6-HzLiM_t8?

How to Open Permaweb Apps with ArNS Names?

Using and remembering TX IDs is hard, and while your browser makes this easier with bookmarks, they don’t help when accessing a Permaweb app you haven’t opened before. You also might want to use new versions of the app, but the data referenced by the TX ID is immutable.

The Arweave Name Service (ArNS) is the Permaweb solution. ArNS names are subdomains, which a gateway will internally resolve to a TX ID, allowing you to access a Permaweb app with an easy name that will always refer to the TX ID of the newest app version.

Popular examples of ArNS names are:

Again, you can switch out the gateway and get the same results:

ArNS works transparently; there is no redirect to a TX ID, just the ArNS subdomain.

How to Interact with a Permaweb App?

Interacting with a Permaweb app means submitting TXs to Arweave. Since you need to sign a TX before you can send it, you need a private key. Arweave wallets manage these keys. They are software running on your device (e.g., PC, Mac, tablet, smartphone, etc.)

On Arweave, you use the private key to sign your TXs; others can use your public key to check that your private key created the signature. Only you know your private key, so only you can make valid signatures, and others can be sure the TXs are yours.

Checking the authenticity of a TX is useful when interacting with Permaweb apps, as it allows the app to restrict certain actions to specific users. For example, if you want to change the target TX ID of your ArNS name, you submit a TX containing the change to Arweave, and ArNS will only process it if your public key signed the TX.

How to Use Arweave Wallets to Interact with Permaweb Apps?

To get a private key for signing TXs, you need an Arweave-compatible crypto wallet. There are different implementations that all have their pros and cons. Let’s review the most popular options so you can decide which fits your needs.

Arweave Wallet: The Web Wallet

The easiest way to get started is probably Arweave Wallet. It’s a web app, so it doesn’t need any installation. The wallet stores your keys in the secure browser storage. You can download a key file or write a seed phrase on paper for backup purposes.

A Permaweb app that supports Arweave Wallet will open a popup with the signing dialog of the wallet where you can create the signature.

ArConnect: The Browser Extension Wallet

Usage of the ArConnect wallet is more involved but comes with features like easy asset management. If you use tokens other than AR or want to keep track of your NTFs in one place, then ArConnect might be a better fit.

The ArConnect wallet is a browser extension that injects a JavaScript object into web apps. Apps use this object to request signatures for interaction TXs.

MetaMask: The Multi-Chain Wallet

MetaMask is a well-known crypto wallet for Ethereum. With its plugin interface, called Snaps, you can add support for non-EVM blockchains. The ArSnap plugin lets you use MetaMask for Arweave. It’s a bit basic, but if you already use MetaMask, ArSnap is probably the best way to get started.

Ledge: The Hardware Wallet

The Arweave Wallet for Ledger comes with the highest security but also the most effort. You must buy a Ledger device. The unique selling point of this wallet is that the private key never leaves the Ledger device; the browser relays signature requests via USB or Bluetooth to the device that creates the signature. The host device (e.g., your computer or smartphone) never sees the private key.

The Arweave (Web) Wallet lets you pass signature requests to your Ledger wallet. So, the interface to Permaweb apps stays the same, just a browser popup.

How to Build a Client-Only Permaweb App?

Building a basic client-only Permaweb app is as easy as creating a traditional web app. You just need frontend skills, HTML, CSS, JavaScript, and you’re good to go. In this scenario, the hosting is the only difference between a traditional web app and a Permaweb app.

Create a new HTML file with the following content:

<!doctype HTML>

<title>My Fist Permaweb App</title>
<style>body {background: black; color: white;}</style>

<h1>My First Permaweb App</h1>

<script>alert("Hello, world!")</script>

Set up one of the mentioned wallets and head to Dragon Deploy, where you can upload this file to Arweave.

If your app is below 100KB, you can deploy it to Arweave for free! Irys, a service that manages uploads to Arweave, covers the costs. If it’s bigger, you need crypto tokens. If you use an Arweave wallet, you need AR tokens, which you can buy on Kriptomat. Irys also supports a range of other popular tokens to pay for uploads (e.g., ETH, SOL, MATIC, etc.)

How to Build an Interactive Permaweb App?

You need additional libraries and services to build a Permaweb app that lets users interact with data on Arweave.

An interactive Permaweb app consists of a frontend, its TXs, and, optionally, a smart contract that manages concurrent user interactions. You can read more about Arweave’s smart contract standard in my SmartWeave article.

How to Connect to Arweave from JavaScript?

The best way to get started with Permaweb frontend development is the Arweave Kit. It's an Arweave SDK that works in the browser and Node.js. It helps with wallet connections, TX signing, smart contract interaction, GraphQL queries, and more.

If a user doesn’t have a wallet, Arweave Kit uses Othent in the background, a service allowing users to sign TXs with OAuth accounts. Since Irys sponsors TXs under 100KB, users don’t need tokens for basic interactions; a wallet address is enough.

Which Features Do Gateways Offer?

The server side of the connection is an Arweave gateway. You already learned that you use gateways to deliver the app to the users, but it can do more!

Grouping Multiple Files with Path a Manifest

Gateways support path manifests, which are JSON files that map path expressions to TX IDs. Instead of uploading multiple files and linking them in your app with various TX IDs, you can use the TX ID of the path manifest and refer to the files with readable paths instead.

You need a path manifest because instead of uploading a directory to Arweave at once, you upload each file in that directory. So, each file becomes a TX on Arweave, and you need multiple TX IDs to access all files. The path manifest solves this by letting you define paths for each of those files, so when you know the TX ID to the path manifest, you can access the files without needing to remember multiple TX IDs. Figure 2 illustrates the difference in access.

Figure 2: Path manifest

Without using a path manifest, you upload an image, get a TX ID, and then upload an HTML file where you reference the TX ID of this image.

The HTML file would look like this:

<!doctype HTML>

<title>My Permaweb App</title>
<h1>My Permaweb App</h1>

<link rel="stylesheet" href="/<STYLE_CSS_TX_ID>">

<img src="/<IMAGE_JPG_TX_ID>">  

<script src="/<BUNDLE_JS_TX_ID>">

Using a path manifest, you upload the image, get a TX ID, upload the HTML file, get a TX ID, and then upload the manifest file, where you map each TX ID to a path.

The path manifest would look like this:

{
  "manifest": "arweave/paths",
  "version": "0.1.0",
  "index": {
    "path": "index.html"
  },
  "paths": {
    "index.html": {
      "id": "<INDEX_HTML_TX_ID>"
    },
    "res/image.jpg": {
      "id": "<IMAGE_JPG_TX_ID>"
    },
    "res/style.css": {
      "id": "<STYLE_CSS_TX_ID>"
    },
    "res/bundle.js": {
      "id": "<BUNDLE_JS_TX_ID>"
    },
  }
}

The HTML file would look like this:

<!doctype HTML>

<title>My Permaweb App</title>
<h1>My Permaweb App</h1>

<link rel="stylesheet" href="/res/style.css">

<img src="/res/image.jpg">  

<script src="/res/bundle.js">

As you can see, TX IDs aren't required when creating the app.

The Irys CLI lets you upload multiple files with one command and automatically creates a manifest file.

Accessing TX Metadata via a GraphQL Endpoint

Each Arweave gateway has a GraphQL endpoint to query TXs and their metadata. This endpoint is useful for filtering TX by specific attributes like tags. To display a list of all TX containing PNG files, you can filter for the tag name Content-Type and the tag value image/png.

The PNG file query would look like this:

{
  transactions(
    tags: [
      { name: "Content-Type", values: ["image/png"] }
    ]
  ) {
    edges {
      node {
        id
      }
    }
  }
}

Of course, you can add custom tags when submitting TXs so your app can filter for them later. Also, Arweave Kit has a GraphQL client to access this data without additional dependencies.

If you liked this article and want to dive deeper into the Arweave ecosystem, check out Arweave Hub, where you can find events, podcasts, and learning resources.

Summary

Connecting to the Permaweb is as easy as opening a website in a browser. Thanks to public gateways and services like Irys, which sponsors TX costs, and Othent, which provides OAuth signatures, most Permaweb features are readily available for users who don’t understand crypto wallets.

Arweave’s wallet ecosystem is growing, so finding a suitable one for your use cases is easier than ever. With Arweave Wallet, you don’t have to install something to get self-custody benefits.

Finally, when you want to build your own Permaweb app, you can leverage Arweave Kit to get up and running quickly.

Blog