alpage

Config Schema

Alpage config is HCL. The blocks below are the complete schema; it is generated from the hcl:"..." struct tags in nns/, so it always matches what the tool parses.

This page documents the current development schema, ahead of the latest release. The Since column gives the release each block and field first appeared in, so a field newer than your binary is visible as such; see Schema History for the schema as of each release.

resources.hcl

subnet "<name>" { }

v0.1.0 A subnet, referenced from proposals and nodes as subnet.<name>.id.

Field Kind Required Since Description
id attr yes v0.1.0 Principal of the subnet.
label attr no v0.1.0 Human-readable name.
sev_enabled attr no v0.1.1 Whether the subnet runs with SEV-SNP enabled, reconciled against the registry's features.sev_enabled. Omitted means false.
type attr no v0.2.0 Subnet type: application, verified_application, system, or cloud_engine. Omitted means application.
cost_schedule attr no v0.2.0 Canister cycles cost schedule: normal or free. Omitted means free for a cloud_engine, which the registry requires, and normal otherwise.
admins attr no v0.2.0 Principals with admin rights on the subnet (subnet_admins). Allowed only on a cloud_engine or a rented subnet (application on the free schedule), at most 10. Declaring none asserts none, so an admin added on-chain is drift. Order is not significant.

data_center "<name>" { }

v0.1.0 A registry data center, referenced by node_operator as data_center.<name>.id.

Field Kind Required Since Description
id attr yes v0.1.0 Registry data center id.
label attr no v0.1.0 Human-readable name.
region attr no v0.1.0 Registry region string (e.g. Europe,CH,Vaud).

node_provider "<name>" { }

v0.1.0 A node provider, referenced by node_operator as node_provider.<name>.id.

Field Kind Required Since Description
id attr yes v0.1.0 Principal of the node provider.
label attr no v0.1.0 Human-readable name.
decommissioned attr no v0.5.0 Marks a node provider removed on-chain. Its block is kept so historical proposal payloads keep resolving to the ids they were submitted with; reconcile expects it, and every operator under it, to be absent from the registry.

node_operator "<name>" { }

v0.1.0 A node operator, referenced by node as node_operator.<name>.id.

Field Kind Required Since Description
id attr yes v0.1.0 Principal of the node operator.
label attr no v0.1.0 Human-readable name.
provider attr no v0.1.0 Id of its node provider (node_provider.<name>.id).
dc attr no v0.1.0 Id of its data center (data_center.<name>.id).
decommissioned attr no v0.5.0 Marks a node operator removed on-chain. Its block is kept so historical proposal payloads keep resolving to the ids they were submitted with; reconcile expects it to be absent from the registry. Implied for every operator under a decommissioned node_provider.

guestos_version "<name>" { }

v0.3.0 A named GuestOS/replica version, referenced by node and by deploy_guestos as guestos_version.<name>.id. alp guestos sync generates the elected set as resources/guestos.hcl.

Field Kind Required Since Description
id attr yes v0.3.0 GuestOS/replica version hash. Spelled id, not hash, so it resolves through the same <kind>.<name>.id form as every other resource.
label attr no v0.3.0 Human-readable name (e.g. the release name).
default attr no v0.5.0 Marks the version every node is expected to run unless its own block overrides it, so a fleet-wide rollout is one edit here rather than one per node. At most one guestos_version may carry it; two is a load error. With a default declared, a node omitting guestos_version inherits it instead of going unchecked, so guestos_version = "none" is how a single node opts out.

node "<name>" { }

v0.1.0 A node, referenced from proposals as node.<name>.id.

Field Kind Required Since Description
id attr yes v0.1.0 Principal of the node.
label attr no v0.1.0 Human-readable name.
subnet attr no v0.1.0 Id of the subnet it belongs to (subnet.<name>.id). Empty means unassigned.
operator attr no v0.1.0 Id of its node operator (node_operator.<name>.id).
decommissioned attr no v0.1.1 Marks a node deregistered on-chain. Its block is kept so historical proposal payloads keep resolving to the ids they were submitted with; reconcile expects it to be absent from the registry.
guestos_version attr no v0.2.0 GuestOS/replica version this node is expected to run. Not a registry fact: the registry stores one version per subnet, so reconcile reads the node's own /api/v2/status impl_version, which needs IPv6. If the node is unreachable it falls back to the public dashboard, marking the row "via dashboard" since that data may lag. Reconcile also checks the version against the NNS elected set and marks it "NOT ELECTED" if absent; when that source is unreadable the check is skipped rather than failing. Omitted inherits the guestos_version marked default, and means unchecked when there is none; setting it while a default exists marks the row "[override]". "none" opts the node out of the check entirely.
chip_id attr no v0.4.0 The node's AMD SEV-SNP CHIP_ID as hex, the form AMD's KDS takes as its hwID parameter (base64 is also accepted; comparison is on the decoded bytes). 64 opaque bytes identifying the physical CPU, recorded by the registry canister only for a node onboarded with SEV. Pins hardware identity, not live TEE state. Reconcile also asks AMD KDS to vouch for the chip, caching the verdict in state.json. Omitted asserts the node carries none, so gaining, losing, or changing one is drift; an unread record reports "unknown".

