SDK: JavaScript

npm install @peaqos/peaq-os-sdk viem dotenv

class PeaqosClient {
  constructor(config: Readonly<PeaqosClientConfig>);

  readonly rpcUrl: string;
  readonly contracts: Readonly<ContractAddresses>;
  readonly apiUrl: string;
  readonly operationalLimits: Readonly<OperationalLimits>;
  readonly publicClient: PublicClient;
  readonly walletClient: WalletClient;
  readonly tokenomics20: ResolvedTokenomics20Deployment | undefined; // set when the config carries tokenomics20

  get address(): Address;

  static fromEnv(): PeaqosClient;
  static fromWallet(
    nameOrId: string,
    passphrase: string | undefined,
    owsSigning: boolean | undefined,
    config: Readonly<Omit<PeaqosClientConfig, "privateKey">>,
    options?: WalletOptions,
  ): Promise<PeaqosClient>;
  static generateKeypair(): Readonly<{ address: Address; privateKey: `0x${string}` }>;

  // Static wallet wrappers (thin pass-throughs to the module-level helpers)
  static createWallet(name: string, passphrase?: string, words?: 12 | 24, options?: WalletOptions): Promise<WalletInfo>;
  static importWallet(name: string, privateKey: string, passphrase?: string, chain?: ImportChain, options?: WalletOptions): Promise<WalletInfo>;
  static importWalletMnemonic(name: string, mnemonic: string, passphrase?: string, index?: number, options?: WalletOptions): Promise<WalletInfo>;
  static listWallets(options?: WalletOptions): Promise<WalletInfo[]>;
  static getWallet(nameOrId: string, options?: WalletOptions): Promise<WalletInfo>;
  static exportWallet(nameOrId: string, passphrase?: string, options?: WalletOptions): Promise<string>;
  static deleteWallet(nameOrId: string, options?: WalletOptions): Promise<void>;

  toJSON(): Record<string, unknown>;
}

static fromEnv(): PeaqosClient;

static fromWallet(
  nameOrId: string,
  passphrase: string | undefined,
  owsSigning: boolean | undefined,
  config: Readonly<Omit<PeaqosClientConfig, "privateKey">>,
  options?: WalletOptions,
): Promise<PeaqosClient>;

static generateKeypair(): Readonly<{
  address: Address;
  privateKey: `0x${string}`;
}>;

static createWallet(name: string, passphrase?: string, words?: 12 | 24, options?: WalletOptions): Promise<WalletInfo>;
static importWallet(name: string, privateKey: string, passphrase?: string, chain?: ImportChain, options?: WalletOptions): Promise<WalletInfo>;
static importWalletMnemonic(name: string, mnemonic: string, passphrase?: string, index?: number, options?: WalletOptions): Promise<WalletInfo>;
static listWallets(options?: WalletOptions): Promise<WalletInfo[]>;
static getWallet(nameOrId: string, options?: WalletOptions): Promise<WalletInfo>;
static exportWallet(nameOrId: string, passphrase?: string, options?: WalletOptions): Promise<string>;
static deleteWallet(nameOrId: string, options?: WalletOptions): Promise<void>;
static fromWallet(nameOrId: string, passphrase: string | undefined, owsSigning: boolean | undefined, config: Omit<PeaqosClientConfig, "privateKey">, options?: WalletOptions): Promise<PeaqosClient>;

async activateMachine(params: ActivateMachineParams): Promise<ActivateMachineResult>;

interface ActivateMachineParams {
  controller: Address;
  verificationMethods: readonly VerificationMethodInput[]; // { id, methodType, controller, publicKeyMultibase }
  authentication: readonly bigint[];                       // indices into verificationMethods
  serviceEndpoints: readonly ServiceEndpointInput[];       // { id, serviceType, serviceEndpoint }
  machineType: string;
  credentialSubject: Hex;
  manufacturer: Address;                                   // recorded, never verified
  tier: SubscriptionTier;                                  // 0 | 1 | 2
  expectedMachineId?: bigint;
  maxNetPeaqAmount?: bigint;
  confirmations?: number;                                  // default 1
  timeoutMs?: number;                                      // default 120_000
  signal?: AbortSignal;
}

async previewMachineActivation(params: ActivateMachineParams): Promise<ActivationPreview>;

async computeMachineId(machineType: string, credentialSubject: Hex): Promise<bigint>;

getMachineOwner(machineId: bigint): Promise<Address>;                    // MACHINE_NOT_FOUND vs READ_FAILED kept apart
getMachineActivationState(machineId: bigint): Promise<MachineActivationState>;  // activated when subscription.periodStart !== 0n
getMachineManagementState(machineId: bigint): Promise<MachineManagementState>;
getMachineSubscription(machineId: bigint): Promise<MachineSubscription>;
getMachineAvailability(machineId: bigint): Promise<MachineAvailability>;
getMachineRelocationStatus({ machineId, destinationClient }): Promise<MachineRelocationStatus>;  // status: pending | completed | cancelled | conflicting; a pending result carries stage: not_started | initiated | arrived

