Submit events

Revenue events (type 0) and activity events (type 1) feed the Machine Credit Rating. Every is validated client-side, hashed, and submitted to the EventRegistry contract. A machine homed on Solana submits to the Solana EventRegistry program instead. Any client submits events; EVENT_REGISTRY_ADDRESS decides whether they reach the Tokenomics 1.0 or the Economics 2.0 registry (see the warning below). machineId is a uint256 in both generations (bigint in JS): the Economics 2.0 machine ID, or the numeric IdentityRegistry ID of a Tokenomics 1.0 machine. From the terminal, peaqos qualify event --machine-id <decimal machine id> reaches the configured EventRegistry.

Set EVENT_REGISTRY_ADDRESS to 0xA1e7F1d7B24dAb55Dc92491e6d9B89F6E925Ad1e for Economics 2.0 machines and 0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA for Tokenomics 1.0 machines. Both contracts share the submitEvent selector, so the SDK cannot catch a wrong address before sending: the 1.0 contract does not hold 2.0 machine IDs, reverts with MachineNotFound, and the event is not recorded.

For a machine homed on Solana, events go to the Solana EventRegistry program, signed by the machine’s Solana owner or controller. The parameters and validation below apply there too; setup, cost and recovery differ: see Machines homed on Solana.

Event types

Type	Value	Purpose	Example
Revenue	`0`	Records economic value generated by the machine	A claw machine collects $5.00 from a play session
Activity	`1`	Records operational activity with no direct revenue	A weather sensor reports a telemetry ping

Trust levels

Each event carries a describing how the data was attested. See Trust levels for the concept overview.

Level	Value	Meaning	Needs source tx hash?
Self-reported	`0`	Machine self-reports. No external verification.	No
On-chain verifiable	`1`	Event references a verifiable on-chain transaction.	Yes
Hardware-signed	`2`	Event signed by tamper-resistant hardware.	No

Currency and value units

currency is a first-class parameter on submitEvent / submit_event. Revenue events take a 3-10 char uppercase alphanumeric code (USD, HKD, JPY, …); activity events must pass "". On single-event submits an omitted currency defaults to "USD" for revenue and "" for activity: JS applies this on both chains, Python only for peaq-homed machines (a Solana-homed machine needs it explicitly in Python). batchSubmitEvents / batch_submit_events always requires it. value is an ISO 4217 minor-unit integer:

Currency	Subunit divisor	Example
`USD`, `HKD`, `EUR` (and other 2-decimal currencies)	`100`	`$1.23 → value: 123`
`JPY`, `KRW`, `VND` (no subunits)	`1`	`¥100 → value: 100`

The MCR converts 25 currencies: USD, HKD, JPY, CNY, KRW, SGD, TWD, THB, PHP, MYR, IDR, VND, INR, EUR, GBP, CHF, SEK, NOK, DKK, PLN, CAD, AUD, NZD, MXN, BRL. Any other code the contract accepts (for example BHD or a token symbol) is stored on chain but adds no revenue. The pipeline converts value to USD cents using the FX rate at timestamp. Only revenue events worth at least 1,000 USD cents ($10) after conversion are summed into total_revenue (USD cents) on GET /mcr/{did}. An event in a currency outside the supported list (unsupported_currency) or with no FX rate available (fx_unavailable) adds no USD revenue. When every FX source fails but the server holds an earlier stored rate for the currency pair, it converts the event at that stale rate and the revenue counts; for a machine homed on peaq, GET /mcr/{did} then returns mcr_degraded: true. "unsupported_currency" and "fx_unavailable" events do not set it. Activity events ignore the FX path entirely. They don’t accumulate revenue.

Validation

Call validateSubmitEventParams (JS) or validate_submit_event_params (Python) before submitting. It throws ValidationError on the first invalid field, and a native TypeError when value is not an integer.

import {
  validateSubmitEventParams,
  EVENT_TYPE_REVENUE,
  TRUST_SELF_REPORTED,
  SUPPORTED_CHAIN_IDS,
} from "@peaqos/peaq-os-sdk";

