Architecture

Pilier is built on Polkadot SDK, the modular blockchain framework powering Polkadot. This architecture delivers enterprise-grade performance, forkless upgrades, and seamless interoperability—all while maintaining EU sovereignty and regulatory compliance.

---

Overview

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                      User Layer                             │
│  pilier.org (SaaS) │ Partners (APIs) │ Public Verifier      │
└────────────────┬────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────┐
│                   Application Layer                         │
│         Autonomous Agents │ DPP Templates                   │
└────────────────┬────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────┐
│           Blockchain Layer (Polkadot SDK)                   │
│  Runtime (Pallets) │ Consensus (AURA+GRANDPA) │ Storage     │
└────────────────┬────────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────────┐
│                  Infrastructure Layer                       │
│  Validators │ RPC Nodes │ Archive Nodes │ Telemetry         │
└─────────────────────────────────────────────────────────────┘

---

Core Components

1. Polkadot SDK Runtime

• Custom blockchain logic (pallets)
• Deterministic state transitions
• Forkless upgrades via WebAssembly

2. Consensus Layer

• AURA (block production)
• GRANDPA (finality)
• Institutional validators (PoA)

3. Storage Layer

• On-chain state (accounts, balances, DPPs)
• Off-chain worker data
• IPFS/Arweave for large files (optional)

4. Network Layer

• P2P communication (libp2p)
• RPC endpoints (JSON-RPC, WebSocket)
• Block propagation

5. Application Layer

• Smart wallets (seedless, OAuth)
• Autonomous agents (lifecycle automation)
• DPP templates (industry presets)

---

Polkadot SDK Framework

Why Polkadot SDK?

Polkadot SDK is a modular blockchain framework developed by Parity Technologies (creators of Polkadot). It provides:

✅ Battle-tested foundation

• Powers Polkadot (60+ parachains, $10B+ total value)
• Used by Kusama, Moonbeam, Astar, and 100+ projects
• 7+ years of production hardening

✅ Forkless upgrades

• Runtime stored as WebAssembly on-chain
• Upgrade via governance vote (no hard forks)
• Zero downtime, backward compatibility

✅ Modular design

• Pick pallets (modules) you need
• Custom business logic without reinventing consensus
• Rapid development (months vs. years)

✅ Enterprise performance

• 6-second block time
• 1,000+ transactions per block
• Sub-second finality with GRANDPA

✅ Interoperability ready

• Native Polkadot parachain compatibility
• Cross-chain messaging (XCMP/XCM)
• Bridge to Ethereum, Cosmos, etc.

---

Polkadot SDK Architecture Layers

┌───────────────────────────────────────────────────────────┐
│                     Client (Node)                         │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              Runtime (WebAssembly)                  │  │
│  │  ┌────────────┬────────────┬────────────┬────────┐  │  │
│  │  │   Pallet   │   Pallet   │   Pallet   │  ...   │  │  │
│  │  │  Balances  │   Assets   │    DPP     │        │  │  │
│  │  └────────────┴────────────┴────────────┴────────┘  │  │
│  │                                                     │  │
│  │  Frame (Runtime Framework)                          │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │             Core (Consensus, Network, Storage)      │  │
│  │  - AURA (Block Production)                          │  │
│  │  - GRANDPA (Finality)                               │  │
│  │  - libp2p (P2P Networking)                          │  │
│  │  - RocksDB (State Storage)                          │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

Client (Node):

• Written in Rust
• Handles networking, consensus, storage
• Executes runtime (WebAssembly)

Runtime:

• Business logic (pallets)
• Compiled to WebAssembly (Wasm)
• Upgradable without node restart

Pallets:

• Modular components (like plugins)
• Each pallet = specific functionality
• Composable (pallets interact with each other)

---

Forkless Upgrades

Traditional blockchains (Bitcoin, Ethereum):

1. Propose protocol change
2. Developers code new version
3. Nodes must manually upgrade
4. If disagreement → hard fork (chain split)

Example: Ethereum → Ethereum Classic (2016)

Polkadot SDK (Pilier):

1. Propose runtime upgrade (governance)
2. tPIL holders vote
3. If passed → runtime Wasm updated on-chain
4. All nodes execute new runtime automatically

Result: No fork, no downtime, no manual upgrades ✓

