{
"$id": "https://raw.githubusercontent.com/genlayerlabs/genvm/refs/heads/main/doc/schemas/runner.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "GenVM runner.json",
"oneOf": [
{ "$ref": "#/definitions/InitAction" }
],
"definitions": {
"WasmMode": {
"enum": ["det", "!det"]
},
"runner-id": {
"type": "string",
"description": "Identifier of a runner to load. Hashes are matched in their canonical GVM32 form; the executor's decoder is additionally lenient about case, the `i`/`l`/`o` aliases and ignored `-`, but ids are not written that way",
"anyOf": [
{
"pattern": "^[a-zA-Z0-9_-]+:[0-9abcdefghjkmnpqrstvwxyz]{52}$",
"not": { "pattern": "^(contract|chain|custom):" },
"description": "`name:hash` — packaged runner by human readable name and archive hash, the latter 52 GVM32 characters (in dev mode the magic `test0000...` hash, which is itself well-formed GVM32). `contract`/`chain`/`custom` are reserved and cannot be used as a name"
},
{
"const": "contract",
"description": "the runner of the contract that is currently being executed"
},
{
"pattern": "^chain:0x[0-9a-fA-F]{40}(:[af](:[0-9abcdefghjkmnpqrstvwxyz]{52})?)?$",
"description": "`chain:<address>[:<a|f>[:<slot>]]` — code blob read from a `0x` 20 byte address at a GVM32-encoded 32 byte slot, `a`=accepted / `f`=finalized. `<a|f>` and `<slot>` are optional: `<a|f>` defaults to `a` and `<slot>` to the target contract's root code slot"
},
{
"pattern": "^custom:[0-9abcdefghjkmnpqrstvwxyz]{52}$",
"description": "`custom:<hash>` — runner registered at runtime, addressed by 52 GVM32 characters"
}
]
},
"NestedInitAction": {
"description": "A rule nested inside another one. `$schema` is only accepted on the top level object.",
"allOf": [
{ "$ref": "#/definitions/InitAction" },
{ "not": { "required": ["$schema"] } }
]
},
"InitAction": {
"description": "A single rule for loading.",
"type": "object",
"allOf": [
{
"oneOf": [
{
"required": [
"AddEnv"
]
},
{
"required": [
"MapFile"
]
},
{
"required": [
"SetArgs"
]
},
{
"required": [
"LinkWasm"
]
},
{
"required": [
"StartWasm"
]
},
{
"required": [
"Depends"
]
},
{
"required": [
"Seq"
]
},
{
"required": [
"When"
]
},
{
"required": [
"With"
]
}
]
}
],
"properties": {
"$schema": { "type": "string" },
"AddEnv": {
"description": "Adds environment variable",
"type": "object",
"additionalProperties": false,
"required": ["name", "val"],
"properties": {
"name": {
"type": "string",
"description": "variable name"
},
"val": {
"type": "string",
"description": "variable value, can use ${} to access currently set env variables"
}
}
},
"MapFile": {
"description": "Makes file available at specified path in genvm",
"type": "object",
"additionalProperties": false,
"required": ["file", "to"],
"properties": {
"file": {
"type": "string",
"description": "path within an archive, if it ends with `/`, it will map all files in that directory recursively"
},
"to": {
"type": "string",
"description": "absolute path in genvm fs"
}
}
},
"SetArgs": {
"description": "sets process arguments for genvm",
"type": "array",
"items": {
"type": "string"
}
},
"LinkWasm": {
"description": "Link wasm file to be available from genvm",
"type": "string"
},
"StartWasm": {
"description": "Start wasm file in genvm",
"type": "string"
},
"Depends": {
"description": "Depend on another runner",
"$ref": "#/definitions/runner-id"
},
"Seq": {
"description": "Execute sequence",
"type": "array",
"items": {
"$ref": "#/definitions/NestedInitAction"
}
},
"When": {
"description": "Conditionally execute action",
"type": "object",
"additionalProperties": false,
"required": ["cond", "action"],
"properties": {
"cond": { "$ref": "#/definitions/WasmMode" },
"action": { "$ref": "#/definitions/NestedInitAction" }
}
},
"With": {
"description": "Makes given runner current without executing it's action. It means that MapFile will fork with files from this archive. Useful for creating lock files",
"type": "object",
"additionalProperties": false,
"required": ["runner", "action"],
"properties": {
"runner": {
"description": "runner id to make current",
"$ref": "#/definitions/runner-id"
},
"action": { "$ref": "#/definitions/NestedInitAction" }
}
}
},
"additionalProperties": false
}
}
}