const params = {
  machineId: 1n,
  eventType: EVENT_TYPE_REVENUE,      // 0
  value: 500,                          // $5.00 in cents
  currency: "USD",
  timestamp: Math.floor(Date.now() / 1000) - 10,
  rawData: new TextEncoder().encode(JSON.stringify({ session: "abc123" })),
  trustLevel: TRUST_SELF_REPORTED,     // 0
  sourceChainId: SUPPORTED_CHAIN_IDS.peaq, // 3338
  sourceTxHash: null,
  metadata: new Uint8Array([]),
};

// Throws ValidationError if any field is invalid
validateSubmitEventParams(params);

import json
import time

from peaq_os_sdk import EVENT_TYPE_REVENUE, TRUST_SELF_REPORTED, SUPPORTED_CHAINS
from peaq_os_sdk.types.events import SubmitEventParams
from peaq_os_sdk.validation import validate_submit_event_params

params = SubmitEventParams(
    machine_id=1,
    event_type=EVENT_TYPE_REVENUE,           # 0
    value=500,                                # $5.00 in cents
    currency="USD",
    timestamp=int(time.time()),
    raw_data=json.dumps({"session": "abc123"}).encode(),
    trust_level=TRUST_SELF_REPORTED,          # 0
    source_chain_id=SUPPORTED_CHAINS["peaq"], # 3338
    source_tx_hash=None,
    metadata=b"",
)

# Raises ValidationError if any field is invalid
validate_submit_event_params(params)

Validation rules

Field	Constraint	Error if violated
`machineId` / `machine_id`	JS: positive `bigint` (a `number` is rejected). Python: positive `int`. Both: below `2^256`	JS: `machineId must be a bigint` for a `number`, `machineId must be a positive bigint` for `0n`. Python: `machine_id must be a positive integer` for `0`. Negative or too large: `must be between 0 and 2^256 - 1`
`eventType` / `event_type`	`0` or `1`	`eventType must be 0 or 1`
`value`	Non-negative integer (ISO 4217 minor units)	`value must be non-negative`
`currency`	Revenue: `^[A-Z0-9]{3,10}$`. Activity: must be `""`.	`revenue events require currency matching ^[A-Z0-9]{3,10}$` / `activity events require an empty currency string`
`trustLevel` / `trust_level`	`0`, `1`, or `2`	`trustLevel must be 0, 1, or 2`
`sourceChainId` / `source_chain_id`	JS: `0`, `3338`, or `8453`. Python also accepts `1`, `10`, `137`, `42161`	`sourceChainId must be a supported chain ID (0, 3338, or 8453)`
`rawData` / `raw_data`	Non-empty when provided	`rawData must not be empty when provided`
`sourceTxHash` / `source_tx_hash`	0x-prefixed 32-byte hex (66 chars) when provided. The SDK checks the length only, so pass a real hash	`sourceTxHash must be a 0x-prefixed 32-byte hex string (66 chars)`
`timestamp`	Positive integer	`timestamp must be a positive integer`
`sourceTxHash` when `trustLevel === 1`	Required	`sourceTxHash is required when trustLevel is 1 (on-chain verifiable)`

The messages above use the JS field names. Python prints the snake_case names (event_type, trust_level, source_chain_id, raw_data, source_tx_hash). The contract additionally rejects metadata larger than 4096 bytes with a MetadataTooLarge . The SDK validators don’t enforce this client-side, so oversized payloads surface as a failure rather than ValidationError: JS throws RuntimeError with code: "MetadataTooLarge", Python raises RpcError with code: "TX_REVERTED". For a Solana-homed machine the Solana EventRegistry program caps metadata at 256 bytes; currency follows the same 3 to 10 character rule.

Computing the data hash

The EventRegistry stores a of the raw data, not the data itself. Compute it with computeDataHash (JS) or compute_data_hash (Python).

import { computeDataHash } from "@peaqos/peaq-os-sdk";

const rawData = new TextEncoder().encode(
  JSON.stringify({ session: "abc123", amount: 500 })
);
const hash = computeDataHash(rawData);
// hash: "0x8dd186bf57dece591311f044eaf97f4886878309ff0b546a58386d2df41978e2"

from peaq_os_sdk.utils import compute_data_hash

raw_data = b'{"session": "abc123", "amount": 500}'
data_hash = compute_data_hash(raw_data)
# data_hash is 32 bytes (keccak256)

The hash is passed as the dataHash field in the on-chain MachineEvent struct. Consumers who need to verify the original data compare its keccak256 against the stored hash.

Submitting a revenue event (type 0)

