grainlify-core-manifest.json

{
  "$schema": "./contract-manifest-schema.json",
  "contract_name": "GrainlifyContract",
  "contract_purpose": "Provides secure contract upgrade mechanism with version tracking, migration support, multisig governance, and comprehensive monitoring capabilities",
  "error_registry": {
    "codes": [
      { "code": 1, "name": "AlreadyInitialized", "description": "Contract already initialized", "range": "common", "added_in": "1.0.0" },
      { "code": 2, "name": "NotInitialized", "description": "Contract not initialized", "range": "common", "added_in": "1.0.0" },
      { "code": 3, "name": "NotAdmin", "description": "Caller is not admin", "range": "common", "added_in": "1.0.0" },
      { "code": 101, "name": "ThresholdNotMet", "description": "Multisig threshold not met", "range": "governance", "added_in": "2.0.0" },
      { "code": 102, "name": "ProposalNotFound", "description": "Upgrade proposal not found", "range": "governance", "added_in": "2.0.0" },
      { "code": 103, "name": "MigrationCommitmentNotFound", "description": "Migration hash commitment not found", "range": "governance", "added_in": "2.0.0" },
      { "code": 104, "name": "MigrationHashMismatch", "description": "Migration hash does not match committed hash", "range": "governance", "added_in": "2.0.0" },
      { "code": 105, "name": "TimelockDelayTooHigh", "description": "Timelock delay exceeds maximum allowed value", "range": "governance", "added_in": "2.0.0" },
      { "code": 106, "name": "SnapshotRestoreAdminPending", "description": "Snapshot restore requires two-step admin confirmation", "range": "governance", "added_in": "2.2.0" },
      { "code": 107, "name": "SnapshotPruned", "description": "Snapshot was pruned and is no longer available", "range": "governance", "added_in": "2.2.0" }
    ],
    "ranges": [
      { "name": "common", "min": 1, "max": 99, "description": "Common initialization and authorization errors" },
      { "name": "governance", "min": 100, "max": 199, "description": "Upgrade, migration, and snapshot governance errors" }
    ],
    "cross_contract_validation": {
      "allow_conflicts": false,
      "conflict_resolution": "warning",
      "excluded_contracts": []
    }
  },
  "version": {
    "current": "2.2.0",
    "schema": "1.0.0",
    "history": [
      {
        "version": "1.0.0",
        "release_date": "2024-01-01",
        "changes": [
          "Initial release with basic upgrade functionality",
          "Single admin authorization model",
          "Simple version tracking"
        ]
      },
      {
        "version": "2.0.0",
        "release_date": "2024-06-01",
        "changes": [
          "Added multisig support for upgrade proposals",
          "Enhanced migration system with state tracking",
          "Added governance module",
          "Comprehensive monitoring and analytics",
          "Improved version management with semantic versioning",
          "Added rollback support"
        ]
      },
      {
        "version": "2.2.0",
        "release_date": "2026-04-24",
        "changes": [
          "feat(contracts): snapshot/rollback guardrails (#1075)",
          "create_config_snapshot and restore_config_snapshot now blocked in read-only mode",
          "confirm_admin_restore now blocked in read-only mode",
          "Removed duplicate liveness_watchdog returning undefined LivenessStatus type",
          "Added WatchdogLastPing to DataKey enum (was missing, caused compile error)",
          "init_admin now writes LivenessSchemaVersion=1 marker",
          "Added get_liveness_schema_version view entrypoint",
          "Added snapshot_rollback_guardrails_tests.rs with 15 guardrail test cases",
          "validate_seed_file.py: added snapshot guardrail manifest check"
        ]
      },
      {
        "version": "2.1.0",
        "release_date": "2026-04-24",
        "changes": [
          "Added liveness_watchdog view: consolidated pause/read-only/health/ping/version snapshot",
          "Added ping_watchdog admin fn: records liveness ping timestamp for off-chain monitors",
          "Added WatchdogLastPing storage key (instance)",
          "Added WatchdogStatus contracttype struct"
        ]
      },
      {
        "version": "2.2.0",
        "release_date": "2026-04-24",
        "changes": [
          "Added deployed contract registry with admin-only register/deregister",
          "Added registry views: list_deployed_contracts, get_deployed_contract, deployed_contract_count",
          "Added ContractKind and DeployedContract contracttype structs",
          "Added DeployedContractRegistry storage key (instance)",
          "Registry events: (registry, reg) and (registry, unreg)"
        ]
      }
    ]
  },
  "entrypoints": {
    "public": [
      {
        "name": "upgrade",
        "description": "Upgrade the contract to new WASM code",
        "parameters": [
          {
            "name": "new_wasm_hash",
            "type": "BytesN<32>",
            "description": "Hash of the uploaded WASM code"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "high"
      },
      {
        "name": "set_version",
        "description": "Update the contract version number",
        "parameters": [
          {
            "name": "new_version",
            "type": "u32",
            "description": "New version number"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "migrate",
        "description": "Perform state migration to new version",
        "parameters": [
          {
            "name": "target_version",
            "type": "u32",
            "description": "Target version to migrate to"
          },
          {
            "name": "migration_hash",
            "type": "BytesN<32>",
            "description": "Hash of the migration data"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "high"
      },
      {
        "name": "propose_upgrade",
        "description": "Propose a WASM upgrade via multisig. Returns the stable proposal ID. Blocked when contract is paused.",
        "parameters": [
          {
            "name": "proposer",
            "type": "Address",
            "description": "Address proposing the upgrade (must be a registered multisig signer)"
          },
          {
            "name": "wasm_hash",
            "type": "BytesN<32>",
            "description": "Hash of the new WASM code to install"
          },
          {
            "name": "expiry",
            "type": "u64",
            "description": "Ledger timestamp after which proposal expires (0 = no expiry)"
          }
        ],
        "returns": {
          "type": "u64",
          "description": "Stable proposal ID for subsequent approve/cancel/execute calls"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "approve_upgrade",
        "description": "Approve a pending upgrade proposal. Automatically starts the timelock when the multisig threshold is met. Blocked when contract is paused.",
        "parameters": [
          {
            "name": "proposal_id",
            "type": "u64",
            "description": "Proposal ID to approve"
          },
          {
            "name": "signer",
            "type": "Address",
            "description": "Signer address approving the proposal"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "signer",
        "pausable": true,
        "gas_estimate": "medium"
      },
      {
        "name": "cancel_upgrade",
        "description": "Cancel a pending upgrade proposal. Any registered multisig signer may cancel. Clears the associated timelock.",
        "parameters": [
          {
            "name": "proposal_id",
            "type": "u64",
            "description": "Proposal ID to cancel"
          },
          {
            "name": "canceller",
            "type": "Address",
            "description": "Signer address cancelling the proposal"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "signer",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "execute_upgrade",
        "description": "Execute an approved upgrade proposal after the timelock delay has elapsed. Panics if timelock has not started or delay has not passed.",
        "parameters": [
          {
            "name": "proposal_id",
            "type": "u64",
            "description": "Proposal ID to execute"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "multisig",
        "pausable": false,
        "gas_estimate": "high"
      },
      {
        "name": "pause",
        "description": "Emergency pause: blocks propose_upgrade and approve_upgrade. Any registered multisig signer may pause.",
        "parameters": [
          {
            "name": "signer",
            "type": "Address",
            "description": "Signer address triggering the pause"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "signer",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "unpause",
        "description": "Resume normal operation after emergency pause. Any registered multisig signer may unpause.",
        "parameters": [
          {
            "name": "signer",
            "type": "Address",
            "description": "Signer address lifting the pause"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "signer",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "commit_migration",
        "description": "Pre-authorize a migration hash for replay protection. Must be called before migrate() with the same target_version and hash.",
        "parameters": [
          {
            "name": "target_version",
            "type": "u32",
            "description": "Target version this commitment authorizes"
          },
          {
            "name": "hash",
            "type": "BytesN<32>",
            "description": "Hash to commit — must match hash passed to migrate()"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "low"
      }
    ],
    "view": [
      {
        "name": "get_version",
        "description": "Get current contract version",
        "parameters": [],
        "returns": {
          "type": "u32",
          "description": "Current version number"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_version_semver_string",
        "description": "Get semantic version string",
        "parameters": [],
        "returns": {
          "type": "String",
          "description": "Semantic version (e.g., '1.0.0')"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_version_numeric_encoded",
        "description": "Get numeric encoded semantic version",
        "parameters": [],
        "returns": {
          "type": "u32",
          "description": "Encoded semantic version (major*10000 + minor*100 + patch)"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "require_min_version",
        "description": "Ensure current version meets minimum requirement",
        "parameters": [
          {
            "name": "min_numeric",
            "type": "u32",
            "description": "Minimum required version"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Panics if version is too low"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_migration_state",
        "description": "Get current migration state",
        "parameters": [],
        "returns": {
          "type": "Option<MigrationState>",
          "description": "Migration state if exists"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_previous_version",
        "description": "Get previous version before migration",
        "parameters": [],
        "returns": {
          "type": "Option<u32>",
          "description": "Previous version if exists"
        },
        "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": "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": "liveness_watchdog",
        "description": "Returns a consolidated liveness snapshot: pause state, read-only mode, monitoring health, last watchdog ping timestamp, and current version. No auth required. Never panics.",
        "parameters": [],
        "returns": {
          "type": "WatchdogStatus",
          "description": "{ paused: bool, read_only: bool, healthy: bool, last_ping_ts: u64, version: u32 }"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "list_deployed_contracts",
        "description": "Return paginated deployed contracts from the registry",
        "parameters": [
          {
            "name": "offset",
            "type": "Option<u32>",
            "description": "Number of entries to skip (default: 0)",
            "optional": true
          },
          {
            "name": "limit",
            "type": "Option<u32>",
            "description": "Maximum entries to return (default: all)",
            "optional": true
          }
        ],
        "returns": {
          "type": "Vec<DeployedContract>",
          "description": "Paginated list of deployed contracts"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "get_deployed_contract",
        "description": "Look up a registered contract by its on-chain address",
        "parameters": [
          {
            "name": "address",
            "type": "Address",
            "description": "Contract address to search for"
          }
        ],
        "returns": {
          "type": "Option<DeployedContract>",
          "description": "Registry entry if found, None otherwise"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "deployed_contract_count",
        "description": "Return the total number of registered deployed contracts",
        "parameters": [],
        "returns": {
          "type": "u32",
          "description": "Total registry size"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      }
    ],
    "admin": [
      {
        "name": "init",
        "description": "Initialize contract with multisig configuration",
        "parameters": [
          {
            "name": "signers",
            "type": "Vec<Address>",
            "description": "List of signer addresses"
          },
          {
            "name": "threshold",
            "type": "u32",
            "description": "Number of signatures required"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "init_admin",
        "description": "Initialize contract with single admin",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin address"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "low"
      },
      {
        "name": "init_governance",
        "description": "Initialize governance system",
        "parameters": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Governance admin address"
          },
          {
            "name": "config",
            "type": "GovernanceConfig",
            "description": "Governance configuration"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "any",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "ping_watchdog",
        "description": "Records a liveness ping — updates WatchdogLastPing to the current ledger timestamp. Allows off-chain monitors to prove the contract is reachable and the admin key is live. Blocked when read-only mode is active.",
        "parameters": [],
        "returns": {
          "type": "()",
          "description": "Empty on success; emits (watchdog, ping) event with (admin, timestamp)"
        },
        "authorization": "admin",
        "pausable": true,
        "gas_estimate": "low"
      },
      {
        "name": "create_config_snapshot",
        "description": "Captures a point-in-time snapshot of admin, version, previous_version, and multisig config. Blocked in read-only mode. Returns the new snapshot ID.",
        "parameters": [],
        "returns": {
          "type": "u64",
          "description": "Monotonically increasing snapshot ID"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "restore_config_snapshot",
        "description": "Restores contract config from a snapshot. Blocked in read-only mode. If the snapshot admin differs from the current admin, creates a PendingAdminRestore requiring two-step confirmation.",
        "parameters": [
          {
            "name": "snapshot_id",
            "type": "u64",
            "description": "ID of the snapshot to restore"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success; panics if snapshot is pruned or read-only mode is active"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      },
      {
        "name": "confirm_admin_restore",
        "description": "Finalises a pending two-step admin restore. Must be called by the proposed new admin address. Blocked in read-only mode. Panics if the pending restore has expired.",
        "parameters": [
          {
            "name": "snapshot_id",
            "type": "u64",
            "description": "Snapshot ID matching the pending restore"
          }
        ],
        "returns": {
          "type": "()",
          "description": "Empty on success"
        },
        "authorization": "admin",
        "pausable": false,
        "gas_estimate": "medium"
      }
    ]
  },
  "configuration": {
    "parameters": [
      {
        "name": "VERSION",
        "type": "u32",
        "default_value": "2",
        "description": "Current contract version",
        "constraints": "value > 0",
        "admin_only": false
      },
      {
        "name": "multisig_threshold",
        "type": "u32",
        "default_value": "2",
        "description": "Number of signatures required for multisig operations",
        "constraints": "1 <= value <= signer_count",
        "admin_only": true
      },
      {
        "name": "multisig_signers",
        "type": "Vec<Address>",
        "default_value": "[]",
        "description": "List of authorized multisig signers",
        "constraints": "non-empty list",
        "admin_only": true
      },
      {
        "name": "timelock_delay",
        "type": "u64",
        "default_value": "86400",
        "description": "Seconds to wait after threshold is met before execute_upgrade is allowed",
        "constraints": "3600 <= value <= 2592000 (1 hour to 30 days)",
        "admin_only": true
      },
      {
        "name": "paused",
        "type": "bool",
        "default_value": "false",
        "description": "Emergency pause flag; blocks propose_upgrade and approve_upgrade when true",
        "constraints": "toggled by any registered multisig signer",
        "admin_only": false
      }
    ],
    "storage_keys": [
      {
        "name": "Admin",
        "type": "instance",
        "description": "Administrator address (immutable after init)",
        "data_structure": "Address"
      },
      {
        "name": "Version",
        "type": "instance",
        "description": "Current contract version",
        "data_structure": "u32"
      },
      {
        "name": "UpgradeProposal(u64)",
        "type": "instance",
        "description": "WASM hash stored per upgrade proposal ID",
        "data_structure": "BytesN<32>"
      },
      {
        "name": "UpgradeTimelock(u64)",
        "type": "instance",
        "description": "Ledger timestamp when timelock started for a given proposal ID",
        "data_structure": "u64"
      },
      {
        "name": "TimelockDelay",
        "type": "instance",
        "description": "Configured timelock delay in seconds (default 86400)",
        "data_structure": "u64"
      },
      {
        "name": "MigrationState",
        "type": "instance",
        "description": "Migration state tracking (from/to version, hash, timestamp)",
        "data_structure": "MigrationState"
      },
      {
        "name": "MigrationCommitment(u32)",
        "type": "instance",
        "description": "Pre-committed migration hash keyed by target_version; consumed after migrate()",
        "data_structure": "MigrationCommitment"
      },
      {
        "name": "PreviousVersion",
        "type": "instance",
        "description": "Previous version before migration",
        "data_structure": "u32"
      },
      {
        "name": "WatchdogLastPing",
        "type": "instance",
        "description": "Ledger timestamp of the last successful ping_watchdog call. 0 / absent means never pinged.",
        "data_structure": "u64"
      },
      {
        "name": "DeployedContractRegistry",
        "type": "instance",
        "description": "Ordered list of deployed contract addresses tracked by this core contract for discoverability and cross-contract coordination.",
        "data_structure": "Vec<DeployedContract>"
      }
    ]
  },
  "behaviors": {
    "security_features": [
      "Immutable admin after initialization",
      "Multisig support for critical operations",
      "Timelocked upgrade execution (default 24h, min 1h, max 30d)",
      "Emergency pause/unpause via any multisig signer",
      "Timelock starts automatically when multisig threshold is met",
      "Paused contract blocks new upgrade proposals and approvals",
      "Commit-reveal replay protection for migrations",
      "Migration commitment consumed after use (no replay)",
      "Version tracking and audit trail",
      "State migration with rollback support",
      "Read-only mode blocks all mutations during incidents",
      "Two-step admin restore for snapshot-based admin changes",
      "Proposal expiry prevents stale approvals",
      "Explicit proposal cancellation by any signer",
      "Comprehensive monitoring and analytics",
      "Performance tracking",
      "Health check capabilities",
      "Invariant verification",
      "Liveness watchdog view: consolidated pause/read-only/health/ping/version snapshot (no auth, never panics)",
      "Watchdog ping: admin-only liveness proof with read-only mode guard",
      "Snapshot/rollback guardrails: create_config_snapshot and restore_config_snapshot are blocked in read-only mode — prevents state mutation during incidents",
      "Two-step admin restore: restoring a snapshot that changes the admin address requires confirmation from the new admin address, preventing silent admin takeover",
      "Pending admin restore expiry: unconfirmed admin restores expire after DEFAULT_TIMELOCK_DELAY (24h) to prevent dangling restore requests"
    ],
    "snapshot_rollback": {
      "enabled": true,
      "snapshot_limit": 20,
      "two_step_admin_restore": true,
      "blocked_in_read_only": true
    },
    "access_control": [
      {
        "mechanism": "admin_auth",
        "description": "Single admin with upgrade authority",
        "configuration": "Set during initialization, immutable afterwards"
      },
      {
        "mechanism": "multisig",
        "description": "Multiple signatures required for upgrade proposals",
        "configuration": "Configurable threshold and signer list"
      }
    ],
    "critical_behaviors": [
      {
        "behavior": "Immutable admin",
        "impact": "Admin cannot be changed after initialization",
        "mitigation": "Choose admin carefully, use multisig for additional security"
      },
      {
        "behavior": "Timelocked upgrade execution",
        "impact": "Approved upgrades cannot execute until the timelock delay elapses (default 24h)",
        "mitigation": "Monitor timelock status; cancel proposal if upgrade is no longer desired"
      },
      {
        "behavior": "Timelock auto-start on threshold",
        "impact": "Timelock begins automatically when the last required approval is recorded",
        "mitigation": "Signers should coordinate timing; use expiry to bound proposal lifetime"
      },
      {
        "behavior": "Emergency pause blocks new proposals",
        "impact": "When paused, propose_upgrade and approve_upgrade revert; execute_upgrade is unaffected",
        "mitigation": "Unpause via any registered multisig signer once the incident is resolved"
      },
      {
        "behavior": "Commit-reveal migration replay protection",
        "impact": "migrate() requires a prior commit_migration() call with the same hash; commitment is consumed on use",
        "mitigation": "Always call commit_migration before migrate; store commitment hash securely"
      },
      {
        "behavior": "WASM upgrade",
        "impact": "Contract code can be completely replaced",
        "mitigation": "Require admin authorization and optionally multisig approval with timelock"
      },
      {
        "behavior": "State preservation",
        "impact": "Instance storage survives upgrades",
        "mitigation": "Use instance storage for critical data like admin address"
      },
      {
        "behavior": "Version tracking",
        "impact": "All upgrades are tracked with version numbers",
        "mitigation": "Always update version after successful upgrade"
      },
      {
        "behavior": "Migration system",
        "impact": "State can be migrated between versions",
        "mitigation": "Test migrations thoroughly and keep rollback data"
      }
    ],
    "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 or multisig configuration"
      },
      {
        "error_code": "Unauthorized",
        "scenario": "Non-admin attempting upgrade operations",
        "resolution": "Ensure caller is admin or authorized multisig signer"
      },
      {
        "error_code": "Threshold not met",
        "scenario": "Multisig operation without sufficient approvals",
        "resolution": "Get required number of signatures before executing"
      },
      {
        "error_code": "Incompatible contract version",
        "scenario": "Version requirement not met",
        "resolution": "Upgrade contract to required minimum version"
      }
    ],
    "gas_considerations": [
      {
        "operation": "upgrade",
        "cost_level": "high",
        "notes": "WASM code replacement is expensive"
      },
      {
        "operation": "migrate",
        "cost_level": "high",
        "notes": "State migration can be complex and expensive"
      },
      {
        "operation": "multisig operations",
        "cost_level": "medium",
        "notes": "Multiple signature validations and storage writes"
      },
      {
        "operation": "view functions",
        "cost_level": "low",
        "notes": "Only storage reads, minimal computation"
      }
    ],
    "events": [
      {
        "name": "ContractInitialized",
        "description": "Contract initialization completed with BuildInfo metadata across all init entrypoints",
        "data": [
          {
            "name": "init_path",
            "type": "Symbol",
            "description": "Initialization path marker (adm_init, msig_init, net_init, gov_init)"
          },
          {
            "name": "admin",
            "type": "Option<Address>",
            "description": "Administrator address for admin-based init paths; None for multisig init"
          },
          {
            "name": "signer_count",
            "type": "u32",
            "description": "Multisig signer count used during init (0 for admin-based paths)"
          },
          {
            "name": "threshold",
            "type": "u32",
            "description": "Multisig threshold used during init (0 for admin-based paths)"
          },
          {
            "name": "version",
            "type": "u32",
            "description": "Initial contract version"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Initialization timestamp (ledger time)"
          }
        ],
        "topic": ["init", "build"],
        "trigger": "Contract initialization via init_admin(), init(), init_with_network(), or init_governance()",
        "auth_context": "Requires valid initialization authorization for selected init path",
        "security_notes": "Only emitted during successful first-time initialization; failed or duplicate init attempts do not emit this event"
      },
      {
        "name": "ContractUpgraded",
        "description": "Contract successfully upgraded",
        "data": [
          {"name": "new_wasm_hash", "type": "BytesN<32>", "description": "New WASM hash installed"},
          {"name": "previous_version", "type": "u32", "description": "Version before upgrade"},
          {"name": "timestamp", "type": "u64", "description": "Upgrade timestamp"}
        ],
        "trigger": "Successful upgrade() or execute_upgrade()"
      },
      {
        "name": "timelock/started",
        "description": "Timelock started after multisig threshold was met",
        "data": [
          {"name": "proposal_id", "type": "u64", "description": "Proposal that triggered the timelock"},
          {"name": "timestamp", "type": "u64", "description": "Ledger timestamp when timelock started"}
        ],
        "trigger": "approve_upgrade() when threshold is first met"
      },
      {
        "name": "timelock/dly_chg",
        "description": "Timelock delay configuration changed",
        "data": [
          {"name": "old_delay", "type": "u64", "description": "Previous delay in seconds"},
          {"name": "new_delay", "type": "u64", "description": "New delay in seconds"}
        ],
        "trigger": "set_timelock_delay()"
      },
      {
        "name": "paused",
        "description": "Contract emergency pause activated",
        "data": [
          {"name": "signer", "type": "Address", "description": "Signer who triggered the pause"}
        ],
        "trigger": "pause()"
      },
      {
        "name": "unpause",
        "description": "Contract emergency pause lifted",
        "data": [
          {"name": "signer", "type": "Address", "description": "Signer who lifted the pause"}
        ],
        "trigger": "unpause()"
      },
      {
        "name": "migrate/commit",
        "description": "Migration hash pre-committed",
        "data": [
          {"name": "target_version", "type": "u32", "description": "Target version authorized"},
          {"name": "timestamp", "type": "u64", "description": "Commitment timestamp"}
        ],
        "trigger": "commit_migration()"
      },
      {
        "name": "migrate/done",
        "description": "State migration completed",
        "data": [
          {"name": "from_version", "type": "u32", "description": "Source version"},
          {"name": "to_version", "type": "u32", "description": "Target version"},
          {"name": "timestamp", "type": "u64", "description": "Migration timestamp"}
        ],
        "trigger": "migrate()"
      },
      {
        "name": "cancelled",
        "description": "Upgrade proposal cancelled",
        "data": [
          {"name": "proposal_id", "type": "u64", "description": "Cancelled proposal ID"},
          {"name": "canceller", "type": "Address", "description": "Signer who cancelled"}
        ],
        "trigger": "Successful migration"
      },
      {
        "name": "WatchdogPing",
        "description": "Admin liveness ping recorded",
        "data": [
          {
            "name": "admin",
            "type": "Address",
            "description": "Admin address that called ping_watchdog"
          },
          {
            "name": "timestamp",
            "type": "u64",
            "description": "Ledger timestamp of the ping"
          }
        ],
        "trigger": "Successful ping_watchdog call"
      },
      {
        "name": "ContractRegistered",
        "description": "A deployed contract address was registered or updated in the registry",
        "data": [
          {
            "name": "address",
            "type": "Address",
            "description": "Registered contract address"
          },
          {
            "name": "name",
            "type": "String",
            "description": "Human-readable name"
          },
          {
            "name": "kind",
            "type": "ContractKind",
            "description": "Contract role/type"
          },
          {
            "name": "version",
            "type": "u32",
            "description": "Version at registration"
          }
        ],
        "trigger": "Successful register_deployed_contract call"
      },
      {
        "name": "ContractDeregistered",
        "description": "A deployed contract address was removed from the registry",
        "data": [
          {
            "name": "address",
            "type": "Address",
            "description": "Deregistered contract address"
          }
        ],
        "trigger": "Successful deregister_deployed_contract call"
      }
    ]
  },
  "dependencies": {
    "contracts": [],
    "tokens": [],
    "external_apis": []
  },
  "deployment": {
    "networks": [],
    "initialization": {
      "steps": [
        {
          "step": 1,
          "description": "Deploy contract to Stellar network",
          "command": "stellar contract deploy --wasm target/wasm32-unknown-unknown/release/grainlify.wasm",
          "notes": "Save contract ID from deployment output"
        },
        {
          "step": 2,
          "description": "Initialize with single admin (simple mode)",
          "command": "stellar contract invoke --id CONTRACT_ID -- init_admin --admin ADMIN_ADDRESS",
          "notes": "Use secure admin address (hardware wallet recommended)"
        },
        {
          "step": 3,
          "description": "OR initialize with multisig (advanced mode)",
          "command": "stellar contract invoke --id CONTRACT_ID -- init --signers SIGNER1,SIGNER2,SIGNER3 --threshold 2",
          "notes": "Choose appropriate threshold for your security requirements"
        }
      ],
      "prerequisites": [
        "Admin address or list of multisig signers",
        "Sufficient XLM for deployment fees",
        "Secure storage of admin private keys"
      ]
    },
    "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/grainlify.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 (single admin)",
          "command": "stellar contract invoke --id MAINNET_CONTRACT_ID -- upgrade --new_wasm_hash WASM_HASH",
          "notes": "Ensure admin authorization"
        },
        {
          "step": 5,
          "description": "OR perform multisig upgrade",
          "command": "stellar contract invoke --id CONTRACT_ID -- propose_upgrade --proposer PROPOSER --wasm_hash WASM_HASH",
          "notes": "Get proposal ID, then collect approvals"
        },
        {
          "step": 6,
          "description": "Approve multisig upgrade",
          "command": "stellar contract invoke --id CONTRACT_ID -- approve_upgrade --proposal_id PROPOSAL_ID --signer SIGNER",
          "notes": "Repeat for required number of signers"
        },
        {
          "step": 7,
          "description": "Execute approved upgrade",
          "command": "stellar contract invoke --id CONTRACT_ID -- execute_upgrade --proposal_id PROPOSAL_ID",
          "notes": "Execute after threshold is met"
        },
        {
          "step": 8,
          "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 upgrade process on testnet",
        "Verify state preservation across upgrades",
        "Test migration procedures if applicable",
        "Verify multisig workflow if used",
        "Test rollback procedure"
      ]
    }
  },
  "testing": {
    "test_coverage": {
      "unit_tests": "95%",
      "integration_tests": "85%",
      "test_files": [
        "test_core_monitoring.rs",
        "upgrade_rollback_tests.rs",
        "migration_hook_tests.rs",
        "test_liveness_watchdog.rs",
        "test_contract_registry.rs"
      ]
    },
    "test_scenarios": [
      "Contract initialization (single admin and multisig)",
      "WASM upgrade process",
      "Version management",
      "State migration",
      "Multisig proposal and approval workflow",
      "Rollback procedures",
      "Error handling for unauthorized access",
      "Health check functionality",
      "Analytics and monitoring",
      "Performance tracking",
      "liveness_watchdog default state (not paused, not read-only, healthy, no ping, version set)",
      "liveness_watchdog reflects read-only mode changes",
      "liveness_watchdog requires no auth (pure view)",
      "liveness_watchdog on uninitialized contract does not panic",
      "ping_watchdog updates last_ping_ts to ledger timestamp",
      "ping_watchdog multiple pings update timestamp monotonically",
      "ping_watchdog blocked in read-only mode",
      "ping_watchdog requires admin auth",
      "register_deployed_contract adds entry to registry",
      "register_deployed_contract updates existing entry (no duplicates)",
      "deregister_deployed_contract removes entry",
      "deregister_deployed_contract is no-op for unknown address",
      "list_deployed_contracts supports pagination",
      "deployed_contract_count reflects registry size",
      "get_deployed_contract returns None for unregistered address",
      "registry mutations blocked in read-only mode",
      "registry enforces max size limit"
    ]
  },
  "registry": {
    "enabled": true,
    "max_entries": 200,
    "entrypoint_register": "register_deployed_contract",
    "entrypoint_deregister": "deregister_deployed_contract",
    "entrypoint_list": "list_deployed_contracts",
    "entrypoint_get": "get_deployed_contract",
    "entrypoint_count": "deployed_contract_count"
  },
  "documentation": {
    "readme": "README.md",
    "api_docs": "lib.rs (comprehensive inline documentation)",
    "examples": [
      "examples/basic_upgrade.rs",
      "examples/multisig_setup.rs",
      "examples/migration_example.rs"
    ]
  }
}