suspendMachine(machineId: bigint, options?): Promise<...>;
resumeMachine(machineId: bigint, options?): Promise<...>;

previewExistingMachineActivation({ machineId, tier, payment: "peaq" | "usdt", slippageBps? });
activateExistingMachine({ machineId, tier, payment: "peaq", maxNetPeaqAmount } | { ..., payment: "usdt", maxUsdtAmount });

previewMachineRenewal({ machineId, payment, slippageBps? });
renewMachine({ machineId, payment: "peaq", maxNetPeaqAmount } | { machineId, payment: "usdt", maxUsdtAmount });  // stored tier, extends from the stored period end

approveMachine(operator: Address, machineId: bigint, options?);
setMachineApprovalForAll(operator: Address, approved: boolean, options?);   // every machine the signer owns, including future ones
transferMachine(from: Address, to: Address, machineId: bigint, options?);
safeTransferMachine(from: Address, to: Address, machineId: bigint, data?: Hex, options?);

setMachineController(machineId: bigint, controller: Address, options?);   // owner only; clearing needs { confirmClearController: true }
setMachineVerificationMethods(machineId: bigint, methods: readonly VerificationMethodInput[], options?);
setMachineAuthentication(machineId: bigint, indices: readonly bigint[], options?);
setMachineServiceEndpoints(machineId: bigint, endpoints: readonly ServiceEndpointInput[], options?);

import { UINT256_MAX, validateTokenomicsMachineId, parseTokenomicsMachineId, serializeTokenomicsMachineId } from "@peaqos/peaq-os-sdk";

async registerMachine(): Promise<number>;

async registerFor(machineAddress: `0x${string}`): Promise<number>;

async setupFaucet2FA(
  ownerAddress: string,
  faucetBaseUrl: string,
  format?: FaucetQrFormat,
): Promise<FaucetSetupResponse>;

async confirmFaucet2FA(
  ownerAddress: string,
  faucetBaseUrl: string,
  twoFactorCode: string,
): Promise<void>;

async fundFromGasStation(
  params: FundFromGasStationParams,
  faucetBaseUrl: string,
): Promise<FaucetFundResponse>;

async mintNft(
  machineId: number,
  recipient: `0x${string}`,
): Promise<Hex>;

async tokenIdOf(machineId: number): Promise<number>;

async writeMachineDIDAttributes(
  params: WriteMachineDIDParams,
): Promise<Hex>;

async writeProxyDIDAttributes(
  params: WriteProxyDIDParams,
): Promise<Hex>;

async function readAttribute(
  client: PeaqosClient,
  did: Address,
  name: string,
): Promise<DIDAttributeResult>;

function encodeAddAttribute(
  didAccount: Address,
  name: string,
  value: string,
  validFor: number,
): Hex;

async deploySmartAccount(
  params: DeploySmartAccountParams,
): Promise<Address>;

async getSmartAccountAddress(
  params: DeploySmartAccountParams,
): Promise<Address>;

async bridgeNft(params: BridgeNftParams): Promise<Hex>;

static async waitForBridgeArrival(
  params: WaitForBridgeArrivalParams,
): Promise<boolean>;

async submitEvent(
  params: SubmitEventParams,
): Promise<{ txHash: Hex; dataHash: Hex }>;

async batchSubmitEvents(
  events: ReadonlyArray<SubmitEventParams>,
): Promise<Hex[]>;

function validateSubmitEventParams(params: SubmitEventParams): void;

function computeDataHash(rawData: Uint8Array): Hex;

function checkOperationalLimits(
  params: { machineId: number; value: number },
  limits: OperationalLimits,
  tracker: EventTracker | null,
): void;

async function queryMcr(
  client: PeaqosClient,
  did: string,
  options?: GetJsonOptions,
): Promise<MCRResponse>;

async function queryMachine(
  client: PeaqosClient,
  did: string,
  options?: GetJsonOptions,
): Promise<MachineProfileResponse>;

async function queryOperatorMachines(
  client: PeaqosClient,
  did: string,
  options?: GetJsonOptions,
): Promise<OperatorMachinesResponse>;

import {
  PeaqosError,
  RuntimeError,
  ValidationError,
  ValueCapExceeded,
  RateLimitExceeded,
  // Economics 2.0 (0.6.0+)
  TokenomicsConfigError,
  TokenomicsActivationError,
  TokenomicsUnsupportedError,
  TokenomicsIntegrationUnavailableError,
  MonetizationCompatibilityError,
} from "@peaqos/peaq-os-sdk";