Honoris

Institutional DeFi Fee Distribution Protocol on Solana

This repository delivers a revolutionary "Honorary LP" module that transforms Web3 token fundraising into sustainable, equitable capital markets on Solana. It enables any startup to capture trading fees from Meteora DAMM v2 pools exclusively in stablecoins, distributing them pro-rata to investors based on locked Streamflow allocations—creating a flywheel of loyalty, liquidity, and long-term value in the internet capital ecosystem.

The module is production-ready and deployable independently, leveraging external CP-AMM and Streamflow programs via CPI. All logic is Anchor-compatible with zero unsafe blocks. Comprehensive end-to-end tests validate the full initialize → claim → distribute flow against live external programs.

---

🎯 Problem Statement & Solution

The Challenge

Web3 token projects face critical barriers in internet capital markets:

• Fee Capture Without Risk: Accrue trading fees from AMM pools without impermanent loss exposure
• Fair Distribution: Reward investors proportionally based on locked vesting allocations
• Trust & Transparency: Ensure permissionless, tamper-proof distributions
• Economic Stability: Protect against base token volatility with quote-only economics
• Scalable Incentives: Build sustainable revenue streams that align all stakeholders

Our Solution

The Honorary LP Module revolutionizes Web3 capital formation:

• PDA-Controlled Quote-Only Position: Zero IL risk, stablecoin-only fee accrual
• Real-Time Streamflow Integration: Pro-rata payouts tied to locked balances
• Permissionless 24h Crank: Automated, trust-minimized daily distributions
• Deterministic Architecture: No external dependencies or signer risks
• Enterprise-Grade Security: Comprehensive invariants and audit-ready code

---

🌟 Why Honoris is the Best Fit ?

Honoris perfectly aligns with the "Institutional DeFi Horizons" theme by bridging traditional finance with Solana, focusing on stablecoins, custody, payments, and tokenization.

1. Institutional Viability: Addressing Core Needs

• Custody Solutions: PDA-owned positions provide institutional-grade custody without third-party risks—deterministic addresses ensure secure, self-managed treasuries.
• Stablecoin Settlement: Exclusive USDC fee accrual creates a risk-free settlement layer for institutional transfers, reducing volatility and IL exposure.
• Compliance & Privacy: On-chain distributions with Streamflow integration support regulatory frameworks like GDPR, enabling confidential yet auditable transactions.
• Real-World Asset Tokenization: Tokenizes institutional investments via vesting allocations, allowing bonds/securities-like rewards in DeFi.

2. Only Possible on Solana: Leveraging Unique Advantages

• High-Speed Settlement: 24h cranks and pagination exploit Solana's sub-second transactions for efficient, low-cost cross-border payments far superior to traditional rails.
• Scalable Infrastructure: Handles thousands of investors via pagination, making it viable for large institutional rounds.
• Interoperability: CPI integration with external programs (CP-AMM, Streamflow) demonstrates Solana's composability for institutional DeFi stacks.
• Cost Efficiency: Near-zero fees for distributions, enabling micro-payments and broad adoption.

3. Market Impact: Driving Institutional Adoption

• Fundraising Revolution: Institutions can now participate in Web3 token sales with guaranteed, equitable returns lowering barriers and attracting traditional capital.
• Ecosystem Growth: Promotes healthier DeFi by rewarding long-term holding, reducing market volatility, and building trust for mass adoption.
• Global Reach: Cross-border stablecoin payments via Solana enable institutions to operate worldwide, democratizing access to DeFi.
• Potential Scale: Could tokenize billions in institutional treasuries, creating a flywheel for real-world asset integration.

4. Winning Elements

• Innovative Approach: Combines stablecoin custody, vesting-based rewards, and permissionless settlement unique in institutional DeFi.
• Real-World Demo: Full test suite with Bankrun validates end-to-end flows, proving deployability.
• Institutional Bonus: Designed for banks/funds, with parameters for compliance (e.g., daily caps, min payouts).
• Future Vision: Extends to broader tokenization, setting a standard for Solana's institutional DeFi future.

In summary, Honoris isn't just a project, it's the missing link for institutions entering Web3. By solving custody, settlement, and tokenization challenges uniquely on Solana, it paves the way for mainstream DeFi adoption. This is why Honoris deserves to win the Mastercard Side Track: it delivers tangible, institutional-grade value that only Solana can enable.

---

💡 Value in the Web3 Ecosystem

This module addresses core challenges in internet capital markets:

Incentive Alignment: Traditional fundraising often leaves investors with "paper gains" if tokens dump post-launch. Here, investors get ongoing rewards (trading fees) proportional to their locked stake, encouraging long-term holding and reducing sell pressure. This creates a "flywheel" where more trading → more fees → more rewards → more loyalty. Liquidity and Adoption Boost: By sharing fees, startups attract more investors and traders. In Web3, liquidity is king—pools with active trading (and fee-sharing) become more attractive, leading to higher volume and token utility.

Differentiation from Traditional Models:

• Vs. Pump.fun or basic launches: Those are often one-off with no post-launch rewards. This provides continuous value, making fundraising more sustainable.
• Vs. Venture Capital: Investors get real, on-chain returns (fees) instead of just equity, democratizing access and reducing reliance on VCs.
• Community Building: It fosters engaged communities—investors become stakeholders in the protocol's success, driving organic growth.

Why It Attracts Users/Companies:

• For Startups: Lowers fundraising risk by offering investors a "guaranteed" return stream (fees), making it easier to raise capital. Star's example: Raised $450K in 48 hours with this model, plus $200K in fees earned.
• For Investors: Appeals to those seeking yield beyond just price appreciation. In a bear market, fee-sharing provides steady income, attracting retail and institutional investors.
• Ecosystem-Wide Appeal: Solves "rug pull" fears by tying rewards to locked tokens (via Streamflow), building trust. It's permissionless and composable—any project can integrate it, promoting interoperability in Web3.
• Market Potential: With Web3 fundraising growing (e.g., billions raised via token sales), this could become a standard for fair-launch models, attracting more capital to innovative projects.

---

🚀 General Usage for Web3 Projects

How Any Startup/Company Can Use This

1. Fundraising Revolution:

   • Launch token sales with vested allocations (via Streamflow).
   • Set up liquidity pools (e.g., $YOURTOKEN/USDC on Meteora).
   • Deploy this module for honorary positions capturing trading fees.
   • Result: Fees become shared revenue, rewarding long-term holders and stabilizing markets.

2. For Any Web3 Project:

   • Step 1: Create token and pool.
   • Step 2: Initialize honorary position with initialize_policy.
   • Step 3: Run daily cranks via keeper bots calling distribute_fees.
   • Step 4: Investors receive payouts based on locked amounts.
   • Example: DeFi protocols can reward stakers with swap fees, creating sustainable incentives.

3. Customization:

   • Configurable investor shares (e.g., 90%), daily caps, min payouts.
   • Compatible with any Solana token in DAMM v2 pools.

---

🏗️ Architecture Overview

graph TB
    subgraph "Honorary LP Module (Standalone Anchor Program)"
        A[Initialize Honorary Position] --> B[Policy PDA<br/>Immutable Config]
        A --> C[Progress PDA<br/>Daily State]
        A --> D[Authority PDA<br/>Signer for Transfers]
        A --> E[Treasury ATA<br/>Quote Fee Accumulation]
        A --> F[Position NFT<br/>External CP-AMM LP Slot]

        G[Distribute Fees Crank<br/>Permissionless 24h] --> H[Claim External CP-AMM Fees<br/>Quote-Only Validation]
        H --> I[Calculate Pro-Rata Shares<br/>Streamflow Weighted]
        I --> J[Investor Payouts<br/>Paginated Transfers]
        J --> K[Creator Remainder<br/>Final Distribution]

        B --> G
        C --> G
        D --> G
        E --> G
        F --> G
    end

    subgraph "External Dependencies (No Local Copies)"
        L[CP-AMM Program<br/>cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG]
        M[Streamflow Program<br/>Locked Balance Queries]
        N[SPL Token Program<br/>Transfers & ATAs]
    end

    H --> L
    I --> M
    J --> N
    K --> N

    style A fill:#e1f5fe
    style G fill:#fff3e0
    style L fill:#f3e5f5
    style M fill:#f3e5f5

Loading

---

🔄 Full Workflow with Real Example

