@@ -29,9 +31,9 @@ A decentralized infrastructure layer built on Arweave and AO, making permanent d
Ar.io operates a network of [gateways](/learn/gateways) — nodes that serve as entry points to Arweave’s data. These gateways fetch and deliver data quickly, supporting everything from static files to dynamic web apps.
-### Arweave Name System (ArNS)
+### Ar.io Name System (ArNS)
-The [Arweave Name System (ArNS)](/learn/arns) is a decentralized naming system for Arweave. It allows users to register and resolve human-readable names to Arweave transaction IDs.
+The [Ar.io Name System (ArNS)](/learn/arns) is a decentralized naming system for Arweave. It allows users to register and resolve human-readable names to Arweave transaction IDs.
### Data Access
@@ -54,7 +56,7 @@ Ar.io builds on Arweave's permanent storage to create a decentralized, scalable
- **Decentralized Gateways**: ar.io operates a network of gateways—nodes that serve as entry points to Arweave’s data. These gateways fetch and deliver data quickly, supporting everything from static files to dynamic web apps.
-- **ArNS (Arweave Name Service)**: ar.io introduces decentralized domain names (e.g., yourname.arweave), mapping human-readable names to Arweave’s data IDs. This makes content easy to find and share, like URLs on the traditional web.
+- **ArNS (Ar.io Name System)**: ar.io introduces decentralized domain names (e.g., yourname.arweave), mapping human-readable names to Arweave’s data IDs. This makes content easy to find and share, like URLs on the traditional web.
- **Indexing and Querying**: ar.io enables efficient data indexing, allowing developers to search and retrieve specific content from Arweave’s vast storage without scanning the entire blockweave.
diff --git a/content/learn/arns/ants.mdx b/content/learn/arns/ants.mdx
index a79102532..d461d85bd 100644
--- a/content/learn/arns/ants.mdx
+++ b/content/learn/arns/ants.mdx
@@ -1,31 +1,35 @@
---
-title: "Arweave Name Tokens (ANTs)"
-description: "Learn about Arweave Name Tokens (ANTs) - the ownership and control system for ArNS names"
+title: "Ar.io Name Tokens (ANTs)"
+description: "Learn about Ar.io Name Tokens (ANTs) - the ownership and control system for ArNS names"
---
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Calculator, FileText, Code } from 'lucide-react';
-To establish ownership of a record in the ArNS Registry, each record contains both a friendly name and a reference to an Arweave Name Token, ANT. Name Tokens are unique AO Computer based tokens/processes that give their owners the ability to update the Arweave Transaction IDs that their associated friendly names point to.
+To establish ownership of a record in the ArNS Registry, each record contains both a friendly name and a reference to an Ar.io Name Token (ANT). ANTs are [Metaplex Core](https://developers.metaplex.com/core) NFTs on Solana that give their owners the ability to update the Arweave transaction IDs their associated friendly names point to.
## What is an ANT?
-The ANT smart contract process is a standardized contract that implements the specific Arweave Name Process specification required by ar.io gateways who resolve ArNS names and their Arweave Transaction IDs. It also contains other basic functionality to establish ownership and the ability to transfer ownership and update the Arweave Transaction ID.
+An ANT is a Metaplex Core NFT managed by the `ario-ant` Solana program. It implements the Ar.io Name Token specification required by ar.io gateways to resolve ArNS names to Arweave transaction IDs. The program handles record updates, controller management, metadata changes, and ownership reconciliation after transfers.
-Name Tokens have an owner, who can transfer the token and control its modifiable settings. These settings include modifying the address resolution time to live (ttl) for each name contained in the ANT, and other settings like the ANT Name, Ticker, and an ANT Controller.
+Name Tokens have an owner, who can transfer the token and control its modifiable settings. These settings include record targets, address-resolution TTL values, the ANT name and ticker, and controller permissions.
## Ownership and Control
-The controller can only manage the ANT and set and update records, name, and the ticker, but cannot transfer the ANT. Note that ANTs are initially created in accordance with network standards by an end user who then has the ability to transfer its ownership or assign a controller as they see fit.
+Controllers can manage records, name, and ticker settings, but cannot transfer the ANT or assign additional controllers.
-Owners of names should ensure their ANT supports evolve ability if future modifications are desired. Loss of a private key for a permanently purchased name can result in the name being "bricked".
+ANTs are minted in accordance with network standards by an end user who can transfer ownership or assign controllers as needed. Because ANT logic lives in the `ario-ant` program rather than inside each individual token, protocol-level updates can apply consistently across ANTs.
-### Under_name Ownership
+When an ANT is transferred through a marketplace outside the ar.io app, the `ario-ant` program reconciles ownership on the next interaction and clears previously assigned controllers so the new owner has clean control.
-Undernames can have an `owner` set on them. This owner is empowered to set that undername as their primary name, can remove that undername as their primary name, and has full control over that Undername's metadata, such as:
+Loss of a private key for a permanently purchased name can result in the name being inaccessible.
-- Transaction Id - the data the record resolves to.
-- TTL Seconds - the Time To Live in seconds the data is cached for by clients.
+### Undername Ownership
+
+Undernames can have an `owner` set on them. This owner is empowered to set that undername as their primary name, remove that undername as their primary name, and control that undername's metadata, such as:
+
+- Transaction ID - the data the record resolves to.
+- TTL seconds - the time to live in seconds the data is cached for by clients.
- Owner - the owner of the record.
- Description - the description of the record.
- Display Name - the display name for the owner of the record.
@@ -44,7 +48,7 @@ The table below indicates some of the possible interactions with the ArNS regist
| Transfer ownership | ✔ | | | |
| Add / remove controllers | ✔ | | | |
| Approve/Remove Primary name | ✔ | | ✔ | |
-| Reassign name to new ANT process | ✔ | | | |
+| Reassign name to new ANT | ✔ | | | |
| Return a permanent name | ✔ | | | |
| Set records (pointers, record metadata) | ✔ | ✔ | ✔ | |
| Update records, name, ticker | ✔ | ✔ | | |
@@ -54,15 +58,17 @@ The table below indicates some of the possible interactions with the ArNS regist
| Increase undernames | ✔ | ✔ | ✔ | ✔ |
| Convert lease to permanent | ✔ | ✔ | ✔ | ✔ |
-## Under_names
+## Undernames
-ANT owners and controllers can configure multiple subdomains for their registered ArNS name known as "under_names" or more easily written "undernames". These undernames are assigned individually at the time of registration or can be added on to any registered name at any time.
+ANT owners and controllers can configure subdomains for their registered ArNS name, known as undernames. These undernames are assigned at registration or added later.
-Under*names use an underscore "*" in place of a more typically used dot "." to separate the subdomain from the main ArNS domain.
+Undernames use an underscore (`_`) in place of a dot (`.`) to separate the subdomain from the main ArNS domain.
## Secondary Markets
-Secondary markets could be created by ecosystem partners that facilitate the trading of Name Tokens. Additionally, tertiary markets could be created that support the leasing of these friendly names to other users. Such markets, if any, would be created by third parties unrelated to and outside of the scope of this paper or control of the Foundation.
+Since ANTs are standard Metaplex Core NFTs, they are tradeable on any compatible NFT marketplace, including **Tensor** and **Magic Eden**. When an ANT is sold on a marketplace, lazy reconciliation clears the existing controllers on the next write operation, ensuring the new owner gets clean control.
+
+Additionally, tertiary markets could be created that support the leasing of these friendly names to other users.
## Next Steps
diff --git a/content/learn/arns/index.mdx b/content/learn/arns/index.mdx
index a059d31a2..e6081d500 100644
--- a/content/learn/arns/index.mdx
+++ b/content/learn/arns/index.mdx
@@ -1,6 +1,6 @@
---
-title: "Arweave Name System (ArNS)"
-description: "ArNS is a censorship-resistant naming system stored on Arweave, powered by ARIO tokens, enabled through ar.io gateway domains, and used to connect friendly domain names to permaweb apps, web pages, data, and identities."
+title: "Ar.io Name System (ArNS)"
+description: "ArNS is a censorship-resistant naming system powered by ARIO and ar.io gateways, connecting friendly names to permaweb apps, pages, data, and identities."
---
import { Card, Cards } from "fumadocs-ui/components/card";
@@ -8,9 +8,9 @@ import { Globe, Key, DollarSign, ShoppingCart } from "lucide-react";
## What is ArNS?
-Arweave URLs and transaction IDs are long, difficult to remember, and occasionally categorized as spam. The Arweave Name System (ArNS) aims to resolve these problems in a decentralized manner.
+Arweave URLs and transaction IDs are long, difficult to remember, and occasionally categorized as spam. The Ar.io Name System (ArNS) aims to resolve these problems in a decentralized manner.
-ArNS is a **censorship-resistant naming system** stored on Arweave, powered by [ARIO tokens](/learn/token), enabled through [ar.io gateway](/learn/gateways) domains, and used to connect friendly domain names to permaweb apps, web pages, data, and identities.
+ArNS is a **censorship-resistant naming system** powered by [ARIO tokens](/learn/token), enabled through [ar.io gateway](/learn/gateways) domains, and used to connect friendly domain names to permaweb apps, web pages, data, and identities.
It's an open, permissionless, domain name registrar that doesn't rely on a single TLD.
@@ -18,48 +18,27 @@ It's an open, permissionless, domain name registrar that doesn't rely on a singl
This system works similarly to traditional DNS services, where users can purchase a name in a registry and DNS Name servers resolve these names to IP addresses. The system is flexible and allows users to purchase names permanently or lease them for a defined duration based on their use case.
-With ArNS, the registry is stored permanently on Arweave via [AO](/glossary), making it immutable and globally resilient. This also means that apps and infrastructure cannot just read the latest state of the registry but can also check any point in time in the past, creating a "Wayback Machine" of permanent data.
+With ArNS, the registry is managed on Solana by the `ario-arns` program, making ownership and registration state globally verifiable. Names are controlled by Ar.io Name Tokens (ANTs), which point to Arweave transaction IDs so gateways can route friendly names to permanent data.
```mermaid
-graph TB
- subgraph "ar.io Smart Contract"
- Registry[ArNS Registry]
- Registry --> Name1[ardrive]
- Registry --> Name2[ao]
- Registry --> Name3[gateways]
- Registry --> NameN[...]
- end
-
- subgraph "Arweave Name Token"
- Name1 -.->|owned by| ANT1[Owner: 0x242424...
Record: @
Target: TxID_123]
- Name2 -.->|owned by| ANT2[Owner: Zjgamagh...
Record: @
Target: TxID_456]
- Name3 -.->|owned by| ANT3[Owner: Hboaalf...
Record: @
Target: TxID_789]
- end
-
- subgraph "Arweave"
- ANT1 -.->|points to| TX1[TxID_123
ArDrive App]
- ANT2 -.->|points to| TX2[TxID_456
Email App]
- ANT3 -.->|points to| TX3[TxID_789
Pages App]
- end
-
- style Registry fill:#f9f,stroke:#333,stroke-width:3px,color:#333
- style ANT1 fill:#b3d9ff,stroke:#333,stroke-width:2px,color:#333
- style ANT2 fill:#b3d9ff,stroke:#333,stroke-width:2px
- style ANT3 fill:#b3d9ff,stroke:#333,stroke-width:2px
- style TX1 fill:#bfb,stroke:#333,stroke-width:2px,color:#333
- style TX2 fill:#bfb,stroke:#333,stroke-width:2px,color:#333
- style TX3 fill:#bfb,stroke:#333,stroke-width:2px,color:#333
+graph TD
+ User[User requests friendly name] --> Gateway[ar.io Gateway]
+ Gateway --> Registry[ArNS Registry
ario-arns]
+ Registry --> ANT[Ar.io Name Token
Metaplex Core NFT]
+ ANT --> Target[Arweave Transaction ID]
+ Gateway --> Content[Permaweb app, page, or data]
+ Target --> Content
```
## Name Resolution
-Users can register a name, like `ardrive`, within the ArNS Registry. Before owning a name, they must create an Arweave Name Token (ANT), an AO Computer based token and open-source protocol used by ArNS to track the ownership and control over the name.
+Users can register a name, like `ardrive`, within the ArNS Registry. Ownership is represented by an Ar.io Name Token (ANT), a Metaplex Core NFT on Solana used by ArNS to track control over the name.
ANTs allow the owner to set a mutable pointer to any type of permaweb data, like a page, app or file, via its Arweave transaction ID.
-Each ar.io gateway acts as an ArNS Name resolver. They fetch the latest state of both the ArNS Registry and its associated ANTs from an AO compute unit (CU) and serve this information rapidly for apps and users.
+Each ar.io gateway acts as an ArNS name resolver. Gateways fetch the latest state of both the ArNS Registry and associated ANTs from Solana and use that state to route users to the right Arweave transaction.
-Ar.io gateways will also resolve that name as one of their own subdomains, e.g., `https://ardrive.arweave.net` and proxy all requests to the associated Arweave transaction ID. This means that ANTs work across all ar.io gateways that support them: `https://ardrive.ar-io.dev`, `https://ardrive.g8way.io/`, etc.
+Ar.io gateways resolve names as gateway subdomains, e.g., `https://ardrive.ar.io`, and proxy requests to the associated Arweave transaction ID. This means an ArNS name can work across ar.io gateways that support ArNS.
Users can easily reference these friendly names in their browsers, and other applications and infrastructure can build rich solutions on top of these ArNS primitives.
@@ -68,10 +47,10 @@ sequenceDiagram
participant User
participant Gateway as ar.io Gateway
participant Registry as ArNS Registry
- participant ANT as Arweave Name Token
+ participant ANT as Ar.io Name Token
participant Arweave
- User->>Gateway: Request ardrive.arweave.net
+ User->>Gateway: Request ardrive.ar.io
Gateway->>Registry: Query "ardrive" record
Registry-->>Gateway: Returns ANT address
Gateway->>ANT: Get target TxID
@@ -88,10 +67,9 @@ sequenceDiagram
- **Human-readable URLs** instead of complex transaction IDs
- **Censorship-resistant** and decentralized
-- **Permanent storage** on Arweave
+- **Permanent data routing** to Arweave transaction IDs
- **Cross-gateway compatibility** - works on all ar.io gateways
-- **Historical data access** - check any point in time
-- **Flexible ownership** - permanent or leased names
+- **Flexible ownership** - lease names for a defined period or buy them permanently
## Explore ArNS
@@ -103,7 +81,7 @@ sequenceDiagram
icon={
}
/>
}
@@ -117,7 +95,7 @@ sequenceDiagram
}
/>
diff --git a/content/learn/arns/meta.json b/content/learn/arns/meta.json
index a5a92bd54..c1b5d242f 100644
--- a/content/learn/arns/meta.json
+++ b/content/learn/arns/meta.json
@@ -1,5 +1,6 @@
{
- "title": "Arweave Name System (ArNS)",
- "pages": ["name-registration", "ants", "pricing-model"],
+ "title": "Ar.io Name System (ArNS)",
+ "icon": "Globe",
+ "pages": ["name-registration", "ants", "pricing-model", "returned-names"],
"defaultOpen": false
}
diff --git a/content/learn/arns/name-registration.mdx b/content/learn/arns/name-registration.mdx
index a5cf8ffc2..75da146bb 100644
--- a/content/learn/arns/name-registration.mdx
+++ b/content/learn/arns/name-registration.mdx
@@ -3,31 +3,31 @@ title: "Name Registration"
description: "Learn about registering ArNS names, including lease vs permanent options, validation rules, and the registration process"
---
-There are two different types of name registrations that can be utilized based upon the needs of the user:
+ArNS names can be registered as leases or permanent purchases, depending on how long the user needs the name and how much they want to commit up front.
## Registration Types
### Lease Registration
-A name may be **leased on a yearly basis**. A leased name can have its lease extended or renewed but only up to a maximum active lease of **five (5) years** at any time.
+A name may be **leased on a yearly basis**. Leases lower the barrier to entry, support temporary projects, and allow inactive names to eventually return to public availability.
### Permanent Registration (Permabuy)
-A name may be **purchased for an indefinite duration** with no expiration date.
+A name may be **purchased for an indefinite duration** with no expiration date. This is useful for long-lived apps, identities, and data references that should remain associated with a stable friendly name.
Registering a name requires spending ARIO tokens corresponding to the name's character length and purchase type.
## Name Registry
-The ArNS Registry is a list of all registered names and their associated ANT Process IDs. Key rules embedded within the smart contract include:
+The ArNS Registry is a list of registered names and their associated ANT mint addresses, managed by the `ario-arns` Solana program. Key rules embedded within the protocol include:
- **Genesis Prices**: Set within the contract as starting conditions
- **Dynamic Pricing**: Varies based on name length, purchase type (lease vs buy), lease duration, and current Demand Factor
-- **Name Records**: Include a pointer to the Arweave Name Token process identifier, lease end time (if applicable), and undername allocation
+- **Name Records**: Include a pointer to the Ar.io Name Token (ANT) mint address, lease end time (if applicable), and undername allocation
- **Reassignment**: Name registrations can be reassigned from one ANT to another
- **Lease Extension**: Anyone with available ARIO Tokens can extend any name's active lease
- **Lease to Permanent Buy**: Anyone with available ARIO Tokens can convert a name's lease to a permanent buy
-- **Undername Capacity**: Additional undername capacity can be purchased for any actively registered name
+- **Undername Capacity**: Additional undername capacity can be purchased for actively registered names
- **Name Removal**: Name records can only be removed from the registry if a lease expires, or a permanent name is returned to the protocol
## Name Validation Rules
@@ -38,19 +38,21 @@ All names registered must meet the following criteria:
2. **Dash placement**: Dashes cannot be leading or trailing characters
3. **Single character domains**: Dashes cannot be used in single character domains
4. **Length limits**: 1 character minimum, 51 characters maximum
-5. **Reserved names**: Cannot be an invalid name predesignated to prevent unintentional use/abuse such as `www`
+5. **43-character prohibition**: Names exactly 43 characters long are prohibited to prevent Arweave transaction ID collisions
+6. **Lowercase enforcement**: Names must be lowercase at submission
+7. **Reserved names**: Cannot be an invalid name predesignated to prevent unintentional use/abuse such as `www`
## Lease Management
### Lease Expirations
-When a lease term ends, there is a **grace period of two (2) weeks** where the lease can be renewed before it fully expires. If this grace period elapses, the name is considered expired and returns to the protocol for public registration. Once expired, a name's associated undername registrations and capacity also expire.
+When a lease term ends, there is a grace period where the lease can be renewed or converted to a permanent purchase before it fully expires. If this grace period elapses, the name is considered expired and returns to the protocol for public registration. Once expired, a name's associated undername registrations and capacity also expire.
-A recently expired name's registration shall be priced subject to the "Returned Name Premium" mechanics.
+A recently expired name enters a **Returned Name Dutch Auction**, where it starts at a premium and decays back toward standard pricing over time. Revenue from returned name purchases is split between the protocol and the previous owner.
### Lease to Permabuy Conversions
-An actively leased name may be converted to a permanent registration. The price for this conversion shall be treated as if it were a new permanent name purchase.
+An actively leased name may be converted to a permanent registration. The price for this conversion is treated as if it were a new permanent name purchase.
This functionality allows users to transition from leasing to permanent ownership based on changing needs and available resources. It generates additional protocol revenue through conversion fees, contributing to the ecosystem's financial health and reward system.
@@ -62,10 +64,14 @@ When a permanent name is returned, the name is subject to a "Returned Name Premi
## Primary Names
-The Arweave Name System (ArNS) supports the designation of a "Primary Name" for users, simplifying how Arweave addresses are displayed across applications. A Primary Name is a user-friendly alias that replaces complex wallet addresses, making interactions and profiles easier to manage and identify.
+The Ar.io Name System (ArNS) supports the designation of a "Primary Name" for users, simplifying how wallet addresses are displayed across applications. A Primary Name is a user-friendly alias that can replace complex wallet addresses, making interactions and profiles easier to manage and identify.
-Users can set one of their owned ArNS names as their Primary Name, subject to a small fee. This allows applications to use a single, human-readable identifier for a wallet, improving user experience across the network.
+Users can set one of their owned ArNS names as their Primary Name. The fee is equivalent to the cost of a single undername on a 51-character name of the same purchase type, adjusted by the current Demand Factor.
+
+Only one Primary Name can be set per wallet, and the same name cannot be the Primary Name for more than one wallet. The base name's ANT owner can remove any Primary Name set on one of its undernames.
+
+This allows applications to use a single, human-readable identifier for a wallet, improving user experience across the network.
## Next Steps
-Now that you understand name registration, learn about [Arweave Name Tokens (ANTs)](/learn/arns/ants) to see how ownership and control work, or explore the [Pricing Model](/learn/arns/pricing-model) to understand how costs are calculated.
+Now that you understand name registration, learn about [Ar.io Name Tokens (ANTs)](/learn/arns/ants) to see how ownership and control work, or explore the [Pricing Model](/learn/arns/pricing-model) to understand how costs are calculated.
diff --git a/content/learn/arns/pricing-model.mdx b/content/learn/arns/pricing-model.mdx
index 27add14ff..e1ac3d94c 100644
--- a/content/learn/arns/pricing-model.mdx
+++ b/content/learn/arns/pricing-model.mdx
@@ -7,198 +7,51 @@ import { Globe, Database, Code } from "lucide-react";
## Addressing Variable Market Conditions
-The future market landscape is unpredictable, and ar.io's smart contract is designed to be immutable, operating without governance or manual intervention. Using a pricing oracle to fix name prices relative to a stable currency is not viable due to the infancy of available solutions and reliance on external dependencies.
+The future market landscape is unpredictable, and ArNS is designed to adapt without relying on a centralized pricing oracle. Instead of fixing name prices to an external currency, the protocol adjusts pricing based on network activity and registration demand.
-To address these challenges, ArNS is self-contained and adaptive, with name prices reflecting network activity and market conditions over time.
+This keeps ArNS self-contained while still allowing name prices to respond to changing market conditions over time.
-To achieve this, ArNS incorporates:
+ArNS pricing is built from a few core ideas:
-1. A **dynamic pricing model** that adjusts fees using a "Demand Factor" based on ArNS purchase activity
-2. A **Returned Name Premium (RNP)** system that applies a timed, descending multiplier to registration prices for names that have recently expired or been returned to the protocol
+1. **Name length**: Shorter, more memorable names generally cost more.
+2. **Registration type**: Names can be leased for a defined period or purchased permanently.
+3. **Demand Factor**: A protocol multiplier adjusts prices based on recent ArNS activity.
+4. **Returned Name Premium (RNP)**: Recently expired or returned names re-enter the market through a descending premium window.
-This approach ensures that name valuations adapt to market conditions within the constraints of an immutable, maintenance-free smart contract framework.
+This approach lets ArNS remain predictable enough for users while still adapting to namespace demand.
-You can view current live pricing at [ArNS.app](https://arns.ar.io/#/prices) to see these formulas in action.
+You can view current live pricing at [arns.ar.io](https://arns.ar.io/#/prices) to see these formulas in action.
## Key Definitions
-- **Protocol Revenue:** Accumulated ARIO tokens from name registrations, lease extensions, and under_name sales
-- **Period (P):** The time unit for DF adjustments, equivalent to one (1) day, denoted in milliseconds
-- **n:** The current period indicator
-- **Price:** The cost for permabuy or lease of a name
-- **Under_names:** Subdomain equivalents, denoted by an underscore "\_" prefixing the base domain
+- **Demand Factor:** A protocol multiplier that adjusts prices based on recent registration activity.
+- **Base Fee:** The starting price for a name before dynamic adjustments.
+- **Lease:** A time-limited registration.
+- **Permabuy:** A permanent registration.
+- **Undername:** A subdomain-style record written with an underscore (`_`) instead of a dot (`.`).
+- **Protocol Revenue:** ARIO collected from ArNS actions, such as name registrations, lease extensions, and undername purchases.
## Dynamic Pricing Model
-ArNS employs an adaptive pricing model to balance market demand with pricing fairness for name registration within the network. This model integrates static and dynamic elements, adjusting prices based on name length and purchase options like leasing, permanent acquisition, and undername amounts.
+ArNS uses an adaptive model to balance name availability, demand, and long-term sustainability. Prices are influenced by name length, whether the name is leased or bought permanently, undername capacity, and the current Demand Factor.
-### Core Pricing Components
+The Demand Factor changes over time based on protocol activity. When demand is high, it can increase prices; when demand is low, it can decrease prices. If demand remains low for long enough, the protocol can step base fees downward so names stay accessible.
-#### Base Registration Fee (BRF)
-
-The fundamental price for names, varying by character length, adjusted periodically.
-
-#### Genesis Registration Fee (GRF)
-
-The starting price for name registrations varies by character length. This is superseded by Base Registration Fees as the protocol evolves.
-
-**Table: Genesis Registration Fees**
-
-| Name Length | Fee (ARIO) |
-| ----------- | ---------- |
-| 1 | 1,000,000 |
-| 2 | 200,000 |
-| 3 | 20,000 |
-| 4 | 10,000 |
-| 5 | 2,500 |
-| 6 | 1,500 |
-| 7 | 800 |
-| 8 | 500 |
-| 9 | 400 |
-| 10 | 350 |
-| 11 | 300 |
-| 12 | 250 |
-| 13-51 | 200 |
-
-#### Demand Factor (DF)
-
-A global price multiplier, reflecting namespace demand, adjusted each period based on revenue trends.
-
-**DF Mechanics:**
-
-- **Intent:** The Demand Factor adjusts based on protocol revenue comparison to the Revenue Moving Average (RMA)
-- **Increase DF:** When recent revenue is higher than or equal to (but non-zero) the RMA, the DF increases by 5.0%
-- **Decrease DF:** When recent revenue is less than the RMA or both are zero, the DF decreases by 1.5%
-- **Maximum DF Value:** Unbounded
-- **Minimum DF Value:** 0.5
-- **Starting Demand Factor:** 1 (initial value at network launch)
-
-#### Revenue Moving Average (RMA)
-
-The average of protocol revenue from the past seven (7) periods.
-
-### Pricing Formulas
-
-#### Adjusted Registration Fee (ARF)
-
-```math
-ARF = BRF × DF
-```
-
-#### Annual Fee
-
-```math
-Annual ~Fee = ARF × 20%
-```
-
-#### Lease Pricing
-
-- **Lease Registration Price:**
-
-```math
-Lease ~Price = ARF + (Annual ~Fee × Years)
-```
-
-- **Lease Extension/Renewal Price:**
-
-```math
-Lease ~Renewal ~Price = Annual ~Fee × Years (max 5 years)
-```
-
-- **Grace period:** Two (2) weeks
-
-#### Permanent Purchases
-
-- **Permabuy Price:**
-
-```math
-Permabuy ~Price = ARF + (Annual Fee × 20 years)
-```
-
-- **Lease to Permabuy Price:** Same as above
-
-#### Under Name Fees
-
-- **Initial Allocation:** 10 `under_names` are included with each name registration
-- **For Leases:**
-
-```math
-Lease ~Under ~Name ~Fee = BRF × DF × 0.1%
-```
-
-- **For Permabuys:**
-
-```math
-Permabuy ~Under ~Name ~Fee = BRF × DF × 0.5%
-```
-
-#### Primary Name Fee
-
-Set or change primary name: The fee is equal to the associated fee for a single `under_name` purchase of a 51-character name of equivalent purchase type to the new primary name, regardless of the new primary name's length.
-
-### Step Pricing Mechanics
-
-- Synchronizes BRF (Base Rate Factor) with ARF (Adjusted Rate Factor) after seven (7) consecutive periods at the minimum DF value
-- Resets DF to 1 following a step pricing adjustment
+For exact costs, users should rely on the live ArNS app or SDK cost simulation rather than copying formulas into their own applications.
## Returned Name Premiums (RNP)
-ArNS applies a **Returned Name Premium (RNP)** to names that re-enter the market after expiration or permanent return. This premium starts at a maximum value and decreases linearly over a predefined window, ensuring fair and transparent pricing for re-registered names.
-
-### RNP Mechanics
-
-#### Intent
-
-The premium starts at its maximum and decreases linearly until the name is purchased. If the name is not purchased before the premium window closes, it reverts to standard pricing and is no longer classified as "recently returned."
-
-#### RNP Window
+ArNS applies a **Returned Name Premium (RNP)** to names that re-enter the market after expiration or permanent return. The premium starts high and decreases over a return window until the name reaches standard pricing again.
-- **Duration:** Fourteen (14) periods
+Returned name purchases split proceeds between the protocol balance and the previous owner. This discourages instant name sniping after expiry and gives owners a reason to release names they no longer need.
-#### Returned Name Premium Formula
-
-The premium multiplier follows a linearly declining function:
-
-```math
-RNP = 50 - (49 / 14) × t
-```
-
-Where:
-
-- **RNP:** The Returned Name Premium multiplier applied to the purchased name price
-- **t:** Amount of time (or time-intervals) elapsed since the start of the return window
-
-#### RNP Registration Price
-
-```math
-Price = RNP × (Lease~Or~Permabuy) ~Registration~ Price
-```
-
-#### Permanent Name Return Proceeds Split
-
-- **50%** goes to the returning name owner
-- **50%** goes to the protocol balance
-
-The RNP multiplier is applied to the registration price of both permanently purchased and leased names.
+For more detail, see [Returned Names](/learn/arns/returned-names).
## Gateway Operator ArNS Discount
-Gateway operators who demonstrate consistent, healthy participation in the network are eligible for a **20% discount** on certain ArNS interactions.
-
-### Qualification Requirements
-
-To qualify for the discount:
-
-- The gateway must maintain a "Gateway Performance Ratio Weight" (GPRW) of **0.9 or higher**
-- The gateway must have a "Tenure Weight" (TW) of **1.0 or greater**
-- A gateway marked as "Leaving" shall not be eligible for this discount
-
-### Eligible Discounted Interactions
+Gateway operators who demonstrate consistent, healthy participation in the network may be eligible for discounted ArNS interactions. This creates another incentive for gateways to provide reliable service while supporting ArNS usage.
-- Purchasing a name
-- Extending a lease
-- Upgrading a lease to permabuy
-- Increasing undernames capacity
+Discount eligibility requires a **Gateway Performance Ratio Weight (GPRW) of 0.9** and a **Tenure Weight (TW) of 1.0**. Eligible operators receive a **20% discount** on new ArNS name registrations, lease extensions, lease upgrades, and undername purchases.
## Next Steps
@@ -209,15 +62,15 @@ Congratulations! You now understand the complete ArNS pricing system. Ready to g
See current ArNS pricing in real-time with the live pricing chart.
-
}>
- Visit ArNS.app to register your first name and explore the pricing in action.
+
}>
+ Visit arns.ar.io to register your first name and explore the pricing in action.
}>
Learn about ar.io gateways and how they integrate with ArNS.
-
}>
+
}>
Start building applications that leverage ArNS for decentralized naming.
diff --git a/content/learn/arns/returned-names.mdx b/content/learn/arns/returned-names.mdx
new file mode 100644
index 000000000..93402096d
--- /dev/null
+++ b/content/learn/arns/returned-names.mdx
@@ -0,0 +1,75 @@
+---
+title: 'Returned Names'
+description: 'How returned ArNS names are repriced through a Dutch auction mechanism'
+---
+
+## Overview
+
+When an ArNS name expires or is voluntarily returned to the protocol, it enters a **Returned Name Dutch Auction** before becoming available for standard registration. This mechanism prevents name squatting at expiry and provides fair pricing through a time-decaying premium.
+
+## Dutch Auction Mechanics
+
+Returned names start at a high premium and decay to the base price over a return window:
+
+- **Starting price**: premium above the base registration price
+- **Ending price**: standard registration price
+- **Decay**: decreases over time until standard pricing resumes
+
+```mermaid
+graph LR
+ A[Name Expired
or Released] --> B[Dutch Auction
Starts at 50x]
+ B --> C[Price Decays
Over Time]
+ C --> D[Reaches
Standard Price]
+ D --> E[Standard
Registration]
+```
+
+## Revenue Split
+
+When a returned name is purchased during the Dutch auction:
+
+- **50%** goes to the **protocol balance** (funds epoch rewards)
+- **50%** goes to the **previous owner** (the ANT holder at the time of return)
+
+This incentivizes name owners to voluntarily release names they no longer need, since they receive half the resale value.
+
+## How Names Enter the Returned Pool
+
+### Lease Expiration
+When a leased name's term ends and the grace period elapses without renewal or conversion to permanent ownership, the name enters the returned pool.
+
+### Voluntary Release
+Permanent name owners can voluntarily release their name back to the protocol. This places the name in the returned pool.
+
+## Lifecycle
+
+| Phase | Duration | Price | Action |
+|-------|----------|-------|--------|
+| **Active lease** | As registered | N/A | Name is in use |
+| **Grace period** | After expiry | N/A | Owner can renew or convert |
+| **Dutch auction** | Return window | Premium → standard price | Anyone can purchase |
+| **Standard registration** | Indefinite | Base price | Normal ArNS purchase |
+
+## Querying Returned Names
+
+Use the SDK to check available returned names and their current auction price:
+
+```typescript
+const ario = ARIO.mainnet();
+
+// Get all active returned names
+const returnedNames = await ario.getArNSReturnedNames({
+ limit: 100,
+ sortBy: 'endTimestamp',
+ sortOrder: 'asc',
+});
+
+// Get a specific returned name
+const name = await ario.getArNSReturnedName({ name: 'example' });
+
+// Check current cost (includes auction premium)
+const cost = await ario.getTokenCost({
+ intent: 'Buy-Name',
+ name: 'example',
+ type: 'permabuy',
+});
+```
diff --git a/content/learn/gateways/architecture.mdx b/content/learn/gateways/architecture.mdx
index 5fee9c446..54007c770 100644
--- a/content/learn/gateways/architecture.mdx
+++ b/content/learn/gateways/architecture.mdx
@@ -5,7 +5,7 @@ description: "Learn about the technical architecture of ar.io gateways, their co
import { Database, Shield, Layers, Server } from 'lucide-react';
-Ar.io gateways are sophisticated data access layers built on top of the Arweave network. They transform the raw Arweave blockchain into a performant, reliable, and developer-friendly platform for storing and retrieving data. Gateways act as bridges between applications and the permanent storage capabilities of Arweave.
+Ar.io gateways are data access layers built on top of Arweave. They make permanent data easier to retrieve, cache, index, and serve through standard web interfaces.
```mermaid
graph TB
@@ -87,14 +87,14 @@ Ar.io gateways are built using modern, scalable technologies designed for high-p
Several important design decisions shape how ar.io gateways operate:
### Data Retrieval Strategy
-Ar.io gateways use a sophisticated **hierarchical fallback system** for data retrieval:
+Ar.io gateways use a **hierarchical fallback system** for data retrieval:
1. **Trusted gateways**: Prioritize data from verified, high-performance peers
2. **Ar.io network**: Leverage the broader network of ar.io gateways
3. **Chunks data items**: Reconstruct data from individual chunks when needed
4. **Transaction data**: Fall back to raw Arweave transaction data
-This approach ensures data availability while optimizing for speed and reliability.
+This approach improves availability while optimizing for speed and reliability.
### Verification and Trust Model
- **Multi-level cryptographic verification**: Data integrity is verified at multiple points
@@ -102,12 +102,16 @@ This approach ensures data availability while optimizing for speed and reliabili
- **Self-healing mechanisms**: Automatic recovery and re-verification of corrupted data
- **Verification headers**: HTTP headers indicate the verification status of returned data
+### Serving Capabilities
+
+Gateways expose a serving layer for applications and end users. This layer includes byte-range requests, signed and verifiable responses, x402 paid access, peer routing, and content moderation hooks. These capabilities let operators tune how data is delivered while preserving verifiability and local operator choice.
+
### Worker Specialization
Different background workers handle specific responsibilities:
-- **Block synchronization workers**: Keep the gateway synchronized with Arweave blocks
-- **Bundle processing workers**: Handle Layer 2 bundled data items (ANS-104)
-- **Data verification workers**: Continuously verify stored data integrity
+- **Block synchronization workers**: Keep the gateway aligned with Arweave blocks
+- **Bundle processing workers**: Extract and index ANS-104 data items
+- **Data verification workers**: Check cached data integrity
- **Maintenance workers**: Perform cleanup and optimization tasks
## Scalability and Configuration
@@ -119,7 +123,7 @@ Gateway services can be independently configured or disabled based on operator n
- **Data serving**: Serve cached data to applications
- **Data indexing**: Index and process new Arweave data
- **Bundle processing**: Handle Layer 2 bundled transactions
-- **ArNS routing**: Provide Arweave Name System resolution
+- **ArNS routing**: Provide Ar.io Name System resolution
## Core Philosophy: Builder Independence
@@ -134,7 +138,7 @@ Operators maintain complete control through **[Data Retrieval](/learn/gateways/d
### Network Resilience
The modular design creates a resilient ecosystem where distributed infrastructure and customizable trust models prevent single points of failure.
-This architecture ensures that builders can create powerful applications on Arweave while maintaining independence from any centralized infrastructure or service provider.
+This architecture helps builders use Arweave without depending on a single infrastructure provider.
## Explore Gateway Capabilities
diff --git a/content/learn/gateways/data-retrieval.mdx b/content/learn/gateways/data-retrieval.mdx
index 94641bc00..04d55dd2f 100644
--- a/content/learn/gateways/data-retrieval.mdx
+++ b/content/learn/gateways/data-retrieval.mdx
@@ -5,7 +5,7 @@ description: "How ar.io gateways retrieve and share data from multiple sources i
import { Shield, Cpu, Globe, Settings } from 'lucide-react';
-Ar.io gateways use a sophisticated multi-tier architecture to retrieve and serve Arweave data. This system ensures high availability, fast response times, and data integrity by leveraging multiple data sources with automatic fallback mechanisms.
+Ar.io gateways retrieve and serve Arweave data from multiple sources. They prefer fast local or trusted sources when available, then fall back to broader network peers, chunks, or Arweave nodes as needed.
## How Gateways Retrieve Data
@@ -37,7 +37,7 @@ graph TD
classDef source fill:#2563eb,stroke:#1d4ed8,stroke-width:2px,color:#fff
classDef process fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
- class TRUSTED,NETWORK,CHUNKS,TXDATA source
+ class TRUSTED,NETWORK,CHUNKS,ARWEAVE source
class VALIDATE,SERVE,STORE process
```
@@ -48,14 +48,14 @@ Ar.io gateways can retrieve data from multiple sources, each with different char
### 1. Trusted Gateways
- **Purpose**: Peer-to-peer data sharing between verified ar.io gateways
- **Benefits**: Distributed redundancy, load balancing, network resilience
-- **Trust Mechanism**: Performance-based trust scores and reciprocity monitoring
-- **Selection**: Prioritized based on established trust relationships
+- **Trust Mechanism**: Operator-defined trust settings, observed performance, and reciprocity
+- **Selection**: Prioritized based on local gateway configuration
### 2. ar.io (Untrusted Peers)
- **Purpose**: Broader network of ar.io gateways without established trust
- **Benefits**: Geographic distribution, expanded data availability
-- **Selection**: Weighted random selection based on performance metrics
-- **Validation**: Enhanced verification required due to untrusted nature
+- **Selection**: Chosen based on availability, configuration, and routing strategy
+- **Validation**: Verification is important because the peer may not be trusted
### 3. Chunk Assembly
- **Purpose**: Direct reconstruction from Arweave chunks via known offsets
@@ -92,7 +92,7 @@ Used specifically for unbundling and verification processes:
## Trust and Validation
### Peer Trust Management
-Gateways maintain sophisticated trust relationships:
+Gateways can maintain trust relationships with peer gateways:
```mermaid
graph TD
@@ -147,7 +147,7 @@ Every piece of retrieved data undergoes validation:
---
-The data retrieval system is fundamental to ar.io's mission of providing reliable, performant access to the permaweb. This sophisticated architecture ensures that Arweave's permanent data remains accessible through a resilient, distributed gateway network.
+The data retrieval system is central to ar.io's mission of providing reliable, performant access to the permaweb. Multiple retrieval paths help keep permanent data accessible through a distributed gateway network.
## Related Gateway Concepts
diff --git a/content/learn/gateways/data-verification.mdx b/content/learn/gateways/data-verification.mdx
index 5a46004d4..9ecdfe298 100644
--- a/content/learn/gateways/data-verification.mdx
+++ b/content/learn/gateways/data-verification.mdx
@@ -5,11 +5,13 @@ description: "How ar.io gateways ensure data integrity by verifying chunks are c
import { Database, Cpu, Server, Cog } from 'lucide-react';
-Ar.io gateways continuously verify that data chunks are correctly stored and retrievable from Arweave. This ensures users receive authentic, uncorrupted data with cryptographic proof of integrity. The verification system is what makes ar.io gateways trustworthy data providers for the permaweb.
+Ar.io gateways verify that retrieved and cached data matches what was committed to Arweave. Verification helps users receive authentic, uncorrupted data without trusting a single gateway operator.
+
+Gateway data verification is one layer of ar.io's broader verification architecture. For how gateway verification composes with signed response claims, client-side verification, and OIP accountability, see [Verification and Accountability](/learn/verification).
## How Gateways Verify Data
-Data verification is an ongoing process that uses Merkle tree cryptography to provide mathematical proof of data integrity. The process involves multiple specialized components working together to ensure cached data matches what's stored on Arweave:
+Data verification uses Arweave data roots, hashes, and Merkle proofs to check that cached data matches what was originally stored. A gateway can verify data before serving it or re-import data when verification fails:
```mermaid
sequenceDiagram
@@ -59,7 +61,7 @@ sequenceDiagram
**The Verification Workflow:**
-Gateways achieve verification through a systematic five-phase process orchestrated by the DataVerificationWorker. This process ensures that every piece of cached data cryptographically matches its original form on Arweave, providing mathematical proof of integrity before serving data to users.
+At a high level, verification moves through discovery, retrieval, cryptographic computation, comparison, and recovery:
**1. Discovery Phase**
- Periodically scan for unverified data items
@@ -92,7 +94,7 @@ Ar.io gateways handle different types of data verification based on the data's o
### Transaction Data Verification
For individual Arweave transactions:
-- **Direct root validation** against transaction data roots stored on-chain
+- **Direct root validation** against transaction data roots stored onchain
- **Complete data reconstruction** from chunks to ensure availability
- **Cryptographic proof** that data matches what was originally stored
@@ -116,12 +118,10 @@ At the most granular level:
### Cryptographic Trust Foundation
- **Mathematical Proof**: Merkle tree cryptography provides irrefutable proof of data integrity
- **Independent Validation**: Multiple gateways verify the same data independently
-- **Network Consensus**: Distributed verification creates trust without central authority
### Data Integrity Guarantees
- **Tamper Detection**: Any alteration to data is immediately detectable
- **Corruption Recovery**: Automatic healing of corrupted data through re-import
-- **Permanent Storage Validation**: Ensures Arweave's permanence promise is maintained
### Gateway Reliability
- **Continuous Monitoring**: Ongoing verification catches issues before users encounter them
diff --git a/content/learn/gateways/gateway-registry.mdx b/content/learn/gateways/gateway-registry.mdx
index 9aee9e22e..f723a3205 100644
--- a/content/learn/gateways/gateway-registry.mdx
+++ b/content/learn/gateways/gateway-registry.mdx
@@ -1,89 +1,87 @@
---
title: "Gateway Registry"
-description: "Ar.io consists of ar.io gateway nodes, which are identified by their registered Arweave wallet addresses and either their IP addresses or hostnames, as stored in the network"
+description: "How ar.io gateways register, publish metadata, and participate in the network."
---
-import { Network, Target, Shield, Settings } from 'lucide-react';
+import { Network, Target, Shield, Settings } from "lucide-react";
## Overview
-Ar.io consists of [ar.io gateway nodes](/learn/what-is-ario), which are identified by their registered Arweave wallet addresses and either their IP addresses or hostnames, as stored in the network's [smart contract](/learn/token) Gateway Address Registry (GAR).
+The Gateway Address Registry (GAR) is the public registry of ar.io gateways. It records which gateways have joined the network, how they can be reached, and the metadata applications need to discover and evaluate them.
-Any gateway operator that wishes to join ar.io must register their node in the ar.io smart contract's Gateway Address Registry. Registration involves staking a minimum amount of ARIO tokens and providing additional metadata describing the gateway service offered.
-
-These nodes adhere to ar.io's protocols, creating a collaborative environment of gateway nodes that vary in scale and specialization. The network promotes a fundamental level of service quality and trust minimization among its participants.
+Gateway registry state is maintained by the ar.io Solana programs. Registered gateways are identified by Solana addresses and publish service information such as hostname, protocol settings, staking state, and operator-provided metadata.
- The gateways.ar.io portal displays all gateways currently in the network, showing their stakes, performance scores, and operational metrics
+ The gateways.ar.io portal displays gateways currently in the network, including stake, performance, and operational metadata.
-### Benefits of Joining the Network
+## Joining the Registry
-Being part of the network grants ar.io gateways an array of advantages:
-- Simplified advertising of services and discovery by end users via the Gateway Address Registry
-- More rapid bootstrapping of key gateway operational data due to prioritized data request fulfillment among gateways joined to the network
-- Sharing of data processing results
-- Auditability and transparency through the use of AGPL-3 licenses, which mandate public disclosure of any software changes, thereby reinforcing the network's integrity and reliability
-- Improved network reliability and performance through an incentive protocol, which uses a system of evaluations and rewards to encourage high-quality service from gateways
-- Eligibility to accept delegated staking improving a gateway's discoverability and reward opportunities
-- **Eligibility to receive distributions from the protocol balance** - Gateways that have joined the network are eligible to receive token distributions based on their performance and contributions to the network
+To join the ar.io network, a gateway operator registers their gateway and locks ARIO as operator stake. Registration connects the gateway's public endpoint, operator address, observer address, and service metadata to the onchain registry.
-### How the GAR Works
+Once registered, a gateway can become eligible for network incentives, delegation, and observation through OIP. Gateway operators also need enough SOL to pay Solana transaction fees for network interactions.
-After joining the network, the operator's gateway can be easily discovered by permaweb apps, its health can be observed, and it can participate in data sharing protocols. A gateway becomes eligible to participate in the network's incentive protocol in the epoch following the one they joined in.
+The registry has a maximum capacity of **3,000 gateways**. Each gateway requires a **20,000 ARIO** minimum network-join stake, and each gateway can have up to **10,000** unique delegated stakers.
-The GAR advertises the specific attributes of each gateway including its stake, delegates, settings and services. This enables permaweb apps and users to discover which gateways are currently available and meet their needs. Apps that read the GAR can sort and filter it using the gateway metadata, for example, ranking gateways with the highest stake, reward performance, or feature set at the top of the list. This allows users to prefer the higher staked, more rewarded gateways with certain capabilities over lower staked, less rewarded gateways.
+## What the Registry Enables
-## Token Incentives and Network Monitoring
+### Discovery
-The ar.io network uses a sophisticated incentive system to ensure gateway quality and reliability:
+Apps, users, and other gateways can use the registry to find gateways by endpoint, service metadata, stake, observed performance, and supported capabilities.
-- **Token Incentives**: Learn more about how gateways earn rewards and participate in the network economy in the [Token section](/learn/token/)
-- **Observer Protocol**: The network employs an Observer system that monitors gateway performance and ensures quality of service. Learn more about the [Observer & Incentive Protocol](/learn/oip) and how it maintains network integrity
+### Incentive Participation
-## Recap
+The registry connects gateway identity to staking, delegated stake, performance history, and reward eligibility. OIP uses this information to evaluate gateways and distribute rewards.
+
+### Network Transparency
+
+Gateway information is publicly visible through Solana state and network tooling such as [gateways.ar.io](https://gateways.ar.io). This makes participation, performance, and configuration easier to inspect.
-The Gateway Registry is the foundation of the ar.io network's decentralized infrastructure. Key takeaways:
+### Operator Choice
-- **Network Participation**: Gateways must register and stake ARIO tokens to join the network
-- **Protocol Distributions**: Registered gateways are eligible to receive token distributions from the protocol balance
-- **Observer Monitoring**: The network employs an [Observer and Incentives Protocol](/learn/oip) that monitors gateway performance and ensures quality of service
-- **Staking & Rewards**: Gateways earn rewards based on performance through a sophisticated [staking system](/learn/token/staking) that includes delegation opportunities
-- **Discoverability**: The GAR enables apps and users to find suitable gateways based on their needs
-- **Performance-Based Selection**: Gateway metadata allows for intelligent routing based on stake, performance, and capabilities
-- **Transparent Ecosystem**: All gateway information is publicly accessible through the smart contract and at gateways.ar.io
+Gateways can specialize. Some may focus on fast public access, some on indexing, some on private infrastructure, some on paid access, and some on specific moderation or compliance policies.
+
+## Relationship to OIP
+
+The registry is the set of gateways that OIP can observe and evaluate. Registered gateways are periodically checked for availability, correctness, and ArNS resolution behavior. Reliable gateways can earn rewards, while gateways that repeatedly fail can lose eligibility and eventually be removed through pruning.
+
+## Recap
-By joining the network, gateways become part of a collaborative ecosystem that rewards quality service and ensures reliable access to the permaweb.
+- The Gateway Address Registry is the public source of network gateway metadata.
+- Gateways join by registering service details and locking operator stake.
+- Registered gateways can participate in OIP, receive delegations, and become eligible for rewards.
+- Apps can use registry data to discover, filter, and route through gateways.
+- Poorly performing gateways can be pruned from the network after sustained failure.
## Explore the Gateway Ecosystem
- }
/>
- }
/>
- }
/>
- }
/>
diff --git a/content/learn/gateways/index.mdx b/content/learn/gateways/index.mdx
index ffb720591..7bf4fb7f6 100644
--- a/content/learn/gateways/index.mdx
+++ b/content/learn/gateways/index.mdx
@@ -1,105 +1,80 @@
---
title: "ar.io Gateways"
-description: "Ar.io gateways bridge the Arweave network and applications, providing fast, reliable access to permanent data through specialized infrastructure."
+description: "Ar.io gateways provide fast, reliable access to permanent Arweave data through decentralized infrastructure."
---
import { Card, Cards } from "fumadocs-ui/components/card";
import { Building, Download, Shield, Server, CreditCard } from "lucide-react";
-## What Are ar.io Gateways?
+## What are Gateways?
-Ar.io gateways are specialized infrastructure nodes that serve as bridges between the Arweave network and applications. They transform raw Arweave blockchain data into a fast, reliable, and developer-friendly platform for storing and retrieving permanent data.
+Ar.io gateways are infrastructure nodes that make Arweave data easy to access from web apps, APIs, and users. They retrieve data from Arweave, cache and index it, resolve ArNS names, and expose standard HTTP interfaces for the permaweb.
-## Core Responsibilities
-
-Ar.io gateways handle three fundamental responsibilities:
-
-### Data Writing & Proxying
-
-- **Transaction relay**: Forward transaction headers to Arweave miners for mempool inclusion
-- **Chunk distribution**: Proxy data chunks to Arweave nodes for storage and replication
-- **Bundle processing**: Receive and bundle ANS-104 data items into base layer transactions
-
-### Data Retrieval & Serving
-
-- **Fast access**: Serve cached data with optimized performance and reliability
-- **Multi-source fallback**: Retrieve data from trusted gateways, network peers, or directly from Arweave
-- **Content delivery**: Stream complete transactions, individual chunks, or bundled data items
+Gateways do not replace Arweave. Arweave provides permanent storage and data availability guarantees; gateways make that data fast, discoverable, and practical to use.
-### Data Discovery & Indexing
-
-- **Structured queries**: Enable efficient searches across transactions, bundles, and wallet data
-- **Real-time indexing**: Process incoming data streams and maintain searchable databases
-- **ArNS routing**: Provide human-readable name resolution for Arweave content
-
-## Key Features
-
-### Modular Architecture
+## Core Responsibilities
-Gateways are built with interchangeable components that operators can customize:
+### Data Access
-- **Configurable services**: Enable or disable features based on specific needs
-- **Scalable storage**: From SQLite for small deployments to cloud databases for enterprise scale
-- **Flexible infrastructure**: Adaptable to different operational environments and requirements
+- **Retrieve permanent data** from Arweave, peer gateways, local cache, or chunk-level sources
+- **Serve content over HTTP** using familiar web patterns
+- **Optimize delivery** through caching, streaming, and source selection
-### Network Connectivity
+### Indexing and Discovery
-- **Decentralized network**: Connect to other ar.io gateways for data sharing and redundancy
-- **Trust-minimized access**: Cryptographically verify data integrity without relying on central authorities
-- **Performance optimization**: Intelligent caching and content delivery strategies
+- **Index transactions and bundled data items** so apps can search and retrieve content efficiently
+- **Resolve ArNS names** into the data records and routes they point to
+- **Expose gateway metadata** so users and applications can discover available infrastructure
-### Developer Experience
+### Network Participation
-- **HTTP APIs**: Standard web interfaces for all gateway functionality
-- **Monitoring & telemetry**: Built-in observability for operational insights
-- **Content moderation**: Configurable policies for community and compliance needs
+- **Register in the Gateway Address Registry** to become discoverable as an ar.io network gateway
+- **Stake ARIO** to participate in network incentives and signal operational commitment
+- **Participate in OIP** by being observed, reporting observations when selected, and earning rewards for reliable service
## What Gateways Are Not
-It's important to understand the boundaries of what ar.io gateways do and don't provide:
-
### Not Storage Providers
-- **Don't enforce Arweave protocol**: Gateways don't validate consensus or mining rules
-- **Don't guarantee permanence**: Storage permanence comes from Arweave itself, not gateways
-- **Don't replicate all data**: Gateways cache popular content but aren't full blockchain replicas
+- **They do not create Arweave permanence**: permanence comes from Arweave itself
+- **They do not need to store everything**: operators choose what to cache, index, and serve
+- **They do not control user data**: data ownership remains with the original publisher and underlying protocols
-### Not Compute Platforms
+### Not Application Compute
-- **Don't depend on AO**: Gateways operate independently of any compute layer
-- **Don't execute smart contracts**: Computation happens on AO or other platforms, not gateways
-- **Don't process application logic**: Gateways focus purely on data access and delivery
+- **They do not run protocol logic**: ar.io protocol state, staking, ArNS, and incentives are coordinated by Solana programs
+- **They do not process arbitrary app logic**: gateways focus on data access, indexing, routing, and delivery
-### Not Centralized Services
+### Not a Single Service
-- **Don't control data**: Content ownership and control remain with original creators
-- **Don't gate access**: Anyone can run a gateway and access Arweave data
-- **Don't create vendor lock-in**: Gateway APIs and protocols are open and interoperable
+- **Anyone can run one**: the gateway network is open to independent operators
+- **Apps can choose among gateways**: routing can consider availability, geography, performance, policy, and payment requirements
+- **Operators can specialize**: gateways may differ in scale, indexing choices, moderation policy, payment setup, and extensions
## Explore Gateways
}
/>
}
/>
}
/>
}
/>
diff --git a/content/learn/gateways/meta.json b/content/learn/gateways/meta.json
index 7472de369..31cfa7786 100644
--- a/content/learn/gateways/meta.json
+++ b/content/learn/gateways/meta.json
@@ -1,5 +1,6 @@
{
"title": "Gateways",
+ "icon": "Network",
"pages": [
"architecture",
"data-retrieval",
diff --git a/content/learn/meta.json b/content/learn/meta.json
index 7d4fad3f1..600196324 100644
--- a/content/learn/meta.json
+++ b/content/learn/meta.json
@@ -8,6 +8,7 @@
"(introduction)",
"cloud",
"gateways",
+ "verification",
"oip",
"arns",
"wayfinder",
diff --git a/content/learn/oip/epoch-pipeline.mdx b/content/learn/oip/epoch-pipeline.mdx
new file mode 100644
index 000000000..3cf4bece2
--- /dev/null
+++ b/content/learn/oip/epoch-pipeline.mdx
@@ -0,0 +1,102 @@
+---
+title: 'Epoch Pipeline'
+description: 'The 6-step permissionless epoch pipeline for observation, reward calculation, and distribution on Solana'
+---
+
+## Overview
+
+On Solana, the ar.io epoch lifecycle is broken into six discrete, permissionless steps. Each step is a separate instruction that can be executed by anyone.
+
+All steps are **idempotent** (safe to run multiple times) and **permissionless** (anyone can crank them). This design ensures the protocol cannot be halted by a single point of failure.
+
+## Pipeline Steps
+
+```mermaid
+graph LR
+ A[create_epoch] --> B[tally_weights]
+ B --> C[prescribe_epoch]
+ C --> D[save_observations]
+ D --> E[distribute_epoch]
+ E --> F[close_epoch]
+```
+
+### 1. create_epoch
+
+**Initializes the epoch account and computes the reward rate.**
+
+- Creates the epoch account
+- Computes the epoch reward allocation from the protocol balance
+
+### 2. tally_weights
+
+**Batched computation of gateway weights for observer selection.**
+
+- Computes composite weights for gateways:
+ - **Stake weight**: Based on total stake (operator + delegated)
+ - **Tenure weight**: Based on how long the gateway has been in the network
+ - **Gateway performance**: Based on pass rate across recent epochs
+ - **Observer performance**: Based on observation submission history
+- Batches work so large gateway sets can be processed safely on Solana
+
+### 3. prescribe_epoch
+
+**Selects observers and prescribed ArNS names via weighted roulette.**
+
+- Selects observers using weighted random selection
+- Selects prescribed ArNS names that observers use as common test targets
+
+### 4. save_observations
+
+**Observers submit their pass/fail observation reports.**
+
+- Each selected observer submits compact pass/fail results for tested gateways
+- This is the only step that requires a specific signer (the selected observer)
+- Observations are stored on the Epoch account
+
+### 5. distribute_epoch
+
+**Batched reward distribution to gateways and their delegates.**
+
+- Functional gateways receive the Base Gateway Reward (BGR)
+- Functional observers receive the Base Observer Reward (BOR)
+- Deficient observers do not receive observer rewards
+- Operator rewards auto-compound into operator stake
+- Delegate rewards are tracked via the reward-per-share accumulator (settled lazily)
+- Leaving gateways receive 0 rewards
+
+### 6. close_epoch
+
+**Reclaims rent from completed epoch accounts.**
+
+- Recovers SOL rent from completed epoch accounts
+- Keeps onchain state lean over time
+
+## Timing
+
+The pipeline steps can be executed as the epoch progresses:
+
+| Step | When | Batched? |
+|------|------|----------|
+| create_epoch | After previous epoch ends | No |
+| tally_weights | After create_epoch | Yes |
+| prescribe_epoch | After all weights tallied | No |
+| save_observations | During observation window | No (per observer) |
+| distribute_epoch | After observation window | Yes |
+| close_epoch | After epoch state is no longer needed | No |
+
+## Who Cranks?
+
+A cranker is a permissionless actor that executes the epoch pipeline on Solana. Since Solana programs cannot execute on a timer, an external wallet must call each instruction to advance the epoch lifecycle.
+
+The key property is that cranking is **permissionless**: any wallet with SOL for transaction fees can run it. No ARIO tokens, gateway registration, or special authorization is required.
+
+Without crankers, the epoch pipeline would stall. Observations would not be prescribed, rewards would not be distributed, and completed epoch state would not be closed. Multiple independent crankers provide redundancy so the network is not dependent on a single operator.
+
+Cranking can run as a standalone bot that watches epoch state and submits whichever pipeline instruction is needed next. It can also be embedded directly in ar.io observers:
+
+```bash
+# In your observer's .env file
+ENABLE_EPOCH_CRANKING=true
+```
+
+Multiple crankers can run at the same time without coordination. The first successful transaction advances the pipeline, and later attempts see that the step is already complete. Because the instructions are idempotent, duplicate calls do not double-distribute rewards or corrupt epoch state.
diff --git a/content/learn/oip/index.mdx b/content/learn/oip/index.mdx
index 9a510b5d3..9fd5facbc 100644
--- a/content/learn/oip/index.mdx
+++ b/content/learn/oip/index.mdx
@@ -8,109 +8,89 @@ import { Target, BarChart, FileText, Coins } from "lucide-react";
## Overview
-The Observation and Incentive Protocol ensures network quality through peer monitoring and performance-based rewards. Gateways are incentivized to maintain high performance while also serving as "observers" that evaluate their peers' ArNS resolution capabilities and data integrity verification.
+The Observation and Incentive Protocol (OIP) helps maintain gateway quality through peer monitoring and performance-based rewards. Gateways are incentivized to serve data reliably while also acting as observers that evaluate their peers.
-The protocol operates on **24-hour epochs** where up to 50 gateways are selected as observers to test other gateways against ArNS name resolution criteria and chunk/offset validation. This creates a self-regulating ecosystem with transparent, consensus-based performance evaluation.
+The protocol runs in epochs. During each epoch, selected gateways observe other gateways, submit reports, and participate in an onchain pass/fail voting process. Functional gateways and observers become eligible for ARIO rewards, while deficient gateways and observers miss rewards and can lose future selection weight.
## Architecture Overview
-The Observer Protocol operates through a systematic process where selected gateways monitor their peers and report findings to maintain network quality:
+The protocol follows a repeatable flow:
```mermaid
sequenceDiagram
- participant SC as ar.io Smart Contract
+ participant SC as ar.io Protocol
participant OBS as Observer Gateway
participant GW as Target Gateway
participant AR as Arweave Network
Note over SC,AR: Epoch Start
- SC->>SC: Select up to 50 observers
(weighted random)
- SC->>SC: Generate 2 prescribed ArNS names
+ SC->>SC: Select observers
(weighted random)
+ SC->>SC: Prescribe ArNS names
SC->>OBS: Notify selection & provide names
Note over SC,AR: Observation Phase
- OBS->>OBS: Choose 8 additional ArNS names
- OBS->>OBS: Select subset for chunk validation
loop For each gateway to test
- OBS->>GW: Test ArNS resolution (10 names)
+ OBS->>GW: Test ArNS resolution
GW-->>OBS: Response data
OBS->>OBS: Score: Pass/Fail
end
- loop For selected gateways
- OBS->>GW: Test chunk/offset validation
- GW-->>OBS: Chunk data + Merkle proof
- OBS->>OBS: Verify cryptographic proof
- end
-
Note over SC,AR: Reporting Phase
OBS->>AR: Upload detailed JSON report
AR-->>OBS: Confirm storage
- OBS->>SC: Submit failed gateways list
+ OBS->>SC: Submit compact pass/fail results
SC-->>OBS: Confirm interaction
Note over SC,AR: Evaluation & Rewards
SC->>SC: Tally all observer votes
- SC->>SC: Determine gateway status
(≥50% pass = functional)
- SC->>SC: Calculate reward distribution
+ SC->>SC: Tally observer votes
+ SC->>SC: Determine rewards
SC->>OBS: Distribute observer rewards
SC->>GW: Distribute gateway rewards
(if functional)
```
-## Epoch Cycle and Responsibilities
+## Epoch Cycle
-Each 24-hour epoch follows a structured process with specific responsibilities for gateways and observers:
+Each epoch follows a structured process with specific responsibilities for gateways and observers:
### Epoch Start
-- **Smart Contract**: Selects up to 50 observers using weighted random selection
-- **Smart Contract**: Generates 2 prescribed ArNS names for all observers to test
+- **ar.io protocol**: Selects observers using weighted random selection
+- **ar.io protocol**: Prescribes common ArNS names for observers to test
- **Selected Observers**: Receive notification of selection and prescribed names
### Observation Phase
-- **Observers**: Choose 8 additional ArNS names to test (total of 10 names per gateway)
-- **Observers**: Select subset of gateways for chunk/offset validation based on sampling rate
-- **Observers**: Test assigned gateways for ArNS resolution, wallet ownership, content hashes, and response times
-- **Observers**: Validate chunk/offset data integrity using cryptographic Merkle proofs
-- **Target Gateways**: Respond to resolution requests, serve content, and provide chunk data with proofs
+- **Observers**: Test assigned gateways for ArNS resolution and response quality
+- **Observers**: Document pass/fail findings and failure reasons
+- **Target Gateways**: Respond to resolution requests and serve the requested content
### Reporting Phase
- **Observers**: Upload detailed JSON reports to Arweave for transparency
-- **Observers**: Submit failed gateway lists to the ar.io Smart Contract for consensus voting
+- **Observers**: Submit compact onchain pass/fail results for consensus voting
### Evaluation and Distribution
-- **Smart Contract**: Tallies all observer votes (≥50% pass = functional gateway)
-- **Smart Contract**: Distributes rewards at epoch end based on performance
-- **Functional Gateways/Observers**: Receive ARIO token rewards automatically
+- **ar.io protocol**: Tallies observer votes to classify gateways
+- **ar.io protocol**: Distributes rewards based on performance
+- **Functional Gateways/Observers**: Become eligible for ARIO rewards
## Key Features
- **Decentralized Monitoring**: Peer-to-peer evaluation ensures no single point of failure
-- **Consensus-Based Scoring**: Majority rule (≥50% pass votes) determines gateway functionality
+- **Consensus-Based Scoring**: Observer submissions determine gateway functionality
- **Performance Incentives**: Only functional gateways and observers receive ARIO token rewards
-- **Data Integrity Validation**: Cryptographic verification of chunk/offset data using Merkle proofs
- **Transparent Accountability**: All reports permanently stored on Arweave and viewable at [gateways.ar.io](https://gateways.ar.io)
- **Sustainable Funding**: Protocol balance funded by ArNS name purchases, aligning rewards with network usage
-## Chunk/Offset Validation
-
-The protocol includes advanced data integrity verification through chunk/offset observation. Observers validate that gateways can correctly serve and verify Arweave data chunks using cryptographic proofs:
-
-### Validation Process
-
-- **Sampling**: A subset of gateways is selected for chunk validation each epoch
-- **Offset Testing**: Random offsets within the stable weave range are tested
-- **Merkle Proof Verification**: Cryptographic validation ensures chunk authenticity
-- **Binary Search Optimization**: Efficient transaction lookup using cached metadata
+## What Observers Evaluate
-### Technical Implementation
+Observer criteria can evolve over time without requiring every detail to live in the protocol itself. At a high level, observers evaluate whether gateways can:
-- **Chunk Retrieval**: `GET /chunk/{offset}` returns chunk data and Merkle proof
-- **Proof Validation**: Uses Arweave's `validatePath()` function for cryptographic verification
-- **Performance Optimization**: LRU caching for blocks, transactions, and metadata
-- **Early Stopping**: Tests stop immediately upon first successful validation
+- Resolve prescribed ArNS names correctly
+- Return expected transaction IDs and response data
+- Serve data with acceptable availability and responsiveness
+- Produce reports that can be independently inspected by users and applications
---
@@ -121,25 +101,25 @@ The protocol includes advanced data integrity verification through chunk/offset
}
/>
}
/>
}
/>
}
/>
diff --git a/content/learn/oip/meta.json b/content/learn/oip/meta.json
index 33e3cb26c..4589cce1f 100644
--- a/content/learn/oip/meta.json
+++ b/content/learn/oip/meta.json
@@ -1,10 +1,14 @@
{
- "title": "Observation & Incentive Protocol",
+ "title": "Observation & Incentive Protocol (OIP)",
+ "icon": "Activity",
"defaultOpen": false,
"pages": [
+ "epoch-pipeline",
"observer-selection",
"reporting",
"performance-evaluation",
- "reward-distribution"
+ "reward-distribution",
+ "staking",
+ "pruning"
]
}
diff --git a/content/learn/oip/observer-selection.mdx b/content/learn/oip/observer-selection.mdx
index 1a18ef958..f128c6919 100644
--- a/content/learn/oip/observer-selection.mdx
+++ b/content/learn/oip/observer-selection.mdx
@@ -1,33 +1,32 @@
---
title: "Observer Selection"
-description: "Learn about how gateways are selected as observers each epoch and how ArNS names are chosen using weighted random selection and Hashchain entropy"
+description: "Learn how gateways are selected as observers each epoch using weighted random selection"
---
## Epochs and Selection Timeline
-The ar.io network operates on **24-hour epochs**, during which the observer selection and evaluation process takes place. At the start of each epoch:
+The ar.io network operates in epochs, during which the observer selection and evaluation process takes place. At the start of each epoch:
-- **50 observers** are selected to monitor the network
-- **2 prescribed ArNS names** are chosen for all observers to test
-- **8 additional names** are selected by each observer individually
-- **Gateway subset** is selected for chunk/offset validation based on sampling rate
+- Observers are selected to monitor the network
+- Prescribed ArNS names are chosen for all observers to test
+- Observers may evaluate additional names or criteria as defined by the current observation process
-This creates a consistent evaluation framework where all observers test the same baseline names while having flexibility to choose additional targets for comprehensive network monitoring, plus advanced data integrity verification.
+This creates a consistent evaluation framework where all observers test the same baseline names while leaving room for the observation process to evolve over time.
## Selection Process
-Up to **fifty (50)** gateways are selected as observers per epoch using a sophisticated weighted random selection system. The selection uses **hashchain entropy** from previous ar.io contract state messages to ensure unpredictable and tamper-resistant selection.
+Gateways are selected as observers using weighted random selection. The process combines randomness with gateway-specific weights so observer duties are unpredictable, but still influenced by stake, tenure, and historical performance.
-The hashchain-based entropy provides cryptographic randomness for selecting:
+The entropy provides cryptographic randomness for selecting:
-- **Observer Gateways**: The 50 gateways chosen to perform observations
-- **Prescribed ArNS Names**: The 2 common names all observers must evaluate
+- **Observer Gateways**: Gateways chosen to perform observations
+- **Prescribed ArNS Names**: Common names all observers must evaluate
This approach prevents manipulation while maintaining weighted probabilities based on gateway performance and commitment.
-{" "}
shows the current epoch prescribed observers and arns names, as well as their
submission status
-
+
## Weighted Selection Criteria
@@ -57,45 +56,11 @@ The selection considers four key factors that are multiplied together to create
- **Gateway Performance Ratio Weight (GPRW)**: Historical gateway performance
- **Observer Performance Ratio Weight (OPRW)**: Historical observer performance
-These weights are then normalized across all eligible gateways to create selection probabilities. For detailed weight calculations and formulas, see [Performance Evaluation](/learn/oip/performance-evaluation).
+These weights are then normalized across all eligible gateways to create selection probabilities. For more on how performance affects those weights, see [Performance Evaluation](/learn/oip/performance-evaluation).
-## Hashchain Random Selection
+## Random Selection
-The selection process uses **hashchain entropy** from previous ar.io contract state messages to achieve cryptographically secure randomness:
-
-### How Hashchain Selection Works
-
-1. **Entropy Source**: Random numbers are generated from the hashchain of previous contract state messages
-2. **Weighted Mapping**: Each random number maps to normalized weight ranges of eligible gateways
-3. **Observer Selection**: The gateway whose weight range contains each random number is selected
-4. **Prescribed Names**: The same entropy selects 2 ArNS names that all observers must test
-
-This creates tamper-resistant selection where higher-weighted gateways have proportionally better chances of selection, while maintaining true randomness that cannot be predicted or manipulated.
-
-## Chunk/Offset Sampling
-
-In addition to observer selection, the protocol includes a separate sampling process for chunk/offset validation:
-
-### Gateway Selection for Chunk Validation
-
-- **Deterministic Selection**: Uses PRNG seeded with observation entropy to select gateway subset
-- **Sampling Rate**: Configurable percentage of gateways tested per observation (default: 1%)
-- **Minimum Guarantee**: At least 1 gateway is always selected for testing
-- **Offset Selection**: Random offsets within the stable weave range are chosen for each selected gateway
-
-
-
-### Validation Process
-
-- **Chunk Retrieval**: Observers request chunk data using `GET /chunk/{offset}`
-- **Merkle Proof Verification**: Cryptographic validation ensures data integrity
-- **Early Stopping**: Tests stop immediately upon first successful validation
-- **Performance Optimization**: Uses LRU caching for efficient transaction lookup
+The selection process maps random values onto normalized gateway weight ranges. Gateways with higher weights have proportionally better chances of selection, while randomness prevents predictable or easily manipulated assignments.
## Fairness and Meritocracy
@@ -103,7 +68,7 @@ This system ensures:
- **Meritocratic Selection**: Higher-performing gateways have better selection odds
- **Fair Opportunity**: All gateways maintain non-zero selection probability
-- **Tamper Resistance**: Hashchain entropy prevents manipulation
+- **Tamper Resistance**: Entropy prevents predictable observer assignment
- **Consistent Standards**: Prescribed names create common evaluation baseline
The selection is saved in the contract state at epoch start to ensure that activities during the epoch do not affect selection or reward distribution.
diff --git a/content/learn/oip/performance-evaluation.mdx b/content/learn/oip/performance-evaluation.mdx
index d28249b3d..b5b944345 100644
--- a/content/learn/oip/performance-evaluation.mdx
+++ b/content/learn/oip/performance-evaluation.mdx
@@ -9,54 +9,30 @@ Consider the following classifications:
- **Functional or Passed Gateways**: are gateways that meet or surpass the network's performance and quality standards, including ArNS resolution and chunk/offset validation (if selected).
- **Deficient or Failed Gateways**: are gateways that fall short of the network's performance expectations, including failures in ArNS resolution or chunk/offset validation.
-- **Functional or Submitted Observers**: are selected observers who diligently perform their duties and submit observation reports and contract interactions.
-- **Deficient or Failed Observers**: are selected observers who do not fulfill their duty of submitting observation reports and contract interactions.
+- **Functional or Submitted Observers**: are selected observers who diligently perform their duties and submit observation reports and onchain observations.
+- **Deficient or Failed Observers**: are selected observers who do not fulfill their duty of submitting observation reports and onchain observations.
## Evaluation Process
-At the end of an epoch, the ar.io Smart Contract processes observer submissions to determine gateway performance through a consensus-based vote tallying system. This evaluation transforms individual observer reports into network-wide performance assessments.
+At the end of an epoch, the ar.io protocol processes observer submissions to determine gateway performance through a consensus-based vote tallying system. This evaluation transforms individual observer reports into network-wide performance assessments.
### Vote Tallying and Gateway Classification
-After observers submit their detailed reports (see [Reporting](/learn/oip/reporting) for submission details), the smart contract performs consensus calculation:
+After observers submit their detailed reports (see [Reporting](/learn/oip/reporting) for submission details), the protocol performs consensus calculation:
**Vote Processing:**
-- **Data Collection**: All observer contract interactions for each gateway are collected
+- **Data Collection**: All observer onchain observations for each gateway are collected
- **Vote Counting**: Each observer submission contributes either a PASS or FAIL vote
-- **Majority Determination**: If ≥50% of submitted observer interactions indicate PASS, the gateway is considered Functional
+- **Majority Determination**: If enough submitted observer interactions indicate PASS, the gateway is considered Functional
- **Binary Classification**: Gateways are classified as either Functional (eligible for rewards) or Deficient (ineligible for rewards)
**Consensus Mechanism:**
- Multiple observers evaluate each gateway independently, ensuring reliable assessment
-- The 50% threshold requires majority agreement for positive performance determination
+- A majority-style threshold requires broad observer agreement for positive performance determination
- Binary scoring provides clear, unambiguous performance classification
-- Vote tallying occurs after the 40-minute confirmation period to ensure all interactions are finalized
-
-## Chunk/Offset Validation Criteria
-
-For gateways selected for chunk/offset validation, additional performance criteria are evaluated:
-
-### Validation Requirements
-
-- **Chunk Retrieval**: Gateway must successfully respond to `GET /chunk/{offset}` requests
-- **Data Integrity**: Chunk data must be non-empty and within reasonable size limits (<1MB)
-- **Merkle Proof Validation**: Cryptographic proof must decode correctly and validate against transaction data_root
-- **Performance Standards**: Response times must meet network expectations
-
-
-
-### Assessment Process
-
-- **Binary Scoring**: Each offset test results in pass/fail determination
-- **Consensus Integration**: Chunk/offset results are integrated into overall gateway assessment
-- **Performance Tracking**: Individual offset assessments are tracked and reported
+- Vote tallying occurs after submissions are finalized
## Weight Impact on Gateway Performance
@@ -64,13 +40,7 @@ Gateway performance directly affects multiple weighted factors that influence fu
### Gateway Performance Ratio Weight (GPRW)
-A gateway's evaluation results directly impact their Gateway Performance Ratio Weight, which affects their likelihood of being selected as an observer in future epochs:
-
-```math
-GPRW = \frac{1 + \text{Passed Epochs}}{1 + \text{Participated Epochs}}
-```
-
-**Impact:**
+A gateway's evaluation results directly impact their Gateway Performance Ratio Weight, which affects their likelihood of being selected as an observer in future epochs.
- **Functional Gateways**: Increase their passed epochs count, improving their GPRW
- **Deficient Gateways**: Decrease their GPRW as participated epochs increase without corresponding passes
@@ -78,32 +48,20 @@ GPRW = \frac{1 + \text{Passed Epochs}}{1 + \text{Participated Epochs}}
### Observer Performance Ratio Weight (OPRW)
-For gateways selected as observers, their performance in submitting reports affects future selection:
-
-```math
-OPRW = \frac{1 + \text{Submitted Epochs}}{1 + \text{Selected Epochs}}
-```
-
-**Impact:**
+For gateways selected as observers, their performance in submitting reports affects future selection.
- **Functional Observers**: Who submit reports increase their OPRW
- **Deficient Observers**: Who fail to submit reports see their OPRW decrease
- **Future Selection**: Higher OPRW improves chances of future observer selection
-### Composite Weight Calculation
-
-All performance factors combine to determine overall network influence:
-
-```math
-CW = SW \times TW \times GPRW \times OPRW
-```
+### Composite Weight
-Where:
+Performance factors combine to determine overall network influence:
-- **SW** = Stake Weight (financial commitment)
-- **TW** = Tenure Weight (network longevity)
-- **GPRW** = Gateway Performance Ratio Weight
-- **OPRW** = Observer Performance Ratio Weight
+- **Stake Weight**: Financial commitment
+- **Tenure Weight**: Network longevity
+- **Gateway Performance Ratio Weight**: Gateway reliability history
+- **Observer Performance Ratio Weight**: Observation duty history
**Long-term Effects:**
@@ -113,13 +71,13 @@ Where:
## Evaluation Timeline
-Rewards are distributed **at the end of each epoch** by the ar.io Smart Contract directly based on the tallied observer votes. The smart contract processes all observer submissions and automatically distributes rewards to functional gateways and observers based on their performance during the epoch.
+Rewards are distributed **at the end of each epoch** by the ar.io protocol based on the tallied observer votes. The protocol processes observer submissions and distributes rewards to functional gateways and observers based on their performance during the epoch.
## Key Features
- **Majority Rule**: Gateway performance is determined by majority vote from observers
- **Binary Scoring**: Simple pass/fail system for clear performance assessment
-- **Network Confirmation**: Delay ensures all votes are confirmed before evaluation
+- **Network Confirmation**: Evaluation happens after observer submissions are finalized
- **Transparent Process**: All evaluations are based on onchain data
## Consequences of Performance
@@ -140,10 +98,10 @@ Rewards are distributed **at the end of each epoch** by the ar.io Smart Contract
- Functional observers receive observer rewards
- Deficient observers forfeit observer rewards
-- Deficient observers who are also functional gateways have their gateway reward reduced by 25%
+- Deficient observers who are also functional gateways can have their gateway reward reduced for that epoch
---
## Next Steps
-Ready to understand how rewards are distributed? Learn about [Reward Distribution](/learn/oip/reward-distribution) to see the formulas and mechanics, or go back to [Observer Selection](/learn/oip/observer-selection) to review the selection process.
+Ready to understand how rewards are distributed? Learn about [Reward Distribution](/learn/oip/reward-distribution), or go back to [Observer Selection](/learn/oip/observer-selection) to review the selection process.
diff --git a/content/learn/oip/pruning.mdx b/content/learn/oip/pruning.mdx
new file mode 100644
index 000000000..2c8b33b04
--- /dev/null
+++ b/content/learn/oip/pruning.mdx
@@ -0,0 +1,58 @@
+---
+title: "Gateway Pruning"
+description: "How persistently underperforming gateways can be removed from the ar.io network."
+---
+
+## Overview
+
+Gateway pruning is the mechanism that removes gateways that continue to fail network performance checks. It helps keep the Gateway Address Registry focused on infrastructure that is reachable, useful, and aligned with the network's quality expectations.
+
+Pruning is based on OIP performance results. A gateway is not removed for a single bad result, but sustained failure can make it eligible for removal.
+
+## How Pruning Works
+
+When a gateway remains deficient for a sustained period:
+
+1. **The gateway becomes prunable** after repeated failed observations.
+2. **A permissionless instruction can remove it** from the Gateway Address Registry.
+3. **The operator's required network-join stake is slashed** to the protocol balance.
+4. **Eligible excess and delegated stake follow the normal withdrawal process** instead of being slashed.
+
+```mermaid
+graph TD
+ A[Gateway participates in OIP] --> B{Performance result}
+ B -->|Pass| C[Failure history resets]
+ B -->|Fail| D[Failure history accumulates]
+ D --> E{Sustained failure?}
+ E -->|No| A
+ E -->|Yes| F[Gateway becomes prunable]
+ F --> G[Gateway removed from registry]
+ G --> H[Required operator stake slashed]
+ G --> I[Eligible excess and delegated stake withdrawable]
+```
+
+## Impact on Operators
+
+Pruning is designed to make gateway operation economically accountable. Operators are expected to keep their gateways online, correctly configured, able to resolve ArNS names, and able to participate in observation duties when selected.
+
+When a gateway is pruned, the operator loses the required stake associated with joining the network. Any eligible excess stake follows the normal withdrawal flow.
+
+## Impact on Delegators
+
+Delegated stake is not the target of pruning slashing. If a gateway is pruned, delegated stake follows the normal withdrawal process for leaving gateways. Delegators should still monitor gateway performance because pruning can interrupt reward eligibility and require withdrawal or redelegation decisions.
+
+## Prevention
+
+Gateway operators can reduce pruning risk by:
+
+- Maintaining reliable uptime and public reachability
+- Keeping ArNS resolution working correctly
+- Monitoring OIP performance results and gateway health
+- Funding the observer wallet with SOL for required transaction fees
+- Reviewing gateway status in [gateways.ar.io](https://gateways.ar.io)
+
+## Related Concepts
+
+- [Gateway Registry](/learn/gateways/gateway-registry)
+- [Observation and Incentive Protocol](/learn/oip)
+- [Staking](/learn/oip/staking)
diff --git a/content/learn/oip/reporting.mdx b/content/learn/oip/reporting.mdx
index a551e6668..2f5b82dfb 100644
--- a/content/learn/oip/reporting.mdx
+++ b/content/learn/oip/reporting.mdx
@@ -1,6 +1,6 @@
---
title: "Reporting"
-description: "Learn about observer responsibilities for submitting reports to Arweave and the ar.io Smart Contract"
+description: "Learn about observer responsibilities for submitting reports to Arweave and compact onchain results to the ar.io protocol"
---
## Observer Responsibilities
@@ -17,7 +17,7 @@ Observers must submit their findings through both channels to fulfill their duti
- **Purpose**: Permanent audit trail and transparency
- **Content**: Complete test results, timing data, and failure details
-### 2. Contract Interactions to ar.io Smart Contract
+### 2. Onchain Observations to the ar.io Protocol
- **Format**: List of failed gateways
- **Purpose**: Efficient vote tallying for consensus
@@ -25,7 +25,7 @@ Observers must submit their findings through both channels to fulfill their duti
## Observer Evaluations
-Observers test assigned gateways against 10 ArNS names (2 prescribed + 8 chosen) and document their findings:
+Observers test assigned gateways against prescribed ArNS names and document their findings:
@@ -38,10 +38,10 @@ Observers test assigned gateways against 10 ArNS names (2 prescribed + 8 chosen)
alt="Successful gateway evaluation report"
style={{ width: "100%" }}
/>
-
- Choose your preferred wallet (Wander, Metamask, or Beacon) to connect.
+ Choose your preferred Solana wallet (Phantom, Solflare, or Backpack) to connect.
- AO
- 
- ar.io
- 
- Arweave
- 
+
+ Delegators can select which gateways to stake with in gateways.ar.io — maximize their potential rewards based on operator performance, stakes, and weights
+
+