import "dotenv/config";
import {
  PeaqosClient,
  validateSubmitEventParams,
  EVENT_TYPE_REVENUE,
  TRUST_SELF_REPORTED,
  SUPPORTED_CHAIN_IDS,
} from "@peaqos/peaq-os-sdk";

const client = PeaqosClient.fromEnv();

const rawData = new TextEncoder().encode(
  JSON.stringify({ session: "abc123", amount: 500 })
);

const params = {
  machineId: 1n,
  eventType: EVENT_TYPE_REVENUE,
  value: 500,                       // $5.00 in cents
  currency: "USD",
  timestamp: Math.floor(Date.now() / 1000) - 10,
  rawData,
  trustLevel: TRUST_SELF_REPORTED,
  sourceChainId: SUPPORTED_CHAIN_IDS.peaq,
  sourceTxHash: null,
  metadata: new Uint8Array([]),
};

validateSubmitEventParams(params);

const { txHash, dataHash } = await client.submitEvent(params);
console.log("Submitted revenue event:", { txHash, dataHash });

from dotenv import load_dotenv
import json
import time
from peaq_os_sdk import (
    PeaqosClient,
    EVENT_TYPE_REVENUE,
    TRUST_SELF_REPORTED,
    SUPPORTED_CHAINS,
)
from peaq_os_sdk.types.events import SubmitEventParams
from peaq_os_sdk.validation import validate_submit_event_params

load_dotenv() # load envs from .env file

client = PeaqosClient.from_env()

raw_data = json.dumps({"session": "abc123", "amount": 500}).encode()

params = SubmitEventParams(
    machine_id=1,
    event_type=EVENT_TYPE_REVENUE,
    value=500,                                # $5.00 in cents
    currency="USD",
    timestamp=int(time.time()) - 10,
    raw_data=raw_data,
    trust_level=TRUST_SELF_REPORTED,
    source_chain_id=SUPPORTED_CHAINS["peaq"],
    source_tx_hash=None,
    metadata=b"",
)

validate_submit_event_params(params)

tx_hash, data_hash = client.submit_event(
    machine_id=params.machine_id,
    event_type=params.event_type,
    value=params.value,
    currency=params.currency,
    timestamp=params.timestamp,
    raw_data=params.raw_data,
    trust_level=params.trust_level,
    source_chain_id=params.source_chain_id,
    source_tx_hash=params.source_tx_hash,
    metadata=params.metadata,
)
print("Submitted revenue event:", tx_hash, data_hash.hex())

Submitting an activity event (type 1)

Activity events record operational telemetry with no direct revenue value.

import "dotenv/config";
import {
  PeaqosClient,
  validateSubmitEventParams,
  EVENT_TYPE_ACTIVITY,
  TRUST_SELF_REPORTED,
  SUPPORTED_CHAIN_IDS,
} from "@peaqos/peaq-os-sdk";

const client = PeaqosClient.fromEnv();

const rawData = new TextEncoder().encode(
  JSON.stringify({ type: "heartbeat", uptimeSeconds: 86400 })
);

const params = {
  machineId: 1n,
  eventType: EVENT_TYPE_ACTIVITY, // 1
  value: 0,                       // No revenue
  currency: "",                   // activity events must be empty
  timestamp: Math.floor(Date.now() / 1000) - 10,
  rawData,
  trustLevel: TRUST_SELF_REPORTED,
  sourceChainId: SUPPORTED_CHAIN_IDS.peaq,
  sourceTxHash: null,
  metadata: new Uint8Array([]),
};

validateSubmitEventParams(params);

const { txHash, dataHash } = await client.submitEvent(params);
console.log("Submitted activity event:", { txHash, dataHash });

from dotenv import load_dotenv
import json
import time
from peaq_os_sdk import (
    PeaqosClient,
    EVENT_TYPE_ACTIVITY,
    TRUST_SELF_REPORTED,
    SUPPORTED_CHAINS,
)
from peaq_os_sdk.types.events import SubmitEventParams
from peaq_os_sdk.validation import validate_submit_event_params

load_dotenv() # load envs from .env file

client = PeaqosClient.from_env()

raw_data = json.dumps({"type": "heartbeat", "uptime_seconds": 86400}).encode()

