program-escrow-manifest.json

{
  "$schema": "./contract-manifest-schema.json",
  "contract_name": "ProgramEscrowContract",
  "contract_purpose": "Handles hackathon and program prize pools with batch payouts, dependency management, circuit breaker protection, and comprehensive monitoring",
  "version": {
    "current": "2.8.0",
    "schema": "1.0.0",
    "history": [
      {
        "version": "1.0.0",
        "release_date": "2024-01-01",
        "changes": [
          "Initial release with basic program escrow",
          "Single program support",
          "Basic batch payout functionality"
        ]
      },
      {
        "version": "2.0.0",
        "release_date": "2024-06-01",
        "changes": [
          "Added multi-program support with registry",
          "Enhanced batch operations with atomicity",
          "Added dependency management system",
          "Implemented circuit breaker for error recovery",
          "Enhanced monitoring and analytics",
          "Added claim period functionality",
          "Improved fee configuration",
          "Added granular pause controls"
        ]
      },
      {
        "version": "2.1.0",
        "release_date": "2026-04-22",
        "changes": [
          "Added deterministic spend-threshold enforcement for single and batch payouts",
          "Added explicit spend-threshold configuration and retrieval entrypoints",
          "Reused per-program persistent config storage for upgrade-safe threshold state"
        ]
      },
      {
        "version": "2.2.0",
        "release_date": "2026-04-22",
        "changes": [
          "Hardened history pagination with deterministic limit validation and explicit range errors",
          "Centralized pagination behavior across payout, schedule, and release history queries",
          "Added upgrade-safe pagination config storage with backward-compatible defaults"
        ]
      },
      {
        "version": "2.3.0",
        "release_date": "2026-04-23",
        "changes": [
          "Hardened spend-limit threshold enforcement: enforce_spend_threshold now returns Result and emits SpendLimitExceededEvent before any token transfer",
          "Added SpendLimitSetEvent audit event emitted after every set_program_spend_threshold call",
          "Added SpendLimitExceededEvent audit event emitted on every threshold rejection",
          "Added SpendLimitSchemaVersionSet audit event emitted on init for upgrade-safe schema tracking",
          "Added SpendLimitSchemaVersion upgrade-safe storage key to instance storage",
          "Added get_spend_limit_schema_version view entrypoint",
          "Added ContractError::SpendLimitExceeded (code 904) to canonical error enum"
        ]
      },
      {
        "version": "2.5.0",
        "release_date": "2026-04-23",
        "changes": [
          "Added token allowlist enforcement: only explicitly permitted token contract addresses may be used in init_program / initialize_program when the allowlist is non-empty",
          "Empty allowlist disables enforcement (backward-compatible default — any token accepted)",
          "Added add_allowed_token(token) admin entrypoint — adds token to allowlist, emits TokenAllowlistUpdatedEvent(added=true)",
          "Added remove_allowed_token(token) admin entrypoint — removes token from allowlist, emits TokenAllowlistUpdatedEvent(added=false); removing last token re-disables enforcement",
          "Added is_token_allowed(token) view entrypoint — returns true when list is empty or token is listed",
          "Added get_allowed_tokens() view entrypoint — returns current allowlist snapshot",
          "Added get_token_allowlist_schema_version() view entrypoint — returns TOKEN_ALLOWLIST_SCHEMA_VERSION_V1 (1) for upgraded contracts, 0 for legacy",
          "Added TokenAllowlistUpdatedEvent audit event (version, token, added, updated_by, timestamp) emitted on every add/remove",
          "Added TokenRejectedEvent audit event (version, token, program_id, timestamp) emitted before panic on rejected init_program calls",
          "Added TokenAllowlistSchemaVersionSet audit event emitted once during initialize_contract for upgrade-safe schema tracking",
          "Added DataKey::TokenAllowlist and DataKey::TokenAllowlistSchemaVersion upgrade-safe storage keys",
          "Added TOKEN_ALLOWLIST_SCHEMA_VERSION_V1 constant (value: 1)",
          "Added ContractError::TokenNotAllowed (code 1100), TokenAlreadyAllowed (1101), TokenNotInAllowlist (1102) to canonical error enum",
          "Deterministic error ordering preserved: allowlist check runs before any state mutation in init_program",
          "Added 22 targeted tests in test_token_allowlist.rs covering all branches, event fields, admin guards, and edge cases"
        ]
      },
      {
        "version": "2.7.0",
        "release_date": "2026-04-24",
        "changes": [
          "Circuit breaker enforcement moved to step 3c — before authorization and all business logic — in both single_payout_internal and batch_payout_internal",
          "Deterministic rejection: an open circuit now blocks payouts before balance, spend-threshold, or spending-window checks, producing stable client-observable failures",
          "Added get_circuit_breaker_status view entrypoint returning CircuitBreakerStatus snapshot from persistent storage",
          "Upgrade-safe: get_circuit_breaker_status returns safe defaults for legacy deployments with no circuit breaker state",
          "Added ContractError::CircuitBreakerOpen (code 800) as the canonical error for circuit-open rejections",
          "Removed duplicate step-7 circuit breaker block from batch_payout_internal",
          "Updated validation-precedence comments in both payout internals to reflect new ordering"
        ]
      },
      {
        "version": "2.6.0",
        "release_date": "2026-04-24",
        "changes": [
          "Added query_payouts_by_recipient: paginated payout history filtered by recipient",
          "Added query_payouts_by_amount: paginated payout history filtered by amount range",
          "Added query_payouts_by_timestamp: paginated payout history filtered by timestamp range",
          "Added query_schedules_by_recipient: paginated release schedules filtered by recipient",
          "Added query_schedules_by_status: paginated release schedules filtered by status",
          "Added query_releases_by_recipient: paginated release history filtered by recipient",
          "Pagination enforces limit 1\u2013200 via HistoryPaginationConfig with upgrade-safe storage",
          "Implemented batch_lock and batch_release with full atomicity and deterministic ordering",
          "Hardened batch operations with explicit error handling and reentrancy protection",
          "Fixed syntax errors in BatchError definition",
          "Added BatchFundsLocked and BatchFundsReleased audit events",
          "Enhanced test coverage for batch edge cases"
        ]
      },
      {
        "version": "2.8.0",
        "release_date": "2026-04-25",
        "changes": [
          "Added scheduled releases trigger with deterministic behavior: all due schedules processed in ascending schedule_id order for replay-identical execution",
          "Implemented upgrade-safe trigger execution storage: ReleaseTriggerSchemaVersion tracks schema evolution and enables backward-compatible migrations",
          "Added explicit release trigger error codes: ReleaseTriggerFailed (905), NoSchedulesDue (906), DeterminismViolation (907)",
          "Added get_release_trigger_schema_version() view entrypoint: returns RELEASE_TRIGGER_SCHEMA_VERSION_V1 (1) for upgraded contracts, 0 for legacy",
          "Enhanced trigger_program_releases_internal documentation with deterministic behavior guarantees, explicit error semantics, and upgrade-safe storage notes",
          "Maintained backward compatibility: legacy contracts without trigger schema version default to 0 and continue operating",
          "Circuit breaker enforcement integrated into trigger path before all business logic for consistent error precedence",
          "All trigger events include version and timestamp for audit trail: ScheduleReleasedEvent, ScheduleTriggerSummaryEvent"
        ]
      }
    ]
  },
  "entrypoints": {
    "public": [
      {
        "name": "init_program",
        "description": "Initialize a new program with authorized payout key",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Unique program identifier"
          },
          {
            "name": "authorized_payout_key",
            "type": "Address",
            "description": "Address authorized to make payouts"
          },
          {
            "name": "token_address",
            "type": "Address",
            "description": "Token contract address"
          }
        ],
        "returns": {
          "type": "ProgramData",
          "description": "Initialized program data"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "initialize_program",
        "description": "Initialize program with metadata and fee configuration",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Unique program identifier"
          },
          {
            "name": "authorized_payout_key",
            "type": "Address",
            "description": "Address authorized to make payouts"
          },
          {
            "name": "token_address",
            "type": "Address",
            "description": "Token contract address"
          },
          {
            "name": "metadata",
            "type": "String",
            "description": "Program metadata",
            "optional": true
          },
          {
            "name": "fee_config",
            "type": "FeeConfig",
            "description": "Fee configuration",
            "optional": true
          }
        ],
        "returns": {
          "type": "ProgramData",
          "description": "Initialized program data"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "batch_initialize_programs",
        "description": "Initialize multiple programs in one transaction",
        "parameters": [
          {
            "name": "items",
            "type": "Vec<ProgramInitItem>",
            "description": "Array of program initialization requests"
          }
        ],
        "returns": {
          "type": "u32",
          "description": "Number of successfully initialized programs"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "high"
      },
      {
        "name": "lock_program_funds",
        "description": "Lock prize pool funds for a program",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier",
            "optional": true
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount to lock"
          }
        ],
        "returns": {
          "type": "ProgramData",
          "description": "Updated program data"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "batch_payout",
        "description": "Distribute prizes to multiple winners with optional idempotency key for retry safety",
        "parameters": [
          {
            "name": "winners",
            "type": "Vec<Address>",
            "description": "Array of winner addresses"
          },
          {
            "name": "amounts",
            "type": "Vec<i128>",
            "description": "Corresponding prize amounts"
          },
          {
            "name": "idempotency_key",
            "type": "Option<String>",
            "description": "Optional idempotency key for deterministic retry behavior",
            "optional": true
          }
        ],
        "returns": {
          "type": "Vec<PayoutRecord>",
          "description": "Array of payout records"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "high"
      },
      {
        "name": "try_batch_payout",
        "description": "Typed batch payout — returns Result<ProgramData, BatchPayoutError> instead of panicking. All pre-validation (zero amounts, duplicates, overflow) runs before any token transfer.",
        "parameters": [
          {
            "name": "recipients",
            "type": "Vec<Address>",
            "description": "Array of recipient addresses (must be unique)"
          },
          {
            "name": "amounts",
            "type": "Vec<i128>",
            "description": "Corresponding payout amounts (all must be > 0)"
          }
        ],
        "returns": {
          "type": "Result<ProgramData, BatchPayoutError>",
          "description": "Updated program data on success, typed error on failure"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "high"
      },
      {
        "name": "single_payout",
        "description": "Distribute prize to single winner with optional idempotency key for retry safety",
        "parameters": [
          {
            "name": "winner",
            "type": "Address",
            "description": "Winner address"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Prize amount"
          },
          {
            "name": "idempotency_key",
            "type": "Option<String>",
            "description": "Optional idempotency key for deterministic retry behavior",
            "optional": true
          }
        ],
        "returns": {
          "type": "PayoutRecord",
          "description": "Payout record"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "single_payout_idempotent",
        "description": "Distribute prize to single winner with idempotency key. Panics with 'Payout already processed' if the key was already used for a successful payout — callers should treat this as a success.",
        "parameters": [
          {
            "name": "idempotency_key",
            "type": "String",
            "description": "Caller-supplied opaque string used to deduplicate payout submissions. Must be unique per logical payout."
          },
          {
            "name": "recipient",
            "type": "Address",
            "description": "Winner address"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Prize amount"
          }
        ],
        "returns": {
          "type": "ProgramData",
          "description": "Updated program data"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "medium",
        "security_notes": [
          "Idempotency check runs before all state reads — duplicate submissions are rejected cheaply.",
          "Key is stored in persistent storage after all token transfers succeed (CEI ordering).",
          "Persistent storage ensures keys survive contract upgrades."
        ]
      },
      {
        "name": "batch_payout_idempotent",
        "description": "Distribute prizes to multiple winners with idempotency key. Panics with 'Payout already processed' if the key was already used for a successful batch payout.",
        "parameters": [
          {
            "name": "idempotency_key",
            "type": "String",
            "description": "Caller-supplied opaque string used to deduplicate batch payout submissions."
          },
          {
            "name": "recipients",
            "type": "Vec<Address>",
            "description": "Array of winner addresses"
          },
          {
            "name": "amounts",
            "type": "Vec<i128>",
            "description": "Corresponding prize amounts"
          }
        ],
        "returns": {
          "type": "ProgramData",
          "description": "Updated program data"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "high",
        "security_notes": [
          "Idempotency check runs before all state reads — duplicate submissions are rejected cheaply.",
          "Key is stored in persistent storage after all token transfers succeed (CEI ordering).",
          "Persistent storage ensures keys survive contract upgrades."
        ]
      },
      {
        "name": "set_program_spend_threshold",
        "description": "Set per-program maximum spend for a single payout operation (single amount or batch total)",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "threshold_amount",
            "type": "i128",
            "description": "Maximum allowed gross spend per payout operation"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_program_spending_limit",
        "description": "Set or update the per-window spending limit for a program. Only the program's authorized_payout_key may call this.",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "window_size",
            "type": "u64",
            "description": "Window length in seconds (must be > 0)"
          },
          {
            "name": "max_amount",
            "type": "i128",
            "description": "Maximum total releasable in one window (must be >= 0)"
          },
          {
            "name": "enabled",
            "type": "bool",
            "description": "If false, config is stored but not enforced"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "authorized_payout_key",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_program_dependencies",
        "description": "Set dependencies for a program",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "dependency_ids",
            "type": "Vec<String>",
            "description": "List of dependency IDs"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "clear_program_dependencies",
        "description": "Clear all dependencies for a program",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "set_dependency_status",
        "description": "Set status for a dependency",
        "parameters": [
          {
            "name": "dependency_id",
            "type": "String",
            "description": "Dependency identifier"
          },
          {
            "name": "status",
            "type": "DependencyStatus",
            "description": "Dependency status"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "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": "emergency_withdraw",
        "description": "Emergency withdraw all program funds",
        "parameters": [
          {
            "name": "target",
            "type": "Address",
            "description": "Address to receive funds"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "high"
      }
    ],
    "view": [
      {
        "name": "program_exists",
        "description": "Check if any program exists",
        "parameters": [],
        "returns": {
          "type": "bool",
          "description": "True if program exists"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "program_exists_by_id",
        "description": "Check if specific program exists",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          }
        ],
        "returns": {
          "type": "bool",
          "description": "True if program exists"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_program_dependencies",
        "description": "Get dependencies for a program",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          }
        ],
        "returns": {
          "type": "Vec<String>",
          "description": "List of dependency IDs"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_dependency_status",
        "description": "Get status of a dependency",
        "parameters": [
          {
            "name": "dependency_id",
            "type": "String",
            "description": "Dependency identifier"
          }
        ],
        "returns": {
          "type": "DependencyStatus",
          "description": "Dependency status"
        },
        "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": "get_program_spend_threshold",
        "description": "Get the configured per-program spend threshold",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          }
        ],
        "returns": {
          "type": "i128",
          "description": "Maximum allowed gross spend per payout operation"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_spend_limit_schema_version",
        "description": "Return the spend-limit storage schema version written during init. Returns 0 on legacy deployments.",
        "parameters": [],
        "returns": {
          "type": "u32",
          "description": "Schema version (1 = current; 0 = legacy pre-v2.3)"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_program_spending_limit",
        "description": "Return the per-window spending limit configuration for a program, or None if not set.",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          }
        ],
        "returns": {
          "type": "Option<ProgramSpendingConfig>",
          "description": "Spending limit config (window_size, max_amount, enabled), or None"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_program_spending_state",
        "description": "Return the current window state for a program's spending limit, or None if no payout has occurred yet.",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          }
        ],
        "returns": {
          "type": "Option<ProgramSpendingState>",
          "description": "Window state (window_start, amount_released), or None"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_program_release_schedules",
        "description": "Get release schedules for all programs",
        "parameters": [],
        "returns": {
          "type": "Vec<ProgramReleaseSchedule>",
          "description": "Array of release schedules"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "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": "get_state_snapshot",
        "description": "Get current state snapshot",
        "parameters": [],
        "returns": {
          "type": "StateSnapshot",
          "description": "State snapshot data"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_performance_stats",
        "description": "Get performance stats for a function",
        "parameters": [
          {
            "name": "function_name",
            "type": "Symbol",
            "description": "Function name to get stats for"
          }
        ],
        "returns": {
          "type": "PerformanceStats",
          "description": "Performance statistics"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "query_payouts_by_recipient",
        "description": "Paginated payout history filtered by recipient address",
        "parameters": [
          {
            "name": "recipient",
            "type": "Address",
            "description": "Recipient address to filter by"
          },
          {
            "name": "offset",
            "type": "u32",
            "description": "Number of matching records to skip"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Maximum records to return (1\u2013200)"
          }
        ],
        "returns": {
          "type": "Vec<PayoutRecord>",
          "description": "Paginated payout records for the recipient"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "query_payouts_by_amount",
        "description": "Paginated payout history filtered by amount range (inclusive)",
        "parameters": [
          {
            "name": "min_amount",
            "type": "i128",
            "description": "Minimum payout amount (inclusive)"
          },
          {
            "name": "max_amount",
            "type": "i128",
            "description": "Maximum payout amount (inclusive)"
          },
          {
            "name": "offset",
            "type": "u32",
            "description": "Number of matching records to skip"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Maximum records to return (1\u2013200)"
          }
        ],
        "returns": {
          "type": "Vec<PayoutRecord>",
          "description": "Paginated payout records within the amount range"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "query_payouts_by_timestamp",
        "description": "Paginated payout history filtered by timestamp range (inclusive)",
        "parameters": [
          {
            "name": "min_timestamp",
            "type": "u64",
            "description": "Start of timestamp range (inclusive)"
          },
          {
            "name": "max_timestamp",
            "type": "u64",
            "description": "End of timestamp range (inclusive)"
          },
          {
            "name": "offset",
            "type": "u32",
            "description": "Number of matching records to skip"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Maximum records to return (1\u2013200)"
          }
        ],
        "returns": {
          "type": "Vec<PayoutRecord>",
          "description": "Paginated payout records within the timestamp range"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "query_schedules_by_recipient",
        "description": "Paginated release schedules filtered by recipient address",
        "parameters": [
          {
            "name": "recipient",
            "type": "Address",
            "description": "Recipient address to filter by"
          },
          {
            "name": "offset",
            "type": "u32",
            "description": "Number of matching records to skip"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Maximum records to return (1\u2013200)"
          }
        ],
        "returns": {
          "type": "Vec<ProgramReleaseSchedule>",
          "description": "Paginated release schedules for the recipient"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "query_schedules_by_status",
        "description": "Paginated release schedules filtered by released status",
        "parameters": [
          {
            "name": "released",
            "type": "bool",
            "description": "True for released schedules, false for pending"
          },
          {
            "name": "offset",
            "type": "u32",
            "description": "Number of matching records to skip"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Maximum records to return (1\u2013200)"
          }
        ],
        "returns": {
          "type": "Vec<ProgramReleaseSchedule>",
          "description": "Paginated release schedules matching the status"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "query_releases_by_recipient",
        "description": "Paginated release history filtered by recipient address",
        "parameters": [
          {
            "name": "recipient",
            "type": "Address",
            "description": "Recipient address to filter by"
          },
          {
            "name": "offset",
            "type": "u32",
            "description": "Number of matching records to skip"
          },
          {
            "name": "limit",
            "type": "u32",
            "description": "Maximum records to return (1\u2013200)"
          }
        ],
        "returns": {
          "type": "Vec<ProgramReleaseHistory>",
          "description": "Paginated release history records for the recipient"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      }
    ],
    "admin": [
      {
        "name": "initialize_contract",
        "description": "Initialize contract with admin",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin address"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_admin",
        "description": "Set or rotate admin address",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "New admin address"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "get_admin",
        "description": "Get current admin address",
        "parameters": [],
        "returns": {
          "type": "Option<Address>",
          "description": "Admin address if set"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "propose_admin",
        "description": "Propose a new admin (two-step rotation step 1). Current admin must authorize. Panics if a rotation is already pending.",
        "parameters": [
          {
            "name": "proposed_admin",
            "type": "Address",
            "description": "Address being proposed as the next admin"
          }
        ],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "accept_admin",
        "description": "Accept the proposed admin role (step 2). Proposed admin must authorize. Panics if no rotation is pending.",
        "parameters": [],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "proposed_admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "cancel_admin_rotation",
        "description": "Cancel a pending admin rotation. Current admin must authorize. Panics if no rotation is pending.",
        "parameters": [],
        "returns": { "type": "()", "description": "Empty on success" },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "propose_controller",
        "description": "Propose a new authorized_payout_key for a program (step 1). Current controller or admin must authorize. Panics if a rotation is already pending.",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "caller",
            "type": "Address",
            "description": "Current controller or admin"
          },
          {
            "name": "proposed_controller",
            "type": "Address",
            "description": "Address being proposed as the next controller"
          }
        ],
        "returns": { "type": "ProgramData", "description": "Current program data" },
        "authorization": "controller_or_admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "accept_controller",
        "description": "Accept the proposed controller role for a program (step 2). Proposed controller must authorize. Panics if no rotation is pending.",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          }
        ],
        "returns": { "type": "ProgramData", "description": "Updated program data with new controller" },
        "authorization": "proposed_controller",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "cancel_controller_rotation",
        "description": "Cancel a pending controller rotation. Current controller or admin must authorize. Panics if no rotation is pending.",
        "parameters": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "caller",
            "type": "Address",
            "description": "Current controller or admin"
          }
        ],
        "returns": { "type": "ProgramData", "description": "Current program data" },
        "authorization": "controller_or_admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "set_circuit_admin",
        "description": "Set circuit breaker admin",
        "parameters": [
          {
            "name": "new_admin",
            "type": "Address",
            "description": "Circuit breaker admin address"
          },
          {
            "name": "caller",
            "type": "Option<Address>",
            "description": "Existing admin (None if setting for first time)",
            "optional": true
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "get_circuit_admin",
        "description": "Get circuit breaker admin",
        "parameters": [],
        "returns": {
          "type": "Option<Address>",
          "description": "Circuit breaker admin if set"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_circuit_breaker_status",
        "description": "Return a full snapshot of the circuit breaker state. Returns safe defaults for legacy deployments that have never written circuit breaker state.",
        "parameters": [],
        "returns": {
          "type": "CircuitBreakerStatus",
          "description": "Snapshot of state, failure_count, success_count, opened_at, and configured thresholds"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "reset_circuit_breaker",
        "description": "Reset circuit breaker to closed state",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Circuit breaker admin address"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "configure_circuit_breaker",
        "description": "Configure circuit breaker parameters",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Circuit breaker admin address"
          },
          {
            "name": "failure_threshold",
            "type": "u32",
            "description": "Consecutive failures to open circuit"
          },
          {
            "name": "success_threshold",
            "type": "u32",
            "description": "Successes to close circuit in half-open"
          },
          {
            "name": "max_error_log",
            "type": "u32",
            "description": "Maximum error log entries"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "get_circuit_status",
        "description": "Return a full snapshot of the circuit breaker state including failure/success counts, timestamps, and configured thresholds",
        "parameters": [],
        "returns": {
          "type": "CircuitBreakerStatus",
          "description": "Circuit breaker status snapshot"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_circuit_error_log",
        "description": "Return the last N circuit breaker error log entries",
        "parameters": [],
        "returns": {
          "type": "Vec<ErrorEntry>",
          "description": "Array of error entries"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "emergency_open_circuit",
        "description": "Immediately open the circuit breaker (circuit admin only). Blocks all payouts until reset.",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Circuit breaker admin address"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "init_threshold_monitoring",
        "description": "Initialize threshold monitoring with default configuration. Idempotent.",
        "parameters": [],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_threshold_config",
        "description": "Return the current threshold monitoring configuration",
        "parameters": [],
        "returns": {
          "type": "ThresholdConfig",
          "description": "Threshold monitoring configuration"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_circuit_breaker_schema_version",
        "description": "Return the circuit-breaker storage schema version written during init. Returns 0 on legacy deployments.",
        "parameters": [],
        "returns": {
          "type": "u32",
          "description": "Schema version (1 = current; 0 = legacy pre-v2.4)"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      }
    ]
  },
  "configuration": {
    "parameters": [
      {
        "name": "BASIS_POINTS",
        "type": "i128",
        "default_value": "10000",
        "description": "Basis points for fee calculations (1% = 100 basis points)",
        "constraints": "value = 10000",
        "admin_only": false
      },
      {
        "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": "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": "payout_fee_rate",
        "type": "i128",
        "default_value": "0",
        "description": "Fee rate for payout 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
      }
    ],
    "storage_keys": [
      {
        "name": "PROGRAM_DATA",
        "type": "instance",
        "description": "Single program data (legacy)",
        "data_structure": "ProgramData"
      },
      {
        "name": "PROGRAM_REGISTRY",
        "type": "instance",
        "description": "Multi-program registry",
        "data_structure": "bool"
      },
      {
        "name": "Program",
        "type": "instance",
        "description": "Program data by ID",
        "data_structure": "ProgramData"
      },
      {
        "name": "FEE_CONFIG",
        "type": "instance",
        "description": "Fee configuration",
        "data_structure": "FeeConfig"
      },
      {
        "name": "DataKey::Admin",
        "type": "instance",
        "description": "Contract admin address",
        "data_structure": "Address"
      },
      {
        "name": "DataKey::PendingAdmin",
        "type": "instance",
        "description": "Proposed next admin address for two-step rotation. Present only while a rotation is in progress; removed on accept or cancel.",
        "data_structure": "Address"
      },
      {
        "name": "DataKey::PendingController(String)",
        "type": "instance",
        "description": "Proposed next authorized_payout_key for a program. Key is program_id. Present only while a rotation is in progress; removed on accept or cancel.",
        "data_structure": "Address"
      },
      {
        "name": "DataKey::PauseFlags",
        "type": "instance",
        "description": "Pause configuration",
        "data_structure": "PauseFlags"
      },
      {
        "name": "DataKey::HistoryPaginationConfig",
        "type": "instance",
        "description": "History pagination configuration",
        "data_structure": "HistoryPaginationConfig"
      },
      {
        "name": "DataKey::SpendLimitSchemaVersion",
        "type": "instance",
        "description": "Upgrade-safe version marker for spend-limit threshold storage layout. Increment when MultisigConfig schema changes.",
        "data_structure": "u32"
      },
      {
        "name": "DataKey::BatchPayoutSchemaVersion",
        "type": "instance",
        "description": "Upgrade-safe version marker for batch payout logic. Written at init with value BATCH_PAYOUT_SCHEMA_VERSION_V1=1. Returns 0 on legacy pre-v1 contracts.",
        "data_structure": "u32"
      },
      {
        "name": "SCHEDULES",
        "type": "instance",
        "description": "Release schedules",
        "data_structure": "Vec<ProgramReleaseSchedule>"
      },
      {
        "name": "DataKey::IdempotencyKey(String)",
        "type": "persistent",
        "description": "Idempotency key for payout deduplication. Key is the caller-supplied opaque string; value is bool (true = processed). Stored in persistent storage so it survives contract upgrades.",
        "data_structure": "bool"
      }
    ]
  },
  "behaviors": {
    "security_features": [
      "Circuit breaker for error recovery",
      "Comprehensive pause functionality",
      "Rate limiting and anti-abuse protection",
      "Atomic batch operations",
      "Dependency management with cycle detection",
      "Reentrancy protection",
      "Comprehensive monitoring and analytics",
      "Input validation for all parameters",
      "Overflow protection in arithmetic operations",
      "Deterministic spend-threshold checks for payout operations",
      "Deterministic history pagination checks with explicit validation failures"
    ],
    "access_control": [
      {
        "mechanism": "admin_auth",
        "description": "Single admin with full control over contract",
        "configuration": "Set during initialization, can be rotated"
      },
      {
        "mechanism": "capability",
        "description": "Program-specific payout authorization",
        "configuration": "Each program has authorized payout key"
      },
      {
        "mechanism": "rbac",
        "description": "Role-based access for different operations",
        "configuration": "Admin vs payout key permissions"
      }
    ],
    "critical_behaviors": [
      {
        "behavior": "Circuit breaker",
        "impact": "Automatically pauses operations on repeated failures",
        "mitigation": "Configurable thresholds and manual reset capability"
      },
      {
        "behavior": "Batch atomicity",
        "impact": "All operations in batch succeed or fail together",
        "mitigation": "Rollback mechanism for partial failures"
      },
      {
        "behavior": "Dependency management",
        "impact": "Programs can depend on other programs/external services",
        "mitigation": "Cycle detection and status tracking"
      },
      {
        "behavior": "Fee calculation",
        "impact": "Fees are deducted from operations",
        "mitigation": "Floor rounding and configurable rates"
      },
      {
        "behavior": "Multi-program support",
        "impact": "Multiple programs can coexist in same contract",
        "mitigation": "Separate storage and authorization per program"
      }
    ],
    "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 address"
      },
      {
        "error_code": "Unauthorized",
        "scenario": "Caller lacks required permissions",
        "resolution": "Ensure caller is admin or authorized payout key"
      },
      {
        "error_code": "InsufficientFunds",
        "scenario": "Program doesn't have enough tokens for payout",
        "resolution": "Ensure sufficient funds are locked in program"
      },
      {
        "error_code": "FundsPaused",
        "scenario": "Operation is paused by admin or circuit breaker",
        "resolution": "Wait for admin to unpause or circuit breaker to reset"
      },
      {
        "error_code": "InvalidFeeRate",
        "scenario": "Fee rate exceeds maximum allowed",
        "resolution": "Use fee rate within allowed range (0-1000 basis points)"
      },
      {
        "error_code": "DependencyCycle",
        "scenario": "Creating circular dependencies between programs",
        "resolution": "Remove circular dependency references"
      },
      {
        "error_code": "PayoutAlreadyProcessed",
        "numeric_code": 1100,
        "scenario": "Submitting a payout with an idempotency key that was already used for a successful payout",
        "resolution": "Treat as success — the funds were already transferred. Use is_payout_processed to query key status before retrying."
      }
    ],
    "gas_considerations": [
      {
        "operation": "batch_initialize_programs",
        "cost_level": "high",
        "notes": "Multiple program initializations and storage writes"
      },
      {
        "operation": "batch_payout",
        "cost_level": "high",
        "notes": "Multiple token transfers and storage updates"
      },
      {
        "operation": "lock_program_funds",
        "cost_level": "medium",
        "notes": "Token transfer and storage updates"
      },
      {
        "operation": "single_payout",
        "cost_level": "medium",
        "notes": "Token transfer and storage updates"
      },
      {
        "operation": "emergency_withdraw",
        "cost_level": "high",
        "notes": "Large token transfer of all program funds"
      },
      {
        "operation": "view functions",
        "cost_level": "low",
        "notes": "Only storage reads, no state changes"
      }
    ],
    "events": [
      {
        "name": "ProgramInitialized",
        "description": "Program initialization event",
        "data": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "authorized_payout_key",
            "type": "Address",
            "description": "Authorized payout address"
          },
          {
            "name": "token_address",
            "type": "Address",
            "description": "Token contract address"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Initialization timestamp"
          }
        ],
        "trigger": "Successful program initialization"
      },
      {
        "name": "FundsLocked",
        "description": "Program funds locked",
        "data": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount locked"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Lock timestamp"
          }
        ],
        "trigger": "Successful fund lock"
      },
      {
        "name": "BatchPayout",
        "description": "Batch payout completed",
        "data": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "winner_count",
            "type": "u32",
            "description": "Number of winners paid"
          },
          {
            "name": "total_amount",
            "type": "i128",
            "description": "Total amount paid out"
          }
        ],
        "trigger": "Successful batch payout"
      },
      {
        "name": "Payout",
        "description": "Single payout completed",
        "data": [
          {
            "name": "program_id",
            "type": "String",
            "description": "Program identifier"
          },
          {
            "name": "winner",
            "type": "Address",
            "description": "Winner address"
          },
          {
            "name": "amount",
            "type": "i128",
            "description": "Amount paid"
          }
        ],
        "trigger": "Successful single payout"
      },
      {
        "name": "SpendLimitSetEvent",
        "description": "Audit event emitted after every set_program_spend_threshold call",
        "topics": [
          "SpLimSet",
          "program_id"
        ],
        "data": [
          {
            "name": "version",
            "type": "u32",
            "description": "Always EVENT_VERSION_V2"
          },
          {
            "name": "program_id",
            "type": "String",
            "description": "Program the threshold applies to"
          },
          {
            "name": "previous_threshold",
            "type": "i128",
            "description": "Previous threshold (i128::MAX = unlimited)"
          },
          {
            "name": "new_threshold",
            "type": "i128",
            "description": "New threshold value"
          },
          {
            "name": "set_by",
            "type": "Address",
            "description": "Admin that made the change"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Ledger timestamp"
          }
        ],
        "trigger": "Every successful set_program_spend_threshold call"
      },
      {
        "name": "SpendLimitExceededEvent",
        "description": "Audit event emitted when a payout is rejected for exceeding the spend threshold",
        "topics": [
          "SpLimExc",
          "program_id"
        ],
        "data": [
          {
            "name": "version",
            "type": "u32",
            "description": "Always EVENT_VERSION_V2"
          },
          {
            "name": "program_id",
            "type": "String",
            "description": "Program the threshold applies to"
          },
          {
            "name": "requested_amount",
            "type": "i128",
            "description": "Amount that was requested and rejected"
          },
          {
            "name": "threshold",
            "type": "i128",
            "description": "Configured threshold that was exceeded"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Ledger timestamp"
          }
        ],
        "trigger": "Every payout rejected due to spend threshold violation"
      },
      {
        "name": "SpendLimitSchemaVersionSet",
        "description": "Upgrade-safe marker recording the spend-limit storage schema version",
        "topics": [
          "SpLimSch"
        ],
        "data": [
          {
            "name": "version",
            "type": "u32",
            "description": "Always EVENT_VERSION_V2"
          },
          {
            "name": "schema_version",
            "type": "u32",
            "description": "Spend-limit schema version written to instance storage"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Ledger timestamp"
          }
        ],
        "trigger": "Contract initialization (init_program)"
      }
    ]
  },
  "dependencies": {
    "contracts": [],
    "tokens": [
      {
        "token_standard": "SAC",
        "purpose": "Program prize token for locking and payouts",
        "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/program_escrow.wasm",
          "notes": "Save contract ID from deployment output"
        },
        {
          "step": 2,
          "description": "Initialize contract with admin",
          "command": "stellar contract invoke --id CONTRACT_ID -- initialize_contract --admin ADMIN_ADDRESS",
          "notes": "Use secure admin address (hardware wallet recommended)"
        },
        {
          "step": 3,
          "description": "Initialize first program",
          "command": "stellar contract invoke --id CONTRACT_ID -- init_program --program_id 'Hackathon2024' --authorized_payout_key PAYOUT_KEY --token_address TOKEN_ADDRESS",
          "notes": "Set up your first program with authorized payout key"
        },
        {
          "step": 4,
          "description": "Configure circuit breaker (optional)",
          "command": "stellar contract invoke --id CONTRACT_ID -- configure_circuit_breaker --admin ADMIN_ADDRESS --failure_threshold 5 --success_threshold 3 --max_error_log 100",
          "notes": "Optional: configure circuit breaker for error recovery"
        }
      ],
      "prerequisites": [
        "Admin address (secure, preferably hardware wallet)",
        "Token contract address for prize funds",
        "Authorized payout key address for each program",
        "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/program_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"
        }
      ],
      "rollback_procedure": "Keep previous WASM hash to enable emergency rollback by calling upgrade with previous hash",
      "testing_requirements": [
        "Test all entrypoints on testnet",
        "Verify batch operations work correctly",
        "Test circuit breaker functionality",
        "Verify dependency management",
        "Test pause/unpause functionality",
        "Verify fee calculations work correctly"
      ]
    }
  },
  "testing": {
    "test_coverage": {
      "unit_tests": "92%",
      "integration_tests": "88%",
      "test_files": [
        "test_lifecycle.rs",
        "test_full_lifecycle.rs",
        "test_pause.rs",
        "test_granular_pause.rs",
        "test_dispute_resolution.rs",
        "test_claim_period_expiry_cancellation.rs",
        "test_metadata_tagging.rs",
        "test_token_math.rs",
        "test_circuit_breaker_audit.rs",
        "test_blacklist_and_whitelist.rs",
        "test_rbac_tests.rs",
        "test_reentrancy_tests.rs",
        "test_reentrancy_guard_standalone_test.rs",
        "test_malicious_reentrant.rs",
        "error_recovery_tests.rs"
      ]
    },
    "test_scenarios": [
      "Complete program lifecycle (init \u2192 fund \u2192 payout)",
      "Batch operations with mixed success/failure",
      "Circuit breaker activation and reset",
      "Dependency management with cycle detection",
      "Pause/unpause functionality",
      "Fee calculation and collection",
      "Error handling and edge cases",
      "Reentrancy attack prevention",
      "Rate limiting enforcement",
      "Gas optimization scenarios",
      "Multi-program interactions"
    ]
  },
  "documentation": {
    "readme": "README.md",
    "api_docs": "lib.rs (comprehensive inline documentation)",
    "examples": [
      "examples/basic_program_setup.rs",
      "examples/batch_payouts.rs",
      "examples/dependency_management.rs",
      "examples/circuit_breaker_setup.rs"
    ]
  }
}