How it works:

Block 1,000,000: Runtime version 1.0
├─ Max DPP size: 10 MB
├─ Transaction fee: 0.004 PIL
└─ 5 pallets active

Governance vote passes: Upgrade to runtime 1.1

Block 1,050,000: Runtime version 1.1 (automatic)
├─ Max DPP size: 50 MB (upgraded)
├─ Transaction fee: 0.003 PIL (upgraded)
└─ 6 pallets active (new pallet added)

Validators did not restart nodes
Users did not update wallets
Everything just works ✓

---

Runtime Architecture

Pallets (Modules)

Pilier's runtime is composed of pallets—modular components that encapsulate specific functionality.

Core Pallets (Polkadot SDK standard)

Pallet	Purpose	Example
pallet-balances	Account balances, transfers	Alice sends 10 PIL to Bob
pallet-timestamp	Block timestamps	Block created at 2027-03-15 10:30:00 UTC
pallet-transaction-payment	Fee calculation, payment	User pays 0.004 PIL gas
pallet-sudo	Superuser (testnet only)	Emergency protocol fix
pallet-aura	Block production (AURA)	Validator takes turn producing block
pallet-grandpa	Finality (GRANDPA)	Validators vote to finalize chain

---

Custom Pallets (Pilier-specific)

Pallet	Purpose	Status
pallet-dpp	Digital Product Passports	✅ Mainnet (v1.0)
pallet-agents	Autonomous agent logic	✅ Mainnet (v1.0)
pallet-trust	tPIL (PIL Trust) governance	🚧 Q2 2027
pallet-vault	Encrypted data storage	🚧 Q3 2027
pallet-oracle	External data feeds (IoT, ERP)	🚧 Q4 2027
pallet-identities	Organization DIDs	📋 Roadmap
pallet-escrow	Marketplace escrow	📋 Roadmap

---

Pallet: DPP (Digital Product Passports)

Purpose: Create, store, and manage DPPs on-chain.

Key functions:

// Create a new DPP
create_dpp(
  origin,
  product_id: Vec<u8>,        // GS1 GTIN or custom ID
  metadata: DppMetadata,       // JSON-LD compliant data
  schema_version: u32          // ESPR schema version
) -> Result<DppId>

// Update DPP (append lifecycle event)
update_dpp(
  origin,
  dpp_id: DppId,
  event: LifecycleEvent        // Production, shipment, receipt, etc.
) -> Result<()>

// Transfer ownership
transfer_dpp(
  origin,
  dpp_id: DppId,
  new_owner: AccountId
) -> Result<()>

// Query DPP
get_dpp(dpp_id: DppId) -> Option<Dpp>

Storage:

// Map: DPP ID → DPP Data
pub Dpps: map DppId => Option<Dpp>;

// Map: Owner → List of DPP IDs
pub DppsByOwner: map AccountId => Vec<DppId>;

// Map: Product ID → DPP ID (for lookups)
pub DppsByProductId: map Vec<u8> => Option<DppId>;

Events:

DppCreated(DppId, AccountId, ProductId)
DppUpdated(DppId, LifecycleEvent)
DppTransferred(DppId, AccountId, AccountId)

---

Pallet: Agents (Autonomous Agents)

Purpose: Attach autonomous logic to DPPs for lifecycle automation.

Key functions:

// Attach agent to DPP
attach_agent(
  origin,
  dpp_id: DppId,
  agent_type: AgentType,       // Lite, Pro, Modular
  config: AgentConfig          // Triggers, actions, webhooks
) -> Result<AgentId>

// Execute agent action (called by off-chain worker or validator)
execute_agent(
  agent_id: AgentId,
  trigger: TriggerEvent         // Barcode scan, IoT data, time-based
) -> Result<Vec<Action>>

// Update agent config
update_agent(
  origin,
  agent_id: AgentId,
  new_config: AgentConfig
) -> Result<()>

Agent types:

enum AgentType {
  Lite,      // Basic triggers (scan → timestamp)
  Pro,       // Multi-step workflows (scan → ERP → webhook)
  Modular    // Plugin-based (marketplace modules)
}

Triggers:

enum TriggerEvent {
  BarcodeScanned(Vec<u8>),
  IoTDataReceived(SensorData),
  TimeElapsed(Duration),
  ManualInvocation
}

Actions:

enum Action {
  UpdateDpp(LifecycleEvent),
  SendWebhook(Url, Payload),
  SendEmail(Address, Body),
  CallExternalApi(Url, Method, Payload)
}

Storage:

// Map: Agent ID → Agent Config
pub Agents: map AgentId => Option<Agent>;

// Map: DPP ID → Agent IDs
pub AgentsByDpp: map DppId => Vec<AgentId>;

// Execution queue (off-chain worker processes)
pub AgentQueue: Vec<(AgentId, TriggerEvent)>;

---

Pallet: Trust (PIL Trust Governance)

Purpose: Manage tPIL (time-locked voting power) and governance.

Key functions:

// Lock PIL to earn tPIL
lock_pil(
  origin,
  amount: Balance,
  duration: BlockNumber         // 1 month = ~432,000 blocks (6s blocks)
) -> Result<LockId>

// Extend existing lock
extend_lock(
  origin,
  lock_id: LockId,
  additional_duration: BlockNumber
) -> Result<()>

// Unlock early (with penalty)
unlock_early(
  origin,
  lock_id: LockId
) -> Result<Balance>             // Returns PIL, loses tPIL

// Calculate current tPIL balance
get_tpil_balance(account: AccountId) -> Balance

Storage:

// Map: Account → List of Locks
pub Locks: map AccountId => Vec<Lock>;

// Lock structure
pub struct Lock {
  amount: Balance,               // PIL locked
  start_block: BlockNumber,
  end_block: BlockNumber,
  initial_tpil: Balance,         // tPIL at lock time
}

// Real-time tPIL calculation (not stored, computed on-the-fly)
fn calculate_tpil(lock: &Lock, current_block: BlockNumber) -> Balance {
  let elapsed = current_block - lock.start_block;
  let total_duration = lock.end_block - lock.start_block;
  let remaining = total_duration - elapsed;

  // Linear decay
  lock.initial_tpil * remaining / total_duration
}

Governance integration:

// Submit proposal
submit_proposal(
  origin,
  proposal: Call,                // Runtime call to execute if passed
  deposit: Balance               // 1,000 PIL deposit
) -> Result<ProposalId>

// Vote on proposal
vote(
  origin,
  proposal_id: ProposalId,
  vote: Vote                     // Aye, Nay, Abstain
) -> Result<()>

// Voting weight = tPIL balance at proposal submission block

---

Data Flow

Example: Create DPP via Agent

Scenario: SME scans barcode → Agent creates DPP automatically

┌──────────┐
│   User   │ Scans barcode via Pilier PWA
└────┬─────┘
     │
     ▼
┌──────────────────┐
│  Pilier Backend  │ Receives scan event
└────┬─────────────┘
     │
     │ (1) Query: Which agent handles this product?
     ▼
┌──────────────────┐
│   RPC Node       │ pallet-agents: get_agent_by_product_id()
└────┬─────────────┘
     │
     │ (2) Response: agent-123 (Pro Agent, DPP creation workflow)
     ▼
┌──────────────────┐
│  Pilier Backend  │ Constructs transaction: execute_agent(agent-123, BarcodeScanned)
└────┬─────────────┘
     │
     │ (3) Sign transaction with sponsor account (gas sponsorship)
     ▼
┌──────────────────┐
│   Validator      │ Receives transaction, validates signature
└────┬─────────────┘
     │
     │ (4) Execute runtime: pallet-agents::execute_agent()
     ▼
┌──────────────────┐
│   Runtime        │ Agent logic runs:
│  (pallet-agents) │ - Fetch product metadata (off-chain worker)
└────┬─────────────┘ - Create DPP (pallet-dpp::create_dpp)
     │               - Send webhook (off-chain worker)
     │
     │ (5) State changes committed, events emitted
     ▼
┌──────────────────┐
│   Storage        │ DPP stored on-chain
│   (RocksDB)      │ Events indexed
└────┬─────────────┘
     │
     │ (6) Block produced (AURA), finalized (GRANDPA)
     ▼
┌──────────────────┐
│   User           │ Receives confirmation: "DPP created: pilier.net/dpp/abc123"
└──────────────────┘ (less than 20 seconds total)

---

Transaction Lifecycle