proposals.hcl

provider { }

v0.1.0 Global submission settings; CLI flags override these.

Field Kind Required Since Description
host attr no v0.1.0 Governance host URL. Defaults per command; overridden by --host.
neuron attr no v0.1.0 Proposer neuron id.
fetch_root_key attr no v0.1.0 Whether to fetch the IC root key. Unset defaults to true for non-mainnet hosts.

proposal "<name>" { }

v0.1.0 One NNS proposal. Carries common metadata plus a nested block named after its kind.

Field Kind Required Since Description
kind attr yes v0.1.0 Proposal kind; selects the nested block (membership, deploy_guestos, update_subnet, remove_nodes, remove_node_operators, remove_node_provider).
title attr yes v0.1.0 Proposal title shown on the NNS.
summary attr no v0.1.0 Proposal summary (markdown).
url attr no v0.1.0 Reference URL (e.g. forum thread).

membership { }

v0.3.0 Nested in a proposal of kind "membership": change_subnet_membership. Holds add/remove node blocks. Renamed from resize in v0.3.0; a config written for v0.2.0 or earlier must rename the block and its kind.

Field Kind Required Since Description
subnet_id attr yes v0.3.0 Subnet whose membership changes (subnet.<name>.id).
add block no v0.3.0 A node to add to the subnet; repeatable. See the add / remove block.
remove block no v0.3.0 A node to remove from the subnet; repeatable. See the add / remove block.

deploy_guestos { }

v0.1.0 Nested in a proposal of kind "deploy_guestos": deploy_guestos_to_all_subnet_nodes.

Field Kind Required Since Description
subnet_id attr yes v0.1.0 Subnet whose nodes to upgrade (subnet.<name>.id).
replica_version_id attr yes v0.1.0 Replica version to deploy to every node in the subnet (guestos_version.<name>.id, or the hash itself). Must be elected by the NNS: preflight checks the registry for a replica_version_<id> record (read via the registry explorer) and refuses an unelected version, since the NNS would reject the proposal. --force submits anyway, and also lets apply proceed when that lookup fails (downgraded to a warning); plan always degrades that way. Preflight additionally resolves the version's release name and election proposal from the public dashboard, which is display-only and degrades to a note when unavailable.

update_subnet { }

v0.5.0 Nested in a proposal of kind "update_subnet": update_subnet (UPDATE_CONFIG_OF_SUBNET). Changes a subnet's configuration record. Every field is optional and an omitted one is left untouched on-chain, so a proposal changes exactly what it declares. Preflight diffs every declared field against the current record. Two payload fields are not settings here: subnet_type, which the registry asserts is unchanged, and a sev_enabled change, which it rejects outright.

