Onboard a machine on Solana

Activate an Economics 2.0 machine whose home chain is Solana: reserve and bond on peaq with an operator wallet, then create the machine on Solana with its owner wallet.

A machine can live on Solana instead of peaq. Its identity record, DID document and Machine NFT are then Solana accounts owned by a Solana key, while the subscription bond and the peaq-side registry entry stay on peaq. Onboarding therefore happens in two places and three phases, in a fixed order: reserve the machine ID on peaq, activate its subscription on peaq, wait for peaq to mirror both to Solana, then create the machine on Solana. The CLI runs one phase per invocation; the SDKs expose the same phases.

Solana support requires CLI 0.0.12 (pip install -U 'peaq-os-cli[solana,ows]') and SDK 0.8.0 (npm install @peaqos/peaq-os-sdk @solana/web3.js @coral-xyz/anchor or pip install -U 'peaq-os-sdk[solana]').

What you need

Item	Notes
CLI or SDK with Solana support	CLI: pip install -U 'peaq-os-cli[solana,ows]>=0.0.12'. Python: pip install "peaq-os-sdk[solana,ows]". JS: @solana/web3.js and @coral-xyz/anchor as peer dependencies.
A peaq operator wallet	Reserves the machine ID and pays the bond and gas on peaq mainnet. Needs PEAQ for gas in every phase; with --payment usdt the bond is paid in USDT on top, not instead.
A Solana owner wallet	Creates the machine on Solana mainnet-beta and pays SOL fees and rent. Needs SOL.
Two RPC endpoints	One for peaq, one for Solana. Choosing a Solana cluster never selects the machine’s home; the flags do.
A DID document	Same three-field JSON as on peaq. Verification-method controllers are base58 Solana keys.

Mainnet only. The Solana half of the deployment record exists for peaq-mainnet; agung-2026-08-28 has none, and there is no testnet walkthrough.

Configure

mkdir -p solana-onboarding && cd solana-onboarding   # one directory per attempt, keep it
export PEAQOS_NETWORK=peaq
export TOKENOMICS_DEPLOYMENT_ID=peaq-mainnet
export PEAQOS_RPC_URL=https://peaq.api.onfinality.io/public
export PEAQOS_SVM_NETWORK=mainnet-beta
export PEAQOS_SVM_RPC_URL=https://api.mainnet-beta.solana.com

Every CLI client, keyless previews included, also needs the six Tokenomics 1.0 contract addresses: run peaqos init in this directory first (or copy a .env that has them), otherwise the first preview exits 3 naming IDENTITY_REGISTRY_ADDRESS. --svm-rpc-url and --svm-network before the command name override the environment, which overrides .env. peaqos whoami shows the cluster and a redacted RPC origin once either variable is set. Keep the SDK journal peaqos.log and the original inputs in this directory for every later phase: the journal is what lets a rerun reconcile instead of resubmitting. Use one directory per machine. The Solana journal check collects unparseable lines before it filters by machine, so a single bad line, whichever machine wrote it, refuses every machine in that directory. The peaq journal skips such lines instead.

Create the two wallets in the OWS vault and note their public addresses. Fund them yourself; wallet creation does not.

peaqos wallet create svm-operator     # peaq address pays gas and the bond
peaqos wallet create svm-owner        # Solana address pays fees and rent
peaqos wallet show svm-owner --json
unset PEAQOS_PRIVATE_KEY              # let the selected OWS wallet sign

The DID document

Save as native-did.json. authentication entries are zero-based indices into verificationMethods. The optional machine-level controller is a separate flag (--solana-controller), not a field here.

{
  "verificationMethods": [
    {
      "id": "#key-1",
      "methodType": "Ed25519",
      "controller": "<base58 Solana public key>",
      "publicKeyMultibase": "<multibase public key>"
    }
  ],
  "authentication": [0],
  "serviceEndpoints": [
    { "id": "#telemetry", "serviceType": "Telemetry", "serviceEndpoint": "https://example.com/telemetry" }
  ]
}

Limits come from the Solana program: 8 verification methods, 8 authentication indices, 8 service endpoints, 128 UTF-8 bytes per string field, 64 bytes for the machine type, 512 bytes of credential subject. Oversized input is rejected before anything is signed; nothing is truncated.

The argument set

Every phase takes the same complete arguments. A changed machine type or credential computes a different machine ID, so the CLI treats it as a new attempt with its own journal entries instead of continuing this one; a changed wallet or ceiling on the same machine ID is refused. Keep the original inputs. Ceilings are explicit integers in base units; 0 is a strict cap, never “unlimited”; the USDT cap is enforced on chain, the PEAQ cap is checked before signing and against the mined receipt.

Set the ten shell variables first (OWNER, OPERATOR, MANUFACTURER, CREDENTIAL_SUBJECT_HEX, PEAQ_CAP, FEE_CAP, RENT_CAP, HISTORY_START = the peaq block number just before your reservation, COMPUTE_LIMIT, PRIORITY_PRICE); the :? guards make the shell stop on an unset one instead of passing an empty argument.

ARGS=(
  --chain solana --json
  --solana-owner "${OWNER:?}"                       # base58, the Solana owner wallet
  --evm-operator "${OPERATOR:?}"                    # 0x…, the peaq operator wallet
  --manufacturer "${MANUFACTURER:?}"                # base58, recorded without verification
  --machine-type Sensor
  --credential-subject-hex "${CREDENTIAL_SUBJECT_HEX:?}"
  --tier basic --did-document ./native-did.json
  --payment peaq --max-net-peaq-amount "${PEAQ_CAP:?}"
  --max-native-fee-lamports "${FEE_CAP:?}"          # network + priority fees, excludes rent
  --max-native-rent-lamports "${RENT_CAP:?}"        # machine + state account rent
  --from-block "${HISTORY_START:?}"                 # inclusive peaq block where this attempt's history starts
  --compute-unit-limit "${COMPUTE_LIMIT:?}"         # 1 to 1,400,000
  --compute-unit-price-micro-lamports "${PRIORITY_PRICE:?}"
)

Flag	Meaning
--chain solana	Home the machine on Solana. Without it peaqos activate is the one-transaction peaq flow.
--phase	reservation, subscription, or native_onboarding. Required for a write; omit it with --dry-run to preview the whole plan.
--solana-owner	Required. The reserved owner’s base58 public key.
--solana-controller	Optional. Omit for the owner-only default.
--evm-operator	Optional assertion, checked against the reservation. Omit to use the matching reservation or the configured wallet.
--max-net-peaq-amount or --max-usdt-amount	Required ceiling for the selected payment asset. With --payment usdt, --max-usdt-amount replaces --max-net-peaq-amount. USDT needs the deployment’s foreign-funding support and must be chosen before the first phase.
--max-native-fee-lamports, --max-native-rent-lamports	Required. Fees exclude rent; rent excludes external delivery rent.
--from-block	Required. Inclusive peaq history start covering the original attempt. Use the peaq block just before your reservation: the SDK reads the reservation history from CrossChainMirror with eth_getLogs from this block to the current block, and a start far in the past (or 0) is rejected or timed out by the public peaq RPCs (READ_FAILED).
--compute-unit-limit, --compute-unit-price-micro-lamports	Required native compute budget and priority price.

Tier entry is not offered on Solana: basic or pro. --for, --machine-key, and --slippage-bps are rejected with --chain solana. The machine ID is the same derivation as on peaq, uint256(keccak256(abi.encode(machineType, credentialSubject))), a decimal string in JSON and the DID did:peaq:<decimal id>.

What the CLI fingerprints

Every phase rechecks a fingerprint of the accepted plan. It covers both wallet addresses, the manufacturer, the machine type and credential subject, the tier, the payment rail, the DID controller if you set one, the contents of the DID document, and the three ceilings (--max-net-peaq-amount or --max-usdt-amount, --max-native-fee-lamports, --max-native-rent-lamports). A changed machine type or credential subject computes a different machine ID and starts a new attempt. Changing any of the others, including raising a ceiling or moving from basic to pro, stops the remaining phases for this machine until you put the original values back.

The fingerprint also covers the deployment record that ships inside the installed SDK, including its record_source and recorded_at fields. An SDK or CLI upgrade in the middle of an attempt can therefore stop a resume that restoring your own values would have fixed. Finish the machine first, then upgrade.

Once the subscription phase has paid the bond, cancelReservation reverts with SubscriptionExists and there is no refund path, so a machine whose original inputs are gone cannot be finished; its ID frees again only after the subscription terminates. Settle the tier and the ceilings at the preview, and store the values and the DID document together.

Three flags sit outside the fingerprint and are safe to change on a later run: --from-block, --compute-unit-limit and --compute-unit-price-micro-lamports. For a first attempt take --from-block from the finalized peaq block, not the chain head: a start ahead of finalized is rejected with STATE_MISMATCH. On a resume it must also stay at or below the block your reservation landed in, or reservation discovery finds nothing.

Run the three phases

1. Preview

   Keyless. Reports each stage’s unresolved prerequisites and the native fee and rent estimate. A preview is not transaction evidence, and did is null before the machine exists.

   peaqos activate "${ARGS[@]}" --dry-run
   
2. Reserve on peaq (operator wallet)

   Reserves the machine ID for the Solana owner. --yes accepts the displayed terms for this phase only.

   PEAQOS_OWS_WALLET=svm-operator peaqos activate "${ARGS[@]}" --phase reservation --yes
   
3. Activate the subscription on peaq (operator wallet)

   Bonds the tier. Approval and activation are separate transactions; an approval receipt alone is not a subscription. The preflight requires isEconomicAuthority() on peaq and reads both technical pause flags before the approval; a pause before the first approval stops with TECHNICALLY_PAUSED and spends nothing; a pause that starts after the approval confirmed ends with the same code, the approval gas spent and the allowance in place, so read the retained transactions before assuming nothing moved.

   peaqos activate "${ARGS[@]}" --phase subscription --dry-run
   PEAQOS_OWS_WALLET=svm-operator peaqos activate "${ARGS[@]}" --phase subscription --yes
   
4. Wait for the reservation mirror and the subscription status

   peaq pushes the reservation to Solana, and the subscription status reaches the machine’s SubscriptionTerminal account (it must read Active or Grace with a non-zero sequence that matches peaq’s subscription signal, and its tier must match your plan). Delivery is external to the CLI; a peaq receipt does not prove it. Repeat the native preview until the SDK reports both ready.

   peaqos activate "${ARGS[@]}" --phase native_onboarding --dry-run
   
5. Create the machine on Solana (owner wallet)

   PEAQOS_OWS_WALLET=svm-owner peaqos activate "${ARGS[@]}" --phase native_onboarding --yes
   

   Exit 0 means the Solana transaction confirmed. It does not mean onboarding is complete: peaq still has to apply the link. Rerun the same phase without --yes to reconcile; done is onboarding_state.evidence.stage.phase equal to complete.

Read the state

With the machine ID alone, no wallet, journal or DID document (MACHINE_ID is the machine_id from any phase’s JSON output, the preview included):

peaqos machine status "$MACHINE_ID" --json

Two read modes. Without --chain solana, the CLI falls back to the Solana read when the peaq record is missing or homed elsewhere and PEAQOS_SVM_RPC_URL is configured; that result has status: "observed" and a native_current_state with separate peaq (finalized) and Solana (confirmed) observations, not an atomic snapshot. Native states: absent, reserved, pending_external, present, conflict, in_flight, unavailable. With --chain solana the CLI reads the native management state instead and prints a different object (execution_chain, identity, mirrors with subscription_source, subscription_terminal_status and subscription_terminal_last_seq, peaq with subscription_status, operator_synchronization, pause flags), not native_current_state; it needs the native machine to exist, so before native creation use the fallback read. present proves the accounts exist, not that this attempt created them or that the link is complete. Pending or conflicting state exits 0; an unavailable configuration exits 3; read failures exit 2.

Resume after an interruption

Never delete peaqos.log, never change the inputs, never submit a replacement transaction on a hunch. The SDK records peaq hashes and nonces before it waits for a receipt, and Solana signatures with their blockhash validity before broadcast.

You see	Do
Reservation or subscription already confirmed	Rerun that phase with the original inputs and without --yes: it reconciles, it does not resubmit.
Approval confirmed, subscription not submitted	Rerun --phase subscription with the operator wallet and fresh consent.
Timeout, cancel, uncertain receipt, expired Solana blockhash	Keep the journal, reconcile first. None of these authorizes a replacement.
Reservation mirror or subscription terminal status pending	Wait for delivery, repeat the native preview.
Native confirmed, link pending	Rerun --phase native_onboarding without --yes.
Input, signer, deployment or account conflict	Fix the mismatch. Do not erase history to get past it. Restore the saved argument set and the original DID document; see what the CLI fingerprints.
STATE_MISMATCH with Select the accepted phase's wallet	The wrong wallet for the phase, usually a missing PEAQOS_OWS_WALLET= prefix. The CLI checks the wallet’s address before it signs, so nothing was submitted. Reservation and subscription take the operator wallet, native onboarding the owner wallet.
RPC_FAILED (“a read from the chain failed”) while reading reservation history	Usually the RPC: rate limiting, a wrong URL or an outage. Try again before changing anything. If it persists, --from-block reaches too far back and the log scan is refused. Raise it, staying below the block your reservation landed in.
STATE_MISMATCH on the same read	Retry once: a lagging or load-balanced RPC can produce it. If it repeats, --from-block is ahead of the finalized block. Use the finalized block, not the chain head.
Reservation discovery is unavailable	The opposite problem: --from-block is later than the block your reservation landed in, so the scan starts past it. Lower it and rerun.
The native preview stays pending for hours	The mirror or the subscription status has not been delivered to Solana. Delivery needs attention on peaq’s side: contact peaq with your machine_id.

Exit codes: 1 input or consent, 2 chain, read or transaction failure, 3 configuration or missing dependency. With --json, read the error_code and the retained evidence, not only the exit code: a phase failure sits in errors[] with its own error_code, and a native transaction can be confirmed at top level while the linkage read afterwards fails with exit 1, 2 or 3, so a nonzero exit is not proof that nothing was created.

The same flow in the SDKs

JavaScript

import { createPublicClient, http } from "viem";
import {
  previewMachineActivation, activateMachine, getMachineActivationState,
  resolveTokenomics20Deployment, resolveSvmDeployment,
  serializeSvmOnboardingProgress, type SvmActivationReadContext, type SvmOnboardingInput,
} from "@peaqos/peaq-os-sdk";

const context: SvmActivationReadContext = {
  publicClient: createPublicClient({ transport: http(process.env.PEAQOS_RPC_URL!) }),
  tokenomics20: resolveTokenomics20Deployment("peaq-mainnet"),
  svm: resolveSvmDeployment("solana-mainnet"),
  svmRpcUrl: process.env.PEAQOS_SVM_RPC_URL!,
};
const input: SvmOnboardingInput = {
  chain: "solana", owner, controller: owner, manufacturer, evmOperator,
  machineType: "Sensor", credentialSubject: "0x0102",
  verificationMethods: [], authentication: [], serviceEndpoints: [],
  tier: 1,                                                   // 1 basic, 2 pro
  funding: { payment: "peaq", maxNetPeaqAmount: 20n * 10n ** 18n },   // 20 PEAQ ceiling, above the Basic bond the preview reports; a ceiling below the bond is refused
  maxNativeFeeLamports: 100_000n, maxNativeRentLamports: 10_000_000n,
};
const preview = await previewMachineActivation(context, {
  ...input, commitment: "confirmed",
  native: { computeUnitLimit: 200_000, computeUnitPriceMicroLamports: 0n },
});
const result = await activateMachine(context, {
  chain: "solana", plan: preview.plan, phase: "reservation",   // then "subscription", then "native_onboarding"
  commitment: "confirmed", timeoutMs: 120_000,
  onProgress: (p) => persist(serializeSvmOnboardingProgress(p)),   // persist: your own durable store
});
const state = await getMachineActivationState(context, preview.plan.machineId, { plan: preview.plan, commitment: "confirmed" });

Store the accepted plan and the serialized progress; restore them with restoreSvmOnboardingProgress(plan, json) before the next phase. In JS, activateMachine previews, reconciles and reports the Solana flow but does not submit its write phases: the public path carries reads and recovery only; a phase that would otherwise be ready comes back blocked with nextAction: "verified_onboarding_deployment_required" and nothing is signed. getMachineActivationState and activateMachine with chain: "solana" read the reservation history from CrossChainMirror with eth_getLogs from block 0 to the current block, with no fromBlock option in the public types; the public peaq RPCs reject that range, so both fail with READ_FAILED. previewMachineActivation does not need that read and works. Run the phases, status and recovery from the CLI or Python; JS against a public RPC is preview only. Reference: SDK JS: Solana.

Python

from dataclasses import replace
from peaq_os_sdk import (
    PeaqosClient, Tokenomics20Config,
    SolanaOnboardingInputs, PeaqOnboardingFunding, normalize_solana_controller,
    SolanaVerificationMethodInput, ServiceEndpointInput,
    PreviewSolanaMachineActivationParams, ActivateSolanaMachineParams,
    SolanaMachineCurrentStateParams,
)

client = PeaqosClient.from_wallet("svm-operator", passphrase, ...,
    tokenomics20=Tokenomics20Config(deployment_id="peaq-mainnet",
                                    creation_home="solana",
                                    solana_rpc_url=SVM_RPC))

inputs = SolanaOnboardingInputs(                     # the same values as the CLI ARGS above
    solana_owner=OWNER, peaq_operator=OPERATOR,      # base58 owner wallet, 0x operator wallet
    controller=normalize_solana_controller(),        # owner-only
    manufacturer=MANUFACTURER, machine_type="Sensor",
    credential_subject=bytes.fromhex(CREDENTIAL_SUBJECT_HEX[2:]),
    verification_methods=(SolanaVerificationMethodInput(
        id="#key-1", method_type="Ed25519", controller=OWNER, public_key_multibase=OWNER_MULTIBASE),),
    authentication=(0,),
    service_endpoints=(ServiceEndpointInput(
        id="#telemetry", service_type="Telemetry", service_endpoint="https://example.com/telemetry"),),
    tier=1,                                          # 1 basic, 2 pro
    funding=PeaqOnboardingFunding(max_net_peaq_amount=20 * 10**18),   # 20 PEAQ, above the Basic bond the preview reports
    max_native_fee_lamports=100_000, max_native_rent_lamports=10_000_000,
)
plan = client.preview_machine_activation(PreviewSolanaMachineActivationParams(
    inputs=inputs, from_block=history_start,
    compute_unit_limit=600_000, compute_unit_price_micro_lamports=0))

persist = journal.append          # your durable store for serialize_solana_onboarding_attempt(...) records
required = client.get_solana_onboarding_signer_requirements(inputs, plan, "native_onboarding")
owner_signer = PeaqosClient.solana_signer_from_wallet("svm-owner", passphrase, chain_id=required.chain_id)

params = ActivateSolanaMachineParams(
    inputs=inputs, accepted_plan=plan, phase="reservation",
    expected_machine_id=plan.binding.machine_id, records=(),
    from_block=history_start, compute_unit_limit=600_000,
    compute_unit_price_micro_lamports=0, on_transaction_submitted=persist)
reservation = client.activate_machine(params)
subscription = client.activate_machine(replace(params, phase="subscription",
    records=reservation.recovery.history.records))
native = client.activate_machine(replace(params, phase="native_onboarding",
    records=subscription.recovery.history.records, solana_signer=owner_signer))

current = client.get_machine_activation_state(plan.binding.machine_id, solana=SolanaMachineCurrentStateParams())

records carries every attempt discovered so far; pass the full history, never a filtered one. Reference: SDK Python: Solana.

After onboarding

• Manage the machine with the same peaqos machine commands plus --chain solana (status, transfer --unsafe, suspend, resume, did set-controller, the DID setters, and the Solana-only set-evm-operator), or the same SDK methods; the SDK resolves the home chain from the machine ID and refuses the wrong chain. Transfer, controller and the peaq operator link need the Solana owner signature; DID lists, suspend and resume take owner or controller. There is no safe transfer on Solana (transfer requires --unsafe, --data-hex is refused), and approve / approve-all do not exist; the SDKs refuse approveMachine, setMachineApprovalForAll and safeTransferMachine by name. Details: SDK JS, SDK Python.
• Submit events with submitEvent / submit_event: the SDK routes a Solana-homed machine to the Solana EventRegistry program and signs with the owner’s or controller’s OWS Solana signer (the EVM operator does not qualify). In Python set client.solana_signer to an OwsSolanaSigner (for example from PeaqosClient.solana_signer_from_wallet(...)) before the call, or submit_event raises SIGNER_UNAVAILABLE; the CLI attaches it itself. The first event for a machine also pays rent for its event-log account. A confirmed event is not yet a rating; the 2.0 MCR indexes Solana events asynchronously.
• Credit rating: the 2.0 MCR scores a Solana-homed machine once its Solana indexer has the machine’s events; until then the response carries home_chain: 5 and a rating_unavailable reason (any non-empty reason means the score is a floor, not a measurement). A freshly created machine reads mcr: "Provisioned", mcr_score: 0 and rating_unavailable: "no_events_yet". See the API reference.
• Monetization opt-in for a Solana-homed machine is refused with SOLANA_MONETIZATION_UNVERIFIED before anything is signed. Rating reads and peaq-homed opt-in are unaffected.
• Relocation between peaq and Solana stays switched off on chain. Onboarding on Solana is not a relocation: the machine is created there.

Related

• Activate: the one-transaction flow on peaq
• Omni-chain: Solana: what is live on Solana
• Smart contracts: Solana mainnet: the eleven program IDs
• CLI: activate