bounty-escrow-manifest.json

{
  "$schema": "./contract-manifest-schema.json",
  "contract_name": "BountyEscrowContract",
  "contract_purpose": "Manages bounty escrow with multi-token support, capability-based authorization, two-step admin rotation with timelock, refund-eligibility views, fee configuration, participant filter pagination with audit events, high-value release timelock queue, and comprehensive security features including reentrancy protection and rate limiting",
  "version": {
    "current": "2.5.0",
    "schema": "1.0.0",
    "history": [
      {
        "version": "1.0.0",
        "release_date": "2024-01-01",
        "changes": [
          "Initial release with basic escrow functionality",
          "Single admin authorization model",
          "Basic fee configuration"
        ]
      },
      {
        "version": "2.0.0",
        "release_date": "2024-06-01",
        "changes": [
          "Added capability-based authorization system",
          "Enhanced fee configuration with separate lock/release rates",
          "Implemented reentrancy protection",
          "Added rate limiting and anti-abuse mechanisms",
          "Enhanced monitoring and analytics",
          "Added claim period functionality"
        ]
      },
      {
        "version": "2.1.0",
        "release_date": "2026-04-22",
        "changes": [
          "Added explicit refund eligibility view with deterministic semantics",
          "Added refund approval audit events for approval set/consumption lifecycle",
          "Added upgrade-safe storage marker for refund eligibility schema versioning"
        ]
      },
      {
        "version": "2.2.0",
        "release_date": "2026-04-22",
        "changes": [
          "Hardened maintenance mode with explicit initialization, idempotent toggling, and audit-friendly v2 events",
          "Added upgrade-safe storage keys for maintenance mode metadata and schema versioning"
        ]
      },
       {
        "version": "2.3.0",
        "release_date": "2026-04-23",
        "changes": [
          "Added FeeRoutingInvariantChecked audit event — emitted after every fee routing operation to prove distributed_total == fee_amount",
          "Added FeeRoutingSchemaVersionSet event — emitted once during init() for upgrade-safe schema versioning",
          "Added reason field to MaintenanceModeChangedV2 for complete audit trail",
          "Added InvalidBatchSize error code for batch size governance",
          "Added BatchSizeCaps and FeeRoutingSchemaVersion DataKey variants for upgrade-safe storage",
          "Fee routing invariant is now enforced on-chain: last destination absorbs rounding remainder ensuring exact accounting"
        ]
      },
      {
        "version": "2.4.0",
        "release_date": "2026-04-23",
        "changes": [
          "query_whitelist and query_blocklist now return ParticipantListPage with items, total, offset, and has_more fields for clear pagination semantics",
          "Added get_whitelist_count and get_blocklist_count view functions for O(1) total-count queries",
          "Added ParticipantFilterQueried audit event emitted on every query_whitelist/query_blocklist call for off-chain audit trails",
          "Limit argument silently capped at MAX_PARTICIPANT_FILTER_PAGE_SIZE (50) to bound per-call ledger cost",
          "Added ParticipantListSchemaVersion storage key initialized on contract init for upgrade-safe storage versioning"
        ]
      },
      {
        "version": "2.5.0",
        "release_date": "2026-04-24",
        "changes": [
          "Added high-value release timelock queue: releases at or above a configurable threshold are queued with a mandatory delay before execution",
          "Added set_high_value_config (admin) to configure threshold and duration; both must be > 0",
          "Added get_high_value_config view to read current configuration",
          "Added get_queued_release view to inspect a pending queued release",
          "Added execute_queued_release (permissionless after delay) to finalize a queued release; respects maintenance mode, escrow freeze, and applies release fees",
          "Added cancel_queued_release (admin) to cancel a pending queued release",
          "Added DataKey::HighValueConfig, DataKey::QueuedRelease(u64), and DataKey::HighValueConfigSchemaVersion storage keys",
          "Added HighValueConfigUpdated, ReleaseQueued, QueuedReleaseExecuted, ReleaseQueueCancelled, and HighValueConfigSchemaVersionSet audit events",
          "Added TimelockNotElapsed (53) and ReleaseAlreadyQueued (54) error codes",
          "Added get_high_value_config_schema_version view for upgrade safety checks"
        ]
      }
    ]
  },
  "entrypoints": {
    "public": [
      {
        "name": "lock_funds",
        "description": "Lock funds into escrow for a bounty",
        "parameters": [
          {
            "name": "depositor",
            "type": "Address",
            "description": "Address locking the funds"
          },
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Unique identifier for the bounty"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount to lock in escrow"
          },
          {
            "name": "deadline",
            "type": "u64",
            "description": "Timestamp when funds can be refunded"
          },
          {
            "name": "metadata",
            "type": "EscrowMetadata",
            "description": "Optional metadata for the escrow",
            "optional": true
          }
        ],
        "returns": {
          "type": "Escrow",
          "description": "The created escrow record"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "release_funds",
        "description": "Release funds to a contributor",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "contributor",
            "type": "Address",
            "description": "Address to receive funds"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "release_with_capability",
        "description": "Release funds using a capability token",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "contributor",
            "type": "Address",
            "description": "Address to receive funds"
          },
          {
            "name": "capability_id",
            "type": "u64",
            "description": "Capability token ID"
          },
          {
            "name": "payout_amount",
            "type": "i128",
            "description": "Amount to release"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "capability",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "refund_funds",
        "description": "Refund funds to depositor after deadline",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "authorize_claim",
        "description": "Authorize a pending claim instead of immediate release",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "recipient",
            "type": "Address",
            "description": "Address authorized to claim"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "claim",
        "description": "Claim funds from an authorized pending claim",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "issue_capability",
        "description": "Issue a capability token for delegated operations",
        "parameters": [
          {
            "name": "owner",
            "type": "Address",
            "description": "Address that owns the capability"
          },
          {
            "name": "holder",
            "type": "Address",
            "description": "Address that can use the capability"
          },
          {
            "name": "action",
            "type": "CapabilityAction",
            "description": "Action this capability authorizes"
          },
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "amount_limit",
            "type": "i128",
            "description": "Maximum amount this capability can release"
          },
          {
            "name": "expiry",
            "type": "u64",
            "description": "Expiration timestamp"
          },
          {
            "name": "uses",
            "type": "u32",
            "description": "Number of uses allowed",
            "optional": true
          }
        ],
        "returns": {
          "type": "u64",
          "description": "Capability token ID"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "revoke_capability",
        "description": "Revoke a capability token",
        "parameters": [
          {
            "name": "owner",
            "type": "Address",
            "description": "Capability owner"
          },
          {
            "name": "capability_id",
            "type": "u64",
            "description": "Capability token ID"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "signer",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "batch_lock_funds",
        "description": "Lock funds for multiple bounties in one transaction",
        "parameters": [
          {
            "name": "items",
            "type": "Vec<LockFundsItem>",
            "description": "Array of lock requests"
          }
        ],
        "returns": {
          "type": "u32",
          "description": "Number of bounties successfully locked"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "high"
      },
      {
        "name": "batch_release_funds",
        "description": "Release funds for multiple bounties in one transaction",
        "parameters": [
          {
            "name": "items",
            "type": "Vec<ReleaseFundsItem>",
            "description": "Array of release requests"
          }
        ],
        "returns": {
          "type": "u32",
          "description": "Number of bounties successfully released"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "high"
      },
      {
        "name": "accept_admin",
        "description": "Accept a pending admin role after timelock expires",
        "parameters": [],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "signer",
        "pausable": false,
        "gas_estimate": "low"
      }
    ],
    "view": [
      {
        "name": "get_filter_mode",
        "description": "Get current participant filter mode",
        "parameters": [],
        "returns": {
          "type": "ParticipantFilterMode",
          "description": "Current participant filter mode"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_whitelist_count",
        "description": "Return total number of allowlisted addresses",
        "parameters": [],
        "returns": {
          "type": "u32",
          "description": "Total count of allowlisted addresses"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_blocklist_count",
        "description": "Return total number of blocklisted addresses",
        "parameters": [],
        "returns": {
          "type": "u32",
          "description": "Total count of blocklisted addresses"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "query_whitelist",
        "description": "Get paginated allowlist participants with total count and has_more metadata. Limit silently capped at 50.",
        "parameters": [
          {
            "name": "offset",
            "type": "u32",
            "description": "Zero-based start index"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Maximum number of results (capped at 50)"
          }
        ],
        "returns": {
          "type": "ParticipantListPage",
          "description": "Page of allowlisted addresses with items, total, offset, and has_more fields"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "query_blocklist",
        "description": "Get paginated blocklist participants with total count and has_more metadata. Limit silently capped at 50.",
        "parameters": [
          {
            "name": "offset",
            "type": "u32",
            "description": "Zero-based start index"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Maximum number of results (capped at 50)"
          }
        ],
        "returns": {
          "type": "ParticipantListPage",
          "description": "Page of blocklisted addresses with items, total, offset, and has_more fields"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_escrow",
        "description": "Get escrow details by bounty ID",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          }
        ],
        "returns": {
          "type": "Escrow",
          "description": "Escrow record"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_capability",
        "description": "Get capability details by ID",
        "parameters": [
          {
            "name": "capability_id",
            "type": "u64",
            "description": "Capability token ID"
          }
        ],
        "returns": {
          "type": "Capability",
          "description": "Capability record"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_fee_config",
        "description": "Get current fee configuration",
        "parameters": [],
        "returns": {
          "type": "FeeConfig",
          "description": "Fee configuration"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_batch_size_caps",
        "description": "Get the effective batch size caps for batch lock and batch release",
        "parameters": [],
        "returns": {
          "type": "BatchSizeCaps",
          "description": "Current effective batch size cap configuration"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_high_value_config",
        "description": "Get the current high-value release timelock configuration, or None if not set.",
        "parameters": [],
        "returns": {
          "type": "Option<HighValueConfig>",
          "description": "Timelock threshold and duration, or None."
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_queued_release",
        "description": "Get the pending queued release for a bounty, or None if no release is queued.",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          }
        ],
        "returns": {
          "type": "Option<QueuedRelease>",
          "description": "Queued release entry (contributor, amount, executable_at), or None."
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_multisig_config",
        "description": "Get multisig configuration",
        "parameters": [],
        "returns": {
          "type": "MultisigConfig",
          "description": "Multisig configuration"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_pause_flags",
        "description": "Get current pause status",
        "parameters": [],
        "returns": {
          "type": "PauseFlags",
          "description": "Pause configuration"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "dry_run_lock",
        "description": "Simulate lock operation without state changes",
        "parameters": [
          {
            "name": "depositor",
            "type": "Address",
            "description": "Address that would lock funds"
          },
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount to lock"
          },
          {
            "name": "deadline",
            "type": "u64",
            "description": "Deadline timestamp"
          }
        ],
        "returns": {
          "type": "SimulationResult",
          "description": "Simulation outcome"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "dry_run_release",
        "description": "Simulate release operation without state changes",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "contributor",
            "type": "Address",
            "description": "Recipient address"
          }
        ],
        "returns": {
          "type": "SimulationResult",
          "description": "Simulation outcome"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "dry_run_refund",
        "description": "Simulate refund operation without state changes",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          }
        ],
        "returns": {
          "type": "SimulationResult",
          "description": "Simulation outcome"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "get_refund_eligibility_view",
        "description": "Return deterministic typed refund eligibility status, amount, and recipient preview",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          }
        ],
        "returns": {
          "type": "RefundEligibilityView",
          "description": "Eligibility state with explicit semantic code and preview fields"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "health_check",
        "description": "Get contract health status",
        "parameters": [],
        "returns": {
          "type": "HealthStatus",
          "description": "Health information"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
       {
        "name": "get_analytics",
        "description": "Get usage analytics",
        "parameters": [],
        "returns": {
          "type": "Analytics",
          "description": "Analytics data"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
       {
        "name": "is_maintenance_mode",
        "description": "Check if maintenance mode is active",
        "parameters": [],
        "returns": {
          "type": "bool",
          "description": "True if maintenance mode is enabled, false otherwise"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_high_value_config",
        "description": "Get the current high-value release timelock configuration",
        "parameters": [],
        "returns": {
          "type": "Option<HighValueConfig>",
          "description": "Threshold and duration, or None if not configured"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_queued_release",
        "description": "Get the pending queued release for a bounty, if any",
        "parameters": [
          { "name": "bounty_id", "type": "u64", "description": "Bounty identifier" }
        ],
        "returns": {
          "type": "Option<QueuedRelease>",
          "description": "Queued release record or None"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      }
    ],
    "admin": [
      {
        "name": "init",
        "description": "Initialize the contract with admin and token",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin address"
          },
          {
            "name": "token",
            "type": "AssetId",
            "description": "Token contract address"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "update_fee_config",
        "description": "Update fee configuration",
        "parameters": [
          {
            "name": "lock_fee_rate",
            "type": "Option<i128>",
            "description": "Fee rate for lock operations",
            "optional": true
          },
          {
            "name": "release_fee_rate",
            "type": "Option<i128>",
            "description": "Fee rate for release operations",
            "optional": true
          },
          {
            "name": "fee_recipient",
            "type": "Option<Address>",
            "description": "Address to receive fees",
            "optional": true
          },
          {
            "name": "fee_enabled",
            "type": "Option<bool>",
            "description": "Enable/disable fees",
            "optional": true
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "update_multisig_config",
        "description": "Update multisig configuration",
        "parameters": [
          {
            "name": "threshold_amount",
            "type": "i128",
            "description": "Amount threshold for multisig"
          },
          {
            "name": "signers",
            "type": "Vec<Address>",
            "description": "List of authorized signers"
          },
          {
            "name": "required_signatures",
            "type": "u32",
            "description": "Number of signatures required"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "approve_large_release",
        "description": "Approve large release requiring multisig",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "contributor",
            "type": "Address",
            "description": "Contributor address"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount to release"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "set_paused",
        "description": "Update pause flags for operations",
        "parameters": [
          {
            "name": "lock",
            "type": "Option<bool>",
            "description": "Pause lock operations",
            "optional": true
          },
          {
            "name": "release",
            "type": "Option<bool>",
            "description": "Pause release operations",
            "optional": true
          },
          {
            "name": "refund",
            "type": "Option<bool>",
            "description": "Pause refund operations",
            "optional": true
          },
          {
            "name": "reason",
            "type": "Option<String>",
            "description": "Reason for pausing",
            "optional": true
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "set_claim_window",
        "description": "Set claim window duration. Emits ClaimWindowSet audit event. Set to 0 to disable enforcement.",
        "parameters": [
          {
            "name": "claim_window",
            "type": "u64",
            "description": "Seconds beneficiary has to claim after authorization. 0 disables enforcement."
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
       },
       {
         "name": "set_maintenance_mode",
         "description": "Update maintenance mode (admin only)",
         "parameters": [
           {
             "name": "enabled",
             "type": "bool",
             "description": "Enable or disable maintenance mode"
           },
           {
             "name": "reason",
             "type": "Option<String>",
             "description": "Optional reason for the change",
             "optional": true
           }
         ],
         "returns": {
           "type": "()",
           "description": "Empty on success"
         },
         "authorization": "admin",
         "pausable": false,
         "gas_estimate": "medium"
       },
       {
         "name": "emergency_withdraw",
        "description": "Emergency withdraw all funds (requires lock_paused=true)",
        "parameters": [
          {
            "name": "target",
            "type": "Address",
            "description": "Address to receive funds"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "high"
      },
       {
        "name": "update_risk_flags",
        "description": "Updates the risk flags for a specific bounty (replaces entire bitmask)",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "new_flags",
            "type": "u32",
            "description": "New bitmask of risk flags (bits outside RISK_FLAG_MASK_ALL are rejected)"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_escrow_risk_flags",
        "description": "OR flag_bits onto stored risk flags for a bounty (admin only). Returns updated EscrowMetadata.",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier (metadata created with zero defaults if absent)"
          },
          {
            "name": "flag_bits",
            "type": "u32",
            "description": "Bits to set; rejected if outside RISK_FLAG_MASK_ALL"
          }
        ],
        "returns": {
          "type": "EscrowMetadata",
          "description": "Updated metadata reflecting new flag state"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "clear_escrow_risk_flags",
        "description": "AND-NOT flag_bits from stored risk flags for a bounty (admin only). Returns updated EscrowMetadata.",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "flag_bits",
            "type": "u32",
            "description": "Bits to clear; rejected if outside RISK_FLAG_MASK_ALL"
          }
        ],
        "returns": {
          "type": "EscrowMetadata",
          "description": "Updated metadata reflecting new flag state"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "update_metadata",
        "description": "Write repo_id, issue_id, bounty_type, and reference_hash for a bounty. Caller must be admin or a registered governor. Preserves risk_flags and notification_prefs.",
        "parameters": [
          {
            "name": "caller",
            "type": "Address",
            "description": "Address performing the update; must be admin or governor"
          },
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "repo_id",
            "type": "u64",
            "description": "Repository identifier"
          },
          {
            "name": "issue_id",
            "type": "u64",
            "description": "Issue identifier"
          },
          {
            "name": "bounty_type",
            "type": "String",
            "description": "Bounty type tag (max 50 chars)"
          },
          {
            "name": "reference_hash",
            "type": "Option<Bytes>",
            "description": "Optional content-addressed reference hash",
            "optional": true
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin-or-governor",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_metadata",
        "description": "Returns full EscrowMetadata for a bounty; zeroed defaults when absent",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          }
        ],
        "returns": {
          "type": "EscrowMetadata",
          "description": "Full metadata record"
        },
        "authorization": "none",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "add_risk_governor",
        "description": "Adds an address to the risk-flag governor list (admin only, max 16 entries)",
        "parameters": [
          {
            "name": "governor",
            "type": "Address",
            "description": "Address to authorize for risk-flag mutations"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_escrow_risk_flags",
        "description": "Sets specific risk flag bits using OR operation (granular governance)",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "flags_to_set",
            "type": "u32",
            "description": "Bitmask of flags to set (OR operation)"
          }
        ],
        "returns": {
          "type": "EscrowMetadata",
          "description": "Updated metadata with new risk flags"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "clear_escrow_risk_flags",
        "description": "Clears specific risk flag bits using AND NOT operation (granular governance)",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "flags_to_clear",
            "type": "u32",
            "description": "Bitmask of flags to clear (AND NOT operation)"
          }
        ],
        "returns": {
          "type": "EscrowMetadata",
          "description": "Updated metadata with cleared risk flags"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "update_metadata",
        "description": "Updates metadata fields for a bounty with validation",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin address (must be authorized)"
          },
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "repo_id",
            "type": "u64",
            "description": "Repository ID"
          },
          {
            "name": "issue_id",
            "type": "u64",
            "description": "Issue ID"
          },
          {
            "name": "bounty_type",
            "type": "String",
            "description": "Bounty type tag (1-50 characters)"
          },
          {
            "name": "reference_hash",
            "type": "Option<Bytes>",
            "description": "Optional reference hash for the bounty",
            "optional": true
          }
        ],
        "returns": {
          "type": "EscrowMetadata",
          "description": "Updated metadata"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_maintenance_mode",
        "description": "Toggle global maintenance mode",
        "parameters": [
          {
            "name": "enabled",
            "type": "bool",
            "description": "Enable or disable maintenance mode"
          },
          {
            "name": "reason",
            "type": "Option<String>",
            "description": "Reason for maintenance mode toggle",
            "optional": true
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_high_value_config",
        "description": "Configure the threshold and delay for high-value releases",
        "parameters": [
          { "name": "threshold", "type": "i128", "description": "Amount triggering the timelock" },
          { "name": "duration", "type": "u64", "description": "Timelock duration in seconds" }
        ],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_batch_size_caps",
        "description": "Set independent runtime caps for batch_lock_funds and batch_release_funds. Both caps must satisfy 1 <= cap <= MAX_BATCH_SIZE (20). Emits BatchSizeCapsUpdated.",
        "parameters": [
          {
            "name": "lock_cap",
            "type": "u32",
            "description": "Maximum items allowed in a single batch_lock_funds call (1..=20)"
          },
          {
            "name": "release_cap",
            "type": "u32",
            "description": "Maximum items allowed in a single batch_release_funds call (1..=20)"
          }
        ],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_high_value_config",
        "description": "Configure the high-value release timelock. Releases at or above threshold are queued for duration seconds before execution. Emits HighValueConfigUpdated.",
        "parameters": [
          {
            "name": "threshold",
            "type": "i128",
            "description": "Minimum amount (inclusive) that triggers the timelock queue. Must be > 0."
          },
          {
            "name": "duration",
            "type": "u64",
            "description": "Delay in seconds before a queued release becomes executable. Must be > 0."
          }
        ],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "cancel_queued_release",
        "description": "Cancel a pending queued high-value release. The escrow remains Locked. Emits ReleaseQueueCancelled.",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty whose queued release should be cancelled."
          }
        ],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "execute_queued_release",
        "description": "Execute a queued high-value release once its timelock has elapsed. Permissionless — anyone may call after executable_at. Respects maintenance mode and release pause flags. Respects escrow freeze and contributor address freeze. Applies release fees consistently with release_funds. Emits QueuedReleaseExecuted.",
        "parameters": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty whose queued release should be executed."
          }
        ],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "any",
        "pausable": true,
        "gas_estimate": "medium"
      }
    ]
  },
  "view_entrypoints_fee_routing": [
    {
      "name": "get_fee_routing",
      "description": "Return the per-bounty fee routing override for bounty_id, or None when no override is set.",
      "parameters": [
        {
          "name": "bounty_id",
          "type": "u64",
          "description": "Bounty identifier"
        }
      ],
      "returns": {
        "type": "Option<PerBountyFeeRouting>",
        "description": "Per-bounty routing config, or None if using global routing."
      },
      "authorization": "any",
      "pausable": false,
      "gas_estimate": "low"
    }
  ],
  "configuration": {
    "parameters": [
      {
        "name": "MAX_FEE_RATE",
        "type": "i128",
        "default_value": "1000",
        "description": "Maximum fee rate (10% = 1000 basis points)",
        "constraints": "0 <= value <= 1000",
        "admin_only": false
      },
      {
        "name": "MAX_BATCH_SIZE",
        "type": "u32",
        "default_value": "20",
        "description": "Compile-time hard upper bound for admin-configurable batch caps",
        "constraints": "value = 20",
        "admin_only": false
      },
      {
        "name": "batch_lock_cap",
        "type": "u32",
        "default_value": "20",
        "description": "Effective runtime cap for batch_lock_funds",
        "constraints": "1 <= value <= MAX_BATCH_SIZE",
        "admin_only": true
      },
      {
        "name": "batch_release_cap",
        "type": "u32",
        "default_value": "20",
        "description": "Effective runtime cap for batch_release_funds",
        "constraints": "1 <= value <= MAX_BATCH_SIZE",
        "admin_only": true
      },
      {
        "name": "lock_fee_rate",
        "type": "i128",
        "default_value": "0",
        "description": "Fee rate for lock operations in basis points",
        "constraints": "0 <= value <= MAX_FEE_RATE",
        "admin_only": true
      },
      {
        "name": "release_fee_rate",
        "type": "i128",
        "default_value": "0",
        "description": "Fee rate for release operations in basis points",
        "constraints": "0 <= value <= MAX_FEE_RATE",
        "admin_only": true
      },
      {
        "name": "fee_enabled",
        "type": "bool",
        "default_value": "false",
        "description": "Whether fees are enabled",
        "admin_only": true
      },
      {
        "name": "claim_window",
        "type": "u64",
        "default_value": "86400",
        "description": "Seconds beneficiary has to claim after authorization",
        "constraints": "value > 0",
        "admin_only": true
      },
      {
        "name": "admin_rotation_timelock_duration",
        "type": "u64",
        "default_value": "86400",
        "description": "Delay in seconds before a pending admin can accept a rotation",
        "constraints": "3600 <= value <= 2592000",
        "admin_only": true
      },
      {
        "name": "MAX_PARTICIPANT_FILTER_PAGE_SIZE",
        "type": "u32",
        "default_value": "50",
        "description": "Hard upper bound on addresses returned per query_whitelist / query_blocklist call. Callers passing a larger limit are silently capped.",
        "constraints": "value = 50",
        "admin_only": false
      }
    ],
    "storage_keys": [
      {
        "name": "Admin",
        "type": "instance",
        "description": "Administrator address",
        "data_structure": "Address"
      },
      {
        "name": "Token",
        "type": "instance",
        "description": "Token contract address",
        "data_structure": "Address"
      },
      {
        "name": "Escrow",
        "type": "persistent",
        "description": "Escrow records by bounty ID",
        "data_structure": "Escrow"
      },
      {
        "name": "Metadata",
        "type": "persistent",
        "description": "Escrow metadata by bounty ID",
        "data_structure": "EscrowMetadata"
      },
      {
        "name": "FeeConfig",
        "type": "instance",
        "description": "Fee configuration",
        "data_structure": "FeeConfig"
      },
      {
        "name": "MultisigConfig",
        "type": "instance",
        "description": "Multisig configuration",
        "data_structure": "MultisigConfig"
      },
      {
        "name": "PauseFlags",
        "type": "instance",
        "description": "Pause configuration",
        "data_structure": "PauseFlags"
      },
      {
        "name": "Capability",
        "type": "persistent",
        "description": "Capability tokens by ID",
        "data_structure": "Capability"
      },
      {
        "name": "RefundEligibilitySchemaVersion",
        "type": "instance",
        "description": "Version marker for refund eligibility view semantics",
        "data_structure": "u32"
      },
      {
        "name": "MaintenanceMode",
        "type": "instance",
        "description": "Maintenance mode flag (explicitly initialized)",
        "data_structure": "bool"
      },
      {
        "name": "MaintenanceModeUpdatedAt",
        "type": "instance",
        "description": "Timestamp when maintenance mode last changed",
        "data_structure": "u64"
      },
      {
        "name": "MaintenanceModeUpdatedBy",
        "type": "instance",
        "description": "Admin address that last changed maintenance mode",
        "data_structure": "Address"
      },
      {
        "name": "MaintenanceModeSchemaVersion",
        "type": "instance",
        "description": "Version marker for maintenance mode semantics",
        "data_structure": "u32"
      },
      {
        "name": "ReentrancyGuard",
        "type": "temporary",
        "description": "Reentrancy protection flag",
        "data_structure": "bool"
      },
      {
        "name": "WhitelistIndex",
        "type": "instance",
        "description": "Paginated index of allowlisted addresses",
        "data_structure": "Vec<Address>"
      },
      {
        "name": "BlocklistIndex",
        "type": "instance",
        "description": "Paginated index of blocklisted addresses",
        "data_structure": "Vec<Address>"
      },
      {
        "name": "ParticipantListSchemaVersion",
        "type": "instance",
        "description": "Upgrade-safe marker for participant list (whitelist/blocklist) storage semantics. Initialized to 1 during init().",
        "data_structure": "u32"
      },
      {
        "name": "HighValueConfig",
        "type": "instance",
        "description": "High-value release timelock configuration (threshold and duration). When set, releases at or above threshold are queued.",
        "data_structure": "HighValueConfig"
      },
      {
        "name": "QueuedRelease",
        "type": "persistent",
        "description": "Per-bounty queued release entry awaiting timelock expiry. Keyed by bounty_id.",
        "data_structure": "QueuedRelease"
      },
      {
        "name": "HighValueConfigSchemaVersion",
        "type": "instance",
        "description": "Upgrade-safe schema marker for high-value timelock config storage layout. Initialized to 1 during init(). Increment when HighValueConfig or QueuedRelease layout changes.",
        "data_structure": "u32"
      }
    ]
  },
  "behaviors": {
    "security_features": [
      "Reentrancy protection using shared guard",
      "Rate limiting with configurable windows and thresholds",
      "Capability-based authorization for delegated operations",
      "Multisig support for large releases",
      "Comprehensive pause functionality",
      "Anti-abuse mechanisms with whitelisting",
      "Input validation for all parameters",
      "Overflow protection in arithmetic operations",
      "Event emission for audit trail",
      "Deterministic refund eligibility view semantics",
      "Deterministic maintenance mode semantics with audit events"
    ],
    "access_control": [
      {
        "mechanism": "admin_auth",
        "description": "Single admin with full control over contract",
        "configuration": "Set during initialization, immutable afterwards"
      },
      {
        "mechanism": "capability",
        "description": "Delegated authorization through capability tokens",
        "configuration": "Admin issues capabilities with specific permissions and limits"
      },
      {
        "mechanism": "multisig",
        "description": "Multiple signatures required for large releases",
        "configuration": "Configurable threshold and signer list"
      },
      {
        "mechanism": "whitelist",
        "description": "Prevents abuse through operation frequency limits",
        "configuration": "Configurable window size and operation limits"
      }
    ],
    "critical_behaviors": [
      {
        "behavior": "Reentrancy protection",
        "impact": "Prevents recursive calls that could drain funds",
        "mitigation": "Shared reentrancy guard with acquire/release pattern"
      },
      {
        "behavior": "Fee calculation",
        "impact": "Fees are deducted from amounts and sent to recipient",
        "mitigation": "Floor rounding ensures fees don't exceed configured rates"
      },
      {
        "behavior": "Batch operations",
        "impact": "All operations succeed or fail together (atomic)",
        "mitigation": "Rollback on any failure in the batch"
      },
      {
        "behavior": "Capability expiration",
        "impact": "Expired capabilities cannot be used",
        "mitigation": "Timestamp validation on every capability use"
      },
      {
        "behavior": "Claim period",
        "impact": "Funds must be claimed within configured window",
        "mitigation": "Automatic expiration and refund after window"
      }
    ],
    "error_handling": [
      {
        "error_code": "AlreadyInitialized",
        "scenario": "Attempting to initialize an already initialized contract",
        "resolution": "Contract can only be initialized once"
      },
      {
        "error_code": "NotInitialized",
        "scenario": "Calling admin functions before initialization",
        "resolution": "Initialize contract with admin and token addresses"
      },
      {
        "error_code": "Unauthorized",
        "scenario": "Caller lacks required permissions",
        "resolution": "Ensure caller is admin, capability holder, or authorized signer"
      },
      {
        "error_code": "InsufficientFunds",
        "scenario": "Contract doesn't have enough tokens for operation",
        "resolution": "Ensure sufficient tokens are locked in escrow"
      },
      {
        "error_code": "DeadlineNotPassed",
        "scenario": "Attempting refund before deadline",
        "resolution": "Wait until deadline passes before refunding"
      },
      {
        "error_code": "FundsPaused",
        "scenario": "Operation is paused by admin",
        "resolution": "Wait for admin to unpause or contact admin"
      },
      {
        "error_code": "InvalidFeeRate",
        "scenario": "Fee rate exceeds maximum allowed",
        "resolution": "Use fee rate within allowed range (0-1000 basis points)"
      }
    ],
    "gas_considerations": [
      {
        "operation": "lock_funds",
        "cost_level": "medium",
        "notes": "Involves token transfer and storage writes"
      },
      {
        "operation": "release_funds",
        "cost_level": "medium",
        "notes": "Involves token transfer and storage updates"
      },
      {
        "operation": "batch_lock_funds",
        "cost_level": "high",
        "notes": "Multiple token transfers and storage writes"
      },
      {
        "operation": "batch_release_funds",
        "cost_level": "high",
        "notes": "Multiple token transfers and storage updates"
      },
      {
        "operation": "emergency_withdraw",
        "cost_level": "high",
        "notes": "Large token transfer of all contract balance"
      },
      {
        "operation": "view functions",
        "cost_level": "low",
        "notes": "Only storage reads, no state changes"
      }
    ],
    "events": [
      {
        "name": "BountyEscrowInitialized",
        "description": "Contract initialization event",
        "data": [
          {
            "name": "version",
            "type": "u32",
            "description": "Contract version"
          },
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin address"
          },
          {
            "name": "token",
            "type": "Address",
            "description": "Token address"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Initialization timestamp"
          }
        ],
        "trigger": "Contract initialization"
      },
      {
        "name": "FundsLocked",
        "description": "Funds locked in escrow",
        "data": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "depositor",
            "type": "Address",
            "description": "Depositor address"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount locked"
          },
          {
            "name": "deadline",
            "type": "u64",
            "description": "Refund deadline"
          }
        ],
        "trigger": "Successful lock_funds call"
      },
      {
        "name": "FundsReleased",
        "description": "Funds released from escrow",
        "data": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "contributor",
            "type": "Address",
            "description": "Recipient address"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount released"
          }
        ],
        "trigger": "Successful release_funds call"
      },
      {
        "name": "FundsRefunded",
        "description": "Funds refunded to depositor",
        "data": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "depositor",
            "type": "Address",
            "description": "Refund recipient"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount refunded"
          }
        ],
        "trigger": "Successful refund_funds call"
      },
      {
        "name": "AdminRotationProposed",
        "description": "Current admin proposed a pending admin rotation",
        "data": [
          {
            "name": "current_admin",
            "type": "Address",
            "description": "Current active admin"
          },
          {
            "name": "pending_admin",
            "type": "Address",
            "description": "Pending admin that may accept after the timelock"
          },
          {
            "name": "timelock_duration",
            "type": "u64",
            "description": "Configured delay in seconds"
          },
          {
            "name": "execute_after",
            "type": "u64",
            "description": "Timestamp when acceptance becomes valid"
          }
        ],
        "trigger": "Successful propose_admin_rotation call"
      },
      {
        "name": "AdminRotationAccepted",
        "description": "Pending admin accepted and became the new active admin",
        "data": [
          {
            "name": "previous_admin",
            "type": "Address",
            "description": "Admin before the rotation completed"
          },
          {
            "name": "new_admin",
            "type": "Address",
            "description": "New active admin"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Acceptance timestamp"
          }
        ],
        "trigger": "Successful accept_admin_rotation call"
      },
      {
        "name": "AdminRotationCancelled",
        "description": "Current admin cancelled a pending admin rotation",
        "data": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin that cancelled the pending rotation"
          },
          {
            "name": "cancelled_pending_admin",
            "type": "Address",
            "description": "Pending admin that was cleared"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Cancellation timestamp"
          }
        ],
        "trigger": "Successful cancel_admin_rotation call"
      },
      {
        "name": "AdminRotationTimelockUpdated",
        "description": "Admin-rotation timelock duration was updated",
        "data": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin that updated the timelock configuration"
          },
          {
            "name": "previous_duration",
            "type": "u64",
            "description": "Prior timelock duration"
          },
          {
            "name": "new_duration",
            "type": "u64",
            "description": "New timelock duration"
          }
        ],
        "trigger": "Successful set_admin_rotation_timelock_duration call"
      },
      {
        "name": "RefundApprovalSet",
        "description": "Admin refund approval created or updated",
        "data": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Approved refund amount"
          },
          {
            "name": "recipient",
            "type": "Address",
            "description": "Approved refund recipient"
          }
        ],
        "trigger": "Successful approve_refund call"
      },
      {
        "name": "RefundApprovalConsumed",
        "description": "Stored refund approval consumed by refund execution",
        "data": [
          {
            "name": "bounty_id",
            "type": "u64",
            "description": "Bounty identifier"
          },
          {
            "name": "refunded_amount",
            "type": "i128",
            "description": "Amount refunded using stored approval"
          }
        ],
        "trigger": "Successful refund call with admin approval record"
      },
       {
        "name": "MaintenanceModeChangedV2",
        "description": "Maintenance mode toggled with previous state (audit-friendly)",
        "data": [
          {
            "name": "previous_enabled",
            "type": "bool",
            "description": "Previous maintenance mode state"
          },
          {
            "name": "enabled",
            "type": "bool",
            "description": "New maintenance mode state"
          },
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin who toggled maintenance mode"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Ledger timestamp"
          }
        ],
        "trigger": "Admin toggles maintenance mode (state change only)"
      },
      {
        "name": "ParticipantFilterQueried",
        "description": "Emitted on every query_whitelist / query_blocklist call for off-chain audit trails",
        "data": [
          {
            "name": "list_type",
            "type": "ParticipantFilterListType",
            "description": "Which list was queried (Allowlist or Blocklist)"
          },
          {
            "name": "offset",
            "type": "u32",
            "description": "Zero-based start index used in this query"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Effective limit after applying MAX_PARTICIPANT_FILTER_PAGE_SIZE cap"
          },
          {
            "name": "result_count",
            "type": "u32",
            "description": "Number of addresses returned in this page"
          },
          {
            "name": "total",
            "type": "u32",
            "description": "Total number of addresses in the list at query time"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Ledger timestamp"
          }
        ],
        "trigger": "Every call to query_whitelist or query_blocklist"
      }
    ]
  },
  "dependencies": {
    "contracts": [
      {
        "contract_name": "grainlify_core",
        "interface": "asset::AssetId",
        "purpose": "Asset normalization and validation"
      }
    ],
    "tokens": [
      {
        "token_standard": "SAC",
        "purpose": "Escrow token for locking and releasing funds",
        "requirements": [
          "Must support transfer function",
          "Must support balance function",
          "Must be approved for contract operations"
        ]
      }
    ],
    "external_apis": []
  },
  "deployment": {
    "networks": [],
    "initialization": {
      "steps": [
        {
          "step": 1,
          "description": "Deploy contract to Stellar network",
          "command": "stellar contract deploy --wasm target/wasm32-unknown-unknown/release/bounty_escrow.wasm",
          "notes": "Save contract ID from deployment output"
        },
        {
          "step": 2,
          "description": "Initialize contract with admin and token",
          "command": "stellar contract invoke --id CONTRACT_ID -- init --admin ADMIN_ADDRESS --token TOKEN_ADDRESS",
          "notes": "Admin address should be secure (hardware wallet recommended)"
        },
        {
          "step": 3,
          "description": "Configure fee settings if needed",
          "command": "stellar contract invoke --id CONTRACT_ID -- update_fee_config --lock_fee_rate 10 --release_fee_rate 5 --fee_recipient FEE_RECIPIENT --fee_enabled true",
          "notes": "Optional: configure fees according to your needs"
        },
        {
          "step": 4,
          "description": "Set up multisig if required",
          "command": "stellar contract invoke --id CONTRACT_ID -- update_multisig_config --threshold_amount 1000000000 --signers SIGNER1,SIGNER2,SIGNER3 --required_signatures 2",
          "notes": "Optional: configure multisig for large releases"
        },
        {
          "step": 5,
          "description": "Optionally tune the admin-rotation timelock",
          "command": "stellar contract invoke --id CONTRACT_ID -- set_admin_rotation_timelock_duration --duration 86400",
          "notes": "Recommended for governance hardening before transferring long-lived admin control"
        }
      ],
      "prerequisites": [
        "Admin address (secure, preferably hardware wallet)",
        "Token contract address",
        "Sufficient XLM for deployment fees",
        "Token approval for contract operations"
      ]
    },
    "upgrade_process": {
      "steps": [
        {
          "step": 1,
          "description": "Build new contract version",
          "command": "cargo build --release --target wasm32-unknown-unknown",
          "notes": "Ensure all tests pass before building"
        },
        {
          "step": 2,
          "description": "Upload new WASM to Stellar",
          "command": "stellar contract install --wasm target/wasm32-unknown-unknown/release/bounty_escrow.wasm",
          "notes": "Save the WASM hash from output"
        },
        {
          "step": 3,
          "description": "Test upgrade on testnet first",
          "command": "stellar contract invoke --id TESTNET_CONTRACT_ID -- upgrade --new_wasm_hash WASM_HASH",
          "notes": "Verify all functionality works on testnet"
        },
        {
          "step": 4,
          "description": "Perform mainnet upgrade",
          "command": "stellar contract invoke --id MAINNET_CONTRACT_ID -- upgrade --new_wasm_hash WASM_HASH",
          "notes": "Ensure admin authorization"
        },
        {
          "step": 5,
          "description": "Update version number",
          "command": "stellar contract invoke --id CONTRACT_ID -- set_version --new_version 2.1.0",
          "notes": "Track version changes for audit trail"
        }
      ],
      "rollback_procedure": "Keep previous WASM hash to enable emergency rollback by calling upgrade with previous hash",
      "testing_requirements": [
        "Test all entrypoints on testnet",
        "Verify fee calculations work correctly",
        "Test pause/unpause functionality",
        "Verify capability system works",
        "Test batch operations",
        "Verify reentrancy protection"
      ]
    }
  },
  "testing": {
    "test_coverage": {
      "unit_tests": "95%",
      "integration_tests": "90%",
      "test_files": [
        "test_bounty_escrow.rs",
        "test_rbac.rs",
        "test_batch_failure_modes.rs",
        "test_reentrancy_guard.rs",
        "test_metadata.rs",
        "test_pause.rs",
        "test_dispute_resolution.rs",
        "test_deadline_variants.rs",
        "test_blacklist_and_whitelist.rs",
        "test_cross_contract_interface.rs",
        "test_lifecycle.rs",
        "test_status_transitions.rs",
        "test_state_verification.rs",
        "test_dry_run_simulation.rs",
        "test_token_math.rs",
        "test_multi_token_fees.rs",
        "test_front_running_ordering.rs",
        "test_upgrade_scenarios.rs",
        "test_expiration_and_dispute.rs",
        "test_auto_refund_permissions.rs",
        "test_granular_pause.rs",
        "test_query_filters.rs",
        "test_capability_tokens.rs",
        "test_metadata_tagging.rs",
        "test_partial_payout_rounding.rs",
        "test_gas.rs",
        "test_analytics_monitoring.rs",
        "test_filter_pagination.rs"
      ]
    },
    "test_scenarios": [
      "Complete escrow lifecycle (lock → release/refund)",
      "Batch operations with mixed success/failure",
      "Reentrancy attack prevention",
      "Rate limiting enforcement",
      "Capability issuance and usage",
      "Fee calculation and collection",
      "Pause/unpause functionality",
      "Multisig approval workflow",
      "Claim period expiration",
      "Emergency withdrawal procedures",
      "Error handling and edge cases",
      "Gas optimization scenarios"
    ]
  },
  "documentation": {
    "readme": "README.md",
    "api_docs": "QUERY_DOCUMENTATION.md",
    "examples": [
      "examples/basic_escrow.rs",
      "examples/batch_operations.rs",
      "examples/capability_usage.rs",
      "examples/multisig_setup.rs"
    ]
  }
}