Paymaster

The Paymaster contract is a central component of the Filament protocol, responsible for managing funds and ensuring secure and reliable payments between Campaigners, Delegates, and potentially Indexers. It acts as an intermediary between the Filament Hub (on a Layer 2) and on-chain assets (FILA and USDC) on Ethereum (Layer 1). The Paymaster handles campaign bonds, facilitates interactions with the Treasury Window, and generates proofs of payment for verification by the Filament Hub.

Motivation

The Paymaster addresses several key challenges:

  • Security: It provides a secure way to manage funds and execute payments, minimizing the risk of theft or loss.
  • Reliability: It ensures that payments are made correctly and that Delegates are compensated even if a Campaigner abandons a campaign.
  • Gas Abstraction (Partial): While FILUM handles computation costs on the Filament Hub, the Paymaster interacts with Layer 1 assets, and the Campaigner is ultimately responsible for those gas costs.
  • Cross-Layer Communication: It facilitates communication between the Filament Hub (on a Layer 2) and the Ethereum blockchain (Layer 1), where the FILA and USDC tokens reside.
  • Treasury Window Integration: It provides a seamless way for Campaigners to purchase FILA through the Treasury Window and use it for campaign bonds.

Key Concepts

  • Campaign Bond: A deposit of FILA tokens made by a Campaigner before starting a campaign. This bond guarantees Delegate payments. The Paymaster manages these bonds.
  • Watermark: A dynamic value representing the minimum amount of FILA that must remain locked in a Campaigner’s overall bond across all their campaigns. The Paymaster tracks and enforces the watermark.
  • RequestForPayment: A message generated by the Filament Hub, instructing the Paymaster to make a payment. This includes information about the recipient, amount, campaign, and phase.
  • PaymentTransaction: A structure generated by the Paymaster, encapsulating the details of a payment to be made. This is signed by the Campaigner.
  • ProofOfPayment: A cryptographic proof generated by the Paymaster after a payment has been successfully executed. This proof is relayed to the Filament Hub to verify the payment.
  • PaymentConfirmation: An acknowledgment from the Filament Hub that a payment has been processed and the corresponding state transition has been applied.
  • Fund Source: The Paymaster determines the source of funds for a payment:
    • CampaignBond: Funds are deducted from the Campaigner’s campaign-specific bond.
    • FilaBalance: Funds are deducted from the Campaigner’s general FILA balance.
    • TreasuryWindow: Funds are acquired by purchasing FILA with USDC through the Treasury Window.
  • Relayer: Relays messages between the Paymaster and the Filament Hub.

Actors

  • Campaigner: Interacts with the Paymaster to create campaign bonds, make payments, and withdraw funds.
  • Filament Hub: Sends RequestForPayment messages to the Paymaster and verifies ProofOfPayment messages.
  • Paymaster (Smart Contract): Manages funds, executes payments, and generates proofs.
  • Relayer: Facilitates communication between the Filament Hub and the Paymaster.
  • Treasury Window: Provides a mechanism for purchasing FILA with USDC.

Protocol Flow (Simplified)

  1. Campaign Creation:
    • The Campaigner interacts with the Paymaster to create a campaign bond (depositing FILA). This may involve purchasing FILA through the Treasury Window.
  2. Campaign Progression:
    • As the campaign progresses through its phases, the Filament Hub calculates fees and generates RequestForPayment messages.
    • These requests are sent to the Campaigner (off-chain).
  3. Payment Generation:
    • The Campaigner, upon recieving the RequestForPayment, interacts with the Paymaster using generatePaymentTransaction which returns a PaymentTransaction.
    • The Campaigner signs the PaymentTransaction.
  4. Payment Execution:
    • The Campaigner sends the signed PaymentTransaction to the Paymaster’s executePayment function.
    • The Paymaster verifies the signature and checks for sufficient funds.
    • The Paymaster executes the payment, deducting funds from the appropriate source (Campaign Bond, FILA balance, or Treasury Window).
    • The Paymaster generates a ProofOfPayment.
  5. Proof Relaying:
    • A Relayer monitors the Paymaster for ProofOfPayment events.
    • The Relayer relays the ProofOfPayment to the Filament Hub.
  6. Verification and State Transition:
    • The Filament Hub verifies the ProofOfPayment.
    • If the proof is valid, the Filament Hub applies the corresponding state transition (e.g., confirming criteria, confirming segments).
    • The Filament Hub generates and queues PaymentConfirmation.
  7. Confirmation Relaying:
    • A Relayer monitors the Filament Hub’s PaymentConfirmation queue.
    • The Relayer relays PaymentConfirmation back to the Paymaster.

Data Structures

// Paymaster (Solidity)

struct CampaignBond {
    uint256 balance;
    uint256 watermark;
}

struct PaymentTransaction {
    uint256 requestId; // Corresponds to the RequestForPayment nonce
    uint256 campaignId;
    uint8 phase;        // Enum: Criteria, Publish, Distribution
    uint8 message;      // Enum: Commit, Reject
    uint256 amount;
    address from;
    uint256 nonce;
    FundSource fundSource;
}

enum FundSource {
    CampaignBond,
    FilaBalance,
    TreasuryWindow
}

struct ProofOfPayment {
    uint256 requestId;
    uint256 campaignId;
    uint8 phase;
    uint8 message;
    uint256 amount;
    address from;
    uint256 nonce;
    FundSource fundSource;
}

// --- Filament Hub (Rust - Conceptual) ---
struct RequestForPayment {
    campaign_id: u64,
    phase: Phase, // Enum: Criteria, Publish, Distribution
    message: Message, // Enum: Commit, Reject
    amount: u64,
    from: Address, // Campaigner address
    nonce: u64,     // Unique identifier
}

struct RelayedProofOfPayment {
    proof: ProofOfPayment,
    relayer: Address,
}

struct PaymentConfirmation {
    request_id: u64,
    status: PaymentStatus,  // Enum: Confirmed, Failed
    action_result: ActionResult,
}
enum PaymentStatus {
    Confirmed,
    Failed,
}

enum Phase {
    Criteria,
    Publish,
    Distribution,
}

enum Message {
    Commit,
    Reject,
}

Functions (Solidity - Paymaster)

  • addToCampaignBond(uint256 campaignId, uint256 amount): Allows a Campaigner to add FILA to their campaign bond.
  • setCampaignBondWatermark(uint256 campaignId, uint256 watermark): Sets the watermark for a specific campaign. This should only be callable by the Filament Hub (or a trusted administrator).
  • withdrawFromCampaignBond(uint256 campaignId, uint256 amount): Allows a Campaigner to withdraw FILA from their campaign bond, provided the withdrawal does not bring the balance below the watermark.
  • generatePaymentTransaction(RequestForPayment memory request) public view returns (PaymentTransaction memory): Takes a RequestForPayment as input and generates a PaymentTransaction. This function determines the appropriate FundSource.
  • executePayment(PaymentTransaction memory transaction, bytes memory signature): Executes a payment based on a signed PaymentTransaction. Verifies the signature, checks for sufficient funds, performs the transfer, and generates a ProofOfPayment.
  • determineFundSource(...) internal view returns (FundSource): Determines the source of funds for a payment (Campaign Bond, FILA balance, or Treasury Window).
  • receiveBondedFila(address campaigner, uint256 amount): Interface Function, called by the TreasuryWindow to credit FILA to a campaigner’s bond.

Security Considerations

  • Signature Verification: The executePayment function must rigorously verify the Campaigner’s signature on the PaymentTransaction to prevent unauthorized payments.
  • Replay Protection: The nonce field in the RequestForPayment and PaymentTransaction prevents replay attacks (where a valid transaction is submitted multiple times).
  • Watermark Enforcement: The Paymaster must strictly enforce the watermark to ensure that sufficient funds are always available for Delegate payments.
  • Access Control: Functions like setCampaignBondWatermark must have appropriate access control to prevent unauthorized modifications.
  • Safe Math: Use SafeMath (or Solidity 0.8+’s built-in overflow/underflow checks) to prevent arithmetic errors.
  • Oracle Reliability: The Treasury Window integration relies on price oracles. Oracle manipulation must be carefully considered.

Failure Modes and Handling

  • Insufficient Funds: If a Campaigner does not have sufficient funds (in their bond, FILA balance, or through the Treasury Window), the executePayment function will revert. The Filament Hub should handle this failure gracefully (e.g., by transitioning to a failure state).
  • Invalid Signature: If the signature on the PaymentTransaction is invalid, the executePayment function will revert.
  • Relayer Failure: If a Relayer fails to relay a ProofOfPayment or PaymentConfirmation, the system should have mechanisms for retries and eventual consistency.
  • Treasury Window Failure: If the Treasury Window is unavailable or the exchange rate changes unexpectedly, the executePayment function may fail. The system should handle this gracefully.
  • Replay Attacks: Mitigated using nonces.
  • Double Spend: Prevented by atomically executing the payment and generating the ProofOfPayment.

Conclusion

The Paymaster contract is a critical component of the Filament protocol, providing a secure and reliable mechanism for managing funds and executing payments. Its integration with the Filament Hub, Treasury Window, and Relayers ensures a seamless and robust system for decentralized token distributions. The careful consideration of security and failure modes is essential for the proper functioning of the Paymaster.