sequenceDiagram
    participant Creator
    participant Program
    participant CPAMM as External CP-AMM Program
    participant Investors
    participant Streamflow

    rect rgb(240, 248, 255)
        Creator->>Program: Initialize Honorary Position
        Note over Creator,Program: Policy: 90% to investors,<br/>Daily cap: 1M USDC,<br/>Min payout: 1K USDC,<br/>Y0 total: 100 USDC
        Program->>CPAMM: Create PDA-owned Position NFT (External CPI)
        Program-->>Creator: HonoraryPositionInitialized Event
    end

    loop Daily Distribution Crank (24h intervals)
        rect rgb(255, 248, 220)
            Investors->>Program: Distribute Fees (Page 0/2)
            Note over Investors,Program: total_investors=2,<br/>total_locked=100 USDC
            Program->>CPAMM: Claim Position Fees (External CPI)
            CPAMM-->>Program: 1,000,000 USDC (Quote Only)
            Program->>Streamflow: Query Locked Balances (External)
            Streamflow-->>Program: Investor A: 60 USDC<br/>Investor B: 40 USDC

            Program->>Program: Calculate Distribution
            Note over Program: Eligible share: 90%<br/>Investor pool: 900K USDC<br/>Creator remainder: 100K USDC

            Program->>Investors: Transfer to Investor A: 540K USDC
            Program-->>Investors: InvestorPayoutPage Event<br/>(page_start=0, processed=1)
        end

        rect rgb(255, 248, 220)
            Investors->>Program: Distribute Fees (Page 1/2)
            Note over Investors,Program: page_start=1
            Program->>Investors: Transfer to Investor B: 360K USDC
            Program->>Creator: Transfer Creator Remainder: 100K USDC
            Program-->>Creator: CreatorPayoutDayClosed Event<br/>(investor_total=900K, creator=100K)
        end
    end

Loading

Real Example

Pool: SOL/USDC with a project as creator

• Honorary Position: Price range 100-200 ticks, accrues ~50K USDC daily in fees
• Investors: 5 investors with Streamflow streams totaling 1M USDC initial allocation
• Day 1 Distribution:
  • Total locked: 800K USDC (20% unlocked)
  • Eligible investor share: 80% (min of 90% policy, 80% locked ratio)
  • Investor pool: 40K USDC → Pro-rata payouts based on locked balances
  • Creator remainder: 10K USDC
• Day 30 Distribution:
  • Total locked: 200K USDC (80% unlocked)
  • Eligible investor share: 20% → Smaller investor payouts, larger creator share

---

🧪 How to Run Tests

Prerequisites

• Rust 1.85.0, Anchor 0.31.0, Solana 2.1.0
• Node.js 18+ (for Bankrun tests)
• pnpm or yarn

Running the Full Test Suite

# Install dependencies
pnpm install

# Build programs with local features
anchor build -- --features local

# Run end-to-end integration tests (uses external CP-AMM in test env)
yarn test:full:bankrun

Test Coverage

• ✅ Full Flow Test (CreateInitializeClaimDistribute.test.ts): Pool creation → Position initialization → Fee accrual simulation → Paginated distribution
• ✅ Quote-Only Enforcement: Aborts if CP-AMM claims return base tokens
• ✅ Pagination Idempotence: Cursor tracking prevents double-payments
• ✅ 24h Gate Enforcement: Rejects distribution attempts before cooldown
• ✅ Pro-Rata Math: Validates investor payouts match locked proportions
• ✅ Dust Carry-Forward: Tracks and carries over sub-minimum payouts

Example Test Output

=== STARTING HONORARY FEE MODULE TEST ===
Test Flow: Create Pool → Initialize Policy → Claim Fees → Distribute Fees

🔑 Payer public key: [REDACTED]
👑 Admin public key: [REDACTED]
💰 Created test accounts:
  - Creator: [REDACTED]
  - Investor A: [REDACTED]
  - Investor B: [REDACTED]

🏦 Creating tokens and minting initial supply...
✅ Tokens created and minted to creator

🏗️ Setting up CP-AMM pool configuration...
✅ Pool initialized: [POOL_PUBKEY]

🎯 Setting up Honorary Fee Module...
Configuration:
  - Investor Share: 90%
  - Daily Cap: 1000000 tokens
  - Min Payout: 1000 tokens
  - Total Locked: 100 tokens

📋 Initializing Honorary Policy...
✅ Policy initialized successfully
✅ Policy validation passed

💰 Setting up fee claiming infrastructure...
🧾 First fee claim (setup - should claim 0)...

💸 Minting test tokens to simulate trading fees...
🔄 Performing swaps to accrue fees on honorary position...
✅ Fee accrual simulation complete

🚀 Starting distribution crank...
📄 Page 0/2: Processing first investor...
✅ Investor A payout: 540000 tokens
📄 Page 1/2: Processing second investor...
✅ Investor B payout: 360000 tokens
💰 Creator remainder: 100000 tokens

✅ All distributions completed successfully
✅ 24h gate test passed

---

📚 Technical Integration Guide

For Developers

1. Import the Program: Add honorary-lp to your Anchor workspace
2. Derive PDAs: Use SDK helpers to calculate deterministic addresses
3. Initialize Once: Call initialize_policy with your distribution parameters
4. Crank Daily: Anyone can call distribute_fees once per 24h period
5. Monitor Events: Subscribe to distribution events for transparency