Step 1: Transaction Construction
├─ User/backend creates transaction
├─ Includes: call (function to execute), signature, nonce
└─ Signed with private key (or sponsored account)

Step 2: Transaction Pool
├─ Submitted to RPC node
├─ Validated (signature, nonce, balance)
└─ Added to transaction pool (mempool)

Step 3: Block Production
├─ Validator's turn (AURA round-robin)
├─ Validator selects transactions from pool
├─ Executes transactions in runtime (Wasm)
└─ Produces block with state changes

Step 4: Block Propagation
├─ Validator broadcasts block to network
├─ Other validators verify block
└─ Block added to chain

Step 5: Finality
├─ GRANDPA validators vote on chain
├─ If 2/3+ agree → block finalized
└─ Irreversible (transaction confirmed)

Timeline:
t=0s: Transaction submitted
t=6s: Block produced (AURA)
t=12s: Block finalized (GRANDPA)

---

Storage Architecture

On-Chain Storage

Storage types:

// Single value
pub RuntimeVersion: Version;

// Map (key → value)
pub Balances: map AccountId => Balance;

// Double map (key1, key2 → value)
pub AgentsByDpp: double_map DppId, AgentId => Agent;

// Vec (list)
pub Validators: Vec<AccountId>;

Storage costs:

Operation	Cost (approximate)	Notes
Store 1 KB	0.00001 PIL	~€0.00001
Read 1 KB	Free	No cost to query
Delete 1 KB	Refund 0.000005 PIL	Incentivize cleanup

Storage rent: None. Once stored, data persists forever (no recurring fees).

---

Off-Chain Storage

Why off-chain?

Some data is too large or unnecessary for on-chain storage:

• ❌ 50 MB PDF documents (too expensive)
• ❌ High-frequency IoT sensor data (bloats chain)
• ❌ Temporary computation results (not critical for consensus)

Off-chain solutions:

1. Off-chain workers (built into Polkadot SDK)

What: Background threads in validator nodes
Use cases:
- Fetch IoT data from external APIs
- Process large files (e.g., image recognition)
- Send webhooks (HTTP requests)

How it works:
- Off-chain worker reads on-chain state
- Performs computation off-chain
- Submits result back on-chain (signed transaction)

2. IPFS (InterPlanetary File System)

What: Decentralized file storage (content-addressed)
Use cases:
- Store large DPP attachments (PDFs, images)
- Archive historical audit trails

How it works:
- Upload file to IPFS → receive hash (CID)
- Store CID on-chain (32 bytes)
- Anyone can retrieve file via CID

Example:
On-chain: dpp-123 → { ..., attachment_cid: "Qm..." }
Off-chain: ipfs.io/ipfs/Qm... → retrieves PDF

3. Arweave (permanent storage)

What: Pay-once, store-forever blockchain
Use cases:
- Legal compliance (documents must persist 10+ years)
- Regulatory audit trails

How it works:
- Upload file to Arweave → pay one-time fee
- Receive transaction ID
- Store txID on-chain

Example:
On-chain: dpp-456 → { ..., arweave_tx: "abc..." }
Off-chain: arweave.net/abc... → retrieves file forever

---

Storage Optimization

Best practices:

// ❌ Bad: Store entire JSON on-chain
pub Metadata: map DppId => Vec<u8>;  // 10 KB JSON

// ✅ Good: Store hash on-chain, JSON on IPFS
pub MetadataHash: map DppId => [u8; 32];  // 32 bytes CID

State pruning:

Archive nodes: Store full history (all blocks, all state changes)
Full nodes: Store recent state (last N blocks, prune old state)
Light clients: Store only headers (query full nodes for data)

Pilier default:
- Validators: Full nodes (prune state older than 1 year)
- RPC nodes: Archive nodes (for public explorer)
- User wallets: Light clients (minimal storage)

---

Network Architecture

Node Types

1. Validator Nodes

Purpose: Produce blocks, finalize chain
Count: 5-10
Hardware: High-performance (dedicated servers)
Requirements:
├─ 8 CPU cores
├─ 32 GB RAM
├─ 1 TB NVMe SSD
├─ 1 Gbps network
└─ 99.9% uptime

Operated by: Universities, NGOs, chambers

2. RPC Nodes

