Smart contracts

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

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.
( by IdentityRegistry) and (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 .

peaq mainnet addresses

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

Core

Contract	Variable	Address
IdentityRegistry	`IDENTITY_REGISTRY_ADDRESS`	`0xb53Af985765031936311273599389b5B68aC9956`
IdentityStaking	`IDENTITY_STAKING_ADDRESS`	`0x11c05A650704136786253e8685f56879A202b1C7`
EventRegistry	`EVENT_REGISTRY_ADDRESS`	`0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA`
MachineNFT	`MACHINE_NFT_ADDRESS`	`0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9`

Precompiles

Contract	Variable	Address
DID	`DID_REGISTRY_ADDRESS`	`0x0000000000000000000000000000000000000800`
Batch	`BATCH_PRECOMPILE_ADDRESS`	`0x0000000000000000000000000000000000000805`
WPEAQ	n/a	`0x0000000000000000000000000000000000000809`

Optional

Contract	Variable	Address	Needed for
MachineAccountFactory	`MACHINE_ACCOUNT_FACTORY_ADDRESS`	`0x4A808d5A90A2c91739E92C70aF19924e0B3D527f`	`deploySmartAccount` / `getSmartAccountAddress`
MachineNFTAdapter	`MACHINE_NFT_ADAPTER_ADDRESS`	`0x9AD5408702EC204441A88589B99ADfC2514AFAE6`	`bridgeNft` from peaq
AdminFlags	`ADMIN_FLAGS_ADDRESS`	`0x1c5f33fBEE6BA38ed9bDE247C1Ba89A2116C25f1`	MCR API server (negative-flag reads + admin trust overrides)

Base mainnet addresses

Needed when bridging into peaq from . Pass as baseNftAddress / base_nft_address to bridgeNft / bridge_nft.

Contract	Address
MachineNFTBase (LayerZero ONFT)	`0xee8A521eA434b11F956E2402beC5eBfa753Babfa`

Agung testnet addresses

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

Core

Contract	Variable	Address
IdentityRegistry	`IDENTITY_REGISTRY_ADDRESS`	`0x9E9463a65c7B74623b3b6Cdc39F71be7274e5971`
IdentityStaking	`IDENTITY_STAKING_ADDRESS`	`0x55f336714aDb0749DbFE33b057a1702405564E3d`
EventRegistry	`EVENT_REGISTRY_ADDRESS`	`0x2DAD8905380993940e340C5cE6d313d5c2780040`
MachineNFT	`MACHINE_NFT_ADDRESS`	`0xB41C2A4f1c19b6B06beaAce0F5CD8439e77C4b1c`

Precompiles

Identical to mainnet: same fixed addresses on every peaq runtime.

Contract	Variable	Address
DID	`DID_REGISTRY_ADDRESS`	`0x0000000000000000000000000000000000000800`
Batch	`BATCH_PRECOMPILE_ADDRESS`	`0x0000000000000000000000000000000000000805`
WPEAQ	n/a	`0x0000000000000000000000000000000000000809`

Optional

Contract	Variable	Address	Needed for
MachineAccountFactory	`MACHINE_ACCOUNT_FACTORY_ADDRESS`	`0x65a4DfEB799dFf8CF15f13816d648a7805d6b1F9`	`deploySmartAccount` / `getSmartAccountAddress`
AdminFlags	`ADMIN_FLAGS_ADDRESS`	`0x4181a2Aa34aFb247450FfcBd65be5aBD4Cbee658`	MCR API server (negative-flag reads + admin trust overrides)

Bridging cannot be exercised on agung. LayerZero deprecated the agung endpoint (EID 40299): DVNs and executors are no longer active, so bridgeNft / bridge_nft cannot relay. No agung MachineNFTAdapter appears in peaq deployment records — the address previously listed here (0x63fD…8De22) is actually the MachineAccountFactory’s UpgradeableBeacon (verifiably the factory’s nonce-2 contract creation). 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 and orchestrates through IdentityStaking.stakeFor(). Implements ERC-8004 so that each Identity NFT’s tokenURI resolves to the machine’s DID-anchored Machine Card. 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) . 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 or the . Stores a keccak256 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 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 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 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 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)

Precompile	Address	Purpose
DID	`0x0000000000000000000000000000000000000800`	Read/write DID attributes. Used for Machine Card metadata and proxy-operator fleet attributes
Batch	`0x0000000000000000000000000000000000000805`	Atomic multi-call for bonding (registration + stake) and proxy DID writes
WPEAQ	`0x0000000000000000000000000000000000000809`	Wrapped 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.

Network	LayerZero V2 endpoint	EID
peaq mainnet	`0x6F475642a6e85809B1c36Fa62763669b1b48DD5B`	`30302`
Base mainnet	`0x1a44076050125825900e736c501f859c50fE728c`	`30184`

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.

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.

Welcome

Get Started

Concepts

Functions

Guides

Smart contracts

Architecture

peaq mainnet addresses

Core

Precompiles

Optional

Base mainnet addresses

Agung testnet addresses

Core

Precompiles

Optional

Core contracts

IdentityRegistry

IdentityStaking

EventRegistry

MachineNFT

Cross-chain contracts

MachineNFTAdapter (peaq)

MachineNFTBase (Base)

ERC-4337 smart accounts

MachineAccountFactory

MachineSmartAccount

AdminFlags

Precompiles (peaq chain)

LayerZero endpoints

Upgrade pattern

See also

Install

SDK reference

API reference

​Architecture

​peaq mainnet addresses

​Core

​Precompiles

​Optional

​Base mainnet addresses

​Agung testnet addresses

​Core

​Precompiles

​Optional

​Core contracts

​IdentityRegistry

​IdentityStaking

​EventRegistry

​MachineNFT

​Cross-chain contracts

​MachineNFTAdapter (peaq)

​MachineNFTBase (Base)

​ERC-4337 smart accounts

​MachineAccountFactory

​MachineSmartAccount

​AdminFlags

​Precompiles (peaq chain)

​LayerZero endpoints

​Upgrade pattern

​See also

Install

SDK reference

API reference

Architecture

peaq mainnet addresses

Core

Precompiles

Optional

Base mainnet addresses

Agung testnet addresses

Core

Precompiles

Optional

Core contracts

IdentityRegistry

IdentityStaking

EventRegistry

MachineNFT

Cross-chain contracts

MachineNFTAdapter (peaq)

MachineNFTBase (Base)

ERC-4337 smart accounts

MachineAccountFactory

MachineSmartAccount

AdminFlags

Precompiles (peaq chain)

LayerZero endpoints

Upgrade pattern

See also