> ## 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

> LayerZero V2 ONFT that anchors a machine's identity and links to its credit history.

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`:

| Token        | Contract         | Token ID                                       | Purpose                                                      | Transferability                                                              |
| :----------- | :--------------- | :--------------------------------------------- | :----------------------------------------------------------- | :--------------------------------------------------------------------------- |
| Identity NFT | IdentityRegistry | Equal to `machineId`                           | On-chain identity credential, governs protocol authorization | Soulbound: transfers revert with `IdentityNFTSoulbound`                      |
| Machine NFT  | MachineNFT       | Independent tokenId (not equal to `machineId`) | Financial digital twin, carries MCR and revenue metadata     | Transfer 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.

<Warning>
  **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)`.
</Warning>

## 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}`:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
  "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/{did}](/peaqos/api-reference/get-machine) or [GET /mcr/{did}](/peaqos/api-reference/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:

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Steps>
  <Step title="Query tokenURI">
    A consumer or marketplace calls `tokenURI(tokenId)` on the **MachineNFT** contract and receives the metadata URL.
  </Step>

  <Step title="Fetch metadata">
    The consumer calls [`GET /metadata/{token_id}`](/peaqos/api-reference/get-metadata) on the MCR API.
  </Step>

  <Step title="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}`](/peaqos/api-reference/get-machine): the full machine profile.
  </Step>
</Steps>

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](#machine-card) (ERC-8004 registration document) lives at a separate endpoint: [`GET /machines/{machine_id}`](/peaqos/api-reference/get-machine-card).

## Cross-chain portability

<Note>
  **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.
</Note>

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.

<CardGroup cols={3}>
  <Card title="peaq (home)" icon="house">
    Canonical Machine NFT contract. Minting and DID linking happen here. Bridging out locks the NFT in `MachineNFTAdapter`; bridging back unlocks it.
  </Card>

  <Card title="Base" icon="arrow-right-arrow-left">
    Bridged destination via LayerZero V2 ONFT. Bridging in mints; bridging back to peaq burns.
  </Card>

  <Card title="Additional peaqOS chains" icon="globe">
    More bridge destinations are added as peer contracts deploy.
  </Card>
</CardGroup>

<div className="text-center text-sm text-gray-500 dark:text-zinc-500 -mt-2 mb-4">
  peaq is the home chain. peaq → Base locks on peaq + mints on Base; Base → peaq burns on Base + unlocks on peaq.
</div>

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.

## Cross-links

* [peaqID](/peaqos/concepts/peaqid) is the DID linked to the Machine NFT via the `nftTokenId` attribute
* [GET /metadata/{token_id}](/peaqos/api-reference/get-metadata) returns the full NFT metadata JSON
* [Activate function](/peaqos/functions/activate) handles the minting flow during onboarding