Purpose: Serve API requests (user queries, transaction submission)
Count: 3-5 (load balanced)
Hardware: Medium-performance
Requirements:
├─ 4 CPU cores
├─ 16 GB RAM
├─ 500 GB SSD
└─ High bandwidth (users query frequently)

Operated by: Pilier Foundation, partners

3. Archive Nodes

Purpose: Store full blockchain history (for explorer, analytics)
Count: 1-2
Hardware: High storage
Requirements:
├─ 4 CPU cores
├─ 32 GB RAM
├─ 5 TB+ SSD (grows over time)
└─ Moderate bandwidth

Operated by: Pilier Foundation

4. Boot Nodes

Purpose: Help new nodes discover network (peer discovery)
Count: 2-3
Hardware: Minimal
Requirements:
├─ 2 CPU cores
├─ 4 GB RAM
├─ Stable IP address

Operated by: Pilier Foundation

---

Network Topology

                    ┌──────────────┐
                    │  Boot Nodes  │
                    └───────┬──────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
    ┌────▼────┐       ┌─────▼────┐       ┌─────▼────┐
    │Validator│◄─────►│Validator │◄─────►│Validator │
    │  Node 1 │       │  Node 2  │       │  Node 3  │
    └────┬────┘       └─────┬────┘       └─────┬────┘
         │                  │                  │
         └──────────────────┼──────────────────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
    ┌────▼────┐       ┌─────▼────┐       ┌─────▼────┐
    │   RPC   │       │   RPC    │       │  Archive │
    │  Node 1 │       │  Node 2  │       │   Node   │
    └────┬────┘       └─────┬────┘       └─────┬────┘
         │                  │                  │
         └──────────────────┼──────────────────┘
                            │
                   ┌────────▼────────┐
                   │  Load Balancer  │
                   │ rpc.pilier.net  │
                   └────────┬────────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
         ┌────▼───┐    ┌────▼───┐    ┌────▼───┐
         │  User  │    │Partner │    │Explorer│
         │ Wallet │    │  API   │    │  UI    │
         └────────┘    └────────┘    └────────┘

---

RPC Endpoints

Public RPC: https://rpc.pilier.net

Methods:

# Get latest block
curl https://rpc.pilier.net \
  -d '{"method":"chain_getBlock"}'

# Get account balance
curl https://rpc.pilier.net \
  -d '{"method":"system_accountInfo", "params":["5Gx8R..."]}'

# Submit transaction
curl https://rpc.pilier.net \
  -d '{"method":"author_submitExtrinsic", "params":["0x..."]}'

# Subscribe to new blocks (WebSocket)
wscat -c wss://rpc.pilier.net
> {"method":"chain_subscribeNewHeads"}

Rate limits:

Public RPC:
├─ 100 requests/minute per IP
├─ 10 WebSocket connections per IP
└─ No authentication required (read-only queries)

Partner API:
├─ 10,000 requests/minute (authenticated)
├─ 100 WebSocket connections
└─ API key required

---

Security Architecture

Defense in Depth

Layer 1: Network Security

DDoS protection:
├─ Cloudflare in front of RPC nodes
├─ Rate limiting (per IP, per method)
└─ Geographic distribution (validators in different data centers)

Sybil resistance:
├─ Known validators (PoA, not anonymous)
├─ Institutional identity verification
└─ Governance approval for new validators

Layer 2: Consensus Security

Byzantine Fault Tolerance:
├─ Can tolerate 1/3 malicious validators
├─ GRANDPA finality prevents chain reorgs
└─ Validator Charter (legal accountability)

No economic attacks:
├─ No token staking (no "nothing at stake" problem)
├─ No mining (no 51% attacks)
└─ Reputation-based (attacking = institutional scandal)

Layer 3: Runtime Security

Deterministic execution:
├─ WebAssembly sandboxing
├─ No system calls (network, filesystem)
└─ All state changes auditable

Formal verification (future):
├─ Critical pallets (balances, governance)
├─ Mathematical proofs of correctness
└─ Collaboration with academic institutions

Layer 4: Application Security

Smart wallet security:
├─ MPC (Multi-Party Computation) for key shards
├─ WebAuthn (biometric auth)
├─ No seed phrases (user-friendly + secure)

