Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt

Use this file to discover all available pages before exploring further.

peaqOS runs on four on-chain layers. The core registry and staking contracts live on peaq chain as UUPS upgradeable proxies; bridging is LayerZero V2 ONFT; smart accounts follow ERC-4337; and low-level DID, batch, and WPEAQ operations are peaq chain precompiles.

​
Architecture

Core (peaq chain, UUPS proxies)
  IdentityRegistry ──owns──► IdentityStaking
        │                         ▲
        │ (gates on)              │ stakeFor()
        └─────► EventRegistry
        │
        └─────► MachineNFT

Cross-chain (peaq ↔ Base, LayerZero V2)
  MachineNFTAdapter (peaq)  ◄──► MachineNFTBase (Base)

ERC-4337 (peaq chain)
  MachineAccountFactory ──deploys──► MachineSmartAccount (BeaconProxy)

Precompiles (peaq chain, fixed addresses)
  DID (0x...800) · Batch (0x...805) · WPEAQ (0x...809)
  • Core contracts use UUPS upgradeable proxies (OpenZeppelin 5.x) with ERC-7201 namespaced storage. Future upgrades preserve state.
  • Identity NFT (minted by IdentityRegistry) and Machine NFT (minted by MachineNFT) are separate ERC-721 spaces with independent tokenId sequences linked by machineId. See Machine NFT.
  • IdentityRegistry implements ERC-8004 for DID-anchored machine metadata; the JSON Machine Card is served by the MCR API.

​
peaq mainnet addresses

Set these in your environment. The SDK reads them from fromEnv() / from_env().

​
Core

ContractVariableAddress
IdentityRegistryIDENTITY_REGISTRY_ADDRESS0xb53Af985765031936311273599389b5B68aC9956
IdentityStakingIDENTITY_STAKING_ADDRESS0x11c05A650704136786253e8685f56879A202b1C7
EventRegistryEVENT_REGISTRY_ADDRESS0x43c6c12eecAf4fB3F164375A9c44f8a6Efc139b9
MachineNFTMACHINE_NFT_ADDRESS0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9

​
Precompiles

ContractVariableAddress
DIDDID_REGISTRY_ADDRESS0x0000000000000000000000000000000000000800
BatchBATCH_PRECOMPILE_ADDRESS0x0000000000000000000000000000000000000805
WPEAQn/a0x0000000000000000000000000000000000000809

​
Optional

ContractVariableAddressNeeded for
MachineAccountFactoryMACHINE_ACCOUNT_FACTORY_ADDRESS0x4A808d5A90A2c91739E92C70aF19924e0B3D527fdeploySmartAccount / getSmartAccountAddress
MachineNFTAdapterMACHINE_NFT_ADAPTER_ADDRESS0x9AD5408702EC204441A88589B99ADfC2514AFAE6bridgeNft from peaq
AdminFlagsADMIN_FLAGS_ADDRESS0x1c5f33fBEE6BA38ed9bDE247C1Ba89A2116C25f1MCR API server (negative-flag reads + admin trust overrides)

​
Base mainnet addresses

Needed when bridging into peaq from Base. Pass as baseNftAddress / base_nft_address to bridgeNft / bridge_nft.
ContractAddress
MachineNFTBase (LayerZero ONFT)0xee8A521eA434b11F956E2402beC5eBfa753Babfa

​
Agung testnet addresses

Use these for development on agung. The contract surface matches mainnet; only the deployed addresses differ.

​
Core

ContractVariableAddress
IdentityRegistryIDENTITY_REGISTRY_ADDRESS0x9E9463a65c7B74623b3b6Cdc39F71be7274e5971
IdentityStakingIDENTITY_STAKING_ADDRESS0x55f336714aDb0749DbFE33b057a1702405564E3d
EventRegistryEVENT_REGISTRY_ADDRESS0x2DAD8905380993940e340C5cE6d313d5c2780040
MachineNFTMACHINE_NFT_ADDRESS0xB41C2A4f1c19b6B06beaAce0F5CD8439e77C4b1c

​
Precompiles

Identical to mainnet: same fixed addresses on every peaq runtime.
ContractVariableAddress
DIDDID_REGISTRY_ADDRESS0x0000000000000000000000000000000000000800
BatchBATCH_PRECOMPILE_ADDRESS0x0000000000000000000000000000000000000805
WPEAQn/a0x0000000000000000000000000000000000000809

​
Optional

ContractVariableAddressNeeded for
MachineAccountFactoryMACHINE_ACCOUNT_FACTORY_ADDRESS0x65a4DfEB799dFf8CF15f13816d648a7805d6b1F9deploySmartAccount / getSmartAccountAddress
MachineNFTAdapterMACHINE_NFT_ADAPTER_ADDRESS0x63fD7e64A38e50D1486Bc569B4CaCeD38528De22bridgeNft from peaq
AdminFlagsADMIN_FLAGS_ADDRESS0x4181a2Aa34aFb247450FfcBd65be5aBD4Cbee658MCR API server (negative-flag reads + admin trust overrides)
Bridging cannot be exercised on agung. MachineNFTAdapter is deployed, but LayerZero V2 has no DVN routes between agung and Base. bridgeNft / bridge_nft calls will not relay end-to-end. Exercise the bridge on peaq mainnet ↔ Base mainnet only.

