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 encrypted on-disk keystore, never in the agent's process memory or context. 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 and ../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.
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 |
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, liquidations |
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, multi-file delivery manifest, reviews, validators, arbitrators (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
# 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
proton contract:set ACCOUNT ./assembly/target
Common RPC Query
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
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
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' }
});
// 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
Safety Reminders
- NEVER modify existing table structures once deployed with data - this breaks deserialization
- Always test on testnet before mainnet deployment
- Verify the target account before deploying - wrong account = overwrite existing contract
- Back up ABIs before deploying changes
- Use new tables for new features instead of modifying existing ones
- 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.
- All-numeric account names (e.g.
333555) cause silent data loss in get_table_rows — see rpc-queries.md for workarounds.
1---2name: xpr-network-dev3description: 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.4version: 2.6.05author: XPR Network Community6repository: https://github.com/XPRNetwork/xpr-network-dev-skill7metadata:8 source: https://skillmd.com/skills/xprnetwork/xpr-network-dev9---1011# XPR Network Developer Skill1213This skill provides comprehensive knowledge for developing on XPR Network, a fast, gas-free blockchain with WebAuthn wallet support.1415> **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 encrypted on-disk keystore, never in the agent's process memory or context. **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.1617> **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*.1819## XPR Network Overview2021XPR Network is an EOS-based blockchain optimized for payments and identity:2223| Feature | Description |24|---------|-------------|25| **Speed** | 0.5 second block times, 4000+ TPS |26| **Fees** | Zero gas fees for end users |27| **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 |28| **Wallets** | WebAuthn support (Face ID, fingerprint, security keys) |29| **Contracts** | AssemblyScript/TypeScript with `proton-tsc` |30| **Storage** | On-chain tables with RAM-based pricing |3132### Name Change: Proton → XPR Network3334The blockchain was rebranded from **Proton** to **XPR Network** in 2024. You may see legacy references to "Proton" in:35- Package names (`@proton/cli`, `@proton/web-sdk`, `proton-tsc`)36- GitHub organization (`XPRNetwork`, formerly `ProtonProtocol`)37- Documentation and code comments38- Explorer (now `explorer.xprnetwork.org`, formerly `protonscan.io` and `proton.bloks.io`)3940The token symbol remains **XPR** and all functionality is unchanged.4142### Chain IDs4344| Network | Chain ID |45|---------|----------|46| Mainnet | `384da888112027f0321850a169f737c33e53b388aad48b5adace4bab97f437e0` |47| Testnet | `71ee83bcf52142d61019d95f9cc5427ba6a0d7ff8accd9e2088ae2abeaf3d3dd` |4849## Progressive Disclosure5051Load specialized modules based on your task:5253### Core Development5455| Module | Read When | Key Topics |56|--------|-----------|------------|57| `smart-contracts.md` | Building contracts | Tables, actions, auth, build/deploy |58| `cli-reference.md` | Using CLI tools | Network, keys, deploy, queries, transfers |59| `web-sdk.md` | Building dApps | Wallet connect, transactions, sessions, transfers |60| `backend-patterns.md` | Server-side dev | proton CLI keychain signing (v0.3.0+), bots, key isolation |61| `rpc-queries.md` | Reading chain data | RPC, Hyperion API, Light API, pagination, token balances |62| `testing-debugging.md` | Testing contracts | Unit tests, testnet, debugging, logs |63| `accounts-permissions.md` | Account management | Create accounts, permissions, multisig |64| `staking-governance.md` | Staking & voting | XPR staking, BPs, DPoS, resource model |6566### Token & Identity6768| Module | Read When | Key Topics |69|--------|-----------|------------|70| `token-creation.md` | Creating tokens | Fungible tokens, issuance, vesting |71| `webauth-identity.md` | User identity | WebAuth wallets, KYC, profiles, trust |72| `nfts-atomicassets.md` | NFT development | Collections, schemas, minting, marketplace |7374### DeFi & Trading7576| Module | Read When | Key Topics |77|--------|-----------|------------|78| `metalx-dex.md` | DEX integration | MetalX DEX API reference, order format, error codes |79| `alcor-dex.md` | Order book + v3 AMM | Alcor order book, concentrated-liquidity AMM, OTC, multi-chain UX |80| `defi-trading.md` | Trading bots/DeFi | Trading bot patterns, swap pools, DeFi strategies |81| `simpledex.md` | Token launch & AMM | SimpleDEX swaps, bonding curves, token creation, graduation |82| `loan-protocol.md` | Lending protocol | LOAN protocol, supply, borrow, liquidations |83| `oracles-randomness.md` | Price feeds & RNG | Oracle prices, verifiable random numbers |8485### Integration Patterns8687| Module | Read When | Key Topics |88|--------|-----------|------------|89| `real-time-events.md` | Live updates | Hyperion streaming, WebSockets, notifications |90| `payment-patterns.md` | Commerce/payments | Payment links, invoicing, POS, subscriptions |91| `xpr-agents.md` | Agent jobs on xpragents.com | Register, bid → select → fund order, multi-file delivery manifest, reviews, validators, arbitrators (canonical: xpragents.com/llms.txt) |9293### Infrastructure9495| Module | Read When | Key Topics |96|--------|-----------|------------|97| `node-operation.md` | Running nodes | API nodes, Block Producers, validators |98| `hyperion-setup.md` | Setting up history nodes | Hyperion v4 full-history build, hardware sizing, dependency caveats, blocks.log replay, nginx/stream proxy |99| `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 |100101### Safety & Reference102103| Module | Read When | Key Topics |104|--------|-----------|------------|105| `safety-guidelines.md` | **BEFORE modifying contracts** | Table rules, deployment safety, recovery |106| `troubleshooting.md` | Debugging errors | Common errors, solutions, diagnostics |107| `examples.md` | Learning patterns | PriceBattle, ProtonWall, ProtonRating |108| `resources.md` | Finding endpoints | RPC URLs, docs, explorers, community |109110---111112## Quick Reference113114### Common CLI Commands115116```bash117# Install CLI118npm i -g @proton/cli119120# Set network121proton chain:set proton # Mainnet122proton chain:set proton-test # Testnet123124# Account info125proton account myaccount -t # With token balances126127# Query table128proton table CONTRACT TABLE129130# Execute action131proton action CONTRACT ACTION 'JSON_DATA' AUTHORIZATION132133# Deploy contract134proton contract:set ACCOUNT ./assembly/target135```136137### Common RPC Query138139```javascript140import { JsonRpc } from '@proton/js';141const rpc = new JsonRpc('https://proton.eosusa.io');142143const { rows } = await rpc.get_table_rows({144 code: 'CONTRACT',145 scope: 'CONTRACT',146 table: 'TABLE',147 limit: 100148});149```150151### Basic Contract Structure152153```typescript154import { Contract, Table, TableStore, Name, requireAuth } from 'proton-tsc';155156@table("mydata")157class MyData extends Table {158 constructor(159 public id: u64 = 0,160 public owner: Name = new Name(),161 public value: string = ""162 ) { super(); }163164 @primary165 get primary(): u64 { return this.id; }166}167168@contract169class MyContract extends Contract {170 dataTable: TableStore<MyData> = new TableStore<MyData>(this.receiver);171172 @action("store")173 store(owner: Name, value: string): void {174 requireAuth(owner);175 const row = new MyData(this.dataTable.availablePrimaryKey, owner, value);176 this.dataTable.store(row, this.receiver);177 }178}179```180181### Basic Frontend Login182183```typescript184import '@proton/link'; // Required for mobile wallet support185import ProtonWebSDK from '@proton/web-sdk';186187const { link, session } = await ProtonWebSDK({188 linkOptions: {189 chainId: '384da888112027f0321850a169f737c33e53b388aad48b5adace4bab97f437e0',190 endpoints: ['https://proton.eosusa.io']191 },192 selectorOptions: { appName: 'My App' }193});194195// session.auth contains { actor, permission }196// Use session.transact() for transactions197```198199---200201## Key Packages202203| Package | Purpose | Install |204|---------|---------|---------|205| `@proton/cli` | Command-line tools | `npm i -g @proton/cli` |206| `proton-tsc` | Contract development | `npm i proton-tsc` |207| `@proton/web-sdk` | Frontend wallet integration | `npm i @proton/web-sdk` |208| `@proton/link` | Mobile wallet transport (required with web-sdk) | `npm i @proton/link` |209| `@proton/js` | RPC queries | `npm i @proton/js` |210211## Official Resources212213- **Documentation**: https://docs.xprnetwork.org214- **GitHub**: https://github.com/XPRNetwork215- **Block Explorer**: https://explorer.xprnetwork.org216- **Resources Portal**: https://resources.xprnetwork.org (buy RAM, etc.)217218---219220## Safety Reminders2212221. **NEVER modify existing table structures** once deployed with data - this breaks deserialization2232. **Always test on testnet** before mainnet deployment2243. **Verify the target account** before deploying - wrong account = overwrite existing contract2254. **Back up ABIs** before deploying changes2265. **Use new tables** for new features instead of modifying existing ones2276. **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`.2287. **All-numeric account names** (e.g. `333555`) cause silent data loss in `get_table_rows` — see `rpc-queries.md` for workarounds.