Fleet onboarding (operator-controlled)

Activate and manage many machines from one operator under Economics 2.0: each machine owns its NFT and pays its bond, the operator is its DID controller.

One operator, many machines. Under Economics 2.0 the account that signs activateMachine becomes the machine’s owner and pays its bond, so a fleet is built the other way round from Tokenomics 1.0: each machine signs its own activation with its own key, and your operator address is recorded as the machine’s DID controller. The operator then runs lifecycle, renewals, and DID updates for the whole fleet.

Economics 2.0 has no operator-sponsored activation. MachineStateAndSync.activateMachine makes msg.sender both owner and payer, so registerFor / register_for throws SPONSORED_ACTIVATION_UNSUPPORTED in Tokenomics mode. Do not make the operator the owner instead: the owner is the account that can transfer the NFT.

Rights in the machine-owned, operator-controlled model

Who	Can	Cannot
Machine wallet (owner)	Transfer the NFT; rotate or clear the controller; everything the controller can
Operator (controller)	Suspend and resume; renew the subscription (paying from the operator wallet); update verification methods, authentication, and service endpoints	Transfer the NFT; rotate or clear the controller

Credits from renewals (bonding reward and voucher credit) land on the owner, even when the controller pays. Both parties should know this before onboarding.

Prerequisites

• Node.js ≥ 22 with @peaqos/peaq-os-sdk 0.8.0+ and dotenv (npm i @peaqos/peaq-os-sdk dotenv; the examples use top-level await, so run them as an ES module), or Python 3.10+ with peaq-os-sdk 0.8.0+ and python-dotenv (pip install peaq-os-sdk python-dotenv), or peaq-os-cli 0.0.13+
• An operator wallet for gas (it signs nothing during activation, but signs later renewals and DID updates)
• Each machine wallet funded with its tier bond plus gas. The bond is quoted per tier at the daily oracle rate: preview one activation first and fund every machine to that amount plus a gas margin. The operator can fund machine wallets from the Gas Station (2FA-gated) for gas and top up the bond from any PEAQ-holding address.
• Environment variables configured per the install guide

JS examples load .env via import "dotenv/config". Python’s from_env() reads from the shell, so export the file first with set -a && source .env && set +a or call load_dotenv().

From the terminal

The CLI does one machine per command. --for and --machine-key switch to machine-owned mode: the machine key signs and pays, and your configured signer (the PEAQOS_OWS_WALLET wallet or the PEAQOS_PRIVATE_KEY address) becomes controller.

Each --machine-key file holds one line: the machine’s 0x-prefixed 64-hex private key. To make one and print the address to pass to --for (the file is created readable only by your user and never overwritten):

python3 -c 'import os; from peaq_os_sdk import PeaqosClient; a,k=PeaqosClient.generate_keypair(); fd=os.open("machine.key",os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600); os.write(fd,(k+"\n").encode()); os.close(fd); print(a)'

The key file is the machine’s owner key: keep it on the device or in a secrets vault.

peaqos activate \
  --for 0xMachineAddress --machine-key ./machine.key \
  --machine-type Sensor --credential-subject-hex 0x<per-machine-anchor> \
  --manufacturer 0x3333333333333333333333333333333333333333 \
  --tier entry --did-document ./did.json --dry-run     # drop --dry-run to submit

Loop it over your key files with --json --yes --skip-funding for scripts, after funding each machine wallet with its bond plus gas. Without --skip-funding, a machine wallet under 0.5 PEAQ makes the CLI enroll that machine’s address in the Gas Station and wait for an authenticator code, which --yes does not answer. If your signer is an OWS wallet, export OWS_PASSPHRASE too. Afterwards the operator manages every machine with peaqos machine ... (status, suspend, resume, subscription renew, DID setters). See CLI: activate and CLI: machine. --for and --machine-key are rejected with --chain solana: a machine homed on Solana is owned by its Solana owner wallet and linked to the peaq operator wallet that reserved it and paid its bond. See Onboard a machine on Solana.

Single machine, from code

