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.

Machine NFT is a LayerZero V2 ONFT, portable across chains by design. It anchors a machine’s identity and links to its credit history.

​
What the Machine NFT represents

The Machine NFT is a financial digital twin, separate from the Identity NFT that IdentityRegistry mints at registration. It carries revenue history, Machine Credit Rating, documentation links, and bond status in its metadata. The two tokens live in different token spaces and are linked by the on-chain machineId:
TokenContractToken IDPurposeTransferability
Identity NFTIdentityRegistryEqual to machineIdOn-chain identity credential, governs protocol authorizationSoulbound: transfers revert with IdentityNFTSoulbound
Machine NFTMachineNFTIndependent tokenId (not equal to machineId)Financial digital twin, carries MCR and revenue metadataTransfer moves the financial representation; identity stays with the machine
Selling or bridging the Machine NFT does not affect the machine’s DID, event submission rights, or protocol authorization.
Machine ID ≠ Machine NFT token ID. The registerMachine SDK method (register() on IdentityRegistry) and registerFor SDK method (registerFor(machineAddress) on IdentityRegistry) both return a machineId. The mintNft(machineId, recipient) SDK method (mint(machineId, recipient) on MachineNFT) results in a different token ID. MachineNFT has its own auto-incrementing tokenId sequence. Read the Machine NFT token ID back with tokenIdOf(machineId).

​
Machine Card

The Machine Card is a peaqOS registration document that follows the ERC-8004 registration file pattern and is served by the MCR API at /machines/{machine_id}: 
{
  "type": "peaqos:registration:v1",
  "name": "Machine #42",
  "description": "peaqOS machine",
  "did": "did:peaq:0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
  "active": true,
  "services": [
    { "name": "web", "endpoint": "https://example.com/machines/42/api" }
  ],
  "data_visibility": "private",
  "documentation_url": "https://example.com/machines/42",
  "operator": "did:peaq:0xOperatorAddress",
  "bond_status": "bonded",
  "event_count": 150,
  "registrations": [
    {
      "type": "peaqos:registration:v1",
      "machineId": 42,
      "machineRegistry": "eip155:3338:0xIdentityRegistryAddress"
    }
  ]
}
For the full MCR score and revenue summary, use GET /machine/ or GET /mcr/; both are computed live by the MCR API on each request.

​
Ownership semantics

Unlike the Identity NFT, the Machine NFT is not minted automatically during registration. It’s a two-step flow owned by the operator or machine:
1

Register

The proxy or machine calls IdentityRegistry’s register() (proxy uses registerFor(machineAddress)) and receives a machineId. IdentityRegistry simultaneously mints the Identity NFT to machineAddress with tokenId == machineId. SDK helpers: registerMachine / registerFor.
2

Mint Machine NFT

The operator or machine then calls MachineNFT’s mint(machineId, recipient). MachineNFT assigns a new, independent tokenId. Read the assigned token ID back with tokenIdOf(machineId). SDK helper: mintNft.
3

Link DID

Call writeMachineDIDAttributes to store machineId and nftTokenId on the machine’s DID, binding the identity to its financial twin. These attribute writes must be signed by the machine’s own key (the DID subject); the proxy can’t write them on the machine’s behalf. Registration does not write them for you.

​
Metadata flow

tokenURI() returns a URL pointing to the MCR API. The API reads onchain events and DID attributes, computes the current MCR score, and returns the full machine profile JSON.
1

Query tokenURI

A consumer or marketplace calls tokenURI(tokenId) on the MachineNFT contract and receives the metadata URL.
2

Fetch metadata

The consumer calls GET /metadata/{token_id} on the MCR API.
3

Compute and return

The API reads onchain events and DID attributes, computes the current MCR score, and returns the same shape as GET /machine/{did}: the full machine profile.
The baseURI is updatable by the protocol admin. If the API domain changes, only the contract’s baseURI is updated. No token migration needed. The lighter Machine Card (ERC-8004 registration document) lives at a separate endpoint: GET /machines/{machine_id}.

​
Cross-chain portability

Supported routes: peaq ↔ Base. Additional peaqOS chains are added as peer contracts deploy. Bridging is mainnet-only: LayerZero V2 has no DVN routes between agung and Base, so bridgeNft / bridge_nft cannot be exercised against the testnet.
The Machine NFT implements the LayerZero V2 ONFT standard. peaq is the home chain: its NFT supply is canonical and uses a lock/unlock adapter (MachineNFTAdapter); destination chains use the standard burn/mint ONFT pattern. Only one live instance exists across the network at any time.

peaq (home)

Canonical Machine NFT contract. Minting and DID linking happen here. Bridging out locks the NFT in MachineNFTAdapter; bridging back unlocks it.

Base

Bridged destination via LayerZero V2 ONFT. Bridging in mints; bridging back to peaq burns.

Additional peaqOS chains

More bridge destinations are added as peer contracts deploy.
peaq is the home chain. peaq → Base locks on peaq + mints on Base; Base → peaq burns on Base + unlocks on peaq.
Key properties:
  • Home chain: peaq. Minting happens on peaq after machine onboarding.
  • Cross-chain: LayerZero V2 ONFT architecture bridges peaq ↔ Base via the MachineNFTAdapter lock/unlock pattern on peaq paired with burn/mint on the destination. Further peaqOS chains are added as peer contracts deploy.
  • Metadata: tokenURI() resolves to the same MCR API URL regardless of which chain holds the NFT.
  • Identity independence: The machine’s peaqID, DID attributes, and event submission stay on peaq regardless of where the NFT sits.
  • peaqID is the DID linked to the Machine NFT via the nftTokenId attribute
  • GET /metadata/ returns the full NFT metadata JSON
  • Activate function handles the minting flow during onboarding