Tier 1

Verify machine-origin data with Tier 1 authentication. Register a machine DID, sign and store its data, then retrieve and check the signature.

Tier 1 verification, machine-origin authentication, proves that data came from a specific machine and has not been altered. The machine signs its own data, and anyone can check that signature against the machine’s onchain identity.

Overview

• Registration: the machine is registered onchain with a DID.
• Data generation and signing: the machine generates data and signs it with its private key.
• Data storage: the signed payload is written to chain storage.
• Retrieval and verification: any party reads the payload back and checks the signature.

Prerequisites

• A Node.js environment.
• The @peaq-network/sdk, @polkadot/keyring, @polkadot/util, and @polkadot/util-crypto packages installed.
• A seeds.json file holding the owner’s and the machine’s account seeds. Both accounts need agung tokens for fees: the owner signs the registration in step 1 and the machine signs the storage write in step 3. See Get test tokens.

1. Registration

The owner registers the machine onchain, creating the identity the rest of the flow verifies against.

// import necessary libraries
import { Sdk } from "@peaq-network/sdk";
import Keyring from "@polkadot/keyring";
import fs from "fs/promises";

const register = async () => {
  const seeds = JSON.parse(await fs.readFile("seeds.json", "utf8"));
  const ownerSeed = seeds.owner;
  const machineSeed = seeds.machine;

  const sdkInstance = await Sdk.createInstance({
    baseUrl: "wss://wss-async-agung.peaq.xyz",
    seed: ownerSeed,
  });

  const keyring = new Keyring({ type: "sr25519" });
  const machinePair = keyring.addFromUri(machineSeed);

  // Register the machine's DID
  await sdkInstance.did.create(
    { name: `did:peaq:${machinePair.address}`, address: machinePair.address },
    (result) => {
      // handle result
    }
  );

  await sdkInstance.disconnect();
};

register();

2. Data generation and signing

The machine signs the data it generates with its private key. Signing happens inside the machine, so the snippet below only illustrates the shape of that step.

// Hypothetical snippet for data generation and signing
import Keyring from "@polkadot/keyring";
import { hexToU8a, stringToHex, u8aToHex } from "@polkadot/util";
import { cryptoWaitReady } from "@polkadot/util-crypto";

// Simulated machine data generation and signing
const generateAndSignData = async (machineSeed) => {
  await cryptoWaitReady();
  const machineKeypair = new Keyring({ type: "sr25519" }).addFromUri(machineSeed);
  const data = "Machine-generated data";
  const dataHex = stringToHex(JSON.stringify(data));
  const signature = machineKeypair.sign(hexToU8a(dataHex));

  return { dataHex, signature: u8aToHex(signature) };
};

3. Data storage

The signed payload goes into chain storage, where anyone can read it back.

// import necessary libraries
import fs from "fs/promises";
import { Sdk } from "@peaq-network/sdk";
import Keyring from "@polkadot/keyring";
import { hexToU8a, stringToHex, u8aToHex } from "@polkadot/util";

// Storage key shared by the writer (this step) and the reader (step 4)
const ITEM_TYPE = "tier1-data";

const store = async () => {
  const seeds = JSON.parse(await fs.readFile("seeds.json", "utf8"));
  const machineSeed = seeds.machine;

  // The machine signs the extrinsic, so the item is stored under the machine's address
  const sdkInstance = await Sdk.createInstance({
    baseUrl: "wss://wss-async-agung.peaq.xyz",
    seed: machineSeed,
  });

  const machineKeypair = new Keyring({ type: "sr25519" }).addFromUri(machineSeed);
  const dataHex = stringToHex(JSON.stringify("test-data"));
  const signature = u8aToHex(machineKeypair.sign(hexToU8a(dataHex)));

  // A storage item is limited to 256 bytes
  await sdkInstance.storage.addItem({
    itemType: ITEM_TYPE,
    item: { data: dataHex, signature: signature },
  });

  await sdkInstance.disconnect();
};

store();

4. Retrieval and verification

Any network participant reads the payload back and checks the signature against the public key of the machine’s identity.

// import necessary libraries
import fs from 'fs/promises';
import { Sdk } from '@peaq-network/sdk';
import Keyring from '@polkadot/keyring';
import { hexToU8a } from '@polkadot/util';
import { cryptoWaitReady, decodeAddress, signatureVerify } from '@polkadot/util-crypto';

// Same storage key the machine wrote in step 3
const ITEM_TYPE = 'tier1-data';

const verifyData = (publicKey, dataHex, signatureHex) => {
  const dataU8a = hexToU8a(dataHex);
  const signatureU8a = hexToU8a(signatureHex);

  return signatureVerify(dataU8a, signatureU8a, publicKey).isValid;
};

const verify = async () => {
  // A verifier only needs the machine's address; it is derived from seeds.json here for brevity
  await cryptoWaitReady();
  const seeds = JSON.parse(await fs.readFile('seeds.json', 'utf8'));
  const machineAddress = new Keyring({ type: 'sr25519' }).addFromUri(seeds.machine).address;

  const sdkInstance = await Sdk.createInstance({
    baseUrl: 'wss://wss-async-agung.peaq.xyz',
  });

  const result = await sdkInstance.storage.getItem({
    itemType: ITEM_TYPE,
    address: machineAddress,
  });
  await sdkInstance.disconnect();

  if (!result) {
    throw new Error('Data not found.');
  }

  const { data: dataHex, signature: signatureHex } = JSON.parse(result[ITEM_TYPE]);

  // The machine's public key is encoded in its address
  const publicKey = decodeAddress(machineAddress);
  const isValid = verifyData(publicKey, dataHex, signatureHex);

  if (isValid) {
    console.log('Data verified successfully.');
  } else {
    console.log('Verification failed.');
  }
};

verify();

Handling keys

The examples read account seeds from a seeds.json file for brevity. Keep machine and owner seeds out of source control and out of shared machines: anyone holding the machine seed can sign data as that machine.