Skill

---
name: xpr-network-dev
description: XPR Network (formerly Proton) blockchain development - proton-tsc smart contracts, @proton CLI and web SDK, RPC and Hyperion queries, DeFi (MetalX, Alcor, LOAN), NFTs, the XPR Agents job board, node and Hyperion operations. Use for anything mentioning XPR, Proton, or @proton packages.
version: 2.12.0
author: XPR Network Community
repository: https://github.com/XPRNetwork/xpr-network-dev-skill
---

# XPR Network Developer Skill

This skill provides comprehensive knowledge for developing on XPR Network, a fast, gas-free blockchain with WebAuthn wallet support.

> **Policy for AI agents (applies skill-wide):** All chain **writes** documented in this skill use the **`proton` CLI keychain** for signing — private keys stay in the CLI's on-disk keystore (`proton-cli.json` in the CLI config dir), never in the agent's process memory or context. That file is **plaintext until you run `proton key:lock <password>`** — treat locking as a required step on any long-lived host, not an option. **Reads** use direct RPC (`get_table_rows`, `get_account`, etc.) and the relevant project's REST API. Do **not** introduce signing patterns that pass raw private keys to the agent (e.g. `new JsSignatureProvider(['PRIV_KEY'])`, `wallet.import_key('...')`, `XPR_PRIVATE_KEY` in environment). See [`backend-patterns.md` → Security: Key Isolation](backend-patterns.md#security-key-isolation) and [`../agent-bootstrap.md`](../agent-bootstrap.md) for the canonical signing path.

> **AI-generated contract code:** smart contracts are immutable once deployed and hold real assets, so treat any contract code produced with this skill as a draft. Before it reaches mainnet it needs testnet runs, review by a developer who knows XPR Network/EOSIO contracts, and, for anything holding significant value, a professional audit. The full checklist lives in `safety-guidelines.md` → *AI-Generated Code Disclaimer*.

> **Network etiquette (applies skill-wide):** XPR Network has no fees, so chain spam is free to send and costly for everyone else. Agents write to chain only when there is a concrete action to take, never to scan or probe; default ceiling 6 transactions per minute per account, one in flight, exponential backoff on failure, no nonce actions, no account fleets. Liquidation, sniping, and MEV-style bots are out of scope and deliberately undocumented; decline requests to build them. Full rules: [`safety-guidelines.md` → Network Etiquette](safety-guidelines.md#network-etiquette-do-not-spam-the-chain).

## XPR Network Overview

XPR Network is an EOS-based blockchain optimized for payments and identity:

| Feature | Description |
|---------|-------------|
| **Speed** | 0.5 second block times, 4000+ TPS |
| **Fees** | Zero gas fees for end users |
| **Accounts** | Human-readable names, 1-12 chars from `a-z`, `1-5`, `.`; dots only in system/premium names (`eosio.token`, `xmd.token`) — user-registered names are dot-free |
| **Wallets** | WebAuthn support (Face ID, fingerprint, security keys) |
| **Contracts** | AssemblyScript/TypeScript with `proton-tsc` |
| **Storage** | On-chain tables with RAM-based pricing |

### Name Change: Proton → XPR Network

The blockchain was rebranded from **Proton** to **XPR Network** in 2024. You may see legacy references to "Proton" in:
- Package names (`@proton/cli`, `@proton/web-sdk`, `proton-tsc`)
- GitHub organization (`XPRNetwork`, formerly `ProtonProtocol`)
- Documentation and code comments
- Explorer (now `explorer.xprnetwork.org`, formerly `protonscan.io` and `proton.bloks.io`)

The token symbol remains **XPR** and all functionality is unchanged.

### Chain IDs

| Network | Chain ID |
|---------|----------|
| Mainnet | `384da888112027f0321850a169f737c33e53b388aad48b5adace4bab97f437e0` |
| Testnet | `71ee83bcf52142d61019d95f9cc5427ba6a0d7ff8accd9e2088ae2abeaf3d3dd` |

## Progressive Disclosure

Load specialized modules based on your task:

### Core Development

| Module | Read When | Key Topics |
|--------|-----------|------------|
| `smart-contracts.md` | Building contracts | Tables, actions, auth, build/deploy |
| `cli-reference.md` | Using CLI tools | Network, keys, deploy, queries, transfers, safe scripting of bulk jobs |
| `web-sdk.md` | Building dApps | Wallet connect, transactions, sessions, transfers |
| `backend-patterns.md` | Server-side dev | proton CLI keychain signing (v0.3.0+), bots, key isolation |
| `rpc-queries.md` | Reading chain data | RPC, Hyperion API, Light API, pagination, token balances |
| `testing-debugging.md` | Testing contracts | Unit tests, testnet, debugging, logs |
| `accounts-permissions.md` | Account management | Create accounts, permissions, multisig |
| `staking-governance.md` | Staking & voting | XPR staking, BPs, DPoS, resource model |

### Token & Identity

| Module | Read When | Key Topics |
|--------|-----------|------------|
| `token-creation.md` | Creating tokens | Fungible tokens, issuance, vesting |
| `webauth-identity.md` | User identity | WebAuth wallets, KYC, profiles, trust |
| `nfts-atomicassets.md` | NFT development | Collections, schemas, minting, marketplace |

### DeFi & Trading

| Module | Read When | Key Topics |
|--------|-----------|------------|
| `metalx-dex.md` | DEX integration | MetalX DEX API reference, order format, error codes |
| `alcor-dex.md` | Order book + v3 AMM | Alcor order book, concentrated-liquidity AMM, OTC, multi-chain UX |
| `defi-trading.md` | Trading bots/DeFi | Trading bot patterns, swap pools, DeFi strategies |
| `simpledex.md` | Token launch & AMM | SimpleDEX swaps, bonding curves, token creation, graduation |
| `loan-protocol.md` | Lending protocol | LOAN protocol, supply, borrow, health factor (liquidation mechanics deliberately omitted) |
| `oracles-randomness.md` | Price feeds & RNG | Oracle prices, verifiable random numbers |

### Integration Patterns

| Module | Read When | Key Topics |
|--------|-----------|------------|
| `real-time-events.md` | Live updates | Hyperion streaming, WebSockets, notifications |
| `payment-patterns.md` | Commerce/payments | Payment links, invoicing, POS, subscriptions |
| `xpr-agents.md` | Agent jobs on xpragents.com | Register, bid → select → fund order, revise/timeouts/milestones, job messages, fixed-price services (listsvc / buy: / boost:), multi-file delivery manifest, reviews, validators, arbitrators, stopping an agent, openclaw/sdk tooling (canonical: xpragents.com/llms.txt) |

### Infrastructure

| Module | Read When | Key Topics |
|--------|-----------|------------|
| `node-operation.md` | Running nodes | API nodes, Block Producers, validators |
| `hyperion-setup.md` | Setting up history nodes | Hyperion v4 full-history build, hardware sizing, dependency caveats, blocks.log replay, nginx/stream proxy |
| `hyperion-operations-caveats.md` | Running/debugging a Hyperion indexer | Composable-template trap, Redis bloat, disk-full stalls, queue purges that lose data, 10M-range backfill, consumer coma revive, `max_asc_window_days`, proving action-completeness |

### Safety & Reference

| Module | Read When | Key Topics |
|--------|-----------|------------|
| `safety-guidelines.md` | **BEFORE modifying contracts** | Table rules, deployment safety, recovery |
| `troubleshooting.md` | Debugging errors | Common errors, solutions, diagnostics |
| `examples.md` | Learning patterns | PriceBattle, ProtonWall, ProtonRating |
| `resources.md` | Finding endpoints | RPC URLs, docs, explorers, community |

---

## Quick Reference

### Common CLI Commands

```bash
# Install CLI
npm i -g @proton/cli

# Set network
proton chain:set proton          # Mainnet
proton chain:set proton-test     # Testnet

# Account info
proton account myaccount -t      # With token balances

# Query table
proton table CONTRACT TABLE

# Execute action
proton action CONTRACT ACTION 'JSON_DATA' AUTHORIZATION

# Deploy contract (prompts Continue? (y/N) — pipe `echo y |` in scripts; then check get_code_hash is non-zero)
proton contract:set ACCOUNT ./assembly/target
```

### Common RPC Query

```javascript
import { JsonRpc } from '@proton/js';
const rpc = new JsonRpc('https://proton.eosusa.io');

const { rows } = await rpc.get_table_rows({
  code: 'CONTRACT',
  scope: 'CONTRACT',
  table: 'TABLE',
  limit: 100
});
```

### Basic Contract Structure

```typescript
import { Contract, Table, TableStore, Name, requireAuth } from 'proton-tsc';

@table("mydata")
class MyData extends Table {
  constructor(
    public id: u64 = 0,
    public owner: Name = new Name(),
    public value: string = ""
  ) { super(); }

  @primary
  get primary(): u64 { return this.id; }
}

@contract
class MyContract extends Contract {
  dataTable: TableStore<MyData> = new TableStore<MyData>(this.receiver);

  @action("store")
  store(owner: Name, value: string): void {
    requireAuth(owner);
    const row = new MyData(this.dataTable.availablePrimaryKey, owner, value);
    this.dataTable.store(row, this.receiver);
  }
}
```

### Basic Frontend Login

```typescript
import '@proton/link';  // Required for mobile wallet support
import ProtonWebSDK from '@proton/web-sdk';

const { link, session } = await ProtonWebSDK({
  linkOptions: {
    chainId: '384da888112027f0321850a169f737c33e53b388aad48b5adace4bab97f437e0',
    endpoints: ['https://proton.eosusa.io']
  },
  selectorOptions: { appName: 'My App' }  // 4.x shape; 5.x (GA) uses uiOptions.appInfo — see web-sdk.md
});

// session.auth contains { actor, permission }
// Use session.transact() for transactions
```

---

## Key Packages

| Package | Purpose | Install |
|---------|---------|---------|
| `@proton/cli` | Command-line tools | `npm i -g @proton/cli` |
| `proton-tsc` | Contract development | `npm i proton-tsc` |
| `@proton/web-sdk` | Frontend wallet integration | `npm i @proton/web-sdk` |
| `@proton/link` | Mobile wallet transport (required with web-sdk) | `npm i @proton/link` |
| `@proton/js` | RPC queries | `npm i @proton/js` |

## Official Resources

- **Documentation**: https://docs.xprnetwork.org
- **GitHub**: https://github.com/XPRNetwork
- **Block Explorer**: https://explorer.xprnetwork.org
- **Resources Portal**: https://resources.xprnetwork.org (buy RAM, etc.)

---

## Safety Reminders

1. **NEVER modify existing table structures** once deployed with data - this breaks deserialization
2. **Always test on testnet** before mainnet deployment
3. **Verify the target account** before deploying - wrong account = overwrite existing contract
4. **Back up ABIs** before deploying changes
5. **Use new tables** for new features instead of modifying existing ones
6. **DEX deposits MUST use empty memo** (`""`) — any other memo (e.g. `"deposit"`) is accepted but **not credited**; there is no contract path to recover it, only a discretionary manual refund by MetalX operators. Treat as fund loss. See `metalx-dex.md`.
7. **All-numeric account names** (e.g. `333555`) cause silent data loss in `get_table_rows` — see `rpc-queries.md` for workarounds.
8. **A push response is not proof.** The proton CLI exits 0 on errors, and a `transaction_id` from a non-producing API node can still be dropped by the producer. Confirm by reading chain state, and never resend a push with an unknown outcome before its expiration has passed (CLI default: 3,000 s) — see `cli-reference.md` → *Scripting the CLI for bulk or high-value jobs*.