Agent sandboxing:
├─ Agents cannot access arbitrary state
├─ Restricted to DPP they're attached to
└─ Off-chain actions (webhooks) rate-limited

Layer 5: Data Security

GDPR compliance:
├─ Personal data off-chain (IPFS encrypted)
├─ On-chain: Only hashes, public identifiers
└─ Right to be forgotten: delete off-chain data, hash remains

Encryption at rest:
├─ Validator storage encrypted (LUKS)
├─ Backups encrypted (AES-256)
└─ Key management (HSM for validators)

---

Audit & Monitoring

Security audits:

Pre-mainnet (2026):
├─ Runtime audit (Trail of Bits or Kudelski)
├─ Smart wallet audit (Cure53)
└─ Infrastructure pentest (internal team)

Annual (2027+):
├─ Runtime upgrade audits (if critical pallets changed)
├─ Third-party pentests (network, RPC nodes)
└─ Bug bounty program (HackerOne)

Monitoring stack:

Telemetry:
├─ Polkadot SDK telemetry (public dashboard)
├─ Per-validator metrics (CPU, RAM, disk, network)
└─ Real-time alerts (Slack, PagerDuty)

Logging:
├─ Centralized logs (Loki or ELK)
├─ 90-day retention (compliance)
└─ Anomaly detection (ML-based)

Alerting:
├─ Validator downtime (immediate)
├─ Chain stall (immediate)
├─ High transaction failure rate (5 min)
└─ Storage near capacity (24 hr warning)

---

Interoperability

Polkadot Integration (Roadmap)

Phase 1 (2026-2027): Standalone chain

Status: Independent Polkadot SDK chain
Consensus: Own validator set (PoA)
Security: Own finality (GRANDPA)

Phase 2 (2028+): Polkadot parachain (optional)

Status: Parachain on Polkadot Relay Chain
Consensus: Polkadot validators secure Pilier
Security: Shared security (Polkadot's $10B+ stake)

Benefits:
├─ Trustless cross-chain messaging (XCMP)
├─ Composability with 60+ parachains
├─ Lower validator costs (outsourced security)

Trade-offs:
├─ Lease cost (~$2M/2 years, paid in DOT)
├─ Less sovereignty (must follow Polkadot governance)
└─ Increased complexity

Decision criteria (2027 governance vote):

Become parachain IF:
├─ Cross-chain demand exists (users want interop with DeFi, etc.)
├─ Treasury has sufficient funds (~$2M for lease)
├─ Polkadot ecosystem aligned with civic mission

Stay standalone IF:
├─ EU sovereignty paramount (own validator set)
├─ No cross-chain demand (Pilier users stay in Pilier)
└─ Lower operational cost matters more

---

Bridges (Future)

Ethereum bridge (2028+):

Use case: Allow Ethereum projects to verify Pilier DPPs
Mechanism:
├─ Light client on Ethereum (verify GRANDPA finality)
├─ Bridge contract (escrow assets)
└─ Relayer network (submit proofs)

Example:
- Ethereum DeFi protocol lends against tokenized DPP
- DPP ownership verified via Pilier → Ethereum bridge
- If default, DPP transferred to lender

Cosmos IBC (2029+):

Use case: Interop with Cosmos ecosystem (supply chain projects)
Mechanism:
├─ IBC module in Pilier runtime
├─ Connect to Cosmos Hub
└─ Cross-chain DPP transfers

Example:
- Cosmos-based supply chain app queries Pilier DPP
- Verifies provenance without leaving Cosmos

---

Development & Deployment

Local Development

Setup local node:

# Clone Pilier node
git clone https://github.com/pilier-org/pilier-node.git
cd pilier-node

# Build (Rust required)
cargo build --release

# Run local testnet (single validator)
./target/release/pilier-node \
  --dev \
  --tmp \
  --rpc-port 9933 \
  --ws-port 9944

# Node runs at:
# RPC: http://localhost:9933
# WebSocket: ws://localhost:9944

Interact with local node:

# Install Polkadot.js CLI
npm install -g @polkadot/api-cli

# Query chain info
polkadot-js-api \
  --ws ws://localhost:9944 \
  query.system.chain

# Transfer tokens
polkadot-js-api \
  --ws ws://localhost:9944 \
  --seed "//Alice" \
  tx.balances.transfer Bob 1000000000000

---

Testnet Deployment

Pilier testnet: wss://testnet-rpc.pilier.net

Faucet: Request test PIL at testnet.pilier.net/faucet

Explorer: testnet-explorer.pilier.net

Differences from mainnet:

Testnet:
├─ Sudo key active (rapid iteration)
├─ State resets periodically (no permanence)
├─ Free PIL from faucet
└─ 3 validators (all Pilier-operated)

Mainnet:
├─ No sudo (governance only)
├─ Permanent state (irreversible)
├─ PIL has real value (~€1)
└─ 5-10 validators (institutional)

---

Mainnet Deployment

Infrastructure:

Validators: 5-10 nodes
├─ Geographic: FR, DE, BE, NL, GE
├─ Operators: Universities, NGOs, chambers
└─ Hosting: OVH, Hetzner, AWS (redundant)

RPC Nodes: 3 nodes
├─ Load balanced (rpc.pilier.net)
├─ Cloudflare DDoS protection
└─ 99.9% uptime SLA

Archive Node: 1 node
├─ Full history (for explorer)
├─ 5 TB storage
└─ Daily backups

Boot Nodes: 2 nodes
├─ Stable IPs
├─ Peer discovery
└─ Minimal resources

Deployment process:

1. Genesis preparation (2-4 weeks before launch)
├─ Finalize genesis state (accounts, balances, pallets)
├─ Distribute genesis file to validators
└─ Validators generate session keys

2. Coordinated launch (launch day)
├─ All validators start nodes simultaneously
├─ First block produced within 60 seconds
└─ Monitor telemetry for 24 hours

3. Post-launch (first week)
├─ Gradual traffic ramp-up
├─ Monitor validator performance
└─ Fix any issues via sudo (if testnet) or governance (if mainnet)

4. Stabilization (first month)
├─ All validators achieving 99.9% uptime
├─ RPC load balanced
└─ Public announcement: mainnet live

---

Performance & Scalability

Current Limits (v1.0)

Metric	Limit	Notes
Block time	6 seconds	AURA configuration
Block size	5 MB	Max transactions per block
Transactions/block	~1,000	Depends on tx size
Transactions/second	~166 TPS	1,000 tx / 6s
Finality	12-18 seconds	2-3 blocks (GRANDPA)
Max DPP size	10 MB	On-chain + IPFS hash
Max accounts	Unlimited	Map storage scales
Storage growth	~10 GB/year	Estimated (depends on usage)

---

Scalability Roadmap

Phase 1 (2026-2027): Optimization

Target: 500 TPS
Approach:
├─ Parallel transaction execution (wasm-opt)
├─ Storage optimization (prune old state)
└─ Off-chain workers for heavy computation

Result: 3× throughput without architectural changes

Phase 2 (2028): Sharding / Parallel Chains

Target: 2,000 TPS
Approach:
├─ Domain-specific shards (electronics, textiles, batteries)
├─ Each shard = separate state, own validators
└─ Cross-shard communication via Pilier relay

Result: 10× throughput with horizontal scaling

Phase 3 (2029+): Parachain

Target: 10,000+ TPS
Approach:
├─ Become Polkadot parachain
├─ Leverage Polkadot's shared security + XCMP
└─ Access to 60+ parachains' liquidity

Result: Unlimited scalability via Polkadot ecosystem

---

Governance of Architecture

Who decides architecture changes?

Phase 1 (Testnet): Pilier core team (sudo key)
Phase 2 (Early mainnet): Simple governance (1 PIL = 1 vote)
Phase 3 (Mature mainnet): tPIL governance (time-locked voting)

Example governance proposals:

Proposal: Increase block size from 5 MB to 10 MB
Rationale: Support larger DPPs (50 MB PDFs)
Impact: Validators need more bandwidth
Vote: 65% approval → passed

Proposal: Add pallet-escrow for marketplace
Rationale: Enable P2P trading with trust bonds
Impact: New runtime logic, audit required
Vote: 75% approval → passed (after audit)

Proposal: Migrate to Polkadot parachain
Rationale: Access cross-chain ecosystem
Impact: Major change, $2M cost
Vote: 80% threshold (high-impact decision)

---

FAQ

Why Polkadot SDK instead of building from scratch?

Building from scratch:

• ❌ 2-3 years to production-ready blockchain
• ❌ Reinvent consensus, networking, storage
• ❌ High security risk (untested codebase)
• ❌ No ecosystem (no tools, no community)

Using Polkadot SDK:

• ✅ 6-12 months to custom blockchain
• ✅ Battle-tested consensus (AURA + GRANDPA)
• ✅ Security audited (Parity + Polkadot ecosystem)
• ✅ Rich ecosystem (wallets, explorers, SDKs)

Result: Focus on business logic (DPPs, agents) instead of reinventing infrastructure.

---

Why not Ethereum?

Ethereum pros:

• ✅ Largest ecosystem (10M+ users)
• ✅ Mature tooling (Metamask, Etherscan)
• ✅ Liquidity (DeFi, NFTs)

Ethereum cons for Pilier:

• ❌ Gas price volatility (unpredictable costs for SMEs)
• ❌ Slow finality (~15 minutes)
• ❌ EVM limitations (hard to build custom logic)
• ❌ Not EU-sovereign (global validator set)

Polkadot SDK advantages:

• ✅ Predictable gas (stable €0.004 per DPP)
• ✅ Fast finality (12 seconds)
• ✅ Custom logic (native pallets, not EVM hacks)
• ✅ EU-focused (validators subject to EU law)

---

Can Pilier interoperate with Ethereum?

Yes, via bridges (2028+ roadmap).

Use case:

Ethereum DeFi protocol wants to verify Pilier DPP:
1. DPP created on Pilier
2. Bridge relayer submits proof to Ethereum
3. Ethereum smart contract verifies proof
4. Ethereum DeFi protocol accepts DPP as collateral

Mechanism: Light client + merkle proofs (trustless verification)

---

Is Pilier open source?

Yes, fully open source (Apache 2.0 license).

Repositories:

pilier-node: Core blockchain node (Rust)
├─ github.com/pilier-org/pilier-node

pilier-pallets: Custom runtime pallets (Rust)
├─ github.com/pilier-org/pilier-pallets

pilier-sdk: TypeScript SDK for developers
├─ github.com/pilier-org/pilier-sdk

pilier-explorer: Block explorer UI (React)
├─ github.com/pilier-org/pilier-explorer

Why open source?

• ✅ Transparency (anyone can audit code)
• ✅ Community contributions (ecosystem growth)
• ✅ Regulatory compliance (no "black box")
• ✅ EU digital sovereignty (no vendor lock-in)

---

How do runtime upgrades work without downtime?

WebAssembly magic:

1. Runtime compiled to Wasm (portable bytecode)
2. Wasm stored on-chain (part of blockchain state)
3. Nodes execute Wasm (not native binary)

Upgrade:
1. Governance votes to update runtime
2. New Wasm uploaded to chain (transaction)
3. At next block, all nodes execute new Wasm
4. No node restart, no downtime

Result: Forkless upgrade ✓

Example:

Block 999,999: Runtime v1.0 (old logic)
Block 1,000,000: Runtime v1.1 (new logic)
                 All nodes instantly switch
                 Users see no disruption

---

What happens if a validator goes offline?

Immediate (seconds):

AURA skips offline validator's slot
Next validator produces block
Network continues normally

Short-term (hours):

Monitoring alerts operator
Validator restarts/troubleshoots
Back online, rejoins rotation

Long-term (days):

If validator offline >24 hours:
├─ Community notified
├─ Governance proposal to remove
└─ Replacement validator onboarded

Impact on network: Minimal (other validators compensate)

---

Next Steps

For Users

Nothing to do! Architecture is transparent. Your DPPs are secured automatically.

Learn more:

• Consensus - How blocks are produced
• Tokenomics - Economics of the network
• Governance - How the protocol evolves

---

For Developers

Build on Pilier:

1. Read the SDK docs → SDK Reference
2. Run local node → Development Guide
3. Deploy testnet app → Testnet Guide
4. Apply for grant → Ecosystem Fund

---

For Validators

Become a validator:

1. Review requirements → Validator Requirements
2. Read the Charter → Validator Charter
3. Submit EOI → validators@pilier.org

---

Questions? Join the conversation:

• Forum: forum.pilier.net/architecture
• Telegram: t.me/pilier_org
• GitHub: github.com/pilier-org