1. Create the operator client

   Used for funding, previews, and later management. It never signs an activation.

   JS/TS

   import "dotenv/config";
   import { PeaqosClient, type ActivateMachineParams } from "@peaqos/peaq-os-sdk";
   
   const operator = PeaqosClient.fromEnv();
   console.log("Operator:", operator.address);
   
2. Generate a keypair for the machine

   Each machine needs its own address. Store the key on the device or in a secrets vault: it is the owner key of that machine’s NFT.

   JS/TS

   const machineKey = PeaqosClient.generateKeypair();
   console.log("Machine address:", machineKey.address);
   
3. Fund the machine wallet

   Gas from the Gas Station (2FA on the operator wallet), the bond from any PEAQ-holding address.

   JS/TS

   const FAUCET_URL = "https://depinstation.peaq.xyz";
   
   await operator.fundFromGasStation(
     { ownerAddress: operator.address, targetWalletAddress: machineKey.address, chainId: "peaq", twoFactorCode: "654321" },
     FAUCET_URL,
   );
   // Then transfer the previewed netPeaqAmount (plus a margin) to machineKey.address from your treasury wallet.
   
4. Build the machine client in Tokenomics mode

   JS/TS

   const machine = new PeaqosClient<"tokenomics20">({
     rpcUrl: operator.rpcUrl,
     privateKey: machineKey.privateKey,
     contracts: operator.contracts,
     tokenomics20: { deploymentId: "peaq-mainnet" },
   });
   
5. Activate with the operator as controller

   controller is the operator address. The machine signs, owns the NFT, and pays the bond.

   JS/TS

   const params: ActivateMachineParams = {
     controller: operator.address,
     verificationMethods: [{ id: "#key-1", methodType: "Ed25519VerificationKey2020", controller: operator.address, publicKeyMultibase: "z6Mk..." }],
     authentication: [0n],
     serviceEndpoints: [{ id: "#docs", serviceType: "peaq-documentation", serviceEndpoint: "https://example.com/docs" }],
     machineType: "Sensor",
     credentialSubject: "0x<per-machine-anchor>",
     manufacturer: "0x3333333333333333333333333333333333333333",
     tier: 0,
   };
   
   const preview = await machine.previewMachineActivation(params);
   const result = await machine.activateMachine(params);
   console.log("machine", result.machineId.toString(), "owner", result.owner, "controller", result.controller);
   
6. Manage from the operator client

   From here the operator client (constructed with the same tokenomics20 deployment) runs the fleet. Renewals paid by the operator credit the owner.

   JS/TS

   const ops = new PeaqosClient<"tokenomics20">({ rpcUrl: operator.rpcUrl, privateKey: process.env.PEAQOS_PRIVATE_KEY!, contracts: operator.contracts, tokenomics20: { deploymentId: "peaq-mainnet" } });
   
   const state = await ops.getMachineManagementState(result.machineId);
   await ops.suspendMachine(result.machineId);
   await ops.resumeMachine(result.machineId);
   
   const renewal = await ops.previewMachineRenewal({ machineId: result.machineId, payment: "peaq" });
   await ops.renewMachine({ machineId: result.machineId, payment: "peaq", maxNetPeaqAmount: renewal.netPeaqAmount });
   
   await ops.setMachineServiceEndpoints(result.machineId, [
     { id: "#docs", serviceType: "peaq-documentation", serviceEndpoint: "https://example.com/docs/v2" },
   ]);
   

Batch activation

Activate machines sequentially; each iteration builds a machine client from that machine’s key and records the operator as controller. Persist every returned machine ID: MachineRegistry does not enumerate a fleet.

JS/TS

import "dotenv/config";
import { PeaqosClient, type ActivateMachineParams } from "@peaqos/peaq-os-sdk";

const operator = PeaqosClient.fromEnv();
const keys = loadMachineKeys(); // your own loader: [{ address, privateKey, credentialSubject }], each funded with bond + gas
const fleet: { address: string; machineId: string }[] = [];

