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

# DID Document

A Decentralized Identifier is at the core of how a machine is represented on-chain. A thorough understanding must be had before a machine can be on-boarded to ensure proper compliance for maximum interoperability.

# Definition

A **Decentralized Identifier (DID) Document** is a structured data object that represents a **DID-based identity** on a blockchain. It acts as a **verifiable and tamper-proof** way to authenticate and authorize entities such as users, organizations, and machines in decentralized ecosystems.

The **peaq network** relies on DID Documents to manage and verify identities, following the [W3C DID Specification](https://www.w3.org/TR/did-1.0/).

DID Documents may include:

* **ID:** A unique string associated with an entity (machine, organization, user, etc.) built using the author's wallet public key.
* **Controller:** The entity that has control over the DID Document (owner of corresponding private key used to trigger the create DID transaction).
* **Verification Methods:** Cryptographic keys or other mechanisms to prove identity.
* **Signature:** A cryptographic proof ensuring integrity and authenticity of the DID Document, preventing tampering.
* **Service Endpoints:** Links to off-chain data, APIs, or metadata that enhance the DID’s functionality.

By eliminating centralized identity authorities (e.g., governments, corporations), DID Documents enable **self-sovereign identities**, allowing individuals and machines to control and prove their identity securely.

## Storing Machine Data Using a DID Document

Decentralized machine identities allow machines to operate autonomously while proving ownership, signing data, and interacting securely within a decentralized system. On **EVM** and **Substrate** chains,
machines can leverage **EcdsaSecp256k1, Ed25519, and Sr25519** cryptographic methods to sign messages and validate their identity. These algorithms are the core mechanisms used to generate and secure wallets in their respective ecosystems. [EVM](https://ethereum.org/en/developers/docs/accounts/#account-creation) chains
allow wallet creation with the `EcdsaSecp256k1` algorithm while [Substrate](https://polkadot.js.org/docs/keyring/start/basics) offers `Ed25519`, `Sr25519`, and `Ecdsa`.

This page provides an overview of how a **machine** can generate and store signed data in a **DID Document**, while also defining its **owner** and linking to **off-chain metadata**.

### Machine Signing & Verification in a DID Document

A machine with its own **public/private key pair** can sign a message and store a proof in its **DID Document**. This signed data ensures that the machine can verify its own identity and that any data it submits is authenticated.

A Verifiable DID Document could include:

1. **Verification Method:** Defines the cryptographic public key associated with the machine.
2. **Signature:** A signed message proving ownership and authentication.
3. **Service Field:**
   * **Owner Information:** DID of the entity that owns the machine.
   * **Metadata Endpoint:** A storage reference for additional machine-related data (e.g., logs, configurations, historical actions).

### Examples Machine DID Document

<CodeGroup>
  ```javascript EVM theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "id": "did:peaq:0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "controller": "did:peaq:0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "verificationMethod": [
      {
        "id": "did:peaq:0x742d35Cc6634C0532925a3b844Bc454e4438f44e#keys-1",
        "type": "EcdsaSecp256k1RecoveryMethod2020",
        "controller": "did:peaq:0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "publicKeyMultibase": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
      }
    ],
    "authentication": [
      "did:peaq:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Qn#keys-1"
    ],
    "signature": {
      "type": "EcdsaSecp256k1Signature2019",
      "issuer": "did:peaq:0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "hash": "0x5f2b7c5e5a1d3a65b9b67b9f2a6e2a8723f5d2b4e7d82b6a5f8e7b4d2f2b6e5a"
    },
    "service": [
      {
        "id": "#metadata",
        "type": "DataStorage",
        "serviceEndpoint": "ipfs://QmT5NvUtoM5nXBgGR2Fz3dRhFtrD4K1PzBEXm1PGRfZgm5"
      },
      {
        "id": "#owner",
        "type": "Owner",
        "data": "did:peaq:0x3F5CE5FBFe3E9af3971dD833D26BA9b5C936F0bE"
      }
    ]
  }
  ```

  ```javascript Substrate theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  {
    "id": "did:peaq:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Qn",
    "controller": "did:peaq:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Qn",
    "verificationMethod": [
      {
        "id": "did:peaq:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Qn#keys-1",
        "type": "Ed25519VerificationKey2020",
        "controller": "did:peaq:5Df42mkztLtkksgQuLyYV6hmhzdjYvDknoxHv1QBkaY12Qn",
        "publicKeyMultibase": "z6MkngYwTj4bW2nY9qHyyTjUEZGqDNRc5cVoXwYFjzwPrXbm"
      },
    ],
    "authentication": [
      "did:peaq:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Qn#keys-1"
    ],
    "signature": {
      "type": "Ed25519VerificationKey2020",
      "issuer": "did:peaq:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Qn",
      "hash": "0x5f2b7c5e5a1d3a65b9b67b9f2a6e2a8723f5d2b4e7d82b6a5f8e7b4d2f2b6e5a"
    },
    "service": [
      {
        "id": "#metadata",
        "type": "DataStorage",
        "serviceEndpoint": "ipfs://QmT5NvUtoM5nXBgGR2Fz3dRhFtrD4K1PzBEXm1PGRfZgm5"
      },
      {
        "id": "#owner",
        "type": "Owner",
        "data": "did:peaq:5H6JkCkybXvKePVoDNFJVBYDHBfStUESSC62QxSpgcS7FFFe"
      }
    ]
  }
  ```
</CodeGroup>

### Breaking Down the Key Components

1. Machine’s Cryptographic Identity
   * The `verificationMethod` field includes the machine’s public keys for different signature schemes:
     * **EcdsaSecp256k1:** Common method in EVM-based chains to produce a signature from a KeyPair.
     * **Ed25519:** Used for fast verification with high security derived from a Substrate Wallet KeyPair.

2. Authentication
   * Specifies which keys can be used to authenticate the entity (e.g., signing transactions, logging in, proving identity).
   * This is **required** for a DID owner to verify themselves.

3. Signature

   * The `signature` field contains:
     * **Type:** Specifies the algorithm (`EcdsaSecp256k1Signature2019`, `Ed25519VerificationKey2020`)
     * **Issuer:** The DID of the machine that signed the data.
     * **Hash:** The cryptographic hash of the signed message.

   This ensures that the **machine itself/administrator signed the DID Document** and that it remains untampered.

4. Service Fields: Linking to External Data.
   * `#metadata` (DataStorage):
     * Points to **off-chain storage** (IPFS in this case) containing **machine metadata.**
     * Could include **technical specifications, sensor logs, historical events.**
   * `#owner` (Owner Field):
     * Stores the **DID of the machine’s owner** (a user, company, or another entity).
     * Verifies that the machine is assigned to a specific **controlling entity.**

These fields are modular and up to the DePIN creator to set relevant verification methods, signatures, and services that align with their project scope.