contract-manifest-schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://grainlify.dev/schemas/contract-manifest.json",
  "title": "Smart Contract Metadata Manifest",
  "description": "Machine-readable metadata manifest for Grainlify smart contracts",
  "type": "object",
  "required": ["contract_name", "contract_purpose", "version", "entrypoints", "configuration", "behaviors"],
  "properties": {
    "error_registry": {
      "type": "object",
      "description": "Error code registry for this contract. Enables cross-manifest uniqueness validation and SDK generation.",
      "properties": {
        "codes": {
          "type": "array",
          "description": "All error codes defined in this contract's error enum, in ascending order.",
          "items": {
            "$ref": "#/$defs/error_registry_entry"
          },
          "minItems": 1,
          "uniqueItems": true
        },
        "ranges": {
          "type": "array",
          "description": "Reserved numeric ranges for this contract's error codes. Must follow established conventions: 1-99 (common), 100-199 (governance), 200-299 (escrow), 300-399 (identity), 400-499 (program_escrow), 1000+ (system).",
          "items": {
            "$ref": "#/$defs/error_code_range"
          },
          "minItems": 1
        },
        "cross_contract_validation": {
          "type": "object",
          "description": "Cross-contract validation configuration",
          "properties": {
            "allow_conflicts": {
              "type": "boolean",
              "description": "Whether conflicts with other contracts are allowed (default: false)",
              "default": false
            },
            "conflict_resolution": {
              "type": "string",
              "enum": ["error", "warning", "ignore"],
              "description": "How to handle cross-contract conflicts",
              "default": "warning"
            },
            "excluded_contracts": {
              "type": "array",
              "description": "List of contract names to exclude from conflict checking",
              "items": {
                "type": "string"
              }
            }
          }
        }
      },
      "required": ["codes", "ranges"]
    },
    "contract_name": {
      "type": "string",
      "description": "Human-readable name of the smart contract",
      "examples": ["BountyEscrowContract", "GrainlifyContract", "ProgramEscrowContract"]
    },
    "contract_purpose": {
      "type": "string",
      "description": "Clear description of what the contract does",
      "examples": [
        "Manages bounty escrow with multi-token support and capability-based authorization",
        "Provides secure contract upgrade mechanism with version tracking and migration support",
        "Handles hackathon program prize pools with batch payouts and dependency management"
      ]
    },
    "version": {
      "type": "object",
      "description": "Version information for the contract",
      "required": ["current", "schema"],
      "properties": {
        "current": {
          "type": "string",
          "description": "Current contract version (semantic versioning)",
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
        },
        "schema": {
          "type": "string",
          "description": "Version of this manifest schema",
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
        },
        "history": {
          "type": "array",
          "description": "Version history with changelog",
          "items": {
            "type": "object",
            "required": ["version", "release_date", "changes"],
            "properties": {
              "version": {
                "type": "string",
                "pattern": "^\\d+\\.\\d+\\.\\d+$"
              },
              "release_date": {
                "type": "string",
                "format": "date"
              },
              "changes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "entrypoints": {
      "type": "object",
      "description": "Contract entrypoints and their specifications",
      "required": ["public", "view"],
      "properties": {
        "public": {
          "type": "array",
          "description": "State-changing functions that require authentication",
          "items": {
            "$ref": "#/$defs/entrypoint"
          }
        },
        "view": {
          "type": "array",
          "description": "Read-only functions that don't require authentication. Includes liveness/health views such as liveness_watchdog() which returns a LivenessStatus snapshot combining pause state, read-only mode, version, and admin presence.",
          "items": {
            "$ref": "#/$defs/entrypoint"
          }
        },
        "admin": {
          "type": "array",
          "description": "Admin-only functions",
          "items": {
            "$ref": "#/$defs/entrypoint"
          }
        }
      }
    },
    "configuration": {
      "type": "object",
      "description": "Configuration parameters and their defaults",
      "required": ["parameters"],
      "properties": {
        "parameters": {
          "type": "array",
          "description": "Configurable parameters",
          "items": {
            "$ref": "#/$defs/config_parameter"
          }
        },
        "storage_keys": {
          "type": "array",
          "description": "Important storage keys used by the contract",
          "items": {
            "$ref": "#/$defs/storage_key"
          }
        }
      }
    },
    "behaviors": {
      "type": "object",
      "description": "Critical behaviors and important notes",
      "required": ["security_features", "access_control"],
      "properties": {
        "security_features": {
          "type": "array",
          "description": "Security mechanisms implemented",
          "items": {
            "type": "string"
          }
        },
        "access_control": {
          "type": "array",
          "description": "Access control mechanisms",
          "items": {
            "$ref": "#/$defs/access_control"
          }
        },
        "critical_behaviors": {
          "type": "array",
          "description": "Critical behaviors that developers should be aware of",
          "items": {
            "$ref": "#/$defs/critical_behavior"
          }
        },
        "error_handling": {
          "type": "array",
          "description": "Common error scenarios and their meanings",
          "items": {
            "$ref": "#/$defs/error_scenario"
          }
        },
        "gas_considerations": {
          "type": "array",
          "description": "Gas cost considerations for different operations",
          "items": {
            "type": "object",
            "required": ["operation", "cost_level", "notes"],
            "properties": {
              "operation": {
                "type": "string"
              },
              "cost_level": {
                "type": "string",
                "enum": ["low", "medium", "high", "very_high"]
              },
              "notes": {
                "type": "string"
              }
            }
          }
        },
        "events": {
          "type": "array",
          "description": "Events emitted by the contract",
          "items": {
            "$ref": "#/$defs/event"
          }
        },
        "emergency_pause": {
          "type": "object",
          "description": "Configuration and policy for emergency pause functionality",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "blocks_upgrades": {
              "type": "boolean"
            }
          }
        },
        "timelocked_upgrades": {
          "type": "object",
          "description": "Configuration and policy for timelocked upgrades",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "min_delay_seconds": {
              "type": "integer"
            },
            "max_delay_seconds": {
              "type": "integer"
            }
          }
        },
        "snapshot_rollback": {
          "type": "object",
          "description": "Configuration and policy for on-chain state snapshots and rollbacks",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "snapshot_limit": {
              "type": "integer",
              "description": "Maximum number of retained snapshots"
            },
            "two_step_admin_restore": {
              "type": "boolean",
              "description": "Whether restoring an admin change requires a two-step confirmation"
            },
            "blocked_in_read_only": {
              "type": "boolean",
              "description": "Whether snapshot mutations are blocked when the contract is in read-only mode"
            }
          }
        }
      }
    },
    "dependencies": {
      "type": "object",
      "description": "External dependencies and integrations",
      "properties": {
        "contracts": {
          "type": "array",
          "description": "Other contracts this contract interacts with",
          "items": {
            "$ref": "#/$defs/contract_dependency"
          }
        },
        "tokens": {
          "type": "array",
          "description": "Token contracts this contract works with",
          "items": {
            "$ref": "#/$defs/token_dependency"
          }
        },
        "external_apis": {
          "type": "array",
          "description": "External APIs or services",
          "items": {
            "$ref": "#/$defs/external_api"
          }
        }
      }
    },
    "deployment": {
      "type": "object",
      "description": "Deployment information",
      "properties": {
        "networks": {
          "type": "array",
          "description": "Networks where this contract is deployed",
          "items": {
            "$ref": "#/$defs/network_deployment"
          }
        },
        "initialization": {
          "$ref": "#/$defs/initialization_guide"
        },
        "upgrade_process": {
          "$ref": "#/$defs/upgrade_process"
        }
      }
    },
    "testing": {
      "type": "object",
      "description": "Testing information",
      "properties": {
        "test_coverage": {
          "type": "object",
          "description": "Test coverage information",
          "properties": {
            "unit_tests": {
              "type": "string",
              "description": "Unit test coverage percentage"
            },
            "integration_tests": {
              "type": "string",
              "description": "Integration test coverage percentage"
            },
            "test_files": {
              "type": "array",
              "description": "List of test files",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "test_scenarios": {
          "type": "array",
          "description": "Important test scenarios covered",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "registry": {
      "type": "object",
      "description": "Deployed contract registry metadata",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether the contract maintains a registry of deployed addresses"
        },
        "max_entries": {
          "type": "integer",
          "description": "Maximum number of contracts that can be registered"
        },
        "entrypoint_register": {
          "type": "string",
          "description": "Entrypoint name for registering a contract"
        },
        "entrypoint_deregister": {
          "type": "string",
          "description": "Entrypoint name for deregistering a contract"
        },
        "entrypoint_list": {
          "type": "string",
          "description": "Entrypoint name for listing registered contracts"
        },
        "entrypoint_get": {
          "type": "string",
          "description": "Entrypoint name for getting a single registered contract"
        },
        "entrypoint_count": {
          "type": "string",
          "description": "Entrypoint name for getting the registry count"
        }
      }
    },
    "documentation": {
      "type": "object",
      "description": "Documentation references",
      "properties": {
        "readme": {
          "type": "string",
          "description": "Path to README file"
        },
        "api_docs": {
          "type": "string",
          "description": "Path to API documentation"
        },
        "examples": {
          "type": "array",
          "description": "Example code or tutorials",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "$defs": {
    "entrypoint": {
      "type": "object",
      "required": ["name", "description", "parameters", "returns"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Function name",
          "examples": ["init_program", "batch_payout", "liveness_watchdog", "get_liveness_schema_version"]
        },
        "description": {
          "type": "string",
          "description": "What the function does"
        },
        "parameters": {
          "type": "array",
          "description": "Function parameters",
          "items": {
            "$ref": "#/$defs/parameter"
          }
        },
        "returns": {
          "type": "object",
          "description": "Return value specification",
          "properties": {
            "type": {
              "type": "string",
              "description": "Return type",
              "examples": ["ProgramData", "bool", "u32", "LivenessStatus", "Option<Address>"]
            },
            "description": {
              "type": "string",
              "description": "What is returned"
            }
          }
        },
        "authorization": {
          "type": "string",
          "description": "Authorization requirements",
          "enum": ["admin", "signer", "any", "none", "capability", "multisig", "admin-or-governor"]
        },
        "pausable": {
          "type": "boolean",
          "description": "Whether this function can be paused"
        },
        "timelocked": {
          "type": "boolean",
          "description": "Whether this function requires a timelock delay before execution",
          "default": false
        },
        "gas_estimate": {
          "type": "string",
          "description": "Gas cost estimate",
          "enum": ["low", "medium", "high", "very_high"]
        }
      }
    },
    "parameter": {
      "type": "object",
      "required": ["name", "type", "description"],
      "properties": {
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "optional": {
          "type": "boolean",
          "default": false
        },
        "validation": {
          "type": "string",
          "description": "Validation rules"
        }
      }
    },
    "config_parameter": {
      "type": "object",
      "required": ["name", "type", "default_value", "description"],
      "properties": {
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "default_value": {
          "description": "Default value for this parameter"
        },
        "description": {
          "type": "string"
        },
        "constraints": {
          "type": "string",
          "description": "Constraints or limits on this parameter"
        },
        "admin_only": {
          "type": "boolean",
          "default": false
        },
        "timelock_seconds": {
          "type": "integer",
          "description": "Required timelock delay in seconds for applying this configuration parameter",
          "minimum": 0
        },
        "requires_proposal": {
          "type": "boolean",
          "description": "Whether this parameter must be changed via propose/execute governance flow",
          "default": false
        }
      }
    },
    "storage_key": {
      "type": "object",
      "required": ["name", "type", "description"],
      "properties": {
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": ["instance", "persistent", "temporary"]
        },
        "description": {
          "type": "string"
        },
        "data_structure": {
          "type": "string",
          "description": "Data structure stored at this key"
        }
      }
    },
    "access_control": {
      "type": "object",
      "required": ["mechanism", "description"],
      "properties": {
        "mechanism": {
          "type": "string",
          "enum": ["admin_auth", "multisig", "capability", "rbac", "whitelist"]
        },
        "description": {
          "type": "string"
        },
        "configuration": {
          "type": "string",
          "description": "How this mechanism is configured"
        }
      }
    },
    "critical_behavior": {
      "type": "object",
      "required": ["behavior", "impact", "mitigation"],
      "properties": {
        "behavior": {
          "type": "string"
        },
        "impact": {
          "type": "string"
        },
        "mitigation": {
          "type": "string"
        }
      }
    },
    "error_scenario": {
      "type": "object",
      "required": ["error_code", "scenario", "resolution"],
      "properties": {
        "error_code": {
          "type": "string"
        },
        "scenario": {
          "type": "string"
        },
        "resolution": {
          "type": "string"
        }
      }
    },
    "event": {
      "type": "object",
      "required": ["name", "description", "data"],
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "event_version": {
          "type": "integer",
          "description": "Schema version of this event struct. Matches the EVENT_SCHEMA_VERSION constant in the contract source. Consumers must validate this field before deserializing event data to detect cross-version incompatibilities.",
          "minimum": 1
        },
        "min_compatible_version": {
          "type": "integer",
          "description": "Minimum EVENT_SCHEMA_VERSION value that a consumer can safely deserialize. Useful when a new version adds optional fields that older consumers can ignore.",
          "minimum": 1
        },
        "data": {
          "type": "array",
          "description": "Event data fields",
          "items": {
            "type": "object",
            "required": ["name", "type"],
            "properties": {
              "name": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            }
          }
        },
        "trigger": {
          "type": "string",
          "description": "When this event is emitted"
        },
        "topic": {
          "type": "array",
          "description": "Event topic path as emitted on-chain (e.g. [\"init\", \"build\"])",
          "items": {
            "type": "string"
          }
        },
        "auth_context": {
          "type": "string",
          "description": "Authorization context required for the event to be emitted"
        },
        "security_notes": {
          "type": "string",
          "description": "Security and audit notes for the event"
        }
      }
    },
    "contract_dependency": {
      "type": "object",
      "required": ["contract_name", "interface"],
      "properties": {
        "contract_name": {
          "type": "string"
        },
        "interface": {
          "type": "string",
          "description": "Interface or functions used"
        },
        "purpose": {
          "type": "string",
          "description": "Why this dependency is needed"
        }
      }
    },
    "token_dependency": {
      "type": "object",
      "required": ["token_standard", "purpose"],
      "properties": {
        "token_standard": {
          "type": "string",
          "enum": ["SAC", "Native", "Custom"]
        },
        "purpose": {
          "type": "string"
        },
        "requirements": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "external_api": {
      "type": "object",
      "required": ["name", "purpose"],
      "properties": {
        "name": {
          "type": "string"
        },
        "purpose": {
          "type": "string"
        },
        "authentication": {
          "type": "string"
        }
      }
    },
    "network_deployment": {
      "type": "object",
      "required": ["network", "contract_id"],
      "properties": {
        "network": {
          "type": "string",
          "enum": ["mainnet", "testnet", "futurenet", "standalone"]
        },
        "contract_id": {
          "type": "string",
          "description": "Contract address on this network"
        },
        "deployed_at": {
          "type": "string",
          "format": "date-time"
        },
        "version": {
          "type": "string"
        }
      }
    },
    "initialization_guide": {
      "type": "object",
      "required": ["steps"],
      "properties": {
        "steps": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["step", "description"],
            "properties": {
              "step": {
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "command": {
                "type": "string"
              },
              "notes": {
                "type": "string"
              }
            }
          }
        },
        "prerequisites": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "upgrade_process": {
      "type": "object",
      "required": ["steps"],
      "properties": {
        "steps": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["step", "description"],
            "properties": {
              "step": {
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "command": {
                "type": "string"
              },
              "notes": {
                "type": "string"
              }
            }
          }
        },
        "rollback_procedure": {
          "type": "string"
        },
        "testing_requirements": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "error_registry_entry": {
      "type": "object",
      "description": "A single error code entry in the registry.",
      "required": ["code", "name", "range"],
      "properties": {
        "code": {
          "type": "integer",
          "description": "Numeric discriminant used in the #[contracterror] enum. Must be within designated ranges: 1-99 (common), 100-199 (governance), 200-299 (escrow), 300-399 (identity), 400-499 (program_escrow), 1000+ (system).",
          "minimum": 1,
          "maximum": 9999
        },
        "name": {
          "type": "string",
          "description": "Rust variant name (e.g. 'AlreadyInitialized'). Must match the enum variant name exactly.",
          "minLength": 1,
          "pattern": "^[A-Z][a-zA-Z0-9]*$"
        },
        "description": {
          "type": "string",
          "description": "Human-readable explanation of when this error is raised. Should be clear and actionable.",
          "minLength": 10
        },
        "range": {
          "type": "string",
          "description": "Logical range this code belongs to. Must be one of: common, governance, escrow, identity, program_escrow, system.",
          "enum": ["common", "governance", "escrow", "identity", "program_escrow", "system"]
        },
        "added_in": {
          "type": "string",
          "description": "Contract version when this code was introduced.",
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
        },
        "deprecated_in": {
          "type": "string",
          "description": "Contract version when this code was deprecated (if applicable).",
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
        },
        "security_critical": {
          "type": "boolean",
          "description": "Whether this error indicates a security-critical condition that should be monitored.",
          "default": false
        }
      }
    },
    "error_code_range": {
      "type": "object",
      "description": "A reserved numeric range for error codes in this contract. Must follow established range conventions.",
      "required": ["name", "min", "max"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Logical name of the range. Must be one of: common, governance, escrow, identity, program_escrow, system.",
          "enum": ["common", "governance", "escrow", "identity", "program_escrow", "system"]
        },
        "min": {
          "type": "integer",
          "description": "Inclusive lower bound. Must align with standard range conventions.",
          "minimum": 1
        },
        "max": {
          "type": "integer",
          "description": "Inclusive upper bound. Must be greater than or equal to min."
        },
        "description": {
          "type": "string",
          "description": "What kinds of errors live in this range.",
          "minLength": 10
        },
        "reserved": {
          "type": "boolean",
          "description": "Whether this range is reserved for future use (default: false).",
          "default": false
        }
      }
    }
  }
}