Skip to content

SKILL.md

Latest commit

 

History

History
238 lines (181 loc) · 9.15 KB

SKILL.md

File metadata and controls

238 lines (181 loc) · 9.15 KB
Raw
name xpr-network-dev
description Comprehensive knowledge for XPR Network blockchain development - smart contracts, CLI, web SDK, DeFi, NFTs, and infrastructure
version 2.3.2
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 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.

IMPORTANT DISCLAIMER: AI-Generated Smart Contract Code

Smart contracts handle real assets and are immutable once deployed. AI-generated code, including code produced with this skill, should always be reviewed by an experienced developer before deployment to mainnet.

  • Test thoroughly on testnet before any mainnet deployment
  • Have code reviewed by someone familiar with XPR Network/EOSIO smart contracts
  • Audit critical contracts - consider professional security audits for contracts handling significant value
  • Understand the code - don't deploy code you don't fully understand

Claude can accelerate development and help with patterns, but it does not replace proper code review, testing, and auditing practices.

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, a-z, 1-5)
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

Infrastructure

Module Read When Key Topics
node-operation.md Running nodes API nodes, Block Producers, validators

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

CRITICAL: Before Modifying Contracts

Read: safety-guidelines.md

  • NEVER modify existing table structures with data
  • Pre-deployment checklist
  • Recovery procedures

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

  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") causes permanent, irrecoverable 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.