---
name: Peaq
description: Use when building decentralized physical infrastructure networks (DePINs), machine identity systems, real-world asset tokenization, or blockchain applications for IoT devices and robotics. Reach for this skill when onboarding machines to a blockchain, managing machine identities, storing verifiable data, controlling access with RBAC, or deploying smart contracts on an EVM-compatible Layer-1 blockchain optimized for the machine economy.
metadata:
    mintlify-proj: peaq
    version: "1.0"
---

# Peaq Skill Reference

## Product Summary

Peaq is a Layer-1 EVM-compatible blockchain purpose-built for the Machine Economy. It enables developers to build DePINs (Decentralized Physical Infrastructure Networks), DePAIs (Decentralized Physical AI), Machine DeFi applications, and Machine RWAs (Real-World Assets) with ultra-low fees (~$0.00025 per transaction) and high throughput (up to 10,000 TPS). The primary SDK is `@peaq-network/sdk` (JavaScript/Node.js) or `peaq-sdk` (Python). Key RPC endpoints are `https://quicknode.peaq.xyz` (mainnet) and `https://peaq-agung.api.onfinality.io/public` (testnet). Chain IDs: peaq = 3338, agung = 9990. Core features include Decentralized Identifiers (DIDs) for machines, Role-Based Access Control (RBAC), on-chain key-value storage, precompiles for efficient operations, and RWA tokenization framework. See [docs.peaq.xyz](https://docs.peaq.xyz) for full documentation.

## When to Use

Use Peaq when:
- **Onboarding machines or IoT devices** to a blockchain with cryptographic identity (DID Documents)
- **Building DePINs** that require machine identity, data verification, and access control
- **Tokenizing physical assets** (machines, equipment) as NFTs with security token compliance (RWA framework)
- **Managing machine data** with verifiable on-chain storage and off-chain solutions (IPFS, MongoDB)
- **Controlling access** to machine operations via role-based permissions
- **Deploying smart contracts** on an EVM-compatible network with low gas costs
- **Storing sensitive data** using hybrid on-chain/off-chain patterns (hashes on-chain, data off-chain)
- **Integrating with robotics** via the Robotics SDK (Python or ROS 2)
- **Handling machine payments** or yield distribution via security tokens

## Quick Reference

### SDK Installation & Setup

| Task | Command |
|------|---------|
| Install JavaScript SDK | `npm install @peaq-network/sdk ethers` |
| Install Python SDK | `pip install peaq-sdk==0.2.1` |
| Create JS project | `npm init -y && npm install @peaq-network/sdk && echo '"type": "module"' >> package.json` |
| Create Python venv | `python -m venv peaq && source peaq/bin/activate` |

### Network Configuration

| Network | Chain ID | RPC (HTTPS) | WSS |
|---------|----------|-------------|-----|
| **peaq (mainnet)** | 3338 | `https://quicknode.peaq.xyz` | `wss://quicknode.peaq.xyz` |
| **agung (testnet)** | 9990 | `https://peaq-agung.api.onfinality.io/public` | `wss://peaq-agung.api.onfinality.io/public-ws` |

### SDK Instance Creation

**JavaScript (EVM):**
```javascript
import { Sdk } from "@peaq-network/sdk";
const sdk = await Sdk.createInstance({
  baseUrl: "https://quicknode.peaq.xyz",
  chainType: Sdk.ChainType.EVM
});
```

**JavaScript (Substrate):**
```javascript
const sdk = await Sdk.createInstance({
  baseUrl: "wss://quicknode.peaq.xyz",
  chainType: Sdk.ChainType.SUBSTRATE,
  seed: process.env.SUBSTRATE_SEED
});
await sdk.disconnect();
```

**Python:**
```python
from peaq_sdk import Sdk
sdk = Sdk.create_instance(base_url="https://peaq-agung.api.onfinality.io/public")
```

### Core Operations

| Operation | Purpose | SDK Method |
|-----------|---------|-----------|
| Create DID | Register machine identity on-chain | `sdk.did.create()` |
| Read DID | Retrieve machine identity document | `sdk.did.read()` |
| Store data | Save key-value pairs on-chain | `sdk.storage.add()` |
| Retrieve data | Fetch stored data by key | `sdk.storage.read()` |
| Create role | Define access control role | `sdk.rbac.createRole()` |
| Create permission | Define access permission | `sdk.rbac.createPermission()` |
| Assign role | Grant role to address | `sdk.rbac.assignRole()` |

### Block Explorers

| Network | Explorer | URL |
|---------|----------|-----|
| peaq | Subscan | https://peaq.subscan.io/ |
| peaq | peaqscan | https://peaqscan.xyz/ |
| agung | Subscan | https://agung-testnet.subscan.io/ |
| agung | peaqscan testnet | https://testnet.peaqscan.xyz/ |

## Decision Guidance

### When to Use EVM vs Substrate Chain Type

| Scenario | Use EVM | Use Substrate |
|----------|---------|---------------|
| Building with ethers.js or web3.js | ✓ | |
| Need to sign transactions with private key directly | ✓ | |
| Using MetaMask or EVM wallets | ✓ | |
| Building with Substrate/Polkadot tools | | ✓ |
| Need automatic transaction submission via seed | | ✓ |
| Interacting with smart contracts | ✓ | |
| Using native Substrate pallets | | ✓ |

### When to Use On-Chain vs Off-Chain Storage

| Data Type | On-Chain | Off-Chain |
|-----------|----------|-----------|
| Hash/proof of data | ✓ | |
| Large files (>1KB) | | ✓ |
| Sensitive/private data | | ✓ |
| Transaction metadata | ✓ | |
| DID document hash | ✓ | |
| Machine telemetry | | ✓ (IPFS/MongoDB) |
| Access control rules | ✓ | |
| Machine configuration | | ✓ |

### When to Use RWA Framework vs Basic DePIN

| Requirement | Basic DePIN | RWA Framework |
|-------------|-------------|---------------|
| Machine identity only | ✓ | ✓ |
| Tokenize physical assets | | ✓ |
| KYC compliance required | | ✓ |
| Security token issuance | | ✓ |
| Yield distribution | | ✓ |
| Simple data storage | ✓ | ✓ |
| Regulated asset trading | | ✓ |

## Workflow

### 1. Onboard a Machine to Peaq

1. **Create machine wallet** — Generate EVM-compatible wallet using ethers.js
2. **Fund machine wallet** — Transfer native tokens from admin wallet (use testnet faucet first)
3. **Create DID Document** — Register machine identity on-chain with `sdk.did.create()`
4. **Verify on-chain** — Check DID exists using `sdk.did.read()` or block explorer
5. **Store machine metadata** — Use `sdk.storage.add()` to persist configuration or telemetry

### 2. Deploy and Interact with Smart Contracts

1. **Write contract** — Create Solidity contract (e.g., SimpleStorage.sol)
2. **Compile** — Use Remix, Hardhat, or Foundry to compile bytecode
3. **Deploy** — Submit deployment transaction via Remix, Hardhat, or Foundry
4. **Record address** — Save deployed contract address from receipt
5. **Interact** — Call contract methods via ethers.js or web3.js
6. **Verify** — Check transaction hash and function calls in block explorer

### 3. Implement Role-Based Access Control

1. **Create roles** — Define roles (e.g., "operator", "admin") with `sdk.rbac.createRole()`
2. **Create permissions** — Define permissions (e.g., "can_start_machine") with `sdk.rbac.createPermission()`
3. **Assign roles** — Grant roles to machine addresses with `sdk.rbac.assignRole()`
4. **Check permissions** — Verify access before executing sensitive operations
5. **Update as needed** — Revoke or reassign roles dynamically

### 4. Store and Retrieve Machine Data

1. **Prepare data** — Serialize machine state or telemetry to JSON/string
2. **Store on-chain** — Use `sdk.storage.add(key, value)` for critical data
3. **Store off-chain** — Use IPFS or MongoDB for large files; store IPFS CID on-chain
4. **Retrieve** — Fetch with `sdk.storage.read(key)` or IPFS gateway
5. **Verify integrity** — Compare hash of retrieved data to on-chain hash

### 5. Tokenize Physical Assets (RWA)

1. **Initialize RWA SDK** — `npm install @peaq-network/sdk-rwa && initialize with .env`
2. **Create identities** — Register KYC-verified identities for participants
3. **Register Machine NFT** — Mint MachineNFT representing physical asset
4. **Create Contract NFT** — Define contractual agreements between parties
5. **Create vault** — Set up vault to hold assets and issue security tokens
6. **Mint tokens** — Deposit NFTs into vault and mint fractional security tokens
7. **Distribute yield** — Deposit yield into vault; token holders claim distributions

## Common Gotchas

- **Private key exposure**: Never hardcode private keys in source code. Always use environment variables (`.env` file with `dotenv`). Never commit `.env` to version control.
- **Testnet vs mainnet**: Always test on agung testnet before deploying to peaq mainnet. Use correct RPC endpoints and chain IDs.
- **Gas estimation failures**: On agung testnet, gas estimates may be inaccurate. Use `--gas-estimate-multiplier 300 --slow` with Foundry if estimates fail.
- **Insufficient gas**: Set `gasLimit` high enough for complex operations. Use `eth_estimateGas` RPC method to simulate before submitting.
- **DID already exists**: Creating a DID for an address that already has one will fail. Check with `sdk.did.read()` first or wrap in try-catch.
- **Storage key collisions**: Use namespaced keys (e.g., `"machine_123_telemetry"`) to avoid overwriting data from other operations.
- **Off-chain data loss**: IPFS data is not guaranteed to persist without pinning. Use a pinning service (Pinata, NFT.storage) or MongoDB for critical data.
- **Transaction not mined**: Always wait for transaction confirmation with `txResponse.wait()` before assuming success. Check block explorer if hash exists but no receipt.
- **Wallet disconnection**: Substrate SDK requires active WSS connection. Call `sdk.disconnect()` when done to clean up resources.
- **RPC rate limits**: Public RPC endpoints have rate limits. Use private endpoints (QuickNode, OnFinality) for production or batch requests.
- **Precompile addresses**: Precompile addresses are fixed (e.g., DID at `0x0000000000000000000000000000000000000801`). Do not try to deploy contracts at these addresses.
- **EVM vs Substrate mismatch**: EVM SDK generates unsigned transactions; you must sign and submit separately. Substrate SDK can auto-submit if seed is provided.

## Verification Checklist

Before submitting work with Peaq:

- [ ] **Network correct**: Verified RPC endpoint matches intended network (testnet vs mainnet)
- [ ] **Private keys secure**: No private keys in code; all sensitive data in `.env` file
- [ ] **SDK instance created**: Called `Sdk.createInstance()` with correct `chainType` and `baseUrl`
- [ ] **Wallet funded**: Machine wallet has sufficient native tokens for gas (check with block explorer)
- [ ] **DID registered**: Machine has on-chain identity; verified with `sdk.did.read()` or explorer
- [ ] **Transactions confirmed**: All transactions have receipts; checked block explorer for status
- [ ] **Data persisted**: Stored data retrievable with `sdk.storage.read()` or IPFS gateway
- [ ] **Access control tested**: RBAC roles and permissions assigned and verified
- [ ] **Smart contracts deployed**: Contract address recorded and verified on explorer
- [ ] **Error handling in place**: Try-catch blocks around SDK calls and RPC requests
- [ ] **Gas optimized**: Complex operations tested for gas usage; no unnecessary computations
- [ ] **Off-chain data pinned**: IPFS data pinned to service or backed up to MongoDB

## Resources

- **Comprehensive navigation**: See [docs.peaq.xyz/llms.txt](https://docs.peaq.xyz/llms.txt) for complete page-by-page documentation index
- **Getting started**: [Introduction to peaq](https://docs.peaq.xyz/build/introduction) — Overview of DePINs, DePAI, Machine DeFi, and RWA
- **SDK reference**: [JavaScript SDK](https://docs.peaq.xyz/sdk-reference/javascript/create-instance), [Python SDK](https://docs.peaq.xyz/sdk-reference/python/create-instance), [RWA SDK](https://docs.peaq.xyz/sdk-reference/rwa)
- **First DePIN tutorial**: [Onboard a Machine](https://docs.peaq.xyz/build/first-depin/onboard-machine) — Step-by-step machine onboarding with code examples

---

> For additional documentation and navigation, see: https://docs.peaq.xyz/llms.txt