​
Core contracts

​
IdentityRegistry

Central machine identity registry. Mints an ERC-721 Identity NFT to each machine on registration and orchestrates bonding through IdentityStaking.stakeFor(). Implements ERC-8004 so that each Identity NFT’s tokenURI resolves to the machine’s DID-anchored Machine Card. DID attributes themselves live on the peaq DID precompile (W3C DID), written by the SDK via writeMachineDIDAttributes and read by the MCR API. Tracks per-machine status (None → Pending → Verified / Rejected / Deactivated). Supports self-registration and proxy registration. SDK methods: registerMachine, registerFor Key state: minBond (currently 1 PEAQ), nextMachineId, operatorOf, machineStatus

​
IdentityStaking

Bond token storage. Tokens are staked at registration time via stakeFor() and held permanently; no withdrawal path is exposed. Only authorized callers (IdentityRegistry) can initiate stakes. Supports pause / unpause by owner. SDK interaction: Indirect. registerMachine / registerFor route the bond through here automatically.

​
EventRegistry

On-chain store for revenue (type 0) and activity (type 1) events. Gates event submission on (a) the machine being registered in IdentityRegistry, and (b) the machine being bonded in IdentityStaking. Authorization rule: msg.sender must be the machine wallet or the operator. Stores a keccak256 hash of the raw data; payloads stay off-chain. SDK methods: submitEvent, batchSubmitEvents Concept: Events

​
MachineNFT

LayerZero V2 ONFT representing a machine’s financial profile. Minted in a separate mintNft call after registration: the Machine NFT tokenId is independent from the Identity NFT tokenId. tokenURI resolves to the MCR API’s /metadata/{token_id} endpoint, which returns the Machine Card. SDK methods: mintNft, tokenIdOf Concept: Machine NFT

​
Cross-chain contracts

​
MachineNFTAdapter (peaq)

Wraps MachineNFT for LayerZero V2 bridging. Lock/unlock pattern: locks the NFT on peaq while the mirror exists on the destination chain. Needed only when bridging from peaq. SDK methods: bridgeNft / bridge_nft when source is "peaq"

​
MachineNFTBase (Base)

Standard ONFT721 on Base. Burn/mint pattern: NFT is burned when bridged back to peaq. Needed when bridging from Base. SDK methods: bridgeNft / bridge_nft when source is "base" (pass the address as baseNftAddress / base_nft_address)

​
ERC-4337 smart accounts

​
MachineAccountFactory

CREATE2 factory for deploying MachineSmartAccount BeaconProxy instances. Standard ERC-4337 flow: smart accounts run through the canonical EntryPoint at 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789 (same address across all EVM networks). SDK methods: deploySmartAccount / deploy_smart_account, getSmartAccountAddress / get_smart_account_address

​
MachineSmartAccount

The shared BeaconProxy implementation behind deployed smart accounts. Handles owner/machine RBAC and broad machine execution authority. Users never interact with the implementation address directly; calls go to the deployed proxy.

​
AdminFlags

Optional peaq-chain contract read by the MCR API server (not the SDK). Holds admin-set flags that modify MCR responses: per-machine negative_flags and trust-level overrides. MCR consumers see the adjusted score in their API response. When the contract isn’t configured, contracts.admin_flags on GET /ready returns false and the service serves unmodified MCR. See API overview.

​
Precompiles (peaq chain)

PrecompileAddressPurpose
DID0x0000000000000000000000000000000000000800Read/write DID attributes. Used for Machine Card metadata and proxy-operator fleet attributes
Batch0x0000000000000000000000000000000000000805Atomic multi-call for bonding (registration + stake) and proxy DID writes
WPEAQ0x0000000000000000000000000000000000000809Wrapped PEAQ used internally by IdentityStaking as the staking token

​
LayerZero endpoints

Used by the bridge adapters. You don’t set these directly; the SDK handles them.
NetworkLayerZero V2 endpointEID
peaq mainnet0x6F475642a6e85809B1c36Fa62763669b1b48DD5B30302
Base mainnet0x1a44076050125825900e736c501f859c50fE728c30184
The SDK exports the EIDs as LAYER_ZERO_EIDS (JS) / LAYERZERO_EIDS (Python) for reference.

​
Upgrade pattern

All core contracts (IdentityRegistry, IdentityStaking, EventRegistry, MachineNFT) use OpenZeppelin UUPS upgradeable proxies with ERC-7201 namespaced storage. Implementation slots are kept distinct by namespace, so future upgrades won’t collide with existing state. MachineSmartAccount uses a BeaconProxy pattern: a single implementation upgrade simultaneously applies to every deployed smart account.

​
See also

Install

Wire the contract addresses into .env for the SDK.

SDK reference

Every method that reads or writes these contracts.

API reference

Off-chain reads derived from the on-chain state.