AssemblyScript Mapping API

The AssemblyScript Mapping API is the foundational specification for the graph-ts library and the host environment in which subgraph mappings execute. Every subgraph developer writing event handlers, call handlers, or block handlers interacts with this API, which provides the bridge between raw blockchain data and the structured entities stored in the subgraph's database. The specification governs critical host imports for cryptographic functions (crypto.keccak256), data source context management (dataSource.context), logging (log.info), and Ethereum-specific data types (Address, BigInt, Bytes).

Changes to this API are high-impact events for the entire ecosystem. A modification to a core type, a new required host function, or a deprecation of an existing import can break every active subgraph that depends on the altered behavior. This creates a cascading risk: indexers must upgrade their Graph Node software to support the new API, subgraph developers must refactor and redeploy their mappings, and all downstream API consumers—dApps, wallets, analytics dashboards—must verify that query responses remain consistent after the transition. The deterministic indexing guarantee means that any divergence in mapping execution across indexers will fracture the network's data consensus.

For teams operating production subgraphs, the AssemblyScript Mapping API is not an abstract standard but a direct dependency with a narrow compatibility surface. Chainscore Labs can audit mapping codebases against upcoming API revisions, identify non-deterministic patterns that violate indexing guarantees, and model the downstream impact of host import changes on query consumers. A proactive review before a graph-ts major version bump is the difference between a planned migration and an emergency redeployment.

The AssemblyScript Mapping API defines the deterministic execution environment for subgraph transformation logic within The Graph. When a subgraph developer writes mapping.ts files, they are not writing code that runs directly on a bare-metal machine or a standard Node.js runtime. Instead, the code compiles to WebAssembly and executes inside a sandboxed runtime provided by Graph Node. This runtime exposes a set of host imports—functions imported from the host environment—that provide the only bridge between the deterministic mapping logic and external data sources like the Ethereum Virtual Machine, IPFS, or cryptographic primitives. The graph-ts library (@graphprotocol/graph-ts) acts as the typed AssemblyScript interface to these host imports, defining classes like ethereum, crypto, ipfs, and dataSource.

The core mechanism relies on a strict separation of concerns: the mapping code is purely functional and deterministic, while the host imports handle all side effects and data retrieval. For example, when a mapping calls crypto.keccak256(), it invokes a host import that executes the hashing operation outside the WebAssembly sandbox. Similarly, ethereum.call() performs a static call to an Ethereum node managed by the indexer. This architecture ensures that given the same input events and the same block state, every indexer produces identical output, which is the foundation of Proof of Indexing (POI). The API also provides context objects like dataSource.context() and dataSource.address() that allow the same mapping logic to be reused across multiple contract instances, a critical feature for factory-deployed contracts.

Operationally, changes to this API—such as adding new host imports for cryptographic functions, modifying the behavior of ethereum.decode(), or introducing new data source kinds—require coordinated upgrades across the graph-ts library, Graph Node implementations, and all downstream subgraphs. A breaking change in the mapping API can cause subgraphs to fail synchronization, produce non-deterministic results, or become incompatible with newer Graph Node versions. Teams operating subgraphs should monitor graph-ts releases and Graph Node changelogs for API deprecations. Chainscore Labs can audit mapping code for compatibility with upcoming API changes, identify reliance on deprecated host imports, and verify that subgraph logic remains deterministic across indexer implementations.