for (const [i, k] of keys.entries()) {
  const machine = new PeaqosClient<"tokenomics20">({
    rpcUrl: operator.rpcUrl, privateKey: k.privateKey, contracts: operator.contracts,
    tokenomics20: { deploymentId: "peaq-mainnet" },
  });
  const params: ActivateMachineParams = {
    controller: operator.address,
    verificationMethods: [{ id: "#key-1", methodType: "Ed25519VerificationKey2020", controller: operator.address, publicKeyMultibase: "z6Mk..." }],
    authentication: [0n],
    serviceEndpoints: [],
    machineType: "Sensor",
    credentialSubject: k.credentialSubject,
    manufacturer: "0x3333333333333333333333333333333333333333",
    tier: 0,
  };
  try {
    const result = await machine.activateMachine(params);
    fleet.push({ address: k.address, machineId: result.machineId.toString() }); // decimal string at the JSON boundary
    console.log(`[${i + 1}/${keys.length}] activated ${k.address} as ${result.machineId}`);
  } catch (err) {
    console.error(`[${i + 1}/${keys.length}] failed for ${k.address}:`, err);
    // A RECEIPT_UNAVAILABLE here means the tx may still mine. Never re-run activation for that machine; check getMachineActivationState.
  }
}
// Persist `fleet` to a file or database. It is your fleet index.

Key management

Approach	How it works	Trade-offs
Per-machine key on the device	The device holds its owner key and signs its own activation and, later, its own transactions.	Strongest isolation. Required if the device should ever transfer its NFT or rotate its controller.
Per-machine key in the operator’s vault	The operator generates and stores one key per machine (HSM, secrets manager) and signs activations from a provisioning host.	The machine still owns its NFT on chain; operationally the operator controls both roles. A vault leak exposes the fleet.

A shared owner key for every machine is possible under 2.0 (a wallet may own many machines), but that key can transfer each NFT and rotate each controller, so one leak exposes the whole fleet. Use setMachineApprovalForAll / peaqos machine approve-all if a second address must be able to transfer the fleet’s NFTs.

Fleet queries

queryOperatorMachines / query_operator_machines lists the machines the MCR API holds for an operator DID (did:peaq:0x<operator address>). In Tokenomics mode the client reads that listing from https://mcr.peaq.xyz. For chain state, read each machine by ID from your own index (ops is the operator client from the “Manage from the operator client” step, fleet the index from the batch script):

for m in fleet:
    state = ops.get_machine_management_state(int(m["machine_id"]))
    print(m["machine_id"], state.subscription.status, state.is_available, state.is_relocating)

Error handling

Error	Cause	Resolution
TokenomicsUnsupportedError SPONSORED_ACTIVATION_UNSUPPORTED	registerFor / register_for called in Tokenomics mode	Activate with the machine key and set the operator as controller
TokenomicsActivationError INSUFFICIENT_BALANCE	The machine wallet holds less than the net PEAQ bond	Fund the machine wallet (net bond plus a gas margin), not the operator’s; this check does not reserve gas
TokenomicsActivationError NOT_OWNER_OR_CONTROLLER	Operator tried a management write on a machine that does not list it as controller	Have the owner call setMachineController
TokenomicsActivationError NOT_MACHINE_OWNER	Operator tried setMachineController or a clear-controller	Owner-only operations; sign with the machine key
TokenomicsActivationError ERC721_INSUFFICIENT_APPROVAL	The transfer signer is neither the owner nor an approved address	Sign with the machine key, or have the owner approve the signer (setMachineApprovalForAll / peaqos machine approve-all)
TokenomicsPendingTransactionError PENDING_TRANSACTION (Python) / TokenomicsActivationError RECEIPT_UNAVAILABLE (JS)	Receipt did not arrive in time	Never resubmit; reconcile the recorded hash

Full code tables on errors.

Fleets onboarded before Economics 2.0

Machines registered with registerFor / register_for are Tokenomics 1.0 machines operated by the proxy: the proxy pays the bond and becomes proxy operator, while the Identity NFT is minted to the machine address. They keep working on a client constructed without tokenomics20. The fleet listing above covers Economics 2.0 machines only. peaq mirrors partner fleets into Economics 2.0 through the MachineMigrationHub; see Economics 2.0: legacy machines.