Documentation Index

Complete guide to all documentation files in the Shield Finance XRP Liquid Staking Protocol.

Whitepaper

Read the Whitepaper (PDF) — Complete technical documentation covering the protocol architecture, yield mechanics, and SHIELD tokenomics.

Quick Start

If you want to…	Start here
Read the whitepaper	Whitepaper (PDF)
Review the project	REVIEWERS.md
Claim the airdrop	AIRDROP_CLAIM_GUIDE.md
Understand tokenomics	docs/protocol/SHIELD_TOKENOMICS.md
Deploy contracts	DEPLOYMENT_GUIDE.md
Understand FAssets bridge	docs/integration/FASSETS_GUIDE.md
Build UI components	design_guidelines.md

Documentation Structure

docs/
├── whitepaper/         # Official whitepaper
│   └── main.tex                  # LaTeX source (PDF at shyield.finance/whitepaper.pdf)
│
├── protocol/           # Token & smart contract documentation
│   ├── SHIELD_TOKENOMICS.md      # Token economics & distribution
│   ├── SHIELD_DEPLOYMENT.md      # Contract deployment guide
│   ├── SHIELD_SECURITY_CHECKLIST.md  # Pre-deployment security
│   ├── STAKING_BOOST_SPEC.md     # SHIELD staking for APY boost
│   └── REVENUE_SYSTEM_SPEC.md    # BuybackBurn & RevenueRouter
│
├── integration/        # External service integrations
│   ├── FASSETS_GUIDE.md              # XRP → FXRP bridging (canonical)
│   ├── FIRELIGHT_INTEGRATION.md      # Yield generation + testnet simulation
│   └── LP_LOCKING_GUIDE.md           # Liquidity pool locking
│
├── partners/           # Partner-facing documentation
│   └── FIRELIGHT_PARTNER_GUIDE.md    # Firelight team integration guide
│
├── platform/           # Application architecture
│   ├── AIRDROP_CLAIM_GUIDE.md    # Airdrop eligibility & claiming
│   ├── SMART_ACCOUNTS_SPEC.md    # ERC-4337 specification
│   ├── swap.md                   # Multi-asset swap feature
│   ├── wallet-integration.md     # Wallet connection guide
│   ├── transaction-signing.md    # Signing flows
│   └── xaman-integration.md      # Xaman wallet details
│
├── api/                # API documentation
│   └── README.md
│
└── operations/         # Operational guides (future)

Protocol Documentation

Whitepaper (PDF)

Purpose: Complete technical documentation for Shield Finance
Contents:

Protocol architecture and user flow
Yield boost mechanics with mathematical formulas
Synthetix-style reward accumulator specification
SHIELD tokenomics and revenue distribution
Smart contract architecture diagrams

SHIELD_TOKENOMICS.md

Purpose: Complete $SHIELD token economics and distribution
Contents:

10M total supply breakdown (11 categories)
Buyback & burn mechanism (50% of revenue)
Staking boost system (1% APY per 100 SHIELD)
Vesting schedules and unlock timelines

SHIELD_DEPLOYMENT.md

Purpose: Smart contract deployment guide
Contents:

Deployed contract addresses (Coston2 testnet)
Step-by-step deployment process
Post-deployment verification
LP locking and airdrop funding

SHIELD_SECURITY_CHECKLIST.md

Purpose: Security audit and deployment checklist
Contents:

Pre-deployment security review
Access control verification
Operational security guidelines
Emergency procedures

STAKING_BOOST_SPEC.md

Purpose: Complete technical specification for SHIELD staking yield boost
Contents:

Synthetix-style reward accumulator math
Pro-rata distribution formula
StakingBoost ↔ ShXRPVault integration
Circular dependency deployment solution
Security considerations and test coverage

REVENUE_SYSTEM_SPEC.md

Purpose: Technical specification for revenue distribution contracts
Contents:

BuybackBurn contract (wFLR → SHIELD burn)
RevenueRouter contract (FXRP → burn + boost + reserves)
SafeERC20 forceApprove security patterns
Slippage protection with price tracking
Allowance clearing for security
51 comprehensive tests (21 + 30)

Dashboard Features

Dashboard Enhancements (v2.2.0)

Purpose: Real-time portfolio analytics and notification system
Components:

PortfolioSummaryCard: Total assets, staked amounts, rewards, SHIELD boost contribution
PortfolioPerformanceChart: Historical visualization with 7D/30D/90D selectors
BoostImpactBanner: Base vs boosted APY comparison with delta indicator
NotificationCenter: Persistent bell icon with categorized notifications

API Endpoints:

GET /api/user/dashboard-summary - Aggregated portfolio data
GET /api/user/portfolio-history - Historical snapshots
GET /api/user/notifications - Paginated notifications
PATCH /api/user/notifications/:id/read - Mark as read

Notification Triggers:

Deposit completion (vault_minted status)
Withdrawal completion (userStatus = completed)
Staking operations (stake/unstake SHIELD)
Reward claims

Integration Documentation

FASSETS_GUIDE.md

Purpose: XRP → FXRP bridging via FAssets protocol (canonical guide)
Contents:

FAssets protocol overview
Contract addresses (mainnet + testnet)
Collateral reservation and minting flow
FDC proof generation and redemption
Integration best practices

FIRELIGHT_INTEGRATION.md

Purpose: Yield generation strategy integration
Contents:

Firelight.finance protocol overview
FXRP deposit strategies
Yield optimization
Compounding automation
Testnet simulation with MockStrategy

Partner Documentation

FIRELIGHT_PARTNER_GUIDE.md

Purpose: Technical documentation for Firelight team partnership
Audience: Firelight.finance team, integration partners
Contents:

FirelightStrategy.sol contract architecture
Technical integration points (ERC-4626)
Security measures and access control
Expected TVL contribution and mutual benefits
Testnet validation results
Mainnet deployment plan

LP_LOCKING_GUIDE.md

Purpose: Liquidity pool token locking
Contents:

SparkDEX V3 LP creation
Team Finance locking process
NFT position management

Platform Documentation

AIRDROP_CLAIM_GUIDE.md

Purpose: Complete guide for earning testnet points and claiming SHIELD airdrop
Contents:

Prerequisites and wallet setup (Coston2 testnet)
Faucet usage (C2FLR + SHIELD tokens)
Points system (deposits, staking, referrals, bug reports)
Tier progression (Bronze → Diamond with multipliers)
Mainnet claiming process (Merkle-proof verification)
Troubleshooting common issues

SMART_ACCOUNTS_SPEC.md

Purpose: ERC-4337 account abstraction specification
Contents:

Smart account architecture
XRPL-triggered Flare transactions
Proxy account system
Coming December 2025 features

swap.md

Purpose: Multi-asset swap feature documentation
Contents:

Token swapping overview
SparkDEX V3 integration
Approval and routing logic
Troubleshooting guide

wallet-integration.md

Purpose: Wallet connection and management
Contents:

Xaman (XRPL) integration
WalletConnect (EVM) integration
Dual wallet support

transaction-signing.md

Purpose: Transaction signing flows
Contents:

XRPL transaction signing
EVM transaction signing
Smart account operations

xaman-integration.md

Purpose: Xaman wallet specific details
Contents:

Xaman SDK integration
QR code signing flow
Mobile deep linking

Root-Level Documentation

REVIEWERS.md

Purpose: Executive summary for research teams and auditors
Audience: External reviewers, research teams, auditors

README.md

Purpose: Main project documentation and getting started
Audience: Developers, contributors, users

DEPLOYMENT_GUIDE.md

Purpose: Quick deployment reference with contract addresses
Audience: DevOps, developers deploying to testnet/mainnet

SMART_ACCOUNTS.md

Purpose: ERC-4337 implementation guide (Etherspot Prime SDK)
Audience: Backend developers, blockchain engineers

MONITORING_GUIDE.md

Purpose: Testnet monitoring and alerting system with real-time metrics
Contents:

Real-time 24-hour sliding window metrics for operational health
Bridge failure rate tracking (excludes cancelled, only counts actual failures)
On-chain event monitoring (OpenZeppelin Monitor-style)
Prometheus metrics export for Grafana integration
Alert conditions and webhook configuration Audience: Operations, DevOps

Documentation by Use Case

For Research Teams / Auditors

Whitepaper (PDF) - Complete technical documentation
REVIEWERS.md - Executive summary
docs/protocol/SHIELD_TOKENOMICS.md - Token economics
docs/protocol/SHIELD_SECURITY_CHECKLIST.md - Security review
Contract source code in /contracts

Scripts Reference

Essential operational scripts are in /scripts:

Script	Purpose
`deploy-shield-10m.ts`	Main SHIELD token deployment
`deploy-all-contracts-10m.ts`	Full contract suite deployment
`fund-merkle-distributor.ts`	Fund airdrop contract
`generate-merkle-tree.ts`	Generate airdrop merkle tree
`sparkdex-lp.ts`	Create SparkDEX liquidity pool
`compound.ts`	Vault compounding operations
`burn.ts`	Manual SHIELD token burn

Archived diagnostic scripts are in /scripts/archive.

Last Updated: December 6, 2025