feat: value-capture fee estimation and billing with tiered pricing (#506)

Co-authored-by: Chris Li <chris@avaprotocol.org>

Author: chrisli30

.github/workflows/publish-dev-docker.yml

@@ -1,6 +1,15 @@
 name: Publish Dev Docker Image
 
 on:
+  # Auto-build on PR merge to staging when protobuf changes — SDK CI pulls :latest to test against.
+  # Non-proto changes don't affect the wire format, so no need to rebuild the image.
+  push:
+    branches:
+      - staging
+    paths:
+      - 'protobuf/avs.proto'
+
+  # Manual dispatch for ad-hoc builds (specific tag, commit, or branch)
   workflow_dispatch:
     inputs:
       branch_name:
@@ -22,13 +31,15 @@ on:
         type: boolean
         default: false
 
+# Cancel in-flight builds when a newer commit lands on staging
+concurrency:
+  group: dev-docker-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   publish-staging-build:
-    # If you want to keep the merged check for manual dispatch, you might need to adjust context
-    # For now, assuming manual dispatch doesn't need this specific PR context check.
-    # if: github.event.pull_request.merged == true 
     name: Build and Publish Dev Docker Image to Dockerhub
-    runs-on: 'blacksmith-4vcpu-ubuntu-2404'
+    runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Login to Docker Hub
         uses: docker/login-action@v3
@@ -40,19 +51,27 @@ jobs:
         id: checkout_code
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0 
-          # Priority: git_tag, then commit_hash, then branch_name
-          ref: ${{ github.event.inputs.git_tag && format('refs/tags/{0}', github.event.inputs.git_tag) || github.event.inputs.commit_hash || github.event.inputs.branch_name }}
+          fetch-depth: 0
+          # push event: github.ref is already correct (staging branch)
+          # workflow_dispatch: priority is git_tag > commit_hash > branch_name
+          ref: ${{ github.event_name == 'push' && github.ref || (github.event.inputs.git_tag && format('refs/tags/{0}', github.event.inputs.git_tag) || github.event.inputs.commit_hash || github.event.inputs.branch_name) }}
 
       - name: Determine Tags and Build Args
         id: vars
         run: |
           SHORT_SHA=$(git rev-parse --short HEAD)
           PRIMARY_DOCKER_TAG=""
-          BRANCH_FOR_CONTEXT="" # Sanitized branch name used for context with commits
+          BRANCH_FOR_CONTEXT=""
           RELEASE_TAG_ARG=""
 
-          if [[ -n "${{ github.event.inputs.git_tag }}" ]]; then
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            # Automatic build from staging push (PR merge)
+            BRANCH_NAME="${{ github.ref_name }}"
+            echo "Source: Push to ${BRANCH_NAME} (auto-build)"
+            PRIMARY_DOCKER_TAG="${BRANCH_NAME}-${SHORT_SHA}"
+            BRANCH_FOR_CONTEXT="$BRANCH_NAME"
+            RELEASE_TAG_ARG="${BRANCH_NAME}-${SHORT_SHA}"
+          elif [[ -n "${{ github.event.inputs.git_tag }}" ]]; then
             echo "Source: Git Tag (${{ github.event.inputs.git_tag }})"
             PRIMARY_DOCKER_TAG="${{ github.event.inputs.git_tag }}"
             RELEASE_TAG_ARG="${{ github.event.inputs.git_tag }}"
@@ -65,18 +84,18 @@ jobs:
               BRANCH_FOR_CONTEXT="$SANITIZED_BRANCH_CTX"
               RELEASE_TAG_ARG="$SANITIZED_BRANCH_CTX-$SHORT_SHA"
             else
-              PRIMARY_DOCKER_TAG="$SHORT_SHA" # Fallback if branch_name was empty
+              PRIMARY_DOCKER_TAG="$SHORT_SHA"
               RELEASE_TAG_ARG="$SHORT_SHA"
             fi
           else
             # Source: Branch Name (no git_tag, no commit_hash)
-            RAW_BRANCH_NAME="${{ github.event.inputs.branch_name }}" # Default 'staging'
+            RAW_BRANCH_NAME="${{ github.event.inputs.branch_name }}"
             echo "Source: Branch ($RAW_BRANCH_NAME)"
             SANITIZED_BRANCH_NAME=$(echo "$RAW_BRANCH_NAME" | sed 's|/|-|g' | tr -cs 'a-zA-Z0-9.-_' '-' | sed 's/--\+/-/g' | sed 's/^-*//;s/-*$//')
             if [[ -n "$SANITIZED_BRANCH_NAME" ]]; then
-              PRIMARY_DOCKER_TAG="$SANITIZED_BRANCH_NAME-$SHORT_SHA" # Always include SHA for branch builds
+              PRIMARY_DOCKER_TAG="$SANITIZED_BRANCH_NAME-$SHORT_SHA"
               BRANCH_FOR_CONTEXT="$SANITIZED_BRANCH_NAME"
-              RELEASE_TAG_ARG="$SANITIZED_BRANCH_NAME-$SHORT_SHA" # Embed branch-sha as version
+              RELEASE_TAG_ARG="$SANITIZED_BRANCH_NAME-$SHORT_SHA"
             else
               PRIMARY_DOCKER_TAG="unknown-$SHORT_SHA"
               RELEASE_TAG_ARG="unknown-$SHORT_SHA"
@@ -104,26 +123,27 @@ jobs:
           echo "---- End Debug ----"
         shell: bash
 
-      - name: Show Build Configuration
+      # Automatic push builds use amd64-only (fast) since SDK CI runs on ubuntu.
+      # Manual dispatch respects the fast_build input.
+      - name: Resolve build platforms
+        id: platforms
         run: |
-          echo "---- Build Configuration ----"
-          if [[ "${{ inputs.fast_build }}" == "true" ]]; then
-            echo "🚀 Fast Build Mode: Building for linux/amd64 only (~50% faster)"
-            echo "Platforms: linux/amd64"
-            echo "QEMU Setup: Skipped"
+          if [[ "${{ github.event_name }}" == "push" || "${{ inputs.fast_build }}" == "true" ]]; then
+            echo "value=linux/amd64" >> $GITHUB_OUTPUT
+            echo "fast=true" >> $GITHUB_OUTPUT
+            echo "Build mode: fast (linux/amd64 only)"
           else
-            echo "🏗️  Full Build Mode: Building for linux/amd64,linux/arm64"
-            echo "Platforms: linux/amd64,linux/arm64"
-            echo "QEMU Setup: Enabled for ARM64"
+            echo "value=linux/amd64,linux/arm64" >> $GITHUB_OUTPUT
+            echo "fast=false" >> $GITHUB_OUTPUT
+            echo "Build mode: full (linux/amd64,linux/arm64)"
           fi
-          echo "---- End Configuration ----"
         shell: bash
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
         with:
-          platforms: 'linux/arm64' # Use specific platform and default image
-        if: ${{ !inputs.fast_build }}
+          platforms: 'linux/arm64'
+        if: steps.platforms.outputs.fast != 'true'
 
       - name: Setup Blacksmith Builder
         uses: useblacksmith/setup-docker-builder@v1
@@ -134,21 +154,21 @@ jobs:
         with:
           images: avaprotocol/avs-dev
           tags: |
-            # Primary tag (e.g., v1.6.0 or main-<sha>)
+            # Primary tag (e.g., v1.6.0 or staging-abc1234)
             type=raw,value=${{ steps.vars.outputs.PRIMARY_DOCKER_TAG }}
 
             # Always set latest tag for any build
             type=raw,value=latest
-            
+
       - name: Build and push avs-dev Docker image
         uses: useblacksmith/build-push-action@v2
         with:
           build-args: |
             RELEASE_TAG=${{ steps.vars.outputs.RELEASE_TAG_ARG }}
             COMMIT_SHA=${{ steps.vars.outputs.SHORT_SHA }}
-          platforms: ${{ inputs.fast_build && 'linux/amd64' || 'linux/amd64,linux/arm64' }}
+          platforms: ${{ steps.platforms.outputs.value }}
           context: .
           file: dockerfiles/operator.Dockerfile
-          push: true 
+          push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

README.md

@@ -32,121 +32,9 @@ ap-avs aggregator
 
 Note: The Ava Protocol team currently manages the aggregator, and the communication IP address between the operator and the aggregator is hardcoded in the operator.
 
-### Configurable Fee Rates
-
-The aggregator supports configurable fee rates for workflow execution and monitoring. This allows for dynamic pricing adjustments without code deployments, environment-specific pricing, and A/B testing of pricing models.
-
-#### Configuration Overview
-
-Fee rates are completely **optional** and **backward compatible**. The aggregator will work exactly as before without any configuration changes. When fee rates are configured, they override the hardcoded defaults.
-
-#### Adding Fee Configuration
-
-To configure custom fee rates, add a `fee_rates:` section to your existing aggregator YAML configuration file:
-
-```yaml
-# Your existing aggregator config (unchanged)
-environment: development
-db_path: /tmp/ap-avs/db
-ecdsa_private_key: your_private_key_here
-# ... other existing config fields ...
-
-# 🆕 Optional fee rates configuration
-fee_rates:
-  # Base fees (one-time per workflow)
-  base_fee_usd: 0.0
-  
-  # Monitoring fees (per minute) - cost to monitor triggers
-  manual_monitoring_fee_usd_per_minute: 0.0      # Manual triggers free
-  fixed_time_monitoring_fee_usd_per_minute: 0.000017  # ~$0.01/day
-  cron_monitoring_fee_usd_per_minute: 0.000033        # ~$0.02/day
-  block_monitoring_fee_usd_per_minute: 0.000033       # ~$0.02/day
-  event_monitoring_fee_usd_per_minute: 0.000083       # ~$0.05/day base
-  
-  # Per-execution fees - cost for each trigger activation
-  manual_execution_fee_usd: 0.0      # Manual executions free
-  scheduled_execution_fee_usd: 0.005 # $0.005 per scheduled execution
-  block_execution_fee_usd: 0.01      # $0.01 per block trigger
-  event_execution_fee_usd: 0.01      # $0.01 per event trigger
-  
-  # Event monitoring scaling factors
-  event_address_fee_usd_per_minute: 0.000008  # ~$0.005/day per address
-  event_topic_fee_usd_per_minute: 0.000003    # ~$0.002/day per topic
-```
-
-#### Configuration Files
-
-The aggregator uses configuration files from the `config/` directory:
-
-- **Default**: `./config/aggregator.yaml` 
-- **Custom**: Specify with `--config` flag
-
-**Available config files:**
-- `config/aggregator.yaml` - Default configuration
-- `config/aggregator-sepolia.yaml` - Sepolia testnet
-- `config/aggregator-base.yaml` - Base network
-- `config/aggregator-ethereum.yaml` - Ethereum mainnet
-
-#### Starting with Custom Config
-
-```bash
-# Use default config (./config/aggregator.yaml)
-./ap-avs aggregator
-
-# Use specific config file
-./ap-avs aggregator --config ./config/aggregator-sepolia.yaml
-./ap-avs aggregator -c ./path/to/your/config.yaml
-```
-
-#### Pricing Strategies
-
-**All fields are optional** - only specify rates you want to override:
-
-**Beta Testing (Free Everything):**
-```yaml
-fee_rates:
-  scheduled_execution_fee_usd: 0.0
-  block_execution_fee_usd: 0.0
-  event_execution_fee_usd: 0.0
-  # All monitoring fees default to existing values
-```
-
-**Premium Pricing (Selective Overrides):**
-```yaml
-fee_rates:
-  # Only override specific rates
-  block_execution_fee_usd: 0.02      # 2x default rate
-  event_execution_fee_usd: 0.015     # 1.5x default rate
-  # All other fees use hardcoded defaults
-```
-
-**Environment-Specific Pricing:**
-```yaml
-# Production - Higher rates
-fee_rates:
-  scheduled_execution_fee_usd: 0.01  # 2x default
-  
-# Development - Free rates  
-fee_rates:
-  scheduled_execution_fee_usd: 0.0   # Free for development
-```
+### Fee Estimation
 
-#### Default Values
-
-When no `fee_rates` section is provided, these hardcoded defaults are used:
-
-- **Base Fee**: $0.00 (one-time per workflow)
-- **Manual Monitoring**: $0.00/minute (free)
-- **Fixed Time Monitoring**: $0.000017/minute (~$0.01/day)
-- **Cron Monitoring**: $0.000033/minute (~$0.02/day) 
-- **Block Monitoring**: $0.000033/minute (~$0.02/day)
-- **Event Monitoring**: $0.000083/minute (~$0.05/day base)
-- **Manual Execution**: $0.00 (free)
-- **Scheduled Execution**: $0.005 per execution
-- **Block Execution**: $0.01 per execution
-- **Event Execution**: $0.01 per execution
-- **Event Address Fee**: $0.000008/minute per monitored address
-- **Event Topic Fee**: $0.000003/minute per topic filter
+See [docs/FEE_ESTIMATION.md](docs/FEE_ESTIMATION.md) for the fee pricing model, configuration, and implementation details.
 
 #### Benefits
 

aggregator/rpc_server.go

@@ -548,6 +548,7 @@ func (r *RpcServer) sendUserOpWithGlobalWs(
 			smartWalletAddress,
 			nil,                // saltOverride - not needed for already-deployed wallets
 			r.smartWalletWsRpc, // Use global WebSocket client
+			nil,                // executionFeeWei - no platform fee for direct RPC calls (e.g., WithdrawFunds)
 			r.config.Logger,    // Pass logger for debug/verbose logging
 		)
 	} else {
@@ -560,6 +561,7 @@ func (r *RpcServer) sendUserOpWithGlobalWs(
 			paymasterReq, // Use provided paymaster request
 			smartWalletAddress,
 			nil,             // saltOverride - not needed for already-deployed wallets
+			nil,             // executionFeeWei - no platform fee for direct RPC calls
 			r.config.Logger, // Pass logger for debug/verbose logging
 		)
 	}
@@ -1255,8 +1257,7 @@ func (r *RpcServer) EstimateFees(ctx context.Context, req *avsproto.EstimateFees
 
 	r.config.Logger.Info("✅ fee estimation completed successfully",
 		"user", user.Address.String(),
-		"final_total_usd", resp.FinalTotal.UsdAmount,
-		"estimation_method", resp.GasFees.EstimationMethod)
+		"pricing_model", resp.PricingModel)
 
 	return resp, nil
 }

aggregator/task_engine.go

@@ -45,6 +45,7 @@ import (
 	"time"
 
 	"github.com/AvaProtocol/EigenLayer-AVS/core/apqueue"
+	"github.com/AvaProtocol/EigenLayer-AVS/core/services"
 	"github.com/AvaProtocol/EigenLayer-AVS/core/taskengine"
 	"github.com/AvaProtocol/EigenLayer-AVS/core/taskengine/macros"
 	sdklogging "github.com/Layr-Labs/eigensdk-go/logging"
@@ -96,8 +97,19 @@ func (agg *Aggregator) startTaskEngine(ctx context.Context) {
 		agg.logger,
 	)
 
+	// Create price service for fee conversion (USD → ETH)
+	var priceService taskengine.PriceService
+	if agg.config.MoralisApiKey != "" {
+		priceService = services.GetMoralisService(agg.config.MoralisApiKey, agg.logger)
+	} else {
+		priceService = newFallbackPriceService()
+	}
+
+	// Store price service on engine for use in simulation path
+	agg.engine.SetPriceService(priceService)
+
 	// Create executor with engine reference for atomic execution indexing
-	taskExecutor := taskengine.NewExecutor(agg.config.SmartWallet, agg.db, agg.logger, agg.engine)
+	taskExecutor := taskengine.NewExecutor(agg.config.SmartWallet, agg.db, agg.logger, agg.engine, priceService)
 	taskengine.SetCache(agg.cache)
 	macros.SetRpc(agg.config.SmartWallet.EthRpcUrl)
 

config/aggregator.example.yaml

@@ -76,28 +76,18 @@ approved_operators:
   - "0xc6b87cc9e85b07365b6abefff061f237f7cf7dc3" # Operator 2
   - "0xa026265a0f01a6e1a19b04655519429df0a57c4e" # Operator 3 (newly added)
 
-# 🆕 CONFIGURABLE FEE RATES
-# All fields are optional - only specify ones you want to override
+# FEE STRUCTURE: execution_fee + COGS + value_fee
+# - execution_fee: flat per-run platform fee
+# - COGS: per-node operational costs (gas, external APIs) — estimated automatically
+# - value_fee: workflow-level % of tx value, classified by urgency/importance
+# All fields optional — unset values use defaults shown below.
 fee_rates:
-  # Base fees (one-time per workflow) - defaults to 0.0
-  base_fee_usd: 0.0
-
-  # Monitoring fees (per minute) - cost to monitor triggers
-  manual_monitoring_fee_usd_per_minute: 0.0 # Manual triggers free (default)
-  fixed_time_monitoring_fee_usd_per_minute: 0.000017 # ~$0.01/day (default)
-  cron_monitoring_fee_usd_per_minute: 0.000033 # ~$0.02/day (default)
-  block_monitoring_fee_usd_per_minute: 0.000033 # ~$0.02/day (default)
-  event_monitoring_fee_usd_per_minute: 0.000083 # ~$0.05/day (default)
-
-  # Per-execution fees - cost for each trigger activation
-  manual_execution_fee_usd: 0.0 # Manual executions free (default)
-  scheduled_execution_fee_usd: 0.005 # $0.005 per scheduled execution (default)
-  block_execution_fee_usd: 0.01 # $0.01 per block trigger (default)
-  event_execution_fee_usd: 0.01 # $0.01 per event trigger (default)
-
-  # Event monitoring scaling factors - additional costs for complex event monitoring
-  event_address_fee_usd_per_minute: 0.000008 # ~$0.005/day per address (default)
-  event_topic_fee_usd_per_minute: 0.000003 # ~$0.002/day per topic (default)
+  execution_fee_usd: 0.02   # Flat per-execution platform fee ($0.02 default)
+  credit_limit_usd: 0.0     # Max outstanding value fees before blocking (0 = block on any outstanding)
+  tiers:
+    tier_1: 0.03             # Value-capture group 1 (0.03% of tx value)
+    tier_2: 0.09             # Value-capture group 2 (0.09% of tx value)
+    tier_3: 0.18             # Value-capture group 3 (0.18% of tx value)
 
 # Macro variables and secrets - Available globally to ALL workflows at runtime
 # Access in workflows via template syntax: {{apContext.configVars.SECRET_NAME}}