This document provides security guidance for administrators managing the vesting vault system on the Soroban smart contract platform. It focuses on a specific security limitation called "revocation front-running" and provides practical procedures to minimize associated risks.

What This Document Covers:

• A detailed explanation of the revocation front-running attack and why it exists
• Technical background on how Stellar and Soroban handle transactions
• Step-by-step procedures for safely revoking tokens from vaults
• Monitoring recommendations to detect potential attacks
• Emergency response procedures if front-running occurs

Who Should Read This Document:

• Administrators responsible for managing vesting vaults and revoking tokens
• Security personnel overseeing blockchain operations
• Legal and compliance teams assessing risk exposure
• Technical staff implementing operational procedures

Key Takeaway:
Revocation front-running is a fundamental limitation of public blockchain transparency that cannot be completely eliminated. However, by following the freeze-then-revoke procedure and operational security practices outlined in this document, administrators can effectively prevent this attack and safely manage token revocations.

Document Structure:

• Known Limitations: Detailed analysis of the revocation front-running attack
• Operational Security Guidance: Step-by-step procedures for safe revocation
• Glossary: Definitions of technical terms for accessibility
• References: Links to official Stellar and Soroban documentation

This glossary defines technical terms used throughout this document to ensure accessibility for administrators, operators, and other stakeholders who may not have deep blockchain expertise.

Administrator
The privileged account authorized to manage vaults, including freezing vaults and revoking unvested tokens. Typically represents the organization or treasury that created the vesting vault.

Beneficiary
The account that owns a vesting vault and has the right to claim vested tokens according to the vesting schedule. Typically represents an employee, contractor, or other token recipient.

Blockchain
A distributed ledger technology where transactions are recorded in blocks and linked together in a chain. Stellar is the blockchain platform on which Soroban smart contracts run.

Ledger
A single block in the Stellar blockchain containing a set of transactions. Stellar ledgers close approximately every 5 seconds, meaning transactions are confirmed and finalized at 5-second intervals.

Mempool (Transaction Queue)
The pool of pending transactions that have been submitted to the network but not yet included in a closed ledger. Transactions in the mempool are visible to all network participants, creating the transparency that enables front-running attacks.

Smart Contract
Self-executing code deployed on a blockchain that automatically enforces rules and executes operations. The vesting vault system is implemented as a Soroban smart contract.

Soroban
The smart contract platform on the Stellar blockchain where the vesting vault system is deployed. Soroban provides fast finality (5 seconds) and supports complex contract logic.

Stellar
The blockchain network that hosts Soroban smart contracts. Stellar uses the Stellar Consensus Protocol (SCP) to achieve agreement on transaction ordering and ledger state.

Stellar Consensus Protocol (SCP)
The consensus mechanism used by Stellar to agree on which transactions to include in each ledger. SCP is a federated Byzantine agreement system that provides strong finality guarantees without mining or staking.

Transaction
An operation submitted to the blockchain that modifies the ledger state. Examples include claiming tokens from a vault, revoking tokens, or freezing a vault.

Transaction Fee (Gas Fee)
The cost (in stroops, the smallest unit of Stellar's native currency XLM) required to submit a transaction to the network. During normal operation, fees do not affect transaction ordering. During surge pricing mode (network congestion), higher fees increase the probability of inclusion in the next ledger.

Claim Transaction
A transaction submitted by a beneficiary to withdraw vested tokens from their vault. The claim_tokens() function transfers tokens from the vault to the beneficiary's account.

Freeze Mechanism
A security feature that allows the administrator to temporarily disable claims on a specific vault by setting the is_frozen flag to true. Frozen vaults cannot process claim transactions, but can still be revoked by the administrator.

Revocation Transaction
A transaction submitted by the administrator to reclaim unvested tokens from a beneficiary's vault. The revoke_tokens() function returns unvested tokens to the administrator's balance.

Unvested Tokens
Tokens that have been allocated to a vault but have not yet completed their vesting schedule. These tokens cannot be claimed by the beneficiary and can be revoked by the administrator.

Vault
A smart contract data structure that holds tokens allocated to a beneficiary and enforces a vesting schedule. Each vault tracks the total allocation, vesting progress, and tokens already claimed.

Vested Tokens
Tokens that have completed their vesting schedule and are available for the beneficiary to claim. Vested tokens represent the beneficiary's earned entitlement.

Vesting Schedule
The timeline that determines when tokens become vested and claimable. Common schedules include linear vesting (e.g., 25% per year over 4 years) or milestone-based vesting (tokens unlock when specific goals are achieved).

Attack Window
The time period during which a beneficiary can observe a pending revocation transaction and submit a competing claim transaction. On Stellar, this window is approximately 5 seconds (one ledger close period).

Extractable Value
The maximum amount of tokens a beneficiary can claim through a front-running attack, calculated as: (vested_amount - released_amount) × token_price. This represents the financial impact of a successful attack.

Front-Running Attack
A scenario where a beneficiary observes a pending revocation transaction in the mempool and submits a competing claim transaction to extract vested tokens before the revocation executes. The attack exploits the race condition between revoke and claim operations.

Mempool Monitoring
The practice of observing pending transactions in the mempool to detect specific operations. Beneficiaries can use mempool monitoring to detect pending revocations and attempt front-running. Administrators can use it to detect competing claim transactions.

Race Condition
A situation where the outcome depends on the relative timing or ordering of events that cannot be controlled. In the vesting vault system, the race condition occurs when both revoke and claim transactions are submitted to the same ledger, and the execution order determines which operation succeeds.

Surge Pricing Mode
A network state that occurs when transaction volume exceeds ledger capacity. During surge pricing, transactions with higher fees are prioritized for inclusion in the next ledger. This allows beneficiaries to increase their front-running success probability by paying higher fees.

Freeze-Then-Revoke Procedure
The recommended operational security procedure for safely revoking tokens: (1) submit freeze transaction, (2) wait for freeze confirmation, (3) submit revocation transaction. This two-step process eliminates the race condition by preventing claims before revocation.

Off-Chain Coordination
Communication and negotiation between the administrator and beneficiary outside the blockchain (e.g., via email, phone, or in-person meetings) to agree on revocation timing and avoid adversarial scenarios.

Operational Security
Procedures and practices that administrators follow to minimize security risks during vault operations. For revocation, this includes proper use of the freeze mechanism, timing optimization, and monitoring.

Preemptive Freezing
The practice of freezing a vault before a revocation decision is finalized, typically used for high-risk scenarios (e.g., employment termination proceedings, high-value vaults). This eliminates the freeze front-running window but restricts beneficiary access during the freeze period.

Transaction Confirmation
The process of verifying that a transaction has been included in a closed ledger and is finalized. On Stellar, confirmation typically occurs within 5-6 seconds, and confirmed transactions cannot be reversed.

Atomicity
A property of transactions where all operations either succeed together or fail together - there is no partial execution. Vault operations (claim, revoke, freeze) are atomic, ensuring consistent state changes.

Finality
The guarantee that a confirmed transaction cannot be reversed or replaced. Stellar provides strong finality - once a ledger closes, the transaction order is permanent and no chain reorganizations can occur.

Pseudo-Random Ordering
Stellar's approach to ordering transactions within a ledger during normal operation. Transactions are applied in a randomized order (not fee-based order) to prevent high-frequency trading manipulation and fee-based front-running.

State
The current data stored in a smart contract or vault. Vault state includes fields like total_amount, released_amount, is_frozen, and is_irrevocable.

Stroop
The smallest unit of Stellar's native currency (XLM). One XLM equals 10,000,000 stroops. Transaction fees are typically measured in stroops (e.g., 100 stroops for a standard transaction).

• Terms marked with underscores (e.g., is_frozen, claim_tokens) refer to specific smart contract fields or functions
• Monetary values are typically expressed in tokens (the vesting vault's token) or USD/EUR for impact assessment
• Time values are typically expressed in seconds (for technical timing) or hours/days (for operational procedures)
• This glossary focuses on terms relevant to the revocation front-running security issue; for comprehensive Stellar/Soroban terminology, consult the official documentation listed in the References section

What is Revocation Front-Running?

Revocation front-running occurs when a beneficiary observes an administrator's pending revocation transaction in the mempool and submits a competing claim transaction to extract vested tokens before the revocation can execute. This attack exploits the inherent transparency of blockchain transaction queues combined with the race condition between revoke and claim operations.

Attack Sequence

The attack unfolds in the following sequence:

1. Initial State: A beneficiary has a vesting vault containing both vested and unvested tokens

   • The administrator has the authority to revoke unvested tokens (e.g., due to employment termination)
   • The beneficiary has the right to claim any vested tokens at any time
   • Both operations are legitimate individually, but their timing creates a race condition

2. Administrator Submits Revocation: The administrator submits a transaction calling revoke_tokens() to reclaim unvested tokens

   • The transaction enters Stellar's mempool (transaction queue)
   • The transaction becomes visible to all network participants
   • The transaction awaits inclusion in the next ledger (approximately 5 seconds)

3. Beneficiary Observes Pending Revocation: The beneficiary (or automated monitoring software) detects the pending revocation transaction

   • Mempool monitoring tools can observe pending transactions in real-time
   • The beneficiary identifies that their vault is the target of revocation
   • The beneficiary has approximately 5 seconds before the next ledger closes

4. Beneficiary Submits Competing Claim: The beneficiary immediately submits a transaction calling claim_tokens() to withdraw vested tokens

   • The claim transaction enters the mempool alongside the revocation transaction
   • During network congestion (surge pricing mode), the beneficiary can submit a higher fee to increase probability of inclusion
   • Both transactions now compete for inclusion and execution order

5. Transaction Inclusion and Execution: Both transactions are included in the next ledger

   • Normal Operation (below capacity): Transactions execute in pseudo-random order within the ledger
     • ~50% probability the claim executes first (beneficiary wins)
     • ~50% probability the revocation executes first (administrator wins)
   • Surge Pricing Mode (network congestion): Higher-fee transactions are prioritized for inclusion
     • If the beneficiary pays a higher fee, their claim transaction is more likely to be included in the current ledger
     • The revocation might be delayed to a subsequent ledger, giving the claim transaction priority

6. Outcome Determination: The execution order determines the attack outcome

   • If claim executes first: Beneficiary successfully extracts vested tokens before revocation
     • Vested tokens are transferred to the beneficiary's account
     • Revocation then executes, reclaiming only the remaining unvested tokens
     • Beneficiary has successfully front-run the revocation
   • If revocation executes first: Administrator successfully revokes before claim
     • Unvested tokens are returned to the administrator
     • Claim transaction may fail (if vault is frozen) or succeed with reduced amount
     • Administrator has prevented the front-running attempt

Concrete Example with Token Amounts

Consider the following scenario:

Initial Vault State

• Total tokens allocated: 100,000 tokens
• Vested tokens (claimable by beneficiary): 40,000 tokens
• Unvested tokens (revocable by administrator): 60,000 tokens
• Beneficiary: Alice (employee being terminated)
• Administrator: Company treasury account

Timeline of Events

T = 0 seconds

• Company decides to terminate Alice's employment
• Administrator prepares revocation transaction to reclaim 60,000 unvested tokens
• Alice's monitoring software is actively watching the mempool

T = 0.1 seconds

• Administrator submits revoke_tokens(alice_vault) transaction with standard fee (100 stroops)
• Transaction enters Stellar mempool
• Transaction is visible to all network participants

T = 0.5 seconds

• Alice's monitoring software detects the pending revocation transaction
• Software identifies that alice_vault is the target
• Software calculates that 40,000 vested tokens are at risk of being inaccessible after revocation

T = 1.0 seconds

• Alice's software automatically submits claim_tokens(alice_vault, 40000) transaction
• During surge pricing mode, Alice's software submits with higher fee (500 stroops) to prioritize inclusion
• Both transactions are now pending in the mempool

T = 5.0 seconds

• Next Stellar ledger closes
• Both transactions are included in the ledger

Scenario A: Claim Executes First (Front-Running Success)

• Alice's claim transaction executes: 40,000 tokens transferred to Alice's account
• Administrator's revocation executes: 60,000 unvested tokens returned to administrator
• Result: Alice successfully extracted all vested tokens before revocation
• Financial Impact: Alice gained 40,000 tokens that the administrator may have intended to freeze or coordinate differently

Scenario B: Revocation Executes First (Front-Running Prevented)

• Administrator's revocation executes: 60,000 unvested tokens returned to administrator
• If vault includes freeze mechanism: Alice's claim transaction fails (vault frozen)
• If no freeze mechanism: Alice's claim may still succeed for any remaining vested tokens
• Result: Administrator successfully revoked before Alice could claim
• Financial Impact: Administrator prevented uncoordinated token extraction

Key Observations

1. Attack Window: The 5-second ledger close time provides a narrow but exploitable window
2. Automation Advantage: Automated monitoring software can react faster than manual intervention
3. Fee Competition: During surge pricing, the beneficiary can pay higher fees to increase success probability
4. Legitimate Operations: Both revoke and claim are individually legitimate operations - the attack exploits their timing
5. Partial Success: Even if revocation executes first, the beneficiary may still claim vested tokens unless a freeze mechanism is used
6. Irreversibility: Once a ledger closes, the execution order is final - no chain reorganization is possible

Why This is a Fundamental Limitation

This attack vector exists due to fundamental blockchain design principles:

• Transparency: Public blockchains require transaction visibility for validation and consensus
• Decentralization: No central authority can hide or prioritize transactions arbitrarily
• Permissionless Access: Any participant can submit transactions and observe the mempool
• Race Conditions: When two legitimate operations conflict, execution order determines the outcome

The front-running risk cannot be eliminated without sacrificing these core blockchain properties. Instead, mitigation focuses on operational procedures, monitoring, and contract-level mechanisms (such as vault freezing) to minimize the attack window and impact.

Transaction Ordering on Stellar/Soroban

Stellar's transaction ordering mechanism operates differently depending on network conditions:

Normal Operation (Below Capacity)

• Transactions are applied in pseudo-random order within each ledger
• Fee amounts do not affect execution order during normal operation
• This randomization prevents high-frequency trading (HFT) manipulation and front-running based on fee priority
• Source: Stellar Stack Exchange

Surge Pricing Mode (Network Congestion)

• When transaction volume exceeds ledger capacity limits, the network enters surge pricing mode
• During surge pricing, fees act as bids for inclusion in the next ledger
• Transactions with higher fee-to-operation ratios are prioritized for inclusion
• Once included in a ledger, transactions are still applied in pseudo-random order
• Source: Stellar Developer Blog

Mempool Visibility

• Stellar's transaction queue (mempool) is visible to network participants
• Pending transactions can be observed before they are included in a ledger
• This transparency is fundamental to blockchain design but enables front-running attacks
• Transaction submission is currently a "black box" - clients cannot query the status of pending transactions in the queue
• While the mempool exists and transactions are visible to validators, there is no standardized API for querying pending transactions
• Source: GitHub stellar-core Issue #2920

Transaction Privacy Features

Stellar and Soroban have recently introduced privacy capabilities, though they are not applicable to standard vesting vault operations:

X-Ray Protocol Upgrade (January 2026)

• Introduces zero-knowledge proof capabilities to Soroban through BN254 curves and Poseidon hashing
• Enables verification of zero-knowledge proofs within smart contracts
• Allows proving attributes of data without revealing the data itself
• Source: Stellar Blog - Financial Privacy

Privacy Pools Implementation

• Privacy Pools enable privacy-preserving transfers by obscuring links between deposits and withdrawals
• Uses Groth16 zero-knowledge proofs over BLS12-381 curves
• Participants deposit funds into a pool and can later withdraw without revealing which deposit corresponds to which withdrawal
• Includes Association Set Providers (ASPs) for compliance and selective disclosure
• Source: Stellar Blog - Privacy Pools

Limitations for Vesting Vault Operations

• Privacy Pools require a fundamentally different contract architecture (deposit/withdraw model)
• The vesting vault system uses direct token operations (revoke/claim) that are inherently transparent
• Retrofitting privacy features would require complete redesign of the vesting mechanism
• Zero-knowledge proofs can verify properties without revealing data, but the act of revoking or claiming tokens must still be recorded on-chain
• Privacy features are most effective for fungible token transfers, not for specific vault state changes

Practical Implications

• Standard Soroban transactions (including revoke and claim operations) remain fully transparent
• Transaction content, including function calls and parameters, is visible once submitted
• Privacy features are available for developers building new privacy-focused applications, but cannot be applied retroactively to existing transparent contract designs
• For the vesting vault system, operational security measures remain the primary defense against front-running

Ledger Close Time and Confirmation

• Stellar ledgers close approximately every 5 seconds on average
• Transaction confirmation typically occurs within 5-6 seconds under normal conditions
• During network congestion, confirmation may take longer as transactions compete for inclusion
• Source: Stellar Stack Exchange

Transaction Finality on Stellar

• Soroban provides 5-second smart contract finality, meaning transactions are considered final and irreversible once included in a closed ledger
• Unlike proof-of-work blockchains (e.g., Bitcoin, Ethereum) where chain reorganizations can occur, Stellar's consensus mechanism prevents branching
• Once a transaction is confirmed in a ledger, it cannot be reversed or replaced by an alternative chain
• This strong finality guarantee eliminates double-spend attacks but does not prevent front-running
• Source: Stellar Soroban Platform, Issuer-Enforced Finality

Stellar Consensus Protocol (SCP) and Front-Running

SCP is a federated Byzantine agreement (FBA) system that provides decentralized consensus without relying on mining or staking. Key properties include:

Consensus Mechanism Properties

• Each validator node chooses a quorum set (trusted nodes) and a threshold for agreement
• Validators only accept ledger updates when their quorum set reaches consensus
• SCP prioritizes safety and fault tolerance over liveness, meaning the network may pause rather than accept conflicting states
• The protocol prevents chain branching, ensuring all honest nodes converge on a single ledger history
• Source: SCP Documentation, SCP Proof and Code

Transaction Ordering and Finality

• Transactions within a ledger are applied in pseudo-random order (not fee-based order) during normal operation
• This randomization prevents high-frequency trading manipulation and fee-based front-running under normal conditions
• Once a ledger closes, the transaction order is final and cannot be changed
• There is no concept of "reorgs" or alternative histories as in proof-of-work chains
• Source: Issuer-Enforced Finality Explained

Front-Running Protection Analysis

• SCP does NOT inherently prevent front-running attacks
• The consensus mechanism ensures agreement on which transactions to include, not on hiding transaction content
• Mempool visibility remains a fundamental characteristic - pending transactions are observable to network participants
• The pseudo-random ordering provides protection against fee-based transaction reordering within a single ledger during normal operation
• However, during surge pricing mode (network congestion), higher-fee transactions are prioritized for inclusion in the next ledger
• An attacker can still observe pending transactions and submit competing transactions before the original is included

Key Distinction: Finality vs. Privacy

• SCP provides strong finality guarantees (no chain reorganizations)
• SCP does NOT provide transaction privacy or mempool obfuscation
• The 5-second ledger close time creates a narrow but exploitable window for front-running
• Validators cannot collude to create alternative transaction histories, but they can observe and react to pending transactions

Implications for Revocation Front-Running

The combination of mempool visibility, 5-second finality, and SCP's consensus properties creates specific conditions for front-running attacks:

1. Attack Window: When an administrator submits a revocation transaction, it becomes visible in the mempool immediately
2. Observation: A beneficiary monitoring the mempool can detect the pending revocation within milliseconds
3. Response Time: The beneficiary has approximately 5 seconds (one ledger close period) to submit a competing claim transaction
4. Inclusion Competition: Both transactions compete for inclusion in the next ledger
   • During normal operation: If both transactions are included in the same ledger, they execute in pseudo-random order (roughly 50/50 odds)
   • During surge pricing: The beneficiary can submit a higher-fee claim transaction to increase probability of inclusion in the current ledger
5. Finality: Once a ledger closes with either transaction, the result is final and irreversible - no chain reorganization is possible

SCP's Role in Attack Dynamics

SCP's design characteristics have both protective and limiting effects:

Protective Aspects

• Pseudo-random ordering during normal operation prevents guaranteed fee-based front-running within a single ledger
• Strong finality eliminates uncertainty about transaction execution - once confirmed, the outcome is permanent
• No possibility of chain reorganization means attackers cannot "undo" a revocation after it executes

Limiting Aspects

• SCP does not hide pending transactions - mempool visibility is inherent to the design
• The 5-second ledger close time is predictable, giving attackers a known window to respond
• During network congestion, surge pricing reintroduces fee-based prioritization for ledger inclusion
• Validators cannot prevent observation of pending transactions by other network participants

Comparison to Other Blockchain Architectures

Stellar's front-running characteristics differ from other platforms:

• vs. Ethereum (pre-MEV protection): Stellar's pseudo-random ordering is better than pure fee-based ordering, but mempool visibility remains
• vs. Bitcoin: Similar mempool visibility, but Stellar's 5-second finality is much faster than Bitcoin's ~10 minute blocks
• vs. Private/Permissioned chains: Stellar prioritizes transparency and decentralization over transaction privacy

Key Takeaway: SCP provides strong consensus and finality guarantees but does not eliminate front-running risk. The protocol ensures that once a transaction executes, it is final and irreversible, but it does not prevent adversaries from observing pending transactions and submitting competing transactions. The pseudo-random ordering provides some protection during normal operation, but the mempool visibility and predictable 5-second ledger close times create sufficient opportunity for an attentive beneficiary to attempt front-running, especially during network congestion when fee-based prioritization becomes active.

Preconditions for Successful Attack

A successful revocation front-running attack requires all of the following conditions to be met:

1. Vault Contains Vested Tokens

   • The target vault must have tokens that have already vested according to the vesting schedule
   • If the vault contains only unvested tokens, there is nothing for the beneficiary to claim
   • The attack is only profitable when vested tokens exist at the time of revocation

2. Beneficiary Has Mempool Monitoring Capability

   • The beneficiary (or their automated software) must be actively monitoring the Stellar mempool for pending transactions
   • This requires running monitoring infrastructure or using third-party mempool observation services
   • Without mempool monitoring, the beneficiary cannot detect the pending revocation in time to respond

3. Beneficiary Can Submit Transactions Quickly

   • The beneficiary must be able to construct and submit a claim transaction within the ~5-second ledger close window
   • This typically requires automated software rather than manual intervention
   • The beneficiary's transaction submission infrastructure must be reliable and low-latency

4. Vault is Not Frozen Before Revocation

   • If the vault has a freeze mechanism and the administrator freezes the vault before submitting the revocation, claims are blocked
   • The attack only succeeds if the vault remains unfrozen during the critical window
   • Freezing is the primary technical countermeasure that breaks this precondition

5. Claim Transaction is Included in Same or Earlier Ledger

   • The beneficiary's claim transaction must be included in the same ledger as the revocation (and execute first due to pseudo-random ordering) or in an earlier ledger
   • During normal operation, if both transactions are in the same ledger, there is approximately 50% probability the claim executes first
   • During surge pricing mode, the beneficiary can increase inclusion probability by submitting a higher fee

6. No Off-Chain Coordination

   • The attack is most effective when the administrator does not coordinate with the beneficiary off-chain
   • If the beneficiary is informed in advance and agrees to the revocation terms, there is no adversarial behavior
   • The attack exploits surprise revocations where the beneficiary is not expecting the action

Financial Impact Quantification

The financial impact of a successful front-running attack can be calculated using the following methodology:

Impact Formula

Maximum_Extractable_Value = Vested_Tokens × Token_Price

Where:

• Vested_Tokens = The number of tokens that have vested in the vault at the time of revocation
• Token_Price = The current market price per token (in USD, EUR, or other reference currency)

Impact Calculation Examples

Example 1: Partial Vesting

• Total vault allocation: 100,000 tokens
• Vested tokens at revocation time: 40,000 tokens
• Unvested tokens: 60,000 tokens
• Token price: $2.50 per token
• Maximum Extractable Value: 40,000 × $2.50 = $100,000

Example 2: Mostly Vested

• Total vault allocation: 50,000 tokens
• Vested tokens at revocation time: 45,000 tokens
• Unvested tokens: 5,000 tokens
• Token price: $10.00 per token
• Maximum Extractable Value: 45,000 × $10.00 = $450,000

Example 3: Fully Unvested (No Risk)

• Total vault allocation: 200,000 tokens
• Vested tokens at revocation time: 0 tokens
• Unvested tokens: 200,000 tokens
• Token price: $5.00 per token
• Maximum Extractable Value: 0 × $5.00 = $0 (no attack possible)

Impact Factors and Considerations

The actual financial impact depends on several factors:

1. Vesting Schedule Progress

   • Early revocations (shortly after vesting begins) have lower impact because fewer tokens have vested
   • Late revocations (near the end of the vesting period) have higher impact because most tokens have vested
   • Cliff vesting schedules create step-function risk (zero risk before cliff, significant risk after cliff)

2. Token Liquidity and Price Volatility

   • Highly liquid tokens with stable prices have predictable impact
   • Illiquid tokens may have lower realized impact if the beneficiary cannot sell extracted tokens at market price
   • Price volatility affects the timing incentive - beneficiaries may be more motivated to extract during price peaks

3. Partial Claims

   • If the beneficiary has already claimed some vested tokens before the revocation, the remaining extractable value is reduced
   • Regular claims by beneficiaries reduce the attack surface by minimizing the vested token balance in the vault
   • Administrators should consider the vault's claim history when assessing risk

4. Transaction Costs

   • The beneficiary must pay transaction fees to submit the claim
   • During surge pricing mode, higher fees may be required to compete for inclusion
   • The attack is only rational if Extractable_Value > Transaction_Fees + Opportunity_Cost

5. Reputational and Legal Consequences

   • While the claim operation is technically legitimate, front-running a revocation may have legal or reputational consequences
   • Employment contracts or vesting agreements may include clauses that address this behavior
   • The beneficiary must weigh financial gain against potential legal liability or reputational damage

Risk Severity Assessment

The severity of the front-running risk can be categorized based on the extractable value:

• Low Risk: Extractable value < $10,000

  • Minimal financial impact
  • May not justify the effort of setting up monitoring infrastructure
  • Operational procedures may be sufficient mitigation

• Medium Risk: Extractable value $10,000 - $100,000

  • Significant financial impact
  • Justifies investment in monitoring and automation by beneficiary
  • Requires operational procedures and consideration of technical countermeasures

• High Risk: Extractable value > $100,000

  • Major financial impact
  • Strong incentive for beneficiary to attempt front-running
  • Requires robust technical countermeasures (vault freezing) and strict operational procedures

Which Tokens Are At Risk: Vested vs. Unvested

It is critical to understand that only vested tokens are at risk in a front-running attack. Unvested tokens are never at risk because the beneficiary has no right to claim them.

Token Risk Breakdown

Vested Tokens (At Risk)

• Vested tokens are those that have completed their vesting schedule and are claimable by the beneficiary
• These tokens are at risk because the beneficiary can legitimately call claim_tokens() to withdraw them
• The front-running attack exploits the race condition to claim these tokens before the administrator can coordinate or freeze the vault
• Risk Level: High - these tokens can be extracted if the beneficiary acts quickly

Unvested Tokens (Not At Risk)

• Unvested tokens are those that have not yet completed their vesting schedule
• These tokens are not claimable by the beneficiary under any circumstances
• The revoke_tokens() function reclaims these tokens and returns them to the administrator
• Risk Level: None - these tokens are protected by the vesting schedule and cannot be claimed

Mixed-State Vault Example

Consider a vault with both vested and unvested tokens:

Vault State at Revocation Time

• Total allocation: 100,000 tokens
• Vested tokens: 40,000 tokens (40% of allocation)
• Unvested tokens: 60,000 tokens (60% of allocation)

Scenario A: Beneficiary Front-Runs Successfully

1. Beneficiary's claim executes first: 40,000 vested tokens transferred to beneficiary
2. Administrator's revocation executes second: 60,000 unvested tokens returned to administrator
3. Outcome: Beneficiary extracted 40,000 tokens, administrator recovered 60,000 tokens

Scenario B: Administrator's Revocation Executes First

1. Administrator's revocation executes first: 60,000 unvested tokens returned to administrator
2. If vault is frozen: Beneficiary's claim fails (0 tokens extracted)
3. If vault is not frozen: Beneficiary's claim may still succeed for the 40,000 vested tokens
4. Outcome: Administrator recovered 60,000 tokens, beneficiary may still claim 40,000 tokens (unless vault is frozen)

Key Insight: Vesting Schedule as Partial Protection

The vesting schedule provides natural protection against front-running:

• Early in the vesting period, few tokens have vested, so the extractable value is low
• The administrator can minimize risk by revoking early (e.g., immediately upon employment termination)
• The longer the administrator waits to revoke, the more tokens vest, and the higher the front-running risk

Clarification: Revocation Does Not Affect Vested Tokens (Unless Vault is Frozen)

It is important to understand that the revoke_tokens() function typically only reclaims unvested tokens. Vested tokens remain claimable by the beneficiary even after revocation, unless:

1. The vault is frozen before or during the revocation, preventing all claims
2. The contract design includes a mechanism to revoke vested tokens (which would be unusual and potentially legally problematic)

Therefore, the front-running attack is not about "stealing" tokens that would otherwise be revoked - it is about claiming vested tokens before the administrator can freeze the vault or coordinate the revocation timing.

Risk Mitigation Through Vesting Schedule Design

Organizations can reduce front-running risk through careful vesting schedule design:

• Longer Cliff Periods: Delay the initial vesting to reduce the window when tokens are at risk
• Shorter Vesting Periods: Complete vesting quickly to eliminate the mixed-state window
• Frequent Vesting Events: Vest tokens in small increments to reduce the extractable value at any given time
• Encourage Regular Claims: Incentivize beneficiaries to claim vested tokens regularly, reducing the vault balance

Summary

• At Risk: Vested tokens that have completed their vesting schedule
• Not At Risk: Unvested tokens that are protected by the vesting schedule
• Impact: Proportional to the vested token balance at the time of revocation
• Mitigation: Freeze vault before revocation, revoke early in vesting period, design vesting schedules to minimize risk windows

This section documents the technical behavior of the vault operation functions involved in the front-running attack vector. Understanding these functions is essential for administrators to assess the attack surface and implement appropriate mitigations.

revoke_tokens Function

The revoke_tokens(vault_id) function allows the administrator to reclaim unvested tokens from a beneficiary's vault and return them to the administrator's balance.

Function Signature

pub fn revoke_tokens(env: Env, vault_id: u64) -> i128

Behavior

• Reclaims all unvested tokens from the specified vault
• Calculates unvested amount as: unreleased_amount = total_amount - released_amount
• Updates the vault's released_amount to equal total_amount, effectively marking all tokens as "released" (preventing future claims)
• Transfers the unvested tokens back to the administrator's balance
• Emits a TokensRevoked event with the amount and timestamp
• Returns the amount of tokens revoked

Preconditions

1. Administrator Authorization: Only the contract administrator can call this function

   • The function calls require_admin() which panics if the caller is not the administrator
   • This prevents beneficiaries or other parties from revoking tokens

2. Vault Must Exist: The vault ID must correspond to an existing vault in storage

   • If the vault is not found, the function panics with "Vault not found"

3. Vault Must Be Revocable: The vault's is_irrevocable flag must be false

   • If the vault is marked as irrevocable, the function panics with "Vault is irrevocable"
   • Irrevocable vaults are permanently protected from revocation (typically used for fully vested grants)

4. Unvested Tokens Must Exist: The vault must have tokens that have not been released

   • If unreleased_amount <= 0, the function panics with "No tokens available to revoke"
   • This prevents revocation of vaults where all tokens have already been claimed or revoked

Effects

• Vault State Change: Sets vault.released_amount = vault.total_amount
  • This marks all tokens as "released" from the vault's perspective
  • Future claim attempts will fail because available_to_claim = unlocked_amount - released_amount will be <= 0
• Administrator Balance Increase: Adds the revoked amount to the administrator's balance
• Event Emission: Publishes a TokensRevoked event for off-chain monitoring
• Atomicity: The entire operation is atomic - either all state changes succeed or the transaction reverts

Interaction with Vault Freeze

• The revoke_tokens function does NOT check if the vault is frozen
• Revocation can proceed even if the vault is frozen
• This is intentional: freezing prevents beneficiary claims but does not prevent administrator revocation
• The freeze mechanism is designed to protect the administrator's ability to revoke, not to prevent revocation itself

Key Insight: Revocation Does Not Affect Already-Claimed Tokens

• The function only reclaims tokens that have not yet been released (claimed) from the vault
• If the beneficiary has already claimed some vested tokens, those tokens are not affected by revocation
• This is why front-running is effective: the beneficiary can claim vested tokens before the revocation executes, permanently removing those tokens from the vault's balance

claim_tokens Function

The claim_tokens(vault_id, claim_amount) function allows a beneficiary to withdraw vested tokens from their vault.

Function Signature

pub fn claim_tokens(env: Env, vault_id: u64, claim_amount: i128) -> i128

Behavior

• Withdraws a specified amount of vested tokens from the vault
• Calculates the amount of tokens that have vested (unlocked) based on the vesting schedule or milestones
• Verifies that the requested claim amount does not exceed the available unlocked tokens
• Updates the vault's released_amount to track the claim
• Returns the amount of tokens claimed

Preconditions

1. Contract Must Not Be Paused: The global contract pause flag must be false

   • If the contract is paused, the function panics with "Contract is paused - all withdrawals are disabled"
   • The pause mechanism is a global emergency stop that affects all vaults

2. Vault Must Exist: The vault ID must correspond to an existing vault in storage

   • If the vault is not found, the function panics with "Vault not found"

3. Vault Must Not Be Frozen: The vault's is_frozen flag must be false

   • If the vault is frozen, the function panics with "Vault is frozen - claims are disabled"
   • This is the primary defense against front-running: freezing the vault before revocation prevents claims

4. Vault Must Be Initialized: The vault's is_initialized flag must be true

   • If not initialized, the function panics with "Vault not initialized"
   • Initialization typically occurs when milestones are configured or the vault is first activated

5. Claim Amount Must Be Positive: The claim_amount parameter must be greater than zero

   • If claim_amount <= 0, the function panics with "Claim amount must be positive"

6. Sufficient Unlocked Tokens: The vault must have enough vested (unlocked) tokens to satisfy the claim

   • The function calculates unlocked_amount based on the vesting schedule or milestone progress
   • It then calculates available_to_claim = unlocked_amount - released_amount
   • If available_to_claim <= 0, the function panics with "No tokens available to claim"
   • If claim_amount > available_to_claim, the function panics with "Insufficient unlocked tokens to claim"

Effects

• Vault State Change: Increases vault.released_amount by the claimed amount
  • This tracks how many tokens have been withdrawn from the vault
  • Future claims will have a reduced available_to_claim amount
• Token Transfer: Transfers the claimed tokens to the beneficiary's account (handled by the calling code)
• Staking Integration: If the vault has staked tokens and the liquid balance is insufficient, the function automatically unstakes tokens to satisfy the claim
• Atomicity: The entire operation is atomic - either all state changes succeed or the transaction reverts

Partial Claim Support

• The function fully supports partial claims
• The beneficiary can claim any amount up to the available_to_claim limit
• Multiple partial claims can be made over time as more tokens vest
• Each claim increments the released_amount, reducing the amount available for future claims
• Impact on Front-Running: Partial claims reduce the attack surface
  • If a beneficiary regularly claims vested tokens, the vault balance is lower
  • A lower vault balance means less value is at risk during a revocation front-running attack
  • Administrators should encourage beneficiaries to claim tokens regularly to minimize the extractable value

Vesting Calculation

• The function supports two vesting mechanisms:
  1. Time-Based Vesting: Calculates unlocked amount based on elapsed time since the vesting start date
     • Uses calculate_time_vested_amount() to compute the vested amount
     • Typically follows a linear vesting schedule (e.g., 25% per year over 4 years)
  2. Milestone-Based Vesting: Calculates unlocked amount based on manually unlocked milestones
     • Uses require_milestones_configured() and unlocked_percentage() to compute the vested amount
     • Milestones must be explicitly unlocked by the administrator or authorized party
• The vesting mechanism determines how much of the vault's total_amount is available for claiming at any given time

Key Insight: Claims Are Irreversible

• Once tokens are claimed and transferred to the beneficiary's account, they cannot be revoked
• The revoke_tokens function only affects tokens that remain in the vault (unreleased tokens)
• This is why the race condition exists: if the claim executes before the revocation, the tokens are permanently transferred to the beneficiary

Vault Freeze Mechanism

The vault freeze mechanism is a critical security feature that allows the administrator to temporarily disable claims on a specific vault without affecting other vaults or the ability to revoke tokens.

freeze_vault Function

pub fn freeze_vault(env: Env, vault_id: u64)

Behavior

• Sets the vault's is_frozen flag to true
• Prevents all claim operations on the vault until it is unfrozen
• Does NOT prevent revocation operations (administrator can still revoke tokens from a frozen vault)
• Emits a VaultFrozen event with the vault ID and timestamp

Preconditions

1. Administrator Authorization: Only the contract administrator can freeze vaults
2. Vault Must Exist: The vault ID must correspond to an existing vault
3. Vault Must Not Already Be Frozen: If the vault is already frozen, the function panics with "Vault is already frozen"

unfreeze_vault Function

pub fn unfreeze_vault(env: Env, vault_id: u64)

Behavior

• Sets the vault's is_frozen flag to false
• Re-enables claim operations on the vault
• Emits a VaultUnfrozen event with the vault ID and timestamp

Preconditions

1. Administrator Authorization: Only the contract administrator can unfreeze vaults
2. Vault Must Exist: The vault ID must correspond to an existing vault
3. Vault Must Be Frozen: If the vault is not frozen, the function panics with "Vault is not frozen"

Effect on Operations

Role in Front-Running Prevention

The vault freeze mechanism is the primary technical countermeasure against revocation front-running:

1. Pre-Revocation Freeze: The administrator should freeze the vault BEFORE submitting the revocation transaction

   • This prevents the beneficiary from claiming tokens even if they observe the pending revocation
   • The freeze transaction must be confirmed (included in a ledger) before the revocation transaction is submitted
   • This creates a two-step process: freeze first, then revoke

2. Attack Window Elimination: If the vault is frozen before revocation, the front-running attack is prevented

   • The beneficiary's claim transaction will fail with "Vault is frozen - claims are disabled"
   • The revocation can proceed safely, reclaiming all unvested tokens
   • The administrator can then unfreeze the vault if needed (though this is typically unnecessary after revocation)

3. Timing Considerations: The freeze mechanism is only effective if used correctly

   • Correct Usage: Submit freeze transaction → Wait for confirmation → Submit revocation transaction
   • Incorrect Usage: Submit freeze and revocation in the same ledger → Race condition still exists
   • Incorrect Usage: Submit revocation without freezing → Beneficiary can front-run

4. Limitations: The freeze mechanism does not prevent all front-running scenarios

   • If the beneficiary observes the freeze transaction in the mempool, they can submit a claim before the freeze is confirmed
   • This creates a "freeze front-running" scenario where the beneficiary races to claim before the freeze takes effect
   • To mitigate this, administrators should monitor the mempool and ensure the freeze transaction is confirmed before proceeding

Key Insight: Freeze is Necessary But Not Sufficient

While the freeze mechanism is the most effective technical countermeasure, it is not a complete solution:

• The freeze transaction itself is visible in the mempool, potentially alerting the beneficiary
• The beneficiary can attempt to front-run the freeze transaction by submitting a claim before the freeze is confirmed
• Operational security measures (monitoring, timing, off-chain coordination) are still necessary to minimize risk

Race Condition Analysis

The revocation front-running attack fundamentally exploits a race condition between two legitimate operations: the administrator's revoke_tokens and the beneficiary's claim_tokens. This section provides a detailed technical analysis of the race condition, including timing diagrams, execution sequences, and the impact of partial claims.

Nature of the Race Condition

A race condition occurs when the outcome of a system depends on the relative timing or ordering of events that cannot be controlled. In the vesting vault system, the race condition arises from:

1. Concurrent Legitimate Rights: Both parties have valid rights that can be exercised simultaneously

   • Administrator: Right to revoke unvested tokens at any time
   • Beneficiary: Right to claim vested tokens at any time
   • Neither operation requires permission from the other party

2. Shared Resource Contention: Both operations modify the same vault state

   • revoke_tokens sets vault.released_amount = vault.total_amount (marking all tokens as released)
   • claim_tokens increases vault.released_amount by the claimed amount
   • The final state depends on which operation executes first

3. Mempool Visibility: Transaction transparency enables adversarial timing

   • The administrator's revocation transaction is visible in the mempool before execution
   • The beneficiary can observe this pending transaction and react
   • The beneficiary has approximately 5 seconds (one ledger close period) to submit a competing transaction

4. Non-Deterministic Ordering: Transaction execution order is not guaranteed

   • During normal operation: Transactions in the same ledger execute in pseudo-random order
   • During surge pricing: Higher-fee transactions are prioritized for inclusion, but execution order within a ledger remains pseudo-random
   • Neither party can guarantee their transaction executes first

Timing Diagram: Successful Front-Running Attack

Time (seconds)    Administrator                Beneficiary                  Blockchain State
─────────────────────────────────────────────────────────────────────────────────────────────
T = 0.0           Decides to revoke            Monitoring mempool           Vault: 40k vested, 60k unvested
                  tokens from vault                                         Beneficiary balance: 0 tokens
                                                                            
T = 0.1           Submits revoke_tokens()      -                            Revocation tx enters mempool
                  transaction (100 stroops)                                 (visible to all participants)
                                                                            
T = 0.5           -                            Detects pending              Mempool: 1 transaction
                                               revocation transaction       (revoke_tokens)
                                                                            
T = 1.0           -                            Submits claim_tokens()       Mempool: 2 transactions
                                               transaction (500 stroops)    (revoke_tokens, claim_tokens)
                                               with higher fee              
                                                                            
T = 5.0           -                            -                            Ledger closes
                                                                            Both transactions included
                                                                            
T = 5.0 + ε       -                            -                            Execution order determined:
                                                                            1. claim_tokens executes first
                                                                            2. revoke_tokens executes second
                                                                            
T = 5.1           -                            -                            After claim_tokens:
                                                                            - Vault: 0k vested, 60k unvested
                                                                            - Beneficiary balance: 40k tokens
                                                                            - vault.released_amount += 40k
                                                                            
T = 5.2           -                            -                            After revoke_tokens:
                                                                            - Vault: 0k vested, 0k unvested
                                                                            - Admin balance: +60k tokens
                                                                            - vault.released_amount = total_amount
                                                                            
T = 5.3           Revocation confirmed         Claim confirmed              FINAL STATE:
                  (60k tokens recovered)       (40k tokens extracted)       - Beneficiary: 40k tokens (SUCCESS)
                                                                            - Administrator: 60k tokens
                                                                            - Vault: empty

Key Observations from Timing Diagram:

• The beneficiary has a 4.9-second window (T=0.1 to T=5.0) to detect and respond
• The higher fee (500 vs 100 stroops) increases inclusion probability during surge pricing but does not guarantee execution order within the ledger
• Once the ledger closes at T=5.0, the execution order is determined by pseudo-random selection
• The claim executes first, permanently transferring 40k tokens to the beneficiary
• The revocation executes second, recovering only the remaining 60k unvested tokens

Timing Diagram: Prevented Attack (Vault Frozen)

Time (seconds)    Administrator                Beneficiary                  Blockchain State
─────────────────────────────────────────────────────────────────────────────────────────────
T = 0.0           Decides to revoke            Monitoring mempool           Vault: 40k vested, 60k unvested
                  tokens from vault                                         vault.is_frozen = false
                                                                            
T = 0.1           Submits freeze_vault()       -                            Freeze tx enters mempool
                  transaction                                               
                                                                            
T = 5.0           -                            -                            Ledger closes
                                                                            Freeze tx executes
                                                                            
T = 5.1           -                            -                            Vault: 40k vested, 60k unvested
                                                                            vault.is_frozen = true
                                                                            
T = 10.0          Freeze confirmed             Detects vault is frozen      Vault frozen, claims blocked
                  Waits for confirmation                                    
                                                                            
T = 15.0          Submits revoke_tokens()      -                            Revocation tx enters mempool
                  transaction                                               
                                                                            
T = 15.5          -                            Detects pending              Mempool: 1 transaction
                                               revocation transaction       (revoke_tokens)
                                                                            
T = 16.0          -                            Submits claim_tokens()       Mempool: 2 transactions
                                               transaction (attempt)        (revoke_tokens, claim_tokens)
                                                                            
T = 20.0          -                            -                            Ledger closes
                                                                            Both transactions included
                                                                            
T = 20.0 + ε      -                            -                            Execution order determined:
                                                                            1. claim_tokens executes first
                                                                            2. revoke_tokens executes second
                                                                            
T = 20.1          -                            -                            claim_tokens execution:
                                                                            - Checks vault.is_frozen = true
                                                                            - PANICS: "Vault is frozen"
                                                                            - Transaction REVERTS
                                                                            - No state changes
                                                                            
T = 20.2          -                            -                            revoke_tokens execution:
                                                                            - Vault is frozen (does not block revocation)
                                                                            - Transfers 60k unvested tokens to admin
                                                                            - Sets vault.released_amount = total_amount
                                                                            - Transaction SUCCEEDS
                                                                            
T = 20.3          Revocation confirmed         Claim FAILED                 FINAL STATE:
                  (60k tokens recovered)       (0 tokens extracted)         - Beneficiary: 0 tokens (FAILURE)
                                                                            - Administrator: 60k tokens
                                                                            - Vault: 40k vested (unclaimed)
                                                                            - vault.is_frozen = true

Key Observations from Prevention Diagram:

• The administrator freezes the vault in a separate transaction BEFORE submitting the revocation
• The freeze transaction is confirmed at T=5.1, establishing vault.is_frozen = true
• The administrator waits for freeze confirmation before submitting the revocation at T=15.0
• Even though the beneficiary's claim executes first (T=20.1), it fails due to the freeze check
• The revocation succeeds (T=20.2) because revoke_tokens does not check the freeze flag
• The two-step process (freeze → revoke) eliminates the race condition

Execution Sequence: Race Condition Outcomes

The race condition has three possible outcomes depending on the execution order and vault state:

Outcome 1: Claim Executes First (Unfrozen Vault) - Front-Running Success

Initial State:
  vault.total_amount = 100,000
  vault.released_amount = 0
  vested_amount = 40,000
  unvested_amount = 60,000
  vault.is_frozen = false

Execution Sequence:
  1. claim_tokens(vault_id, 40000) executes
     - Checks: vault.is_frozen = false ✓
     - Checks: available_to_claim = 40,000 - 0 = 40,000 ✓
     - Checks: claim_amount (40,000) <= available_to_claim (40,000) ✓
     - Effect: vault.released_amount = 0 + 40,000 = 40,000
     - Effect: Transfer 40,000 tokens to beneficiary
     - Result: SUCCESS
  
  2. revoke_tokens(vault_id) executes
     - Checks: vault.is_irrevocable = false ✓
     - Calculates: unreleased_amount = 100,000 - 40,000 = 60,000
     - Checks: unreleased_amount > 0 ✓
     - Effect: vault.released_amount = 100,000
     - Effect: Transfer 60,000 tokens to administrator
     - Result: SUCCESS

Final State:
  vault.total_amount = 100,000
  vault.released_amount = 100,000
  beneficiary_balance = +40,000 tokens
  administrator_balance = +60,000 tokens
  
Outcome: Beneficiary successfully front-ran the revocation

Outcome 2: Revocation Executes First (Unfrozen Vault) - Partial Prevention

Initial State:
  vault.total_amount = 100,000
  vault.released_amount = 0
  vested_amount = 40,000
  unvested_amount = 60,000
  vault.is_frozen = false

Execution Sequence:
  1. revoke_tokens(vault_id) executes
     - Checks: vault.is_irrevocable = false ✓
     - Calculates: unreleased_amount = 100,000 - 0 = 100,000
     - Checks: unreleased_amount > 0 ✓
     - Effect: vault.released_amount = 100,000
     - Effect: Transfer 100,000 tokens to administrator
     - Result: SUCCESS
  
  2. claim_tokens(vault_id, 40000) executes
     - Checks: vault.is_frozen = false ✓
     - Calculates: available_to_claim = vested_amount - released_amount
     - Calculates: available_to_claim = 40,000 - 100,000 = -60,000
     - Checks: available_to_claim <= 0 ✗
     - Result: PANIC "No tokens available to claim"
     - Transaction REVERTS

Final State:
  vault.total_amount = 100,000
  vault.released_amount = 100,000
  beneficiary_balance = 0 tokens
  administrator_balance = +100,000 tokens
  
Outcome: Administrator prevented front-running by executing first
Note: This outcome depends on the specific contract implementation. Some implementations may allow the revocation to reclaim ALL tokens (including vested), while others may only reclaim unvested tokens. The example above assumes revocation reclaims all unreleased tokens.

Outcome 3: Claim Executes First (Frozen Vault) - Complete Prevention

Initial State:
  vault.total_amount = 100,000
  vault.released_amount = 0
  vested_amount = 40,000
  unvested_amount = 60,000
  vault.is_frozen = true  ← Vault was frozen before revocation

Execution Sequence:
  1. claim_tokens(vault_id, 40000) executes
     - Checks: vault.is_frozen = true ✗
     - Result: PANIC "Vault is frozen - claims are disabled"
     - Transaction REVERTS
     - No state changes
  
  2. revoke_tokens(vault_id) executes
     - Checks: vault.is_irrevocable = false ✓
     - Checks: vault.is_frozen (NOT CHECKED - revocation ignores freeze)
     - Calculates: unreleased_amount = 100,000 - 0 = 100,000
     - Checks: unreleased_amount > 0 ✓
     - Effect: vault.released_amount = 100,000
     - Effect: Transfer 100,000 tokens to administrator
     - Result: SUCCESS

Final State:
  vault.total_amount = 100,000
  vault.released_amount = 100,000
  beneficiary_balance = 0 tokens
  administrator_balance = +100,000 tokens
  vault.is_frozen = true
  
Outcome: Freeze mechanism completely prevented front-running

Impact of Partial Claims on the Attack Vector

Partial claims significantly affect the front-running attack dynamics by reducing the extractable value and changing the risk-reward calculation for the beneficiary.

Scenario 1: No Prior Claims (Maximum Risk)

Vault State at Revocation Time:
  total_amount = 100,000
  released_amount = 0  ← No prior claims
  vested_amount = 40,000
  available_to_claim = 40,000 - 0 = 40,000

Front-Running Potential:
  Maximum Extractable Value = 40,000 tokens
  Beneficiary Incentive: HIGH
  Administrator Risk: HIGH

Scenario 2: Regular Partial Claims (Reduced Risk)

Vault State at Revocation Time:
  total_amount = 100,000
  released_amount = 30,000  ← Beneficiary claimed 30k tokens previously
  vested_amount = 40,000
  available_to_claim = 40,000 - 30,000 = 10,000

Front-Running Potential:
  Maximum Extractable Value = 10,000 tokens
  Beneficiary Incentive: MEDIUM
  Administrator Risk: MEDIUM
  
Prior Claims History:
  - Month 1: Claimed 10,000 tokens (released_amount = 10,000)
  - Month 2: Claimed 10,000 tokens (released_amount = 20,000)
  - Month 3: Claimed 10,000 tokens (released_amount = 30,000)
  - Month 4: Revocation occurs (only 10,000 tokens remain claimable)

Scenario 3: Frequent Claims (Minimal Risk)

Vault State at Revocation Time:
  total_amount = 100,000
  released_amount = 39,000  ← Beneficiary claimed 39k tokens previously
  vested_amount = 40,000
  available_to_claim = 40,000 - 39,000 = 1,000

Front-Running Potential:
  Maximum Extractable Value = 1,000 tokens
  Beneficiary Incentive: LOW
  Administrator Risk: LOW
  
Prior Claims History:
  - Weekly claims of small amounts
  - Vault balance kept minimal
  - Front-running attack not economically rational (transaction fees may exceed extractable value)

Mathematical Relationship: Partial Claims and Risk

The extractable value in a front-running attack is directly proportional to the unclaimed vested balance:

Extractable_Value = Vested_Amount - Released_Amount
Risk_Level = Extractable_Value × Token_Price

Where:
  Vested_Amount = Tokens that have completed vesting schedule
  Released_Amount = Tokens already claimed by beneficiary
  Token_Price = Current market price per token

Impact Analysis:

1. Risk Reduction Through Regular Claims

   • Each partial claim reduces available_to_claim by the claimed amount
   • Lower available_to_claim means lower extractable value in a front-running attack
   • Beneficiaries who claim regularly present lower risk to administrators

2. Beneficiary Incentive Calculation

   • Rational beneficiaries will only attempt front-running if: Extractable_Value > Transaction_Fees + Opportunity_Cost + Risk_Premium
   • As Extractable_Value decreases (due to prior claims), the attack becomes less attractive
   • Below a certain threshold (e.g., $1,000), the attack may not be worth the effort

3. Administrator Strategy

   • Encourage beneficiaries to claim vested tokens regularly (e.g., monthly or quarterly)
   • Monitor vault balances and prioritize revocation of high-balance vaults
   • Consider the claim history when assessing front-running risk

4. Partial Claim During Front-Running

   • A sophisticated beneficiary might submit a partial claim (rather than claiming all vested tokens) to reduce suspicion
   • Example: If 40,000 tokens are vested, the beneficiary might claim only 20,000 to appear less adversarial
   • This strategy is less effective because the administrator can still observe the claim transaction in the mempool

Key Insight: Partial Claims as a Risk Mitigation Tool

Organizations can reduce front-running risk by implementing policies that encourage regular partial claims:

• Automatic Claim Reminders: Notify beneficiaries when tokens vest and encourage immediate claiming
• Claim Incentives: Provide small bonuses or reduced fees for regular claims
• Vault Balance Monitoring: Track vault balances and flag high-balance vaults for priority monitoring
• Revocation Timing: Schedule revocations shortly after vesting events (when vault balances are highest) to minimize the window of vulnerability

By encouraging beneficiaries to claim vested tokens regularly, administrators can significantly reduce the extractable value in a front-running attack, making the attack less attractive and reducing the financial risk.

Summary: Race Condition Characteristics

The revocation front-running race condition has the following key characteristics:

1. Concurrent Legitimate Operations: Both revoke and claim are individually legitimate, but their timing creates a conflict
2. Shared State Modification: Both operations modify vault.released_amount, creating a dependency on execution order
3. Mempool Visibility: Transaction transparency enables the beneficiary to observe and react to pending revocations
4. Non-Deterministic Ordering: Pseudo-random execution order within a ledger creates uncertainty for both parties
5. Freeze Mechanism as Defense: The vault freeze flag provides a technical countermeasure by blocking claims before revocation
6. Partial Claims Reduce Risk: Regular partial claims by beneficiaries reduce the vault balance and lower the extractable value
7. Operational Procedures Required: Technical mechanisms alone are insufficient; administrators must follow proper procedures (freeze before revoke) to eliminate the race condition

Administrators must understand these race condition dynamics to implement effective operational security procedures and minimize the risk of front-running attacks.

This section evaluates technical countermeasures that can mitigate or eliminate the revocation front-running attack vector. We analyze three primary contract-level approaches and assess their feasibility, effectiveness, and trade-offs.

Technical Countermeasure Evaluation

1. Vault Freezing Mechanism (Currently Implemented)

Description

The vault freezing mechanism is a binary flag (is_frozen) that, when set to true, prevents all claim operations on a specific vault while still allowing revocation operations. This creates a two-step revocation process:

1. Administrator calls freeze_vault(vault_id) and waits for confirmation
2. Administrator calls revoke_tokens(vault_id) after freeze is confirmed

Feasibility: IMPLEMENTED

The vault freezing mechanism is already implemented in the current vesting vault system and is fully operational.

Effectiveness: HIGH (when used correctly)

The freeze mechanism provides strong protection against front-running when used according to the correct operational procedure:

Strengths:

• Complete Attack Prevention: If the vault is frozen before revocation, claim transactions will fail with "Vault is frozen - claims are disabled", regardless of execution order
• Granular Control: Freezing affects only the target vault, not other vaults in the system
• Reversible: Vaults can be unfrozen if needed (though typically unnecessary after revocation)
• No Gas Competition: The administrator does not need to compete on transaction fees - the freeze guarantee is cryptographic, not economic
• Simple Implementation: Uses a single boolean flag with minimal gas overhead

Limitations:

• Requires Two Transactions: The administrator must submit two separate transactions (freeze, then revoke), increasing operational complexity and gas costs
• Freeze Transaction is Visible: The freeze transaction itself is visible in the mempool, potentially alerting the beneficiary
• Freeze Front-Running Risk: A sophisticated beneficiary monitoring the mempool can attempt to front-run the freeze transaction by submitting a claim before the freeze is confirmed
• Operational Discipline Required: The mechanism is only effective if administrators follow the correct procedure (freeze → wait for confirmation → revoke). Submitting both transactions simultaneously or revoking without freezing leaves the attack vector open
• No Automatic Enforcement: The system does not enforce the freeze-before-revoke pattern - administrators can still revoke without freezing

Trade-offs:

• Cost vs. Security: The two-transaction approach doubles the gas costs for revocation, but provides strong security guarantees
• Speed vs. Safety: The freeze-then-revoke process takes at least two ledger close periods (~10 seconds minimum), compared to a single revocation transaction (~5 seconds)
• Complexity vs. Simplicity: Administrators must understand and follow a multi-step procedure rather than a single revoke operation

Effectiveness Assessment:

Recommendation: STRONGLY RECOMMENDED

The vault freezing mechanism is the most effective technical countermeasure currently available. Administrators should:

• Always freeze vaults before revoking
• Wait for freeze confirmation before submitting revocation
• Monitor mempool for competing claim transactions during the freeze window
• Consider freezing vaults preemptively for high-risk beneficiaries (e.g., employees under performance review)

2. Two-Step Revocation Process (Announce Then Execute)

Description

A two-step revocation process would introduce a mandatory delay between announcing the intent to revoke and executing the revocation. The process would work as follows:

1. Administrator calls announce_revocation(vault_id, delay_period) - marks the vault as "pending revocation" with a timestamp
2. System enforces a mandatory delay period (e.g., 24 hours, 7 days)
3. After the delay period expires, administrator calls execute_revocation(vault_id) to complete the revocation
4. During the delay period, claims may be blocked, allowed, or rate-limited depending on implementation

Feasibility: FEASIBLE (requires contract modification)

Implementing a two-step revocation process would require significant contract modifications:

Required Changes:

• Add revocation_announced_at timestamp field to vault struct
• Add revocation_delay_period configuration parameter
• Modify revoke_tokens to check if announcement period has elapsed
• Add announce_revocation function to initiate the process
• Add cancel_revocation_announcement function to abort if needed
• Modify claim_tokens to enforce restrictions during the announcement period

Implementation Complexity: MEDIUM

• Estimated development effort: 2-3 days
• Testing effort: 2-3 days (including edge cases and timing scenarios)
• Gas cost increase: Minimal (one additional timestamp storage per vault)

Effectiveness: MEDIUM TO HIGH (depends on implementation variant)

The effectiveness of a two-step revocation process depends on how claims are handled during the announcement period:

Variant A: Block All Claims During Announcement Period

pub fn announce_revocation(env: Env, vault_id: u64, delay_period: u64) {
    // Mark vault as pending revocation
    vault.revocation_announced_at = env.ledger().timestamp();
    vault.revocation_delay_period = delay_period;
}

pub fn claim_tokens(env: Env, vault_id: u64, claim_amount: i128) {
    // Check if revocation is announced
    if vault.revocation_announced_at > 0 {
        panic!("Vault has pending revocation - claims are blocked");
    }
    // ... rest of claim logic
}

Effectiveness: HIGH

• Prevents front-running by blocking claims once revocation is announced
• Functionally equivalent to the freeze mechanism but with a mandatory delay
• Beneficiaries cannot extract tokens after announcement

Drawback:

• Creates a new front-running vector: beneficiaries can front-run the announcement transaction itself
• The announcement transaction is visible in the mempool, giving beneficiaries ~5 seconds to submit a claim before the announcement is confirmed
• This shifts the race condition from revocation to announcement, but does not eliminate it

Variant B: Allow Claims During Announcement Period

pub fn announce_revocation(env: Env, vault_id: u64, delay_period: u64) {
    // Mark vault as pending revocation
    vault.revocation_announced_at = env.ledger().timestamp();
    vault.revocation_delay_period = delay_period;
}

pub fn claim_tokens(env: Env, vault_id: u64, claim_amount: i128) {
    // Claims are allowed during announcement period
    // ... normal claim logic
}

Effectiveness: LOW

• Does not prevent front-running - beneficiaries can still claim during the announcement period
• The delay period gives beneficiaries more time to extract tokens, potentially increasing risk
• Only benefit is transparency: beneficiaries are notified of impending revocation

Drawback:

• Provides no security benefit over the current system
• May actually increase risk by giving beneficiaries advance notice

Variant C: Rate-Limit Claims During Announcement Period

pub fn announce_revocation(env: Env, vault_id: u64, delay_period: u64) {
    // Mark vault as pending revocation
    vault.revocation_announced_at = env.ledger().timestamp();
    vault.revocation_delay_period = delay_period;
    vault.max_claim_per_period = calculate_rate_limit(vault);
}

pub fn claim_tokens(env: Env, vault_id: u64, claim_amount: i128) {
    // Check if revocation is announced
    if vault.revocation_announced_at > 0 {
        // Enforce rate limit
        if claim_amount > vault.max_claim_per_period {
            panic!("Claim amount exceeds rate limit during revocation period");
        }
    }
    // ... rest of claim logic
}

Effectiveness: MEDIUM

• Limits the amount beneficiaries can extract during the announcement period
• Provides partial protection by reducing extractable value
• Allows beneficiaries to claim some vested tokens (maintaining fairness)

Drawback:

• Complex to implement correctly (requires tracking claim history, time windows, rate limits)
• Still allows partial front-running (beneficiaries can extract up to the rate limit)
• Rate limit calculation is subjective and may be difficult to calibrate fairly

Trade-offs:

Comparison to Vault Freezing:

The two-step revocation process (Variant A: block claims during announcement) is functionally similar to the vault freezing mechanism but with key differences:

Similarities:

• Both require two transactions (announce/freeze, then revoke)
• Both block claims during the critical period
• Both are vulnerable to front-running of the first transaction (announcement/freeze)

Differences:

• Two-step process enforces a mandatory delay period (e.g., 24 hours), while freeze can be followed immediately by revocation
• Two-step process provides advance notice to beneficiaries (potentially more fair), while freeze can be executed without warning
• Two-step process requires contract modifications, while freeze is already implemented

Recommendation: NOT RECOMMENDED (redundant with freeze mechanism)

The two-step revocation process does not provide significant security benefits over the existing vault freezing mechanism:

• Variant A (block claims): Functionally equivalent to freeze but with mandatory delay - adds complexity without improving security
• Variant B (allow claims): Provides no security benefit and may increase risk
• Variant C (rate-limit claims): Complex to implement and only provides partial protection

The existing freeze mechanism is simpler, faster, and equally effective. If advance notice to beneficiaries is desired for fairness reasons, this can be achieved through off-chain communication rather than on-chain enforcement.

Exception: If regulatory or legal requirements mandate advance notice before revocation (e.g., employment law requiring notice periods), a two-step process may be necessary for compliance. In this case, Variant A (block claims during announcement) should be implemented.

3. Time-Locks on Claim Operations After Revocation Announcement

Description

Time-locks would introduce a mandatory delay between when a beneficiary submits a claim transaction and when the claim can be executed. The mechanism would work as follows:

1. Beneficiary calls request_claim(vault_id, claim_amount) - creates a pending claim request with a timestamp
2. System enforces a mandatory delay period (e.g., 24 hours)
3. After the delay period expires, beneficiary calls execute_claim(vault_id) to complete the claim
4. During the delay period, the administrator can observe the pending claim and freeze the vault or revoke tokens

Feasibility: FEASIBLE (requires contract modification)

Implementing time-locks on claim operations would require significant contract modifications:

Required Changes:

• Add pending_claims storage map to track pending claim requests
• Add claim_delay_period configuration parameter
• Split claim_tokens into request_claim and execute_claim functions
• Add cancel_claim_request function for beneficiaries to abort pending claims
• Modify revoke_tokens to invalidate pending claim requests
• Add cleanup logic to remove expired claim requests

Implementation Complexity: MEDIUM TO HIGH

• Estimated development effort: 3-4 days
• Testing effort: 3-4 days (including edge cases, timing scenarios, and concurrent requests)
• Gas cost increase: Moderate (additional storage for pending claims, two transactions per claim)
• Storage management: Requires cleanup of expired/completed claim requests to prevent storage bloat

Effectiveness: HIGH (for preventing front-running)

Time-locks on claim operations would effectively eliminate the front-running attack vector by giving administrators visibility into pending claims before they execute.

Strengths:

• Advance Warning: Administrators can observe pending claim requests during the delay period
• Reaction Time: The delay period (e.g., 24 hours) gives administrators ample time to freeze the vault or revoke tokens before the claim executes
• Transparent Intent: Pending claims are visible on-chain, enabling monitoring and alerting systems
• Eliminates Race Condition: The delay period removes the time pressure that enables front-running

Limitations:

• Severe User Experience Degradation: Beneficiaries must wait 24+ hours to claim vested tokens, even under normal circumstances (no revocation)
• Two Transactions Per Claim: Beneficiaries must submit two transactions (request and execute), doubling gas costs and operational complexity
• Unfair to Honest Beneficiaries: The vast majority of beneficiaries who would never attempt front-running are penalized with delays and extra costs
• Claim Request Front-Running: Beneficiaries could submit claim requests preemptively (e.g., immediately after each vesting event) to avoid delays, creating storage bloat
• Complexity: Managing pending claims, expiration, cancellation, and cleanup adds significant complexity to the contract
• Gas Costs: Storing and managing pending claims increases gas costs for all claim operations

Trade-offs:

Effectiveness Assessment:

Comparison to Vault Freezing:

Time-locks on claims provide stronger protection against front-running but at a severe cost to user experience:

Security Comparison:

• Time-locks: Proactive defense - prevents front-running by design
• Freeze mechanism: Reactive defense - requires administrator action to prevent front-running

User Experience Comparison:

• Time-locks: All beneficiaries experience delays on every claim, regardless of whether revocation is occurring
• Freeze mechanism: Only affects beneficiaries whose vaults are being revoked (rare event)

Fairness Comparison:

• Time-locks: Punishes all users (including honest beneficiaries) to prevent a rare attack
• Freeze mechanism: Only affects users involved in revocation scenarios

Recommendation: NOT RECOMMENDED (disproportionate impact on user experience)

Time-locks on claim operations provide strong security guarantees but impose unacceptable costs on user experience:

Why Not Recommended:

1. Disproportionate Impact: The vast majority of claims occur under normal circumstances (no revocation). Imposing 24+ hour delays on all claims to prevent a rare attack is not justified.
2. User Experience Degradation: Beneficiaries expect to claim vested tokens instantly. A 24-hour delay would significantly degrade the user experience and may violate user expectations.
3. Redundant with Freeze: The existing freeze mechanism provides adequate protection when used correctly, without imposing delays on normal operations.
4. Implementation Complexity: The added complexity of managing pending claims, expiration, and cleanup is not justified given the availability of simpler alternatives.
5. Gas Cost Increase: Doubling the number of transactions (and gas costs) for every claim operation is a significant burden on users.

Alternative Approach: If advance warning of claims is desired, consider implementing optional claim announcements rather than mandatory time-locks:

• Beneficiaries can optionally announce claims in advance (e.g., for large amounts) to demonstrate good faith
• Administrators can monitor for unannounced large claims as a potential front-running signal
• This preserves instant claims for normal operations while providing transparency for high-risk scenarios

Exception: If the vesting vault system is used in a high-security context where front-running risk is extremely high (e.g., vesting of governance tokens with significant voting power), time-locks may be justified despite the user experience cost. In this case, the delay period should be as short as possible (e.g., 1-6 hours) to balance security and usability.

Summary: Technical Countermeasure Comparison

Overall Recommendation:

The vault freezing mechanism is the optimal technical countermeasure for preventing revocation front-running:

• It is already implemented and requires no additional development effort
• It provides high effectiveness when used according to proper operational procedures
• It does not degrade user experience for normal claim operations
• It imposes costs (two transactions, operational complexity) only on administrators during revocation scenarios, not on all users

Administrators should focus on:

1. Operational Discipline: Always freeze vaults before revoking, and wait for freeze confirmation
2. Monitoring: Implement mempool monitoring to detect competing claim transactions during the freeze window
3. Preemptive Freezing: Consider freezing vaults preemptively for high-risk beneficiaries (e.g., employees under performance review or termination proceedings)
4. Off-Chain Coordination: When possible, coordinate with beneficiaries off-chain to avoid adversarial scenarios

The two-step revocation and time-lock approaches do not provide sufficient additional security benefits to justify their implementation costs and user experience impacts.

Operational Procedures to Minimize Attack Windows

While the vault freezing mechanism provides strong technical protection, operational procedures are essential to minimize the attack window and ensure the freeze mechanism is used effectively.

1. Pre-Revocation Preparation

Before initiating any revocation, administrators should:

• Assess Vault State: Review the vault's vested and unvested token balances to understand the extractable value at risk

  • Query vault state: vault.total_amount, vault.released_amount, current vested amount
  • Calculate extractable value: (vested_amount - released_amount) × token_price
  • Prioritize high-value vaults for additional security measures

• Review Claim History: Check the beneficiary's claim patterns to assess front-running risk

  • Beneficiaries who claim regularly have lower vault balances (lower risk)
  • Beneficiaries who never claim may have accumulated large balances (higher risk)
  • Unusual claim patterns (e.g., sudden large claims) may indicate mempool monitoring capability

• Verify Beneficiary Status: Confirm the revocation is necessary and authorized

  • Employment termination documentation
  • Contract breach evidence
  • Legal authorization for revocation

• Prepare Transaction Infrastructure: Ensure reliable transaction submission capability

  • Verify administrator account has sufficient balance for gas fees
  • Test transaction submission infrastructure (if using automated tools)
  • Have backup transaction submission methods available (e.g., multiple RPC endpoints)

2. Freeze-Then-Revoke Procedure (CRITICAL)

The freeze-then-revoke procedure is the core operational security measure. Administrators MUST follow this sequence:

Step 1: Submit Freeze Transaction

Action: Call freeze_vault(vault_id)
Timing: Immediate
Gas Fee: Standard fee (no need to overpay)

Step 2: Wait for Freeze Confirmation

Action: Monitor ledger for freeze transaction inclusion
Timing: Wait at least 1 ledger close period (~5 seconds)
Verification: Query vault state to confirm is_frozen = true
CRITICAL: Do NOT proceed to Step 3 until freeze is confirmed

Step 3: Submit Revocation Transaction

Action: Call revoke_tokens(vault_id)
Timing: After freeze confirmation
Gas Fee: Standard fee (no need to overpay)

Step 4: Verify Revocation Success

Action: Monitor ledger for revocation transaction inclusion
Verification: Query vault state to confirm released_amount = total_amount
Result: Unvested tokens returned to administrator balance

Common Mistakes to Avoid:

• ❌ Submitting freeze and revoke in the same transaction batch: This creates a race condition - both transactions may be included in the same ledger, and if revoke executes before freeze, the attack window remains open
• ❌ Not waiting for freeze confirmation: If you submit revoke before freeze is confirmed, the beneficiary can still claim during the window
• ❌ Revoking without freezing: This leaves the full attack window open - the beneficiary has ~50% probability of front-running success

Timing Considerations:

• Minimum safe delay between freeze and revoke: 1 ledger close period (~5 seconds)
• Recommended delay: 2-3 ledger close periods (~10-15 seconds) to account for network variability
• During network congestion: Wait for explicit confirmation rather than relying on time estimates

3. Mempool Monitoring During Freeze Window

During the critical window between freeze submission and revocation execution, administrators should monitor for competing claim transactions:

Monitoring Approach:

• Manual Monitoring: Use Stellar block explorers or mempool monitoring tools to observe pending transactions

  • Look for claim_tokens transactions targeting the vault being revoked
  • If detected, the beneficiary is attempting to front-run the freeze

• Automated Monitoring: Implement automated alerts for claim transactions on target vaults

  • Subscribe to mempool feeds or transaction streams
  • Filter for transactions calling claim_tokens with the target vault_id
  • Alert administrators immediately if a competing claim is detected

Response to Detected Front-Running Attempt:

• If a claim transaction is detected in the mempool before freeze confirmation:

  • Do NOT panic - the freeze transaction is already submitted and will likely be confirmed first
  • Monitor which transaction is included in the next ledger
  • If freeze is confirmed first, the claim will fail - proceed with revocation
  • If claim is confirmed first, the beneficiary has extracted vested tokens - proceed with revocation to recover unvested tokens

• If a claim transaction is detected after freeze confirmation:

  • The claim will fail due to the freeze - no action needed
  • Proceed with revocation as planned

4. Preemptive Freezing for High-Risk Scenarios

In certain high-risk scenarios, administrators may choose to freeze vaults preemptively before a revocation decision is finalized:

When to Consider Preemptive Freezing:

• Employment Termination Proceedings: When an employee is under performance review or termination proceedings, freeze their vault to prevent front-running if termination occurs
• High-Value Vaults: Vaults with extractable value exceeding a risk threshold (e.g., $100,000+)
• Suspicious Activity: Beneficiaries who demonstrate mempool monitoring capability or unusual claim patterns
• Legal Disputes: When a beneficiary is involved in legal disputes with the organization

Trade-offs of Preemptive Freezing:

• Benefit: Eliminates the freeze front-running window - the vault is already frozen when revocation is decided
• Cost: Prevents legitimate claims by the beneficiary during the freeze period
• Legal Risk: May be challenged as improper restriction of vested token access
• Recommendation: Only use preemptive freezing when revocation is highly likely and the risk justifies restricting beneficiary access

5. Timing Revocations to Minimize Risk

The timing of revocation relative to the vesting schedule significantly affects the extractable value:

Optimal Timing Strategies:

• Revoke Early in Vesting Period: Shortly after employment termination or contract breach, when few tokens have vested

  • Example: If termination occurs 6 months into a 4-year vesting schedule, only ~12.5% of tokens have vested
  • Lower extractable value reduces the beneficiary's incentive to front-run

• Revoke Immediately After Vesting Events: If the vesting schedule has discrete vesting events (e.g., quarterly vesting), revoke shortly after a vesting event when the beneficiary is likely to have already claimed

  • Beneficiaries often claim immediately after vesting events
  • Vault balance is lower after claims, reducing extractable value

• Avoid Revoking Before Major Vesting Events: If a large vesting event (e.g., cliff vesting) is imminent, consider waiting until after the event if the beneficiary is likely to claim

  • Example: If 25% of tokens vest at a 1-year cliff, and the beneficiary typically claims immediately, wait until after the cliff and their claim before revoking
  • This reduces the vault balance and extractable value

Timing Trade-offs:

• Early Revocation: Lower extractable value (lower risk) but may be perceived as unfair if termination is disputed
• Delayed Revocation: Higher extractable value (higher risk) but may allow beneficiary to claim vested tokens they are entitled to
• Recommendation: Revoke as soon as the decision is finalized and authorized, prioritizing security over timing optimization

6. Off-Chain Coordination and Communication

In many cases, off-chain coordination with the beneficiary can eliminate the adversarial scenario entirely:

Coordination Strategies:

• Advance Notice: Inform the beneficiary of the impending revocation and coordinate the timing

  • Beneficiary can claim vested tokens before revocation (if entitled)
  • Administrator can revoke unvested tokens without competition
  • Eliminates the need for freezing and reduces transaction costs

• Mutual Agreement: Negotiate a settlement where the beneficiary agrees not to claim during the revocation window

  • May involve legal agreements or employment termination settlements
  • Reduces operational complexity and potential disputes

• Scheduled Revocation Windows: Establish regular revocation windows (e.g., monthly) where beneficiaries are notified in advance

  • Beneficiaries can claim vested tokens before the window
  • Administrators can revoke unvested tokens during the window without surprise
  • Reduces the adversarial nature of revocations

When Off-Chain Coordination is Not Feasible:

• Adversarial terminations (e.g., termination for cause, legal disputes)
• Beneficiaries who are unresponsive or uncooperative
• Emergency revocations (e.g., security breaches, fraud)
• In these cases, rely on the freeze-then-revoke procedure and operational security measures

7. Post-Revocation Verification

After completing the revocation, administrators should verify the outcome:

Verification Steps:

• Confirm Revocation Success: Query vault state to verify released_amount = total_amount
• Verify Token Transfer: Confirm unvested tokens were transferred to administrator balance
• Check for Failed Claim Attempts: Review transaction history for failed claim attempts during the freeze window
• Document the Revocation: Record the revocation details for audit and compliance purposes
  • Vault ID, beneficiary address, revoked amount, timestamp
  • Any front-running attempts detected
  • Freeze and revocation transaction hashes

Administrative Controls Where Technical Mitigations Are Unavailable

In scenarios where technical mitigations (vault freezing) are not available or not feasible, administrative controls provide an alternative layer of protection:

1. Policy-Based Controls

Vesting Agreement Clauses:

• Include clauses in vesting agreements that address front-running behavior
  • Define front-running as a breach of contract
  • Specify penalties for front-running attempts (e.g., forfeiture of vested tokens, legal liability)
  • Require beneficiaries to acknowledge the clause and agree to cooperate during revocations

Revocation Authorization Procedures:

• Establish clear authorization requirements for revocations
  • Multi-signature approval for high-value revocations
  • Legal review for disputed revocations
  • Documentation requirements (termination letters, breach evidence)

Beneficiary Monitoring Policies:

• Implement policies for monitoring high-risk beneficiaries
  • Regular review of vault balances and claim patterns
  • Flagging beneficiaries with unusual activity
  • Preemptive freezing authorization for high-risk cases

2. Governance-Based Controls

Multi-Signature Revocation:

• Require multiple administrator signatures for revocation transactions
  • Reduces the risk of unauthorized or premature revocations
  • Provides additional review and oversight
  • Trade-off: Increases coordination complexity and time to execute

Revocation Review Board:

• Establish a review board that must approve revocations
  • Board reviews the justification, vault state, and risk assessment
  • Board authorizes the revocation and freeze procedure
  • Provides accountability and reduces arbitrary revocations

Time-Delayed Governance:

• Implement governance delays for revocation policy changes
  • Changes to revocation procedures must be announced in advance
  • Beneficiaries have time to review and respond to policy changes
  • Reduces surprise and adversarial scenarios

3. Monitoring and Alerting Controls

Vault Balance Monitoring:

• Implement automated monitoring of vault balances
  • Alert administrators when vault balances exceed risk thresholds
  • Track vesting progress and predict future extractable value
  • Prioritize high-value vaults for additional security measures

Mempool Monitoring:

• Deploy mempool monitoring infrastructure to detect claim transactions
  • Real-time alerts for claim transactions on monitored vaults
  • Automated response triggers (e.g., submit freeze transaction)
  • Historical analysis of claim patterns to identify suspicious behavior

Beneficiary Activity Monitoring:

• Track beneficiary claim patterns and account activity
  • Identify beneficiaries who claim regularly (lower risk)
  • Flag beneficiaries who never claim (higher risk - accumulated balance)
  • Detect unusual claim patterns (e.g., sudden large claims, claims immediately after vesting events)

4. Legal and Compliance Controls

Legal Agreements:

• Include front-running provisions in employment contracts or vesting agreements
  • Define front-running as a breach of contract
  • Specify remedies and penalties
  • Require beneficiaries to cooperate during revocations

Regulatory Compliance:

• Ensure revocation procedures comply with applicable regulations
  • Employment law requirements (e.g., notice periods, severance)
  • Securities regulations (if tokens are securities)
  • Data protection and privacy regulations

Dispute Resolution Procedures:

• Establish clear procedures for resolving revocation disputes
  • Mediation or arbitration clauses
  • Appeals process for beneficiaries
  • Documentation and evidence requirements

5. Insurance and Risk Transfer

Revocation Insurance:

• Consider insurance products that cover losses from front-running attacks
  • Policies that reimburse the organization for extracted tokens
  • Coverage for legal costs related to front-running disputes
  • Trade-off: Insurance premiums vs. risk exposure

Risk Pooling:

• Participate in risk pooling arrangements with other organizations
  • Shared insurance or mutual aid agreements
  • Collective bargaining for better insurance terms
  • Knowledge sharing on front-running prevention

6. Fallback Procedures When Freeze is Unavailable

If the vault freezing mechanism is not available (e.g., older contract versions, technical issues), administrators must rely on alternative procedures:

Rapid Revocation Procedure:

• Submit revocation transaction with higher gas fee during surge pricing mode
  • Increases probability of inclusion in the current ledger
  • Does not guarantee execution order within the ledger (still ~50% probability)
  • Trade-off: Higher gas costs vs. slightly improved odds

Coordinated Revocation:

• Coordinate with beneficiary off-chain to avoid adversarial scenario
  • Negotiate timing of revocation
  • Allow beneficiary to claim vested tokens first (if entitled)
  • Reduces conflict and eliminates front-running risk

Accept the Risk:

• In low-value scenarios, accept the front-running risk as a cost of doing business
  • If extractable value is low (e.g., < $1,000), the risk may not justify complex procedures
  • Focus operational efforts on high-value revocations
  • Document the risk acceptance decision for audit purposes

Summary: Layered Defense Strategy

Effective mitigation of revocation front-running requires a layered defense strategy combining technical, operational, and administrative controls:

Layer 1: Technical Controls (Primary Defense)

• Vault freezing mechanism (freeze-then-revoke procedure)
• Mempool monitoring and automated alerts

Layer 2: Operational Controls (Supporting Defense)

• Pre-revocation preparation and risk assessment
• Proper freeze-then-revoke procedure execution
• Timing optimization (revoke early, avoid high-risk windows)
• Off-chain coordination when feasible

Layer 3: Administrative Controls (Governance and Policy)

• Vesting agreement clauses and legal protections
• Multi-signature or governance-based revocation authorization
• Beneficiary monitoring and risk-based prioritization
• Compliance with legal and regulatory requirements

Layer 4: Risk Acceptance and Transfer

• Insurance or risk pooling for high-value scenarios
• Accept risk for low-value scenarios where mitigation costs exceed potential losses

By implementing multiple layers of defense, administrators can significantly reduce the risk and impact of revocation front-running attacks while maintaining operational efficiency and fairness to beneficiaries.

This section provides a detailed, step-by-step procedure for administrators to safely revoke tokens from a beneficiary's vault while minimizing the risk of front-running attacks. Following these procedures will significantly reduce the attack window and protect unvested tokens.

Safe token revocation requires a multi-step approach that combines technical countermeasures (vault freezing) with operational security practices (monitoring, timing, coordination). The procedure is designed to:

1. Minimize the time window during which a beneficiary can observe and react to pending revocation transactions
2. Use the vault freeze mechanism to prevent claims during the revocation process
3. Verify successful execution and monitor for attempted front-running
4. Maintain clear documentation and audit trails for compliance and dispute resolution

Key Principle: Always freeze the vault BEFORE submitting the revocation transaction. The freeze transaction must be confirmed on-chain before proceeding with revocation.

Before initiating a token revocation, administrators should complete the following checklist to assess risk and prepare for safe execution:

1. Verify Revocation Authority and Justification

• Confirm that revocation is authorized according to the vesting agreement (e.g., employment termination, breach of contract)
• Document the reason for revocation for audit and legal purposes
• Verify that the vault is not marked as irrevocable (is_irrevocable = false)
• Ensure the administrator account has the necessary permissions to execute freeze_vault() and revoke_tokens()

2. Assess Vault State and Risk Level

• Query the vault to determine current token balances:
  • Total allocated tokens (total_amount)
  • Tokens already claimed by beneficiary (released_amount)
  • Vested tokens available for claiming (vested_amount)
  • Unvested tokens subject to revocation (unvested_amount)
• Calculate the extractable value: Extractable_Value = (vested_amount - released_amount) × token_price
• Assess risk level based on extractable value:
  • Low Risk: < $10,000 (operational procedures may be sufficient)
  • Medium Risk: $10,000 - $100,000 (follow standard procedure with monitoring)
  • High Risk: > $100,000 (follow enhanced procedure with off-chain coordination)
• Review the beneficiary's claim history to identify patterns (frequent claims reduce risk)

3. Check Beneficiary Account Activity

• Monitor the beneficiary's account for recent transaction activity
• Check if the beneficiary has submitted any transactions in the past 24 hours
• Identify if the beneficiary is running automated monitoring software (frequent transaction submissions, mempool queries)
• Note the beneficiary's typical transaction fee patterns (higher fees may indicate willingness to compete during surge pricing)

4. Assess Network Conditions

• Check current Stellar network status and ledger close times (target: ~5 seconds)
• Verify if the network is in surge pricing mode (high transaction volume)
• If surge pricing is active, consider waiting for normal operation or prepare to submit higher fees for the freeze transaction
• Check mempool congestion levels to estimate transaction confirmation times

5. Prepare Transaction Parameters

• Identify the vault ID to be revoked
• Prepare the freeze transaction: freeze_vault(vault_id)
• Prepare the revocation transaction: revoke_tokens(vault_id)
• Set appropriate transaction fees:
  • Freeze transaction: Use standard fee during normal operation, higher fee during surge pricing
  • Revocation transaction: Use standard fee (freeze provides protection regardless of fee)
• Configure transaction submission tools and ensure reliable network connectivity

6. Consider Off-Chain Coordination (High-Risk Scenarios)

• For high-value vaults (> $100,000), consider contacting the beneficiary off-chain before revocation
• Negotiate a mutually agreed revocation time to avoid adversarial behavior
• Document any agreements or communications for legal purposes
• If coordination is not possible or appropriate, proceed with the standard procedure

7. Prepare Monitoring and Response Tools

• Set up mempool monitoring to observe pending transactions
• Prepare scripts or tools to quickly query vault state after revocation
• Ensure access to emergency response procedures in case front-running is detected
• Notify relevant stakeholders (legal, finance, security teams) of the planned revocation

Follow these steps in order to safely revoke tokens from a beneficiary's vault:

Phase 1: Freeze the Vault

Step 1: Submit Freeze Transaction

• Submit the freeze_vault(vault_id) transaction to the Stellar network
• Use appropriate transaction fees based on network conditions:
  • Normal operation: Standard fee (100 stroops)
  • Surge pricing: Higher fee to ensure timely inclusion (500-1000 stroops)
• Record the transaction hash and submission timestamp for audit purposes
• Critical: Do NOT submit the revocation transaction yet

Step 2: Monitor Freeze Transaction Confirmation

• Monitor the mempool and ledger for the freeze transaction
• Wait for the freeze transaction to be included in a closed ledger (typically 5-6 seconds)
• Verify the transaction status: SUCCESS (not FAILED or PENDING)
• Warning: If the freeze transaction fails, investigate the cause before proceeding:
  • Common causes: Vault already frozen, vault does not exist, insufficient authorization
  • Do NOT proceed with revocation until the freeze issue is resolved

Step 3: Verify Vault is Frozen

• Query the vault state to confirm is_frozen = true
• Verify the freeze timestamp matches the expected ledger close time
• Check for any claim transactions submitted between freeze submission and confirmation:
  • If a claim transaction was submitted before the freeze, it may have succeeded
  • Query the vault's released_amount to check if any tokens were claimed
  • Recalculate the extractable value based on the updated vault state
• Checkpoint: Vault must be confirmed frozen before proceeding to Phase 2

Phase 2: Execute Revocation

Step 4: Wait for Freeze Confirmation (Recommended Delay)

• After confirming the vault is frozen, wait an additional 10-30 seconds before submitting the revocation
• This delay ensures:
  • The freeze state is propagated across all network nodes
  • Any pending claim transactions have been processed and failed
  • The beneficiary has time to observe the freeze and understand that claims are blocked
• During this delay, monitor for any attempted claim transactions (they should fail with "Vault is frozen")

Step 5: Submit Revocation Transaction

• Submit the revoke_tokens(vault_id) transaction to the Stellar network
• Use standard transaction fees (the freeze provides protection, so fee competition is unnecessary)
• Record the transaction hash and submission timestamp
• Note: The revocation transaction is now visible in the mempool, but the vault is frozen, so the beneficiary cannot front-run

Step 6: Monitor Revocation Transaction Confirmation

• Monitor the mempool and ledger for the revocation transaction
• Wait for the revocation transaction to be included in a closed ledger (typically 5-6 seconds)
• Verify the transaction status: SUCCESS (not FAILED or PENDING)
• Warning: If the revocation transaction fails, investigate the cause:
  • Common causes: Vault is irrevocable, no unvested tokens remain, insufficient authorization
  • The vault remains frozen; you can retry the revocation or unfreeze the vault

Step 7: Verify Revocation Success

• Query the vault state to confirm the revocation was successful:
  • released_amount should equal total_amount (all tokens marked as released)
  • Administrator balance should have increased by the unvested token amount
  • Vault should still be frozen (is_frozen = true)
• Calculate the actual tokens revoked: revoked_amount = total_amount - released_amount_before_revocation
• Compare the revoked amount to the expected unvested amount:
  • If they match, the revocation was successful
  • If they differ, investigate whether the beneficiary claimed tokens before the freeze

Phase 3: Post-Revocation Actions

Step 8: Decide Whether to Unfreeze the Vault

• Determine if the vault should remain frozen or be unfrozen:
  • Keep Frozen: If no vested tokens remain or if you want to prevent any future claims
  • Unfreeze: If vested tokens remain and the beneficiary should be allowed to claim them
• If unfreezing, submit the unfreeze_vault(vault_id) transaction
• Verify the unfreeze transaction is confirmed and is_frozen = false
• Note: In most revocation scenarios, the vault can remain frozen indefinitely since all unvested tokens have been reclaimed

Step 9: Document the Revocation

• Record all transaction details in the organization's audit log:
  • Freeze transaction hash and timestamp
  • Revocation transaction hash and timestamp
  • Unfreeze transaction hash and timestamp (if applicable)
  • Vault ID and beneficiary address
  • Amount of tokens revoked
  • Reason for revocation
  • Any attempted front-running or claim transactions observed
• Notify relevant stakeholders (legal, finance, HR) of the completed revocation
• Update internal records to reflect the beneficiary's final token allocation

Step 10: Monitor for Post-Revocation Activity

• Continue monitoring the beneficiary's account for 24-48 hours after revocation
• Watch for any attempted claim transactions (they should fail if the vault is frozen)
• Check for any dispute or communication from the beneficiary
• Be prepared to provide transaction evidence if the beneficiary contests the revocation

After completing the revocation procedure, administrators should monitor for the following activities to detect attempted front-running or other anomalies:

Immediate Monitoring (First 24 Hours)

1. Attempted Claim Transactions

   • Monitor the beneficiary's account for any claim_tokens() transactions targeting the revoked vault
   • These transactions should fail with "Vault is frozen" or "No tokens available to claim"
   • If claim attempts are observed, document the transaction hashes and timestamps
   • Frequent claim attempts may indicate the beneficiary was attempting to front-run but was blocked by the freeze

2. Mempool Activity

   • Review mempool logs (if available) to identify if the beneficiary submitted any transactions during the freeze-to-revocation window
   • Look for claim transactions submitted between the freeze submission (Step 1) and freeze confirmation (Step 2)
   • If a claim transaction was submitted before the freeze, verify whether it succeeded or failed

3. Vault State Verification

   • Periodically query the vault state to ensure it remains in the expected state:
     • is_frozen = true (if not unfrozen)
     • released_amount = total_amount (all tokens marked as released)
     • No unexpected state changes
   • If the vault state changes unexpectedly, investigate immediately

4. Administrator Balance Verification

   • Verify that the administrator's token balance increased by the expected revoked amount
   • Compare the actual balance change to the calculated unvested amount
   • If the amounts do not match, investigate whether tokens were claimed before the freeze

Ongoing Monitoring (First Week)

1. Beneficiary Communication

   • Monitor for any communication from the beneficiary regarding the revocation
   • Be prepared to provide transaction evidence and explain the revocation process
   • Document all communications for legal and compliance purposes

2. Dispute Detection

   • Watch for any on-chain or off-chain disputes raised by the beneficiary
   • Check if the beneficiary submits any transactions attempting to challenge the revocation
   • Consult legal counsel if a dispute arises

3. Network Event Logs

   • Review blockchain event logs for the vault:
     • VaultFrozen event (from freeze transaction)
     • TokensRevoked event (from revocation transaction)
     • VaultUnfrozen event (if vault was unfrozen)
     • Any TokensClaimed events (should not exist after freeze, unless they occurred before)
   • Verify that the event sequence matches the expected procedure

4. Audit Trail Completion

   • Ensure all transaction details are recorded in the organization's audit system
   • Verify that the revocation is reflected in internal accounting and HR systems
   • Prepare a summary report of the revocation for stakeholders

Red Flags and Anomalies

If any of the following anomalies are detected during monitoring, investigate immediately and consult security experts:

• Unexpected Token Balance Changes: The vault's released_amount or administrator's balance does not match expected values
• Successful Claim After Freeze: A claim transaction succeeded after the vault was frozen (indicates a potential bug or exploit)
• Freeze Transaction Failed: The freeze transaction failed unexpectedly (may indicate a race condition or authorization issue)
• Revocation Transaction Failed: The revocation transaction failed unexpectedly (may indicate vault state issues)
• High-Frequency Claim Attempts: The beneficiary submits many claim transactions in rapid succession (indicates automated front-running attempts)
• Mempool Manipulation: Evidence of unusual mempool activity or transaction reordering (may indicate advanced attack techniques)

For high-value vaults (extractable value > $100,000) or situations where the beneficiary is known to have sophisticated monitoring capabilities, consider the following enhanced procedures:

1. Off-Chain Coordination

• Contact the beneficiary off-chain (email, phone, in-person meeting) before initiating revocation
• Negotiate a mutually agreed revocation time and process
• Obtain written acknowledgment of the revocation terms
• If coordination is successful, the beneficiary is less likely to attempt front-running

2. Multi-Signature Authorization

• Use multi-signature authorization for freeze and revocation transactions to add an additional layer of security
• Require approval from multiple administrators before executing the procedure
• This reduces the risk of unauthorized or premature revocation

3. Timing Optimization

• Execute the revocation during off-peak hours (e.g., late night, weekends) when network activity is lower
• Avoid executing during known high-traffic periods (e.g., major token launches, network upgrades)
• Lower network congestion reduces the likelihood of surge pricing and fee competition

4. Redundant Monitoring

• Deploy multiple independent monitoring systems to observe mempool activity
• Use both on-chain and off-chain monitoring tools to detect attempted front-running
• Set up automated alerts for any claim transactions targeting the vault

5. Legal Preparation

• Consult legal counsel before initiating revocation for high-value vaults
• Prepare documentation of the revocation justification and authorization
• Be ready to defend the revocation in case of legal disputes

6. Staged Revocation (If Applicable)

• If the contract supports partial revocation, consider revoking tokens in multiple stages
• This reduces the extractable value in any single revocation event
• However, this approach increases operational complexity and may not be suitable for all scenarios

1. Submitting Freeze and Revocation Simultaneously

• Mistake: Submitting both transactions in the same ledger or without waiting for freeze confirmation
• Consequence: The race condition still exists; the beneficiary can front-run if their claim executes before the freeze
• Solution: Always wait for freeze confirmation before submitting the revocation

2. Not Verifying Freeze Success

• Mistake: Assuming the freeze transaction succeeded without querying the vault state
• Consequence: The vault may not be frozen, allowing the beneficiary to claim tokens
• Solution: Always query the vault state to confirm is_frozen = true before proceeding

3. Using Insufficient Transaction Fees During Surge Pricing

• Mistake: Submitting the freeze transaction with standard fees during network congestion
• Consequence: The freeze transaction may be delayed, giving the beneficiary more time to front-run
• Solution: Monitor network conditions and use higher fees during surge pricing to ensure timely freeze confirmation

4. Revoking Without Assessing Risk

• Mistake: Executing revocation without checking the vault's vested token balance or extractable value
• Consequence: Unnecessary risk exposure or wasted effort on low-risk vaults
• Solution: Always complete the pre-revocation checklist to assess risk and prioritize high-risk vaults

5. Not Monitoring Post-Revocation Activity

• Mistake: Assuming the revocation was successful without verifying the final vault state
• Consequence: Missing evidence of attempted front-running or failing to detect revocation failures
• Solution: Follow the post-revocation monitoring procedures for at least 24 hours

6. Unfreezing the Vault Prematurely

• Mistake: Unfreezing the vault immediately after revocation without considering whether vested tokens remain
• Consequence: The beneficiary can claim remaining vested tokens, which may not be intended
• Solution: Carefully decide whether to unfreeze based on the organization's policy and the vault's remaining balance

7. Not Documenting the Revocation

• Mistake: Failing to record transaction details and revocation justification
• Consequence: Lack of audit trail for compliance, disputes, or legal proceedings
• Solution: Maintain comprehensive documentation of all revocation activities

Safe token revocation requires a disciplined, multi-step approach that prioritizes the vault freeze mechanism as the primary defense against front-running. By following this procedure, administrators can:

• Eliminate the race condition by freezing the vault before submitting the revocation
• Minimize the attack window through careful timing and monitoring
• Verify successful execution by checking vault state and transaction confirmations
• Maintain audit trails for compliance and dispute resolution
• Respond to anomalies through post-revocation monitoring

Key Takeaway: The freeze-then-revoke pattern is the most effective operational security measure available. Always freeze first, verify the freeze, then revoke. Never skip the freeze step, even for low-risk vaults, as it provides strong protection with minimal operational overhead.

This section provides guidance on monitoring beneficiary account activity to detect potential front-running attempts and assess risk before initiating token revocations. Effective monitoring enables administrators to make informed decisions about revocation timing, coordination strategies, and the level of security measures required.

Monitoring beneficiary accounts before and during revocation serves several critical purposes:

1. Risk Assessment: Identify beneficiaries who are actively monitoring the blockchain and may be prepared to front-run
2. Timing Optimization: Choose revocation timing when beneficiaries are less likely to be actively monitoring
3. Evidence Collection: Document beneficiary behavior for audit trails and potential dispute resolution
4. Threat Detection: Identify automated monitoring systems or suspicious transaction patterns
5. Coordination Planning: Determine whether off-chain coordination is necessary based on beneficiary sophistication

Key Principle: Proactive monitoring before revocation is more effective than reactive detection after an attack. Understanding beneficiary behavior patterns enables better security decisions.

Before initiating a token revocation, administrators should monitor the beneficiary's account for at least 24-48 hours to establish a baseline of activity and identify potential risks.

1. Transaction Frequency Analysis

Monitor the beneficiary's account for recent transaction activity to assess their engagement level with the blockchain:

Low Activity (Low Risk)

• No transactions in the past 7 days
• Infrequent historical transactions (less than 1 per week)
• Long gaps between transactions
• Interpretation: Beneficiary is not actively monitoring their account and is unlikely to detect a pending revocation quickly
• Recommendation: Standard revocation procedure with freeze-then-revoke pattern is sufficient

Moderate Activity (Medium Risk)

• 1-5 transactions in the past 7 days
• Regular but not constant transaction activity
• Transactions occur during business hours or predictable times
• Interpretation: Beneficiary is periodically checking their account but may not have real-time monitoring
• Recommendation: Execute revocation during off-hours (nights, weekends) when beneficiary is less likely to be monitoring

High Activity (High Risk)

• Daily or multiple daily transactions
• Transactions at irregular hours (24/7 activity)
• Very short time intervals between transactions (minutes or seconds)
• Interpretation: Beneficiary may be running automated monitoring software or is highly engaged with their account
• Recommendation: Consider off-chain coordination or execute during periods of lowest activity; use enhanced monitoring during revocation

2. Transaction Type Analysis

Examine the types of transactions the beneficiary is submitting to understand their blockchain sophistication:

Simple Transactions (Lower Risk)

• Basic token transfers
• Standard claim operations
• Infrequent contract interactions
• Interpretation: Beneficiary is using basic wallet functionality and may not have advanced monitoring capabilities

Complex Transactions (Higher Risk)

• Smart contract interactions beyond basic claims
• Multi-operation transactions (batched operations)
• Transactions with custom memos or data fields
• Interactions with DeFi protocols or advanced features
• Interpretation: Beneficiary has technical sophistication and may be capable of setting up mempool monitoring

3. Transaction Fee Pattern Analysis

Analyze the fees the beneficiary pays for transactions to assess their willingness to compete during surge pricing:

Standard Fees (Lower Risk)

• Consistent use of minimum or standard transaction fees (100 stroops)
• No variation in fee amounts across transactions
• Interpretation: Beneficiary is cost-conscious and may not be willing to pay premium fees to front-run

Variable or High Fees (Higher Risk)

• Frequent use of fees above the standard minimum
• Fee amounts vary based on network conditions
• Willingness to pay 2-10x standard fees during congestion
• Interpretation: Beneficiary understands surge pricing and may be willing to compete with higher fees during front-running

4. Claim History Analysis

Review the beneficiary's historical claim transactions from their vesting vault:

Regular Claims (Lower Risk)

• Beneficiary claims vested tokens regularly (weekly, monthly)
• Vault balance is typically low due to frequent claims
• Predictable claim patterns
• Interpretation: Regular claims reduce the extractable value in the vault, lowering front-running incentive

Infrequent Claims (Higher Risk)

• Beneficiary rarely claims vested tokens
• Large vested token balance has accumulated in the vault
• No claims in the past 30+ days
• Interpretation: High extractable value creates strong incentive for front-running

No Claims (Highest Risk)

• Beneficiary has never claimed tokens despite vesting
• Maximum vested token balance in the vault
• Interpretation: Beneficiary may be waiting for a specific event (e.g., price peak, revocation attempt) to claim all tokens at once

5. Mempool Monitoring Capability Detection

Attempt to identify whether the beneficiary has mempool monitoring infrastructure:

Indicators of Mempool Monitoring

• Transactions submitted immediately after specific on-chain events (within seconds)
• Transactions that appear to respond to pending transactions in the mempool
• Use of advanced transaction features (sequence numbers, time bounds) that suggest automation
• Transactions submitted from multiple addresses in coordinated patterns

Detection Methods

• Review historical transaction timestamps for patterns of rapid response to on-chain events
• Check if the beneficiary has submitted transactions that competed with other pending transactions
• Look for evidence of automated transaction submission (consistent timing, identical transaction structures)
• Search for public information about the beneficiary's technical background or blockchain involvement

If Mempool Monitoring is Detected

• High Risk: Beneficiary is likely capable of detecting and responding to pending revocation transactions
• Recommendation: Strongly consider off-chain coordination or execute revocation with maximum security measures (freeze-then-revoke with minimal delay)

6. Off-Chain Information Gathering

Supplement on-chain monitoring with off-chain information sources:

Public Information Sources

• Social media profiles (Twitter, LinkedIn, GitHub) to assess technical sophistication
• Public statements or posts about blockchain monitoring, MEV, or front-running
• Participation in blockchain communities or developer forums
• Employment history or technical background (e.g., blockchain developer, trader, security researcher)

Internal Information Sources

• HR records indicating technical skills or blockchain experience
• IT department logs showing access to blockchain monitoring tools or services
• Previous interactions with the organization regarding vesting or token claims
• Legal or compliance records indicating disputes or adversarial behavior

Privacy and Legal Considerations

• Ensure all monitoring activities comply with privacy laws and regulations (GDPR, CCPA, etc.)
• Only collect information that is necessary for security purposes
• Document the legal basis for monitoring (e.g., legitimate interest in protecting organizational assets)
• Consult legal counsel if monitoring raises privacy concerns

During the revocation process (from freeze submission to revocation confirmation), administrators should actively monitor for attempted front-running:

1. Mempool Monitoring

If mempool monitoring tools are available, watch for any transactions submitted by the beneficiary during the critical window:

Critical Window Timeline

• T=0: Administrator submits freeze transaction
• T=0 to T=5 seconds: Freeze transaction is pending in mempool (vulnerable window)
• T=5 seconds: Freeze transaction confirmed in ledger (vault is now frozen)
• T=5 to T=35 seconds: Recommended delay before submitting revocation
• T=35 seconds: Administrator submits revocation transaction
• T=35 to T=40 seconds: Revocation transaction is pending in mempool
• T=40 seconds: Revocation transaction confirmed in ledger

What to Watch For

• Any claim_tokens() transactions submitted by the beneficiary during the T=0 to T=5 window
• Transactions with higher fees than the freeze transaction (indicates fee competition)
• Multiple claim attempts in rapid succession (indicates automated response)

Response Actions

• If a claim transaction is detected before freeze confirmation (T=0 to T=5):
  • Do NOT panic - the freeze may still execute first due to pseudo-random ordering
  • Monitor which transaction executes first in the ledger
  • If freeze executes first: Proceed with revocation as planned
  • If claim executes first: Follow emergency response procedures (see Emergency Response section)
• If a claim transaction is detected after freeze confirmation (T>5):
  • The claim should fail with "Vault is frozen"
  • Document the attempted front-running for audit purposes
  • Proceed with revocation as planned

2. Ledger Monitoring

Monitor the Stellar ledger in real-time to verify transaction inclusion and execution order:

Tools and Methods

• Use Stellar Horizon API to query recent ledgers and transactions
• Subscribe to ledger close events via WebSocket or streaming endpoints
• Use blockchain explorers (e.g., StellarExpert, Stellar.Expert) for visual monitoring
• Set up automated alerts for transactions involving the target vault

Key Metrics to Track

• Ledger close times (should be ~5 seconds)
• Transaction inclusion status (pending, confirmed, failed)
• Execution order of freeze, claim, and revocation transactions
• Transaction fees paid by administrator and beneficiary

3. Vault State Monitoring

Continuously query the vault state during the revocation process to detect unexpected changes:

State Checkpoints

• Before Freeze: Record initial vault state (vested amount, released amount, is_frozen status)
• After Freeze Confirmation: Verify is_frozen = true and no change in released amount
• After Revocation Confirmation: Verify released_amount = total_amount and tokens transferred to administrator

Anomaly Detection

• If released_amount increases between freeze submission and freeze confirmation: A claim transaction executed before the freeze
• If is_frozen does not change to true after freeze confirmation: Freeze transaction failed
• If released_amount does not equal total_amount after revocation: Revocation transaction failed or was partial

4. Automated Alerting

Set up automated alerts to notify administrators of critical events during revocation:

Alert Triggers

• Beneficiary submits any transaction during the critical window
• Freeze transaction fails or is delayed beyond expected confirmation time
• Claim transaction is detected in the mempool before freeze confirmation
• Vault state changes unexpectedly
• Revocation transaction fails or is delayed

Alert Channels

• Email notifications to security team
• SMS or push notifications for high-priority alerts
• Slack or other team communication tools
• Automated logging to security information and event management (SIEM) systems

After the revocation is complete, continue monitoring for 24-48 hours to detect attempted front-running or disputes:

1. Failed Claim Attempt Detection

Monitor for any claim transactions submitted by the beneficiary after the vault is frozen:

What to Look For

• claim_tokens() transactions that fail with "Vault is frozen" error
• Multiple failed claim attempts in rapid succession
• Claim attempts with varying fee amounts (indicates desperation or testing)

Interpretation

• Failed claim attempts indicate the beneficiary attempted to front-run but was blocked by the freeze
• Multiple attempts suggest automated monitoring software was running
• Document all failed attempts for audit purposes and potential legal proceedings

2. Dispute Indicators

Watch for signs that the beneficiary may dispute the revocation:

On-Chain Indicators

• Transactions attempting to interact with the vault in unusual ways
• Transactions with custom memos or data fields that may contain dispute messages
• Attempts to call administrative functions (will fail due to authorization checks)

Off-Chain Indicators

• Communication from the beneficiary questioning the revocation
• Legal notices or formal dispute filings
• Social media posts or public statements about the revocation
• Contact with regulatory authorities or blockchain governance bodies

Response Actions

• Document all dispute indicators and preserve evidence
• Consult legal counsel before responding to disputes
• Prepare transaction evidence (hashes, timestamps, vault state snapshots) for potential legal proceedings
• Review the revocation justification and ensure it complies with vesting agreement terms

3. Audit Trail Completion

Finalize the monitoring documentation for compliance and audit purposes:

Required Documentation

• Pre-revocation monitoring summary (beneficiary activity patterns, risk assessment)
• Real-time monitoring logs (mempool observations, ledger events, vault state changes)
• Post-revocation monitoring summary (failed claim attempts, dispute indicators)
• Transaction evidence (hashes, timestamps, fees, execution order)
• Decision rationale (why revocation was necessary, why specific timing was chosen)

Retention and Access

• Store monitoring documentation in secure, tamper-proof storage
• Ensure documentation is accessible to legal, compliance, and audit teams
• Retain documentation for the period required by organizational policy and legal regulations
• Implement access controls to protect sensitive beneficiary information

To effectively monitor beneficiary activity and detect front-running attempts, administrators should consider deploying the following tools and infrastructure:

1. Blockchain Monitoring Services

Commercial Services

• Blockchain analytics platforms (e.g., Chainalysis, Elliptic, TRM Labs) for transaction tracking
• Mempool monitoring services (if available for Stellar/Soroban)
• Real-time alerting services for on-chain events

Open-Source Tools

• Stellar Horizon API for querying ledgers and transactions
• Custom scripts using Stellar SDK (JavaScript, Python, Rust) for automated monitoring
• Blockchain explorers (StellarExpert, Stellar.Expert) for manual monitoring

2. Automated Monitoring Scripts

Develop custom scripts to automate monitoring tasks:

Pre-Revocation Monitoring Script

### Pseudocode example for monitoring beneficiary activity
def monitor_beneficiary_activity(beneficiary_address, days=7):
    transactions = fetch_transactions(beneficiary_address, days)
    
    # Analyze transaction frequency
    frequency = len(transactions) / days
    
    # Analyze transaction types
    complex_tx_count = count_complex_transactions(transactions)
    
    # Analyze fee patterns
    avg_fee = calculate_average_fee(transactions)
    max_fee = calculate_max_fee(transactions)
    
    # Generate risk assessment
    risk_level = assess_risk(frequency, complex_tx_count, avg_fee, max_fee)
    
    return {
        "frequency": frequency,
        "risk_level": risk_level,
        "recommendation": generate_recommendation(risk_level)
    }

Real-Time Monitoring Script

### Pseudocode example for real-time monitoring
def monitor_revocation_process(vault_id, beneficiary_address):
    # Subscribe to ledger close events
    subscribe_to_ledger_events()
    
    # Monitor for beneficiary transactions
    while revocation_in_progress:
        pending_txs = fetch_mempool_transactions(beneficiary_address)
        
        for tx in pending_txs:
            if is_claim_transaction(tx, vault_id):
                alert("Claim transaction detected in mempool!")
                log_transaction(tx)
        
        # Check vault state
        vault_state = fetch_vault_state(vault_id)
        if vault_state_changed_unexpectedly(vault_state):
            alert("Vault state changed unexpectedly!")
        
        sleep(1)  # Check every second

3. Alerting Infrastructure

Set up automated alerting to notify administrators of critical events:

Alert Configuration

• Define alert severity levels (info, warning, critical)
• Configure notification channels (email, SMS, Slack, PagerDuty)
• Set up escalation policies for unacknowledged alerts
• Implement rate limiting to prevent alert fatigue

Alert Types

• Info: Beneficiary submitted a transaction (routine activity)
• Warning: Beneficiary submitted a claim transaction during monitoring period
• Critical: Claim transaction detected in mempool during freeze-to-revocation window

4. Dashboard and Visualization

Create a monitoring dashboard for real-time visibility:

Dashboard Components

• Beneficiary activity timeline (transaction history, frequency chart)
• Vault state display (vested amount, unvested amount, freeze status)
• Real-time transaction feed (pending and confirmed transactions)
• Risk assessment summary (risk level, recommendations)
• Alert history and status

Dashboard Tools

• Grafana or Kibana for visualization
• Custom web dashboard using Stellar SDK and charting libraries
• Blockchain explorer integrations for quick reference

For high-risk revocations or situations where off-chain coordination is appropriate, administrators should consider the following strategies:

1. When to Consider Off-Chain Coordination

Off-chain coordination (communicating with the beneficiary before revocation) may be appropriate in the following scenarios:

High-Value Vaults

• Extractable value exceeds $100,000
• Potential legal or reputational consequences of adversarial revocation
• Organization prefers cooperative approach to minimize conflict

Sophisticated Beneficiaries

• Beneficiary has demonstrated technical sophistication (blockchain developer, trader, security researcher)
• Evidence of mempool monitoring capability
• History of adversarial behavior or disputes with the organization

Legal or Compliance Requirements

• Vesting agreement requires notice before revocation
• Regulatory requirements mandate beneficiary notification
• Employment law requires advance notice of benefit changes

Organizational Policy

• Company culture emphasizes transparency and cooperation
• HR policy requires communication before terminating benefits
• Risk management policy prioritizes dispute avoidance over surprise revocations

2. Off-Chain Communication Methods

Choose communication methods based on urgency, formality, and documentation requirements:

Formal Written Communication

• Email: Provides written record, suitable for most scenarios
• Registered Mail: Provides proof of delivery, suitable for legal requirements
• Legal Notice: Formal notification through legal counsel, suitable for disputes

Informal Communication

• Phone Call: Allows real-time discussion, suitable for cooperative beneficiaries
• Video Conference: Enables face-to-face conversation, suitable for complex situations
• In-Person Meeting: Highest level of engagement, suitable for high-value or sensitive revocations

Communication Timing

• Advance Notice: Notify beneficiary days or weeks before revocation (suitable for cooperative scenarios)
• Same-Day Notice: Notify beneficiary hours before revocation (suitable for time-sensitive scenarios)
• Immediate Notice: Notify beneficiary minutes before revocation (suitable for emergency scenarios)

3. Coordination Negotiation Strategies

When coordinating with the beneficiary, consider the following negotiation approaches:

Cooperative Approach

• Explain the reason for revocation (e.g., employment termination, contract breach)
• Acknowledge the beneficiary's right to claim vested tokens
• Propose a mutually agreed revocation time (e.g., "We will revoke unvested tokens at 3:00 PM today")
• Offer to unfreeze the vault after revocation so the beneficiary can claim vested tokens
• Document the agreement in writing

Incentivized Approach

• Offer the beneficiary an incentive to cooperate (e.g., extended claim period, partial vested token retention)
• Negotiate a settlement that avoids adversarial behavior
• Use financial incentives to align interests (e.g., "If you agree not to front-run, we will allow you to claim vested tokens over the next 30 days")

Firm Approach

• Clearly state the organization's intent to revoke unvested tokens
• Inform the beneficiary that the vault will be frozen to prevent front-running
• Emphasize that vested tokens will remain claimable after revocation (if applicable)
• Set clear expectations and timelines

4. Coordination Documentation

Document all off-chain coordination activities for legal and compliance purposes:

Required Documentation

• Communication records (emails, call logs, meeting notes)
• Agreements or acknowledgments from the beneficiary
• Timestamps of all communications
• Names and roles of all participants
• Summary of negotiation outcomes

Legal Considerations

• Ensure all communications comply with employment law and contract terms
• Avoid making promises or commitments that are not authorized
• Consult legal counsel before making binding agreements
• Preserve all documentation for potential disputes or audits

5. When NOT to Coordinate

Off-chain coordination is not appropriate in all scenarios. Avoid coordination in the following situations:

Adversarial Beneficiaries

• Beneficiary has a history of disputes or adversarial behavior
• Beneficiary has threatened legal action or made hostile statements
• Beneficiary is unresponsive or refuses to communicate

Time-Sensitive Revocations

• Immediate revocation is required due to security concerns (e.g., beneficiary is suspected of fraud)
• Legal or regulatory requirements mandate immediate action
• Delay would significantly increase risk or financial exposure

Confidentiality Requirements

• Revocation is part of a confidential investigation
• Disclosure to the beneficiary would compromise security or legal proceedings
• Organizational policy prohibits advance notice

Operational Efficiency

• Low-value vaults where coordination overhead is not justified
• Routine revocations where standard procedures are sufficient
• Beneficiary is unlikely to front-run based on monitoring assessment

Effective monitoring and coordination strategies enable administrators to:

• Assess risk by understanding beneficiary behavior patterns and technical sophistication
• Optimize timing by executing revocations when beneficiaries are less likely to be monitoring
• Detect threats by identifying mempool monitoring capabilities and automated systems
• Coordinate proactively by communicating with beneficiaries when appropriate to avoid adversarial behavior
• Respond quickly by using real-time monitoring and automated alerting during revocation
• Document thoroughly by maintaining comprehensive audit trails for compliance and dispute resolution

Key Recommendations:

1. Always monitor beneficiary activity for 24-48 hours before revocation to establish a baseline and assess risk
2. Use real-time monitoring during the freeze-to-revocation window to detect attempted front-running
3. Consider off-chain coordination for high-value vaults or sophisticated beneficiaries to minimize conflict
4. Deploy automated monitoring tools and alerting infrastructure to improve detection and response times
5. Document all monitoring and coordination activities for legal, compliance, and audit purposes

By combining proactive monitoring with strategic coordination, administrators can significantly reduce the risk and impact of revocation front-running attacks while maintaining operational efficiency and fairness to beneficiaries.

This section provides procedures for responding to detected or suspected front-running attacks. While the freeze-then-revoke pattern should prevent most front-running attempts, administrators must be prepared to respond quickly if a beneficiary successfully claims tokens before the vault can be frozen or if other anomalies occur during the revocation process.

Emergency response procedures should be activated when any of the following conditions are detected:

1. Successful Front-Running (Claim Before Freeze)

• A beneficiary's claim transaction executes before the administrator's freeze transaction
• Vested tokens are extracted from the vault before the revocation can be completed
• The vault's released_amount increases between freeze submission and freeze confirmation

2. Freeze Transaction Failure

• The freeze transaction fails unexpectedly (e.g., due to authorization issues, vault state problems)
• The freeze transaction is delayed beyond the expected confirmation time (>10 seconds)
• The vault remains unfrozen (is_frozen = false) after freeze transaction submission

3. Revocation Transaction Failure

• The revocation transaction fails unexpectedly after the vault is frozen
• The revocation transaction is delayed or stuck in the mempool
• The vault state does not update as expected after revocation submission

4. Unexpected Vault State Changes

• The vault's released_amount changes unexpectedly during the revocation process
• The vault's is_frozen status changes without administrator action
• Tokens are transferred from the vault to unexpected addresses

5. Multiple Rapid Claim Attempts

• The beneficiary submits multiple claim transactions in rapid succession (indicates automated front-running)
• Claim transactions with escalating fees (indicates fee competition during surge pricing)
• Claim transactions submitted within seconds of freeze transaction submission

6. Mempool Manipulation or Anomalies

• Evidence of unusual mempool activity (e.g., transaction reordering, delayed inclusion)
• Transactions with suspicious parameters (e.g., unusual time bounds, sequence numbers)
• Coordinated activity from multiple addresses targeting the same vault

When emergency conditions are detected, follow these procedures to minimize damage and preserve evidence:

Phase 1: Immediate Assessment (First 60 Seconds)

Step 1: Confirm the Emergency

• Verify that an emergency condition has actually occurred (not a false alarm)
• Query the vault state to determine the current status:
  • is_frozen status
  • released_amount (compare to expected value)
  • total_amount (should not change)
• Check the administrator's token balance to verify if tokens were revoked
• Review recent ledger transactions to identify what executed and in what order

Step 2: Identify the Emergency Type

• Determine which emergency condition has occurred (see list above)
• Assess the severity:
  • Critical: Tokens have been extracted by the beneficiary (successful front-running)
  • High: Freeze or revocation transaction failed, vault is still vulnerable
  • Medium: Unexpected state changes but no token loss yet
  • Low: Failed claim attempts after freeze (no action needed, monitoring only)

Step 3: Alert the Response Team

• Notify the security team, legal counsel, and relevant stakeholders immediately
• Provide a brief summary of the emergency condition
• Activate the incident response protocol
• Assign roles and responsibilities for the response effort

Phase 2: Containment (First 5 Minutes)

Step 4: Attempt to Freeze the Vault (If Not Already Frozen)

• If the vault is not frozen and tokens remain at risk, immediately submit a freeze transaction
• Use higher transaction fees to prioritize inclusion during surge pricing
• Monitor the freeze transaction for confirmation
• If the freeze fails again, investigate the cause:
  • Vault may already be frozen (check state again)
  • Authorization issues (verify administrator account)
  • Vault may not exist or may be in an invalid state

Step 5: Halt Further Revocation Attempts

• Do NOT submit the revocation transaction if the vault is not frozen
• Cancel any pending revocation transactions if possible (may not be possible once submitted)
• Reassess the situation before proceeding with revocation

Step 6: Document the Incident

• Record all transaction hashes, timestamps, and vault state snapshots
• Capture mempool logs if available
• Screenshot blockchain explorer pages showing the transaction sequence
• Preserve all evidence for potential legal proceedings or forensic analysis

Phase 3: Analysis and Response (First 30 Minutes)

Step 7: Analyze What Happened

• Reconstruct the sequence of events:
  • When was the freeze transaction submitted?
  • When was the claim transaction submitted?
  • Which transaction executed first?
  • What was the execution order in the ledger?
• Identify the root cause:
  • Was the freeze transaction delayed due to network congestion?
  • Did the beneficiary submit a higher-fee claim transaction?
  • Was there a technical failure (e.g., authorization issue, vault state problem)?
  • Was the beneficiary running automated monitoring software?

Step 8: Quantify the Impact

• Calculate the amount of tokens extracted by the beneficiary:
  • Extracted_Tokens = Released_Amount_After - Released_Amount_Before
• Calculate the financial impact:
  • Financial_Impact = Extracted_Tokens × Token_Price
• Determine the remaining tokens in the vault:
  • Remaining_Vested_Tokens = Vested_Amount - Extracted_Tokens
  • Remaining_Unvested_Tokens = Unvested_Amount
• Assess whether further revocation is still necessary and feasible

Step 9: Decide on Next Steps

• Based on the analysis, choose one of the following response paths:

Response Path A: Successful Front-Running (Tokens Extracted)

• The beneficiary successfully claimed vested tokens before the freeze
• Action: Proceed with revoking the remaining unvested tokens (if any)
• Action: Freeze the vault to prevent further claims
• Action: Consult legal counsel about potential recovery options (see Step 10)
• Action: Document the incident for audit and potential legal proceedings

Response Path B: Freeze Failed, Vault Still Vulnerable

• The freeze transaction failed and the vault is still unfrozen
• Action: Investigate the cause of the freeze failure
• Action: Retry the freeze transaction with corrected parameters
• Action: If freeze continues to fail, escalate to technical support or contract developers
• Action: Do NOT proceed with revocation until the vault is frozen

Response Path C: Revocation Failed After Freeze

• The vault is frozen but the revocation transaction failed
• Action: Investigate the cause of the revocation failure
• Action: Retry the revocation transaction with corrected parameters
• Action: The vault remains frozen, so there is no immediate risk of further token extraction
• Action: Document the failure and retry until successful

Response Path D: False Alarm (No Actual Emergency)

• The detected condition was a false alarm or monitoring error
• Action: Verify the vault state and confirm no tokens were extracted
• Action: Proceed with the standard revocation procedure
• Action: Review monitoring systems to prevent future false alarms

Phase 4: Recovery and Legal Action (First 24 Hours)

Step 10: Assess Legal Recovery Options

If the beneficiary successfully extracted tokens through front-running, consult legal counsel to evaluate recovery options:

Legal Theories for Recovery

Breach of Contract

• If the vesting agreement includes clauses prohibiting front-running or requiring cooperation during revocation
• If the beneficiary's actions violated the terms of the employment contract or vesting agreement
• Potential remedy: Return of extracted tokens, damages for breach

Breach of Fiduciary Duty

• If the beneficiary was an employee or officer with fiduciary duties to the organization
• If the front-running constitutes a breach of loyalty or good faith
• Potential remedy: Disgorgement of profits, damages

Unjust Enrichment

• If the beneficiary's extraction of tokens was inequitable or contrary to the parties' understanding
• If the beneficiary exploited a technical vulnerability in bad faith
• Potential remedy: Restitution of the unjust gain

Fraud or Misrepresentation

• If the beneficiary made false statements or concealed their intent to front-run
• If the beneficiary's actions constitute fraudulent conduct
• Potential remedy: Rescission, damages, punitive damages

Practical Considerations

• Legal action may be costly and time-consuming
• Recovery may be difficult if the beneficiary has transferred or sold the tokens
• Reputational impact of legal disputes should be considered
• Settlement negotiations may be more efficient than litigation

Evidence Preservation

• Preserve all transaction records, mempool logs, and vault state snapshots
• Document the timeline of events with precise timestamps
• Collect any communications with the beneficiary (emails, messages, calls)
• Prepare a detailed incident report for legal counsel

Step 11: Communicate with Stakeholders

Notify relevant stakeholders about the incident and response actions:

Internal Stakeholders

• Executive leadership (CEO, CFO, General Counsel)
• Finance team (for accounting and financial impact assessment)
• HR team (if the beneficiary is a current or former employee)
• IT/Security team (for technical analysis and prevention measures)

External Stakeholders (If Applicable)

• Legal counsel (for recovery options and legal strategy)
• Auditors (if the incident affects financial statements or compliance)
• Regulators (if required by law or regulation)
• Insurance providers (if the organization has cyber insurance or fidelity bonds)

Communication Guidelines

• Provide factual, objective information about the incident
• Avoid speculation or blame until the analysis is complete
• Emphasize the response actions taken to contain and resolve the incident
• Maintain confidentiality to protect legal strategy and beneficiary privacy

Step 12: Complete the Revocation (If Possible)

If unvested tokens remain in the vault after the front-running incident, complete the revocation:

Revocation After Front-Running

• Verify the vault is frozen (is_frozen = true)
• Submit the revocation transaction to reclaim remaining unvested tokens
• Monitor the revocation transaction for confirmation
• Verify the final vault state and administrator balance
• Document the completed revocation

If Revocation is No Longer Necessary

• If all tokens have been extracted or if the organization decides not to proceed with revocation
• Document the decision and rationale
• Consider whether to unfreeze the vault or leave it frozen
• Update internal records to reflect the final token allocation

Phase 5: Post-Incident Review (First Week)

Step 13: Conduct Post-Incident Analysis

After the immediate response is complete, conduct a thorough post-incident analysis:

Analysis Questions

• What was the root cause of the incident?
• Could the incident have been prevented? If so, how?
• Were the emergency response procedures effective?
• What lessons can be learned to prevent future incidents?
• Are there technical or operational improvements that should be implemented?

Analysis Deliverables

• Detailed incident timeline with all events and transactions
• Root cause analysis report
• Impact assessment (financial, operational, reputational)
• Lessons learned document
• Recommendations for prevention and improvement

Step 14: Implement Preventive Measures

Based on the post-incident analysis, implement measures to prevent future front-running incidents:

Technical Improvements

• Enhance monitoring systems to detect front-running attempts earlier
• Implement automated freeze-then-revoke workflows to reduce human error
• Deploy mempool monitoring tools to observe pending transactions in real-time
• Improve transaction fee management during surge pricing

Operational Improvements

• Update revocation procedures to incorporate lessons learned
• Provide additional training to administrators on front-running risks
• Establish clearer guidelines for when to use off-chain coordination
• Improve communication protocols between security, legal, and operations teams

Policy Improvements

• Update vesting agreements to include explicit anti-front-running clauses
• Establish clear policies for legal action in response to front-running
• Define escalation procedures for high-risk revocations
• Implement regular audits of revocation procedures and compliance

Step 15: Update Documentation and Training

Update security documentation and training materials based on the incident:

Documentation Updates

• Add the incident as a case study in the SECURITY.md file (anonymized if necessary)
• Update emergency response procedures based on lessons learned
• Document new preventive measures and their implementation
• Update risk assessment guidelines to reflect new threat intelligence

Training Updates

• Conduct training sessions for administrators on the incident and lessons learned
• Update training materials to include the new procedures and preventive measures
• Conduct tabletop exercises or simulations to practice emergency response
• Ensure all relevant personnel are aware of the updated procedures

Use this checklist during an emergency to ensure all critical steps are completed:

Immediate Assessment (First 60 Seconds)

• Confirm the emergency condition has occurred
• Query vault state and verify current status
• Identify the emergency type and assess severity
• Alert the response team and activate incident response protocol

Containment (First 5 Minutes)

• Attempt to freeze the vault if not already frozen
• Halt further revocation attempts until situation is assessed
• Document the incident with transaction hashes and timestamps
• Preserve all evidence for potential legal proceedings

Analysis and Response (First 30 Minutes)

• Reconstruct the sequence of events and identify root cause
• Quantify the impact (tokens extracted, financial loss)
• Decide on response path (A, B, C, or D)
• Execute the chosen response actions

Recovery and Legal Action (First 24 Hours)

• Assess legal recovery options with counsel
• Preserve evidence for potential legal proceedings
• Communicate with internal and external stakeholders
• Complete the revocation if possible and appropriate

Post-Incident Review (First Week)

• Conduct post-incident analysis and document lessons learned
• Implement preventive measures to avoid future incidents
• Update documentation and training materials
• Conduct training sessions for relevant personnel

Maintain an up-to-date list of emergency contacts for incident response:

Internal Contacts

• Security Team Lead: [Name, Phone, Email]
• Legal Counsel: [Name, Phone, Email]
• Finance Team Lead: [Name, Phone, Email]
• IT/Operations Team Lead: [Name, Phone, Email]
• Executive Sponsor: [Name, Phone, Email]

External Contacts

• External Legal Counsel: [Firm Name, Contact, Phone, Email]
• Blockchain Forensics Firm: [Firm Name, Contact, Phone, Email]
• Stellar/Soroban Technical Support: [Contact Information]
• Cyber Insurance Provider: [Company Name, Policy Number, Contact]

Communication Channels

• Emergency Slack Channel: [Channel Name]
• Emergency Email List: [Email Address]
• Incident Management System: [System Name, URL]
• On-Call Rotation: [Schedule Link]

Scenario 1: Beneficiary Claims Tokens Before Freeze Confirmation

Situation: Administrator submits freeze transaction at T=0. Beneficiary observes the pending freeze and submits a claim transaction at T=1 with a higher fee. Due to surge pricing, the claim transaction is included in the ledger before the freeze transaction.

Response:

1. Confirm that the claim executed before the freeze by checking the ledger
2. Calculate the amount of tokens extracted by the beneficiary
3. Verify that the freeze transaction eventually confirmed and the vault is now frozen
4. Proceed with revoking the remaining unvested tokens
5. Consult legal counsel about recovery options for the extracted vested tokens
6. Document the incident and implement preventive measures (e.g., use higher fees for freeze transactions during surge pricing)

Scenario 2: Freeze Transaction Fails Due to Authorization Issue

Situation: Administrator submits freeze transaction, but it fails with "Unauthorized" error because the wrong administrator account was used or the account's authorization was revoked.

Response:

1. Immediately identify the correct administrator account with freeze authorization
2. Submit a new freeze transaction from the authorized account
3. Use higher fees to ensure rapid inclusion
4. Monitor the new freeze transaction for confirmation
5. Once the vault is frozen, proceed with the revocation
6. Review authorization management procedures to prevent future errors

Scenario 3: Revocation Transaction Fails After Freeze

Situation: Vault is successfully frozen, but the revocation transaction fails with "No tokens to revoke" or another error.

Response:

1. Query the vault state to understand why the revocation failed
2. Possible causes:
   • All tokens were already claimed before the freeze (check released_amount)
   • Vault is marked as irrevocable (check is_irrevocable)
   • Vault does not exist or is in an invalid state
3. If tokens remain in the vault, investigate the error and retry the revocation with corrected parameters
4. If no tokens remain, document the outcome and consider legal recovery options
5. The vault remains frozen, so there is no immediate risk

Scenario 4: Multiple Failed Claim Attempts After Freeze

Situation: After the vault is frozen, the beneficiary submits multiple claim transactions that all fail with "Vault is frozen" error.

Response:

1. This is the expected outcome - the freeze mechanism is working correctly
2. Document the failed claim attempts as evidence of attempted front-running
3. Proceed with the revocation as planned
4. No emergency action is required, but the failed attempts should be noted in the audit trail
5. Consider this evidence if legal action is pursued

Scenario 5: Network Congestion Delays Freeze Confirmation

Situation: During severe network congestion, the freeze transaction is delayed for 30+ seconds, giving the beneficiary an extended window to front-run.

Response:

1. Monitor the mempool for any claim transactions submitted by the beneficiary
2. If a claim transaction is detected, assess whether it will execute before the freeze
3. Consider submitting a second freeze transaction with a much higher fee to compete for inclusion
4. If the claim executes before the freeze, follow the response procedures for Scenario 1
5. If the freeze eventually confirms without a successful claim, proceed with the revocation
6. Document the delay and consider implementing higher default fees for freeze transactions during surge pricing

Effective emergency response requires:

• Rapid detection of front-running attempts or revocation failures through real-time monitoring
• Immediate containment by freezing the vault and halting further revocation attempts
• Thorough analysis to understand what happened and quantify the impact
• Appropriate recovery actions including legal consultation and stakeholder communication
• Post-incident learning to prevent future incidents through improved procedures and training

Key Principles:

1. Stay calm and follow the checklist - panic leads to mistakes
2. Preserve evidence immediately - transaction records may be needed for legal action
3. Prioritize containment over recovery - freeze the vault first, then assess options
4. Consult legal counsel early - recovery options are time-sensitive
5. Learn from every incident - update procedures and training based on lessons learned

While the freeze-then-revoke pattern should prevent most front-running attempts, having a well-defined emergency response plan ensures that administrators can respond effectively when unexpected situations arise. Regular training and tabletop exercises will help ensure the response team is prepared to execute these procedures under pressure.

This section provides links to official Soroban and Stellar documentation referenced throughout this security analysis. These resources provide additional context on transaction ordering, consensus mechanisms, and blockchain security considerations.

1. Stellar Soroban Platform Overview

   • URL: https://stellar.org/soroban
   • Description: Official overview of the Soroban smart contract platform, including finality guarantees and performance characteristics
   • Relevance: Provides context on Soroban's 5-second finality and smart contract capabilities

2. Stellar Consensus Protocol (SCP) Documentation

   • URL: https://developers.stellar.org/docs/glossary/scp
   • Description: Technical documentation of Stellar's federated Byzantine agreement consensus mechanism
   • Relevance: Explains how SCP achieves consensus and why it prevents chain reorganizations

3. SCP Proof and Code

   • URL: https://stellar.org/blog/foundation-news/stellar-consensus-protocol-proof-code
   • Description: Formal proof and implementation details of the Stellar Consensus Protocol
   • Relevance: Provides deeper understanding of SCP's safety and liveness properties

4. Transaction Submission Timeouts and Dynamic Fees FAQ

   • URL: https://stellar.org/blog/developers/transaction-submission-timeouts-and-dynamic-fees-faq
   • Description: Explanation of Stellar's surge pricing mechanism and how fees affect transaction inclusion during network congestion
   • Relevance: Critical for understanding when and how fee-based prioritization occurs

5. Benefit of Overpaying Fees (Stellar Stack Exchange)

   • URL: https://stellar.stackexchange.com/questions/674/benefit-of-overpaying-fees
   • Description: Community discussion on transaction fee behavior and pseudo-random ordering during normal operation
   • Relevance: Clarifies that higher fees do not affect execution order within a ledger during normal operation

6. Ledger Close Time Variation (Stellar Stack Exchange)

   • URL: https://stellar.stackexchange.com/questions/2057/how-do-you-explain-variation-in-ledger-close-times
   • Description: Technical explanation of ledger close timing and confirmation speeds
   • Relevance: Provides context on the ~5-second attack window for front-running

7. Issuer-Enforced Finality Explained
   • URL: https://www.stellar.org/blog/developers/issuer-enforced-finality-explained
   • Description: Explanation of Stellar's strong finality guarantees and why chain reorganizations do not occur
   • Relevance: Demonstrates that once a transaction is confirmed, it cannot be reversed, eliminating certain attack vectors

8. Financial Privacy on Stellar (X-Ray Protocol Upgrade)

   • URL: https://stellar.org/blog/developers/financial-privacy
   • Description: Introduction to zero-knowledge proof capabilities in Soroban (BN254 curves, Poseidon hashing)
   • Relevance: Discusses privacy features available for new contract designs, though not applicable to existing vesting vaults

9. Prototyping Privacy Pools on Stellar

   • URL: https://stellar.org/blog/ecosystem/prototyping-privacy-pools-on-stellar
   • Description: Implementation of Privacy Pools using Groth16 zero-knowledge proofs for privacy-preserving transfers
   • Relevance: Demonstrates advanced privacy techniques available on Stellar, though requiring fundamental contract redesign

10. Transaction Queue Status Query (GitHub Issue #2920)
    • URL: stellar/stellar-core#2920
    • Description: Discussion of transaction queue visibility and the lack of standardized APIs for querying pending transactions
    • Relevance: Explains mempool visibility characteristics and limitations of transaction status queries

11. Stellar Developer Documentation

    • URL: https://developers.stellar.org/
    • Description: Comprehensive developer documentation for Stellar and Soroban
    • Relevance: General reference for understanding Stellar's architecture and capabilities

12. Soroban Smart Contracts Documentation

    • URL: https://developers.stellar.org/docs/smart-contracts
    • Description: Technical documentation for developing and deploying Soroban smart contracts
    • Relevance: Provides context on smart contract capabilities and limitations

13. Stellar Security Best Practices
    • URL: https://developers.stellar.org/docs/security
    • Description: General security guidance for Stellar applications
    • Relevance: Broader security context beyond the specific front-running issue

14. Stellar Stack Exchange

    • URL: https://stellar.stackexchange.com/
    • Description: Community Q&A forum for Stellar and Soroban developers
    • Relevance: Source of practical insights and community knowledge on transaction behavior

15. Stellar Discord Community

    • URL: https://discord.gg/stellar
    • Description: Real-time community discussion and support
    • Relevance: Platform for asking questions and staying updated on protocol changes

This security documentation is based on information available as of the document creation date. Stellar and Soroban are actively developed platforms, and protocol changes may affect the accuracy of this analysis. Administrators should:

• Monitor official Stellar and Soroban channels for protocol updates
• Review this documentation periodically and update based on new information
• Consult with Stellar experts or security auditors for high-value deployments
• Subscribe to Stellar developer newsletters and security advisories

Last Updated: [Document creation date]
Next Review Date: [Recommended: 6 months from creation]

For questions or clarifications about this security documentation, consult the official Stellar and Soroban resources listed above or engage with the Stellar developer community.