params = SubmitEventParams(
    machine_id=1,
    event_type=EVENT_TYPE_ACTIVITY,           # 1
    value=0,                                    # No revenue
    currency="",                                # activity events must be empty
    timestamp=int(time.time()) - 10,
    raw_data=raw_data,
    trust_level=TRUST_SELF_REPORTED,
    source_chain_id=SUPPORTED_CHAINS["peaq"],
    source_tx_hash=None,
    metadata=b"",
)

validate_submit_event_params(params)

tx_hash, data_hash = client.submit_event(
    machine_id=params.machine_id,
    event_type=params.event_type,
    value=params.value,
    currency=params.currency,
    timestamp=params.timestamp,
    raw_data=params.raw_data,
    trust_level=params.trust_level,
    source_chain_id=params.source_chain_id,
    source_tx_hash=params.source_tx_hash,
    metadata=params.metadata,
)
print("Submitted activity event:", tx_hash, data_hash.hex())

Machines homed on Solana

A machine homed on Solana takes its events on Solana: the Solana EventRegistry program, signed by the machine’s Solana owner or controller, who also pays. Event types, trust levels, currency and value units are the same as on peaq. What differs:

Endpoint. The CLI, both SDKs and the machine’s .env need PEAQOS_SVM_RPC_URL, the Solana endpoint the machine was onboarded with. from_env() / fromEnv() do not read it; the examples below build the client from the .env themselves.
Signer. The OWS wallet holding the machine’s Solana owner or controller key. A peaq key signs nothing.
Cost, in SOL. The first event for a machine pays rent for its event-log account (2,946,400 lamports measured) plus a 5,000-lamport network fee, about 0.003 SOL. Every later event pays the fee only.
Gates. The signer must be the machine’s current owner or controller and its subscription must be eligible; the registry must not be paused and the machine not relocating. Python and the CLI check all of this in a preview before signing; JS checks it before signing too, but has no separate preview.
Limits. metadata is capped at 256 bytes (4,096 on peaq). timestamp must not be later than the Solana cluster’s clock. sourceChainId / source_chain_id is provenance only: any value is accepted, and the examples use 0 (same chain), as the CLI does.
Confirmation is not the MCR. The MCR indexes Solana events on its own schedule. GET /mcr/{did} (peaqos qualify mcr) counted them within minutes in our runs. At the time of writing, the machine profile (peaqos show machine) and machines.peaq.xyz do not list them yet (event_history_not_indexed).

CLI
Python
TypeScript

CLI 0.0.18 or newer, with pip install 'peaq-os-cli[solana,ows]'. 0.0.16 and 0.0.17 refuse a Solana-homed machine with MACHINE_HOMED_ELSEWHERE. Run it in the machine’s directory, with the .env it was onboarded with:

# Preview: price and eligibility. Signs nothing.
PEAQOS_OWS_WALLET=<owner wallet> peaqos qualify event --machine-id <machine-id> \
  --type activity --value 1 --ts "$(date +%s)" --dry-run

# Submit: shows the same preview, asks, then signs and waits for confirmation.
PEAQOS_OWS_WALLET=<owner wallet> peaqos qualify event --machine-id <machine-id> \
  --type activity --value 1 --ts "$(date +%s)"

The result names the Solana transaction:

Event submitted.
  Execution Chain:  solana
  Submission ID  :  247303243568646217976204659601125903134
  Signature      :  4kLbofKm8Wwo2XYNCKtJ1hyC8Em1Vk9oY2akagjHN3fUioygR9pfNyWi5Cq9BPiHcJ5yPCq2tEhyaSZqCrnQyfCT
  Slot           :  454751920
  Confirmation   :  confirmed
  Machine ID     :  42581867695199888670555386101443910530672475932641965651512985654630415296741
  Data Hash      :  0x0000000000000000000000000000000000000000000000000000000000000000
  Event Index    :  2
  Event Log      :  EmAGCLWJ6WWgUhmogfPimGCVtwHC5pUzicibriGuzP12
  Compute Units  :  39490

The full preview, the --json fields and the --resume recovery are on the CLI page.

SDK 0.11.2 or newer, with pip install -U "peaq-os-sdk[solana,ows]" python-dotenv. submit_event routes a Solana-homed machine on its own and returns (signature, data_hash); submit_native_event, used here, returns the whole result (slot, event index, event log, submission ID) and takes an on_broadcast hook for a journal. Save as submit_solana_event.py and run it in the machine’s directory, --dry-run first:

python submit_solana_event.py <machine-id> <base58 owner> --dry-run
# event log initialized · rent 0 · fee 5000 lamports · 39490 CU
python submit_solana_event.py <machine-id> <base58 owner>

"""Submit one activity event for a machine homed on Solana: preview, then sign and submit.

    python submit_solana_event.py <machine id> <base58 owner or controller> [--dry-run]

Run it in the machine's directory: it reads the CLI's .env, signs with the OWS wallet
PEAQOS_OWS_WALLET names, and reads the vault passphrase from OWS_PASSPHRASE.
"""

import json
import os
import sys
import time
from pathlib import Path

from dotenv import load_dotenv
from peaq_os_sdk import (
    EVENT_TYPE_ACTIVITY,
    TRUST_SELF_REPORTED,
    Address,
    PeaqosClient,
    SolanaPubkey,
    Tokenomics20Config,
    TokenomicsActivationError,
    preview_event_submission,
)
from peaq_os_sdk.events import submit_native_event
from peaq_os_sdk.types.events import SubmitEventParams

load_dotenv(".env")  # the machine directory's .env, from the working directory


def need(key: str) -> str:
    value = os.environ.get(key)
    if not value:
        raise SystemExit(f"{key} is not set")
    return value


client = PeaqosClient(
    rpc_url=need("PEAQOS_RPC_URL"),
    identity_registry=Address(need("IDENTITY_REGISTRY_ADDRESS")),
    identity_staking=Address(need("IDENTITY_STAKING_ADDRESS")),
    event_registry=Address(need("EVENT_REGISTRY_ADDRESS")),
    machine_nft=Address(need("MACHINE_NFT_ADDRESS")),
    did_registry=Address(need("DID_REGISTRY_ADDRESS")),
    batch_precompile=Address(need("BATCH_PRECOMPILE_ADDRESS")),
    tokenomics20=Tokenomics20Config(
        deployment_id=need("TOKENOMICS_DEPLOYMENT_ID"),  # peaq-mainnet
        creation_home="solana",  # lets the client be built without a peaq private key
        solana_rpc_url=need("PEAQOS_SVM_RPC_URL"),
    ),
)

machine_id, submitter = int(sys.argv[1]), SolanaPubkey(sys.argv[2])
params = SubmitEventParams(
    machine_id=machine_id,
    event_type=EVENT_TYPE_ACTIVITY,
    value=1,
    currency="",  # required on the Solana path: "" for activity, a code such as "USD" for revenue
    timestamp=int(time.time()) - 10,  # must not be later than the cluster's clock
    raw_data=json.dumps({"type": "heartbeat"}).encode(),
    trust_level=TRUST_SELF_REPORTED,
    source_chain_id=0,  # same chain; on Solana this is provenance only
    source_tx_hash=None,
    metadata=b"",
)

# Price and eligibility, signing nothing and unlocking no wallet.
preview = preview_event_submission(client, params, submitter=submitter)
print(
    f"event log {preview.log_state} · rent {preview.rent_lamports} · "
    f"fee {preview.network_fee_lamports} lamports · {preview.compute_units} CU"
)
if "--dry-run" in sys.argv:
    raise SystemExit(0)

# Mainnet by default; the passphrase falls back to OWS_PASSPHRASE.
client.solana_signer = PeaqosClient.solana_signer_from_wallet(need("PEAQOS_OWS_WALLET"))

journal = Path("events-py.log")


def record(attempt) -> None:
    # Called after the broadcast and before the wait: a resumable reference survives a crash.
    with journal.open("a", encoding="utf-8") as handle:
        handle.write(json.dumps(dict(attempt)) + "\n")


try:
    result = submit_native_event(client, params, on_broadcast=record)
except TokenomicsActivationError as err:
    if err.code != "PENDING_TRANSACTION":
        raise
    raise SystemExit(f"not confirmed yet; resolve the last line of {journal} before resending")
print(
    f"confirmed {result.signature} · slot {result.slot} · "
    f"event {result.event_index} · log {result.event_log}"
)

The client needs creation_home="solana" only so it can be built without a peaq private key; routing comes from the machine’s home. Pass currency explicitly: on the Solana path Python applies no default. Without client.solana_signer the submission raises SIGNER_UNAVAILABLE; for a peaq-homed machine submit_native_event raises CHAIN_MISMATCH (use submit_event, which routes either way).If the wait ends without a confirmation (PENDING_TRANSACTION), the event may still land. Resolve the journaled attempt, read-only, before sending it again:

from peaq_os_sdk.events import resolve_event_submission

attempt = json.loads(Path("events-py.log").read_text().splitlines()[-1])
resolution = resolve_event_submission(client, attempt)
print(resolution.outcome, resolution.detail)

confirmed: it landed. expired_unlanded: nothing landed, sending again is safe. unresolved: ask again later.

SDK 0.11.2 or newer, with @solana/web3.js, @coral-xyz/anchor and dotenv installed beside it. A client built with svm sends every submitEvent to Solana and needs the second argument; it refuses a peaq-homed machine with CHAIN_MISMATCH, so keep a client without svm for those. Save as submit-solana-event.mjs and run node submit-solana-event.mjs <machine-id> in the machine’s directory:

// submit-solana-event.mjs <machine id>
// Run it in the machine's directory: it reads the CLI's .env, signs with the OWS wallet
// PEAQOS_OWS_WALLET names, and reads the vault passphrase from OWS_PASSPHRASE.
import "dotenv/config";
import { randomBytes } from "node:crypto";
import { appendFileSync } from "node:fs";
import {
  EVENT_TYPE_ACTIVITY,
  PeaqosClient,
  TRUST_SELF_REPORTED,
  solanaSignerFromWallet,
} from "@peaqos/peaq-os-sdk";

const env = (key) => {
  const value = process.env[key];
  if (!value) throw new Error(`${key} is not set`);
  return value;
};

// TypeScript: new PeaqosClient<"tokenomics20", "svmEnabled">({ ... })
const client = new PeaqosClient({
  rpcUrl: env("PEAQOS_RPC_URL"),
  // Nothing is signed on peaq. A throwaway key satisfies the constructor.
  privateKey: "0x" + randomBytes(32).toString("hex"),
  contracts: {
    identityRegistry: env("IDENTITY_REGISTRY_ADDRESS"),
    identityStaking: env("IDENTITY_STAKING_ADDRESS"),
    eventRegistry: env("EVENT_REGISTRY_ADDRESS"),
    machineNft: env("MACHINE_NFT_ADDRESS"),
    didRegistry: env("DID_REGISTRY_ADDRESS"),
    batchPrecompile: env("BATCH_PRECOMPILE_ADDRESS"),
  },
  tokenomics20: { deploymentId: env("TOKENOMICS_DEPLOYMENT_ID") }, // peaq-mainnet
  svm: { deploymentId: "solana-mainnet", rpcUrl: env("PEAQOS_SVM_RPC_URL") },
});

// The SDK asks for the signer more than once; unlock the wallet only the first time.
let signer;
const getSigner = async () => {
  signer ??= await solanaSignerFromWallet(env("PEAQOS_OWS_WALLET")); // mainnet by default
  return signer;
};

const toJson = (value) =>
  JSON.stringify(value, (_key, v) => (typeof v === "bigint" ? v.toString() : v));

const result = await client.submitEvent(
  {
    machineId: BigInt(process.argv[2]),
    eventType: EVENT_TYPE_ACTIVITY,
    value: 1,
    currency: "", // "" for activity; omitted, it defaults to "USD" for revenue and "" for activity
    timestamp: Math.floor(Date.now() / 1000) - 10, // must not be later than the cluster's clock
    rawData: new TextEncoder().encode(JSON.stringify({ type: "heartbeat" })),
    trustLevel: TRUST_SELF_REPORTED,
    sourceChainId: 0, // same chain; on Solana this is provenance only
    sourceTxHash: null,
    metadata: new Uint8Array([]),
  },
  {
    commitment: "confirmed",
    getSigner,
    // Refused before signing if the fee or the rent would be higher.
    acceptedCostBounds: { maxFeeLamports: 10_000n, maxRentLamports: 3_000_000n },
    // Awaited before the broadcast: a failure here sends nothing.
    onTransactionSubmitted: (attempt) => appendFileSync("events-js.log", toJson(attempt) + "\n"),
  },
);
console.log(
  `confirmed ${result.signature} · slot ${result.slot} · event ${result.eventIndex}`,
);

