ARC-18 establishes a formal convention for how applications and users attach metadata to Arweave transactions through the protocol's native tag system. Rather than defining specific tag names or values, it specifies a structured format—a colon-separated key-value encoding—that allows multiple logical attributes to be packed into a single tag. This convention is critical for integration engineers building GraphQL queries, indexers, or explorers who need to filter transactions by content type, application ID, protocol version, or other custom metadata without relying on ad-hoc, application-specific tagging schemes that fragment the network's queryability.
Protocols
Transaction Tag Conventions (ARC-18)
Documents the community-agreed metadata tags used to index, query, and categorize Arweave transactions. Critical for integration engineers building GraphQL queries, indexers, or explorers who need to filter by content type, application ID, or protocol version.
introduction
METADATA TAGGING CONVENTION
What ARC-18 Defines
A community standard for structuring metadata in Arweave transaction tags to enable consistent indexing, querying, and categorization across the permaweb.
The standard addresses a fundamental indexing challenge on Arweave: while any transaction can include arbitrary key-value tags, the lack of a unified convention forces indexers and gateways to understand every application's bespoke tag structure. ARC-18 solves this by defining a deterministic way to encode structured data within the value field of a tag, using a format like App-Name:MyApp;Content-Type:image/png;Version:1.0. This allows a single tag to carry multiple indexed fields, making it possible for generic indexers to parse and expose rich metadata without application-specific logic. The convention also specifies rules for escaping special characters, handling nested structures, and defining namespaces to avoid key collisions between different protocols.
For operators and builders, ARC-18 compliance is a force multiplier for discoverability. Transactions that follow this convention are automatically indexed by major Arweave gateways and explorers, making application data queryable through standard GraphQL interfaces without custom integration work. Teams that ignore the standard risk rendering their transactions invisible to the broader ecosystem's indexing infrastructure. Chainscore Labs can review a protocol's transaction tagging strategy against ARC-18 to ensure maximum compatibility with the permaweb's query layer and to identify integration risks before deployment.
TRANSACTION TAG CONVENTIONS
ARC-18 at a Glance
Operational impact and integration requirements for the community-agreed metadata tagging standard used to index, query, and categorize Arweave transactions.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
Tag Namespace | Standardizes a set of well-known tag names (e.g., App-Name, Content-Type, Protocol) to ensure consistent querying across the ecosystem. | Indexers, explorers, gateway operators, and dApp developers building GraphQL queries. | Audit existing transaction creation logic to ensure compliance with the canonical tag list. Verify against the official ARC-18 specification. |
Query Reliability | Adopting standard tags makes transactions discoverable via predictable GraphQL filters. Non-standard tags may render data invisible to standard indexers. | Data analysts, compliance teams, and application backends relying on Arweave as a data availability layer. | Refactor queries to use ARC-18 tags as the primary filter. Monitor for transactions missing required tags in your application namespace. |
Application Identity | Introduces the App-Name and App-Version tags, creating a convention for on-chain application identification and versioning. | Wallet developers (ArConnect, Arweave.app), bundler services, and any platform generating transactions on behalf of users. | Define a unique App-Name for your service. Implement logic to inject App-Name and App-Version into every transaction your system creates. |
Content Addressing | Formalizes the Content-Type tag convention, allowing gateways and browsers to serve data with the correct MIME type. | Permaweb application deployers, gateway operators (arweave.net), and developers using path manifests (ARC-26). | Ensure the Content-Type tag is set accurately for all uploaded data assets, especially when deploying web applications via manifests. |
Protocol Versioning | Establishes a Protocol tag to signal which application-level protocol a transaction adheres to, enabling parsers to handle data correctly. | Smart contract developers (Warp Contracts), token issuers (ARC-20), and NFT platforms (ARC-19/69). | Include the specific protocol identifier and version in the Protocol tag. Update parsers to branch logic based on this tag to handle future breaking changes. |
Interoperability Risk | Divergence from ARC-18 conventions creates fragmentation, where transactions are only understood by a subset of tools and explorers. | Exchanges integrating Arweave-native assets, cross-chain bridges, and analytics platforms. | Conduct an integration review to identify any custom, non-standard tags. Migrate to ARC-18 conventions to ensure broad ecosystem compatibility. |
Indexer Performance | Standard tags allow indexers to build optimized, tag-specific database columns, drastically improving query performance over generic key-value searches. | Gateway and indexer infrastructure teams (e.g., Goldsky, ar.io nodes). | Optimize indexing logic to prioritize ARC-18 defined tags. Publish performance benchmarks for queries relying on these standard conventions. |
technical-context
ARC-18 METADATA INDEXING
Tag Structure and Namespace Conventions
Defines the community-agreed conventions for structuring transaction metadata tags to ensure consistent indexing, querying, and categorization across the Arweave ecosystem.
ARC-18 establishes a formal namespace convention for Arweave transaction tags, moving beyond ad-hoc key-value pairs to a structured system that prevents collisions and enables reliable GraphQL filtering. The standard specifies that application-specific tags should use a reverse-domain namespace prefix (e.g., App-Name, App-Version) while reserving a set of protocol-level tags for cross-cutting concerns like content type, Unix time, and data protocol identifiers. This convention is critical for indexers, gateways, and explorers that must construct deterministic queries across millions of transactions without ambiguity.
The operational impact is immediate for any team building on Arweave's GraphQL endpoint. Without adherence to ARC-18 namespaces, transactions become invisible to standard indexing pipelines or, worse, collide with tags from other applications. The standard defines reserved tags including Content-Type for MIME type declaration, Unix-Time for temporal ordering, and Protocol for signaling which application-layer standard a transaction conforms to. Builders who ignore these conventions risk their data being miscategorized by gateways like arweave.net, breaking discovery in explorers, and failing to integrate with ecosystem tooling that expects ARC-18 compliance.
A breaking change introduced by ARC-18 was the deprecation of generic, unnamespaced tags in favor of the App-Name prefixed convention. Applications that previously used bare keys like type or version must migrate to App-Name and App-Version to remain indexable under the new standard. Teams maintaining legacy applications should audit their transaction construction logic and bundler configurations to ensure compliance. Chainscore Labs can assist with integration reviews to verify that tag structures align with current gateway indexing behavior and that migration paths do not introduce data availability gaps.
IMPACT BY ACTOR
Who Is Affected by Tag Conventions
Indexing Infrastructure
Tag conventions directly determine how indexers parse, categorize, and expose transaction data. Changes to standard tag names or value formats break GraphQL queries, warp the results of findTransactions, and corrupt downstream datasets.
Action items:
- Audit all GraphQL queries for hardcoded tag name strings.
- Subscribe to ARC-18 amendment discussions to anticipate breaking changes.
- Implement tag normalization layers that map legacy tags to current conventions.
- Monitor query performance degradation when new tag patterns emerge.
Chainscore Labs can review your indexing pipeline for tag dependency risks and help design resilient query architectures that survive convention changes.
implementation-impact
INDEXER AND GATEWAY COMPATIBILITY
Integration and Query Impact
ARC-18 defines the community-agreed metadata tags used to index, query, and categorize Arweave transactions. Adopting these conventions is critical for ensuring transactions are discoverable by GraphQL gateways, explorers, and application-specific indexers.
02
Indexer Categorization Logic
Explorers and analytics platforms use ARC-18 tags to categorize transactions into human-readable activities. For example, an App-Name: SmartWeaveAction tag signals a contract interaction, while Content-Type: image/png indicates a media upload. Inconsistent or missing tags cause indexers to misclassify transactions, leading to broken activity feeds, incorrect analytics, and poor user experience in block explorers.
04
Bundler and Gateway Propagation
ANS-104 bundled transactions must include ARC-18 compliant tags at the data-item level for individual items to be queryable. If a bundler strips or alters these tags before submitting the bundle to the network, the inner transactions become opaque to gateways. Teams operating bundler infrastructure must validate that their bundling logic preserves all application-level tags to ensure end-to-end data discoverability.
05
Warp Contracts Integration
The Warp Contracts SDK and its indexer rely on specific ARC-18 tags to identify contract interactions and state. The Contract tag, for instance, is used to route an interaction to the correct contract. Failure to include the correct tag format will cause the Warp sequencer to ignore the transaction, effectively making the contract interaction fail from the application's perspective, even if it is confirmed on-chain.
06
Chainscore Labs Tag Audit
Chainscore Labs can audit your application's transaction construction logic to ensure full compliance with ARC-18 and related standards. We review your integration against the canonical tag registry, verify queryability across major gateways, and assess the impact of proposed namespace changes on your data pipeline, preventing silent indexing failures before they reach production.
ARC-18 TAG CONVENTION DEVIATIONS
Compatibility and Operational Risks
Operational risks introduced when transactions omit, misuse, or incorrectly format ARC-18 metadata tags. This table helps integration engineers, indexer operators, and application developers identify failure modes that break GraphQL queries, data discovery, and protocol-level filtering.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
Content-Type Tag | Missing or non-standard Content-Type tag prevents gateways and indexers from correctly identifying data MIME type, breaking rendering and retrieval logic. | Gateway operators, explorer UIs, data retrieval services, permaweb applications | Validate that all uploaded transactions include a standard Content-Type tag matching the actual payload. Audit existing data for missing tags. |
App-Name Namespace | Omitting the App-Name tag or using an unregistered namespace causes transactions to be invisible to application-specific GraphQL queries. | Application developers, indexer operators, analytics platforms | Register and consistently apply a unique App-Name tag. Indexers should verify query logic does not silently drop untagged transactions. |
App-Version Tag | Failing to increment or include App-Version when data schemas change leads to indexers processing data with incorrect parsers, causing corruption or query errors. | Application developers, data consumers, indexer operators | Always include App-Version. Implement version-aware parsing in indexers. Coordinate schema migrations with tag updates. |
Protocol Tag | Incorrect or missing Protocol tag prevents routing transactions to the correct execution environment, such as a specific Warp Contracts fork or AO process. | Smart contract platforms, AO compute units, bundlers | Verify the Protocol tag matches the target execution environment. Bundlers should reject or flag transactions with unrecognized Protocol values. |
Tag Key Collisions | Duplicate tag keys in a single transaction lead to non-deterministic parsing behavior across different gateway implementations and SDKs. | SDK maintainers, gateway operators, application developers | Ensure transaction construction logic prevents duplicate keys. Gateways should adopt a consistent, documented resolution strategy for duplicate tags. |
Unicode and Encoding | Using non-ASCII characters in tag keys or values without proper encoding causes parsing failures in strict ANS-104 implementations. | Bundler operators, gateway software, SDK developers | Restrict tags to printable ASCII or enforce a standard encoding convention. Test tag handling across all target gateway implementations. |
Tag Size Limits | Excessively large tag sets or individual tag values can cause transactions to be rejected by bundlers or incur unexpected storage costs. | High-throughput application developers, bundler operators | Audit tag payload sizes. Implement client-side limits. Bundlers should document and enforce maximum tag size policies. |
ARC-18 READINESS
Integration Engineer's Tag Conformance Checklist
A practical checklist for integration engineers to verify that their application's transaction tagging strategy is compliant with ARC-18 conventions. Proper tagging is critical for GraphQL query performance, indexer accuracy, and application discoverability on the permaweb.
What to check: Every transaction must include a Content-Type tag with a valid MIME type (e.g., application/json, image/png).
Why it matters: Gateways and indexers rely on this tag as the primary signal for how to process and serve data. A missing or incorrect Content-Type can cause applications to fail to render, data to be indexed incorrectly, or GraphQL queries to return unexpected results.
Confirmation signal: Query the transaction via an Arweave gateway's /tx/{id} endpoint and confirm the Content-Type tag is present and matches the actual data payload. Test that your application's GraphQL queries filter correctly on this tag.
resource-links
ARC-18 IMPLEMENTATION REFERENCES
Canonical Resources and Tools
Use these resources to verify the current ARC-18 tag conventions, construct compliant Arweave transactions, and test indexer or gateway behavior before relying on tag-based discovery in production.
04
Indexer Compatibility Checklist
Teams operating explorers, gateways, analytics systems, or compliance tooling should maintain a small ARC-18 compatibility matrix: supported tag names, accepted value formats, case-sensitivity assumptions, bundled transaction support, GraphQL schema behavior, and backfill coverage. This is especially important for application identifiers, content types, protocol versions, and collection-level metadata where a single inconsistent tag can split discovery across multiple query patterns.
05
Wallet and Uploader Validation
Wallets, upload services, and bundlers should validate ARC-18 tags before signing or posting data. Practical controls include allowlisted tag names for known standards, warnings for conflicting protocol-version tags, deterministic casing, and preview screens that show the final tag set. For user-generated uploads, avoid silently rewriting tags unless the user or application has explicitly delegated that behavior, because tags become part of the permanent transaction record.
06
Operational Review with Chainscore Labs
Chainscore Labs can help teams review ARC-18-dependent integrations before launch or migration. Typical work includes tag taxonomy review, GraphQL query hardening, gateway/indexer compatibility testing, bundled transaction visibility checks, and monitoring design for malformed or spoofed metadata. This is most useful for exchanges, wallets, marketplaces, AO applications, and analytics teams whose product behavior depends on reliable Arweave transaction discovery.
Chains We Build On
Looking to build on a specific blockchain?
We build smart contracts, DeFi applications, wallets, tokenization platforms, and blockchain infrastructure across the major ecosystems teams choose today. That includes Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Solana, Sui, Aptos, Hedera, Stellar, and NEAR, with support for additional EVM and non-EVM networks based on your product requirements.
EVM ecosystems
- Ethereum
- Arbitrum
- Optimism
- Polygon
- Avalanche
- Cronos
Non-EVM ecosystems
- Solana
- Sui
- Aptos
- Hedera
- Stellar
- NEAR
Additional ecosystems
- Polkadot
- Cosmos
- TON
- Cardano
- Algorand
- Tempo
Also available for Base, appchains, custom EVM networks, and cross-chain product architecture.
ARC-18 IMPLEMENTATION FAQ
Frequently Asked Questions
Common questions from integration engineers, indexer operators, and application developers implementing the Transaction Tag Conventions standard.
ARC-18 reserves the App- prefix for application-specific metadata. The convention is App-Name for the application identifier and App-Version for its semantic version. For example, a marketplace dApp would use App-Name: Arweave-Marketplace and App-Version: 1.2.0. This namespace prevents collisions between different protocols and allows indexers to filter transactions by application context. Teams should verify their chosen App-Name against community registries to avoid fragmentation.
Trusted by Industry Leaders
Delivering blockchain solutions for 5+ years.
We have partnered with 50+ leading DeFi protocols, NFT ecosystems, and fintech innovators to build secure, scalable, and capital-efficient blockchain products.
Selected Partners & Clients
“I've been working with Chainscore Labs for last 3+ years, they've consistently delivered with strong ownership across multiple projects. The team is reliable and detail-oriented.”
L
Lee Erswell
CEO, Telos Foundation
how to get started
How to get started?
If you're looking for blockchain integration, ChainScore Labs has 5+ years of experience helping teams build and integrate exchanges, wallets, smart contracts, tokenization solutions, and protocol-connected products, we can help you choose the right path, integrate securely, and get to production faster. Our team consists of experienced blockchain developers and architects who can help you with your blockchain integration needs.
01
Exploration & Strategy
Define your product goals and choose the right blockchain architecture for your use case.
02
Architecture & Design
Design the smart contracts, tokenomics, and security parameters of your system.
03
Development & Integration
Build and integrate with wallets, oracles, and front-end dApps for a seamless experience.
04
Security & Launch
Comprehensive audits followed by a risk-managed mainnet deployment to protect your users.
Explore More Solutions
Discover our
blockchain development services.
We build production-grade blockchain solutions for top-tier projects across DeFi and Web3.
Book a Call
Start a build
Need a blockchain engineering team?
Send the project context and we will respond with next steps, scope questions, and a practical path to delivery.