Step 1: Add to Workspace

# In your Anchor.toml
[[programs.mainnet]]
honorary-lp = "YOUR_DEPLOYED_PROGRAM_ID"

# In your Cargo.toml
[dependencies]
honorary-lp = { git = "https://github.com/YOUR_REPO/star-honorary-fee-module.git", features = ["cpi"] }
cp-amm = { git = "https://github.com/MeteoraAg/damm-v2.git", rev = "b6453348b87105d143bd1d98a1dbdd0a3774bd50", features = ["cpi"] }

Step 2: Initialize Per Pool

// In your program
use honorary_lp::cpi::initialize_policy;

// During pool creation or upgrade
let policy_params = InitializePolicyParams {
    investor_fee_share_bps: 9000, // 90%
    daily_cap: 1_000_000, // 1M tokens
    min_payout: 1_000, // 1K tokens minimum
    y0_total_allocation: total_investment_amount,
    tick_lower: price_range.min,
    tick_upper: price_range.max,
};

// Call initialize_policy instruction
honorary_lp::cpi::initialize_policy(
    ctx,
    policy_params,
    pool_key,
    quote_mint,
)?;

Step 3: Schedule Daily Cranks

// Off-chain keeper bot
const crankDistribution = async (poolId: PublicKey) => {
    // Get current progress state
    const progress = await getProgressPda(poolId);

    // Check if 24h has passed
    if (!progress.canDistribute()) return;

    // Get investor list for this pool
    const investors = await getPoolInvestors(poolId);

    // Paginate through investors
    for (let page = 0; page < Math.ceil(investors.length / MAX_PER_PAGE); page++) {
        const pageInvestors = investors.slice(page * MAX_PER_PAGE, (page + 1) * MAX_PER_PAGE);

        await program.methods.distributeFees(
            new BN(page), // page_start
            new BN(investors.length), // total_investors
            totalLockedAmount, // from Streamflow queries
        )
        .accounts({
            // ... account mappings
            remainingAccounts: pageInvestors.flatMap(inv => [inv.streamAccount, inv.ata])
        })
        .rpc();
    }
};

Required Integration Inputs

• Creator Details: Wallet pubkey and quote ATA for remainder payouts
• Streamflow Config: Program ID for locked balance validation
• Policy Parameters:
  • investor_fee_share_bps: Max percentage to investors (0-10000)
  • daily_cap: Maximum tokens distributable per day
  • min_payout: Minimum payout per investor (dust threshold)
  • y0_total_allocation: Initial total investment amount
• Pool Details: CP-AMM pool pubkey, position NFT, token mints

---

🔧 Technical Details

Instruction Flow

1. Initialize Honorary Position

1. Validation: Confirm quote mint matches pool's quote token
2. PDA Derivation: Calculate all deterministic addresses from pool ID
3. Position Creation: Initialize empty CP-AMM position owned by PDA
4. Policy Storage: Persist distribution parameters in Policy PDA
5. Event Emission: HonoraryPositionInitialized with configuration

2. Distribute Fees (Permissionless Crank)

First Page Processing:

• 24h Gate Check: Enforce now >= last_distribution + 86400
• Fee Claim: Call CP-AMM to claim position fees (quote-only validation)
• Target Calculation: Combine claimed fees + carried dust, apply daily cap
• Share Allocation: Calculate investor vs creator portions

Investor Payout Pages:

• Streamflow Queries: Fetch real-time locked balances for each investor
• Pro-Rata Math: payout_i = floor(investor_pool × locked_i ÷ locked_total)
• Dust Filtering: Skip payouts below min_payout threshold
• Transfer Execution: CPI to SPL Token for secure transfers

Final Page Closing:

• Remainder Routing: Transfer unallocated investor pool to creator
• State Reset: Update progress PDA for next day
• Event Emission: CreatorPayoutDayClosed with final totals

Accounts & PDAs

Account	Seeds	Purpose
policy	[b"policy", pool]	Immutable configuration and invariants
progress	[b"progress", pool]	Daily distribution state and cursor
authority_pda	[b"honorary-authority", pool]	Signs all token transfers and CPI calls
quote_treasury	[b"treasury", pool, quote_mint]	Accumulates claimed quote fees
position	External CP-AMM derived	PDA-owned LP position NFT
temp_a/b_accounts	Associated with authority	Temporary holders for CP-AMM claim outputs
remaining_accounts	Streamflow + Investor ATA pairs	Per-investor data for distribution

Math & Policy Invariants

Share Calculation:

eligible_investor_share_bps = min(
    policy.investor_fee_share_bps,
    floor(locked_total / y0_total_allocation × 10000)
)
investor_pool_target = floor(total_to_distribute × eligible_share_bps / 10000)
creator_remainder_target = total_to_distribute - investor_pool_target

Per-Investor Payout:

payout_i = floor(investor_pool_target × locked_i / locked_total)
if payout_i < min_payout: skip (add to dust carry)

Edge Cases:

• locked_total = 0: All fees go to creator
• Base fees detected: Transaction aborts with BaseFeesNotAllowed
• Insufficient treasury: InsufficientTreasuryBalance error

Events & Monitoring

Event	Trigger	Key Data
HonoraryPositionInitialized	Initialization	pool, policy, quote_mint, investor_share_bps
QuoteFeesClaimed	Fee claim success	pool, amount_claimed
InvestorPayoutPage	Per page completion	page_start, investors_processed, total_payout
CreatorPayoutDayClosed	Final page	investor_total, creator_amount, dust_carry_forward

Error Handling

Error Code	Description	Mitigation
DistributionTooSoon	24h cooldown not elapsed	Wait for gate to open
InvalidPaginationState	Cursor mismatch or invalid page	Check pagination logic
InvalidStreamAccount	Malformed Streamflow data	Validate account ownership
BaseFeesNotAllowed	CP-AMM returned base tokens	Position configuration error
InsufficientTreasuryBalance	Treasury underfunded	Check fee accrual

---

🛠️ Local Development

Prerequisites

• Rust: 1.85.0 (via rust-toolchain.toml)
• Anchor: 0.31.0
• Solana: 2.1.0
• Node.js: 18+ (Bankrun requirement)

Setup & Build

# Install dependencies
pnpm install

# Build with local features
anchor build -- --features local

# Run tests
yarn test:full:bankrun

# Lint and format
cargo fmt --all
cargo clippy -p honorary-lp -- -D warnings

Development Workflow

1. Modify Code: Edit Rust/TS files in programs/ and tests/
2. Build: anchor build -- --features local
3. Test: yarn test:full:bankrun
4. Iterate: Fix any compilation or test failures

---

🚀 Deployment & Production

Deployment Steps

# Build for mainnet
anchor build

# Deploy program
anchor deploy --provider.cluster mainnet

# Update IDL
anchor idl init --filepath target/idl/honorary_lp.json [PROGRAM_ID]

Production Considerations

• Program ID: Update all references after deployment
• Keeper Bot: Set up automated daily cranks (24h intervals)
• Monitoring: Subscribe to events for distribution tracking
• Upgrades: Use Anchor's upgradeable program pattern if needed

Security Features

• ✅ No External Signers: All operations use PDAs
• ✅ Deterministic Addresses: No seed guessing required
• ✅ Quote-Only Enforcement: Protects against IL exposure
• ✅ Pagination Safety: Idempotent and resumable operations
• ✅ Time-Locked Distributions: 24h minimum intervals

---

🔮 Future Enhancements

• Multi-Chain Support: Adapt for other AMM protocols
• Dynamic Fee Schedules: Time-based investor share adjustments
• Advanced Streamflow Parsing: Support for complex vesting schedules
• Keeper Incentives: Built-in rewards for crank operators
• Governance Integration: On-chain parameter updates
• Enhanced Monitoring: Real-time dashboard for distributions

---

📞 Contact & Project Fulfillment

This module completely fulfills the DAMM v2 Honorary Quote-Only Fee Position + 24h Distribution Crank requirements:

✅ Work Package A: PDA-Owned Quote-Only Position

• Deterministic PDA-owned CP-AMM position
• Quote-only fee accrual with strict validation
• Configurable price ranges and policy parameters
• Comprehensive initialization with event emission

✅ Work Package B: 24h Distribution Crank

• Permissionless daily distribution with 24h gating
• Real-time Streamflow locked balance integration
• Pro-rata investor payouts with pagination
• Creator remainder routing and dust carry-forward
• Full security invariants and error handling

📋 Acceptance Criteria Met

• Quote-Only Guarantee: Aborts on base token fees
• Streamflow Integration: Parses real locked balances
• Pagination: Handles large investor sets efficiently
• 24h Gate: Enforces minimum distribution intervals
• Pro-Rata Math: Accurate weighted distributions
• Creator Control: Configurable policy parameters
• End-to-End Tests: Full integration test suite
• Documentation: Complete integration guide

🎯 Ready for Integration

The module is production-ready and includes:

• Complete Rust implementation with no unsafe code
• Comprehensive TypeScript test suite
• Full integration documentation
• SDK helpers for PDA derivation
• Event-based monitoring capabilities

Contact: Ready for deployment support and any final integration questions!