result carries executionChain ("solana"), signature, submissionId, slot, confirmationLevel, machineId, dataHash, eventIndex and, when known, computeUnits. There is no dry run in JS: acceptedCostBounds is the guard, and the gates above are checked before signing either way. Failures are TokenomicsActivationError with a code: NOT_OWNER_OR_CONTROLLER, SUBSCRIPTION_NOT_ELIGIBLE, TECHNICALLY_PAUSED, MACHINE_RELOCATING, INSUFFICIENT_BALANCE, STATE_MISMATCH (a cost above the bounds, or a timestamp later than the cluster’s clock), or CONTRACT_REVERTED for a transaction that landed and failed.If the wait ends without a confirmation (TRANSACTION_PENDING, by default after 120 s; timeoutMs changes it), the event may still land. The attempt in events-js.log carries its signature and lastValidBlockHeight. Look the signature up (getSignatureStatuses, or any Solana explorer) before sending again: found without an error, it landed; not found once the cluster’s block height is past lastValidBlockHeight, it can no longer land, and sending again is safe.

Cross-chain revenue pattern

When a machine earns revenue on another (e.g., ), reference the source transaction for on-chain verifiable trust (level 1).

import {
  validateSubmitEventParams,
  EVENT_TYPE_REVENUE,
  TRUST_ON_CHAIN_VERIFIABLE,
  SUPPORTED_CHAIN_IDS,
  type SubmitEventParams,
} from "@peaqos/peaq-os-sdk";

const params: SubmitEventParams = {
  machineId: 1n,
  eventType: EVENT_TYPE_REVENUE,
  value: 1200,                              // $12.00 in cents
  currency: "USD",
  timestamp: Math.floor(Date.now() / 1000) - 10,
  rawData: new TextEncoder().encode(JSON.stringify({ invoice: "INV-0042" })),
  trustLevel: TRUST_ON_CHAIN_VERIFIABLE, // 1
  sourceChainId: SUPPORTED_CHAIN_IDS.base, // 8453
  sourceTxHash: "0xa1b2c3d4e5f6789000000000000000000000000000000000000000000000a1b2",
  metadata: new Uint8Array([]),
};

validateSubmitEventParams(params);
// sourceTxHash is required when trustLevel is 1.
// The MCR scores the declared trust level; it does not check sourceTxHash on Base.

import json
import time

from peaq_os_sdk import (
    EVENT_TYPE_REVENUE,
    TRUST_ON_CHAIN_VERIFIABLE,
    SUPPORTED_CHAINS,
)
from peaq_os_sdk.types.events import SubmitEventParams
from peaq_os_sdk.validation import validate_submit_event_params

params = SubmitEventParams(
    machine_id=1,
    event_type=EVENT_TYPE_REVENUE,
    value=1200,                                    # $12.00 in cents
    currency="USD",
    timestamp=int(time.time()),
    raw_data=json.dumps({"invoice": "INV-0042"}).encode(),
    trust_level=TRUST_ON_CHAIN_VERIFIABLE,        # 1
    source_chain_id=SUPPORTED_CHAINS["base"],     # 8453
    source_tx_hash="0xa1b2c3d4e5f6789000000000000000000000000000000000000000000000a1b2",
    metadata=b"",
)

validate_submit_event_params(params)
# source_tx_hash is required when trust_level is 1.
# The MCR scores the declared trust level; it does not check source_tx_hash on Base.

Supported chain IDs

Chain	ID
peaq (same-chain)	`3338`
Base	`8453`

Operational limits

The SDK enforces per-transaction value caps and rate limits before submitting.

import { checkOperationalLimits } from "@peaqos/peaq-os-sdk";

checkOperationalLimits(
  { machineId: 1n, value: 500 },
  {
    maxValuePerTx: 10000,
    rateLimitMaxEvents: 60,
    rateLimitWindowSeconds: 3600,
  },
  null, // or an EventTracker carried over from previous submissions
);
// Throws ValueCapExceeded if value > maxValuePerTx
// Throws RateLimitExceeded if count >= rateLimitMaxEvents within window

from peaq_os_sdk.types.client import OperationalLimits
from peaq_os_sdk.validation import check_operational_limits

check_operational_limits(
    params,  # SubmitEventParams (or any object with .machine_id and .value)
    OperationalLimits(
        max_value_per_tx=10000,
        rate_limit_max_events=60,
        rate_limit_window_seconds=3600,
    ),
    None,  # or an EventTracker carried over from previous submissions
)
# Raises ValueCapExceeded if value > max_value_per_tx
# Raises RateLimitExceeded if count >= rate_limit_max_events within window

Limit	Error type	Description
`maxValuePerTx` / `max_value_per_tx`	`ValueCapExceeded`	Single event value exceeds the per-transaction cap
`rateLimitMaxEvents` / `rate_limit_max_events`	`RateLimitExceeded`	Too many events submitted within the rate-limit window

Set limits to 0 to disable (the default).

Error handling

submitEvent / submit_event raise four SDK error types, plus a native TypeError for a non-integer value. Validation and limit errors are local; RuntimeError (JS) / RpcError (Python) wraps every chain or RPC failure on peaq. A submission for a Solana-homed machine raises TokenomicsActivationError instead (JS also TokenomicsConfigError), which the handlers below do not catch. JS collapses chain and HTTP errors into a single RuntimeError; Python keeps them separate (RpcError for chain, ApiError for HTTP).

import {
  ValidationError,
  ValueCapExceeded,
  RateLimitExceeded,
  RuntimeError,
} from "@peaqos/peaq-os-sdk";

try {
  const { txHash, dataHash } = await client.submitEvent(params);
} catch (err) {
  if (err instanceof ValidationError) {
    // Bad params: check err.field, err.constraint
  } else if (err instanceof ValueCapExceeded) {
    // Per-tx value cap tripped
  } else if (err instanceof RateLimitExceeded) {
    // Local rate limit tripped
  } else if (err instanceof RuntimeError) {
    // Chain/RPC failure. err.code carries the revert name when the SDK's ABI
    // knows it (e.g. "MetadataTooLarge", "InvalidCurrencyShape", "FutureTimestamp").
    // The Economics 2.0 registry's NotOwnerOrController, SubscriptionNotEligible
    // and ERC721NonexistentToken reverts are not in that ABI: err.code is
    // undefined and err.message carries the raw selector.
  } else {
    throw err;
  }
}

from peaq_os_sdk import (
    ValidationError,
    ValueCapExceeded,
    RateLimitExceeded,
    RpcError,
)

try:
    tx_hash, data_hash = client.submit_event(
        machine_id=params.machine_id,
        event_type=params.event_type,
        value=params.value,
        currency=params.currency,
        timestamp=params.timestamp,
        raw_data=params.raw_data,
        trust_level=params.trust_level,
        source_chain_id=params.source_chain_id,
        source_tx_hash=params.source_tx_hash,
        metadata=params.metadata,
    )
except ValidationError as err:
    # Bad params: inspect err.field, err.constraint
    raise
except ValueCapExceeded:
    # Per-tx value cap tripped
    raise
except RateLimitExceeded:
    # Local rate limit tripped
    raise
except RpcError as err:
    # Chain/RPC failure: err.code is "TX_REVERTED" for every Economics 2.0
    # revert (NotOwnerOrController, SubscriptionNotEligible, MetadataTooLarge, ...);
    # 1.0 names such as "MachineNotFound" appear only on the 1.0 registry.
    raise

See SDK errors reference for the full code map and the cross-language equivalence between RuntimeError (JS) and RpcError/ApiError (Python).

Next steps

Events concept for deeper coverage of event types and trust levels
SDK reference for full method signatures

Welcome

Get Started

Concepts

Functions

Guides

Submit events

Event types

Trust levels

Currency and value units

Validation

Validation rules

Computing the data hash

Submitting a revenue event (type 0)

Submitting an activity event (type 1)

Machines homed on Solana

Cross-chain revenue pattern

Supported chain IDs

Operational limits

Error handling

Next steps

​Event types

​Trust levels

​Currency and value units

​Validation

​Validation rules

​Computing the data hash

​Submitting a revenue event (type 0)

​Submitting an activity event (type 1)

​Machines homed on Solana

​Cross-chain revenue pattern

​Supported chain IDs

​Operational limits

​Error handling

​Next steps

Event types

Trust levels

Currency and value units

Validation

Validation rules

Computing the data hash

Submitting a revenue event (type 0)

Submitting an activity event (type 1)

Machines homed on Solana

Cross-chain revenue pattern

Supported chain IDs

Operational limits

Error handling

Next steps