Field Kind Required Since Description
subnet_id attr yes v0.5.0 Subnet whose configuration changes (subnet.<name>.id).
is_halted attr no v0.5.0 Whether the subnet is halted: a halted subnet no longer creates or executes blocks. This is how a subnet is frozen for a recovery, and setting it back to false is how it resumes.
halt_at_cup_height attr no v0.5.0 Halt the subnet once it reaches the next CUP height rather than immediately, so it stops at a known state. The registry resets this flag when a new CUP proposal is approved and sets is_halted instead, so the subnet stays halted until a later proposal sets is_halted = false.
max_number_of_canisters attr no v0.5.0 Maximum number of canisters that may be present on the subnet at any one time. 0 does not mean unlimited: it means the replica's own default applies.
ssh_readonly_access attr no v0.5.0 Public keys whose owners get "readonly" SSH access to every replica on the subnet, for when a subnet recovery has to be performed. The list is replaced, not merged, so it must name every key that keeps access; an empty list revokes all of them. Preflight flags a declared list that clears existing entries.
ssh_backup_access attr no v0.5.0 Public keys whose owners get "backup" SSH access to the subnet's nodes, which is what makes backing up the NNS possible. Replaced wholesale like ssh_readonly_access.
subnet_admins attr no v0.5.0 Principals that have admin privileges on the subnet. Replaced wholesale, so the list must be complete.
features block no v0.5.0 The subnet's feature flags. Replaced wholesale; see the features block.
resource_limits block no v0.5.0 The subnet's resource-consumption limits. Replaced wholesale; see the resource_limits block.
unit_delay_millis attr no v0.5.0 Unit delay for the blockmaker, in milliseconds.
initial_notary_delay_millis attr no v0.5.0 Initial delay for the notary, in milliseconds, which gives rank-0 blocks time to propagate.
dkg_interval_length attr no v0.5.0 Length of every DKG interval, counted in the rounds that follow the DKG summary.
dkg_dealings_per_block attr no v0.5.0 Upper bound on the number of DKG dealings allowed in one block.
max_ingress_bytes_per_message attr no v0.5.0 Maximum bytes per ingress message. A hard cap: a message over the limit is dropped.
max_ingress_bytes_per_block attr no v0.5.0 How big an ingress payload may be when held in memory, which may exceed max_block_payload_size since ingress messages are stripped before a block is disseminated. 0 means the replica's built-in default; too high a value drives up replica memory use.
max_ingress_messages_per_block attr no v0.5.0 Maximum number of ingress messages per block.
max_block_payload_size attr no v0.5.0 Maximum size in bytes a block payload may have when sent over the wire. Setting it too high slows block delivery to peers, which can cause forks as higher-rank blocks get proposed meanwhile.

remove_nodes { }

v0.5.0 Nested in a proposal of kind "remove_nodes": deregisters nodes, freeing their operators' allowance. Holds one node block per node. The registry rejects a node that is still a subnet member, so remove it from its subnet first; preflight checks this before the proposal is cut.

Field Kind Required Since Description
node block no v0.5.0 A node to deregister. Repeat the block for each one.

remove_node_operators { }

v0.5.0 Nested in a proposal of kind "remove_node_operators": deletes node operator records. The registry silently skips an operator that still owns nodes, so deregister its nodes first; preflight checks this.

Field Kind Required Since Description
operators attr yes v0.5.0 Ids of the node operators whose records to delete (node_operator.<name>.id).

remove_node_provider { }

v0.5.0 Nested in a proposal of kind "remove_node_provider": removes a node provider. Unlike the other kinds this is a native governance action rather than an ExecuteNnsFunction. Governance rejects a provider it does not know, and removing one that still has operators orphans them; preflight checks both.

Field Kind Required Since Description
node_provider_id attr yes v0.5.0 Principal of the node provider to remove (node_provider.<name>.id).

add / remove { }

v0.1.0 Inside a membership block: a node to add to or remove from the subnet.

Field Kind Required Since Description
id attr yes v0.1.0 Node id (node.<name>.id).
label attr no v0.1.0 Optional human-readable name.

features { }

v0.5.0 Inside an update_subnet block: the subnet's feature flags. Sending it replaces the whole features record rather than merging, so all three fields are required: an omitted one would be written as false. sev_enabled must therefore restate what the subnet already has; the registry rejects a change to it.

Field Kind Required Since Description
canister_sandboxing attr yes v0.5.0 Whether canister execution happens in a sandboxed process. Disabled by default.
http_requests attr yes v0.5.0 Whether canisters on the subnet may perform outbound HTTP(S) requests.
sev_enabled attr yes v0.5.0 Whether the subnet runs with SEV-SNP enabled. Required because the features record is replaced wholesale, but it cannot be changed: the registry only accepts sev_enabled as it was set when the subnet was created, and traps on any change after the proposal is adopted. State the subnet's current value; preflight and the dry-run both reject anything else.

resource_limits { }

v0.5.0 Inside an update_subnet block: the subnet's state-size limits. Replaced wholesale like features, so both fields are required.

Field Kind Required Since Description
maximum_state_size attr yes v0.5.0 Maximum subnet state size in bytes.
maximum_state_delta attr yes v0.5.0 Maximum subnet state delta in bytes.

Schema History

Each release's schema, as generated at that tag: