Supra Framework

This repository holds the Move framework packages deployed at address 0x1 on each Supra network: MoveStdlib, AptosStdlib, SupraStdlib and SupraFramework. The source is read from each network's on-chain 0x1::code::PackageRegistry, so a network's branch holds the framework that network is running.

Using the framework as a dependency

Add the framework to your package's Move.toml:

[dependencies]
SupraFramework = { git = "https://github.com/Entropy-Foundation/supra-framework.git", rev = "mainnet", subdir = "supra-framework" }

SupraFramework depends on the other three packages, so they need no entries of their own. To depend on one of them directly, use the same git and rev with subdir set to move-stdlib, aptos-stdlib or supra-stdlib.

Branches

Branch	Network	Chain ID
mainnet	Mainnet	8
testnet	Testnet	6
devnet	Devnet	50

A scheduled workflow reads each network's registry every hour and regenerates that network's branch. When the generated files change, the workflow commits them to the branch, and it tags each registry state it has not seen before.

A framework upgrade publishes its packages in separate transactions. When the registry has changed, the workflow reads it and the genesis hash a second time five minutes later, and uses them only if both reads return the same values; otherwise it skips that run.

While the genesis hash is unchanged, a package's upgrade_number never decreases. The workflow does not commit a registry in which any package's upgrade_number is lower than on the branch, as served by an RPC node that has not yet applied an upgrade. That run fails, and the next run that reads an up-to-date registry continues.

main holds this README and the workflow that generates the network branches.

Network resets

registry.json records the network's genesis hash: the hash that the genesis committee certifies for epoch 0, served at /rpc/v4/consensus/committees/0. It is the digest of the network's genesis configuration.

When the genesis hash on devnet changes, the workflow treats it as a reset and commits the reset network's framework on top of the branch's history; the commit message records both genesis hashes, and registry.json adds the previous one to retired_genesis_hashes. A change to a retired genesis hash fails the run, as does a changed genesis hash on mainnet or testnet.

A reset whose genesis configuration is byte-identical to the previous one, including its genesis timestamp, has the same genesis hash and is not detected. If its registry is older than the branch, every run fails. To resume, commit a change to devnet's registry.json that sets genesis_hash to 0x followed by 64 zeros. The next run treats the network as reset, does not add that value to retired_genesis_hashes, and says in its commit message that the branch was marked for reset.

Tags

Each registry state is tagged <network>-<hash>, for example mainnet-0f0b6eac260e. <hash> is the first 12 hex characters of the SHA-256 of the registry's BCS encoding, as the network's RPC returns it:

curl -s -H 'Accept: application/x-bcs' \
  'https://rpc-mainnet.supra.com/rpc/v3/accounts/0x1/resources/0x1::code::PackageRegistry' | sha256sum

The registry includes each package's upgrade_number, which increases with every upgrade of that package, so every framework upgrade produces a new tag, including one that deploys source the network ran before. A network reset that recreates a registry byte for byte reuses the existing tag, which points at the commit generated before the reset.

A tag points at the first commit generated from its registry state and is never moved. A later commit generated from the same registry state, after a change to the generator, can differ in its module sources and in its generated files, both described below, and carries no new tag. registry.json records the full SHA-256 of the registry each commit was generated from.

To build against a fixed version of the framework, use a tag as rev:

SupraFramework = { git = "https://github.com/Entropy-Foundation/supra-framework.git", rev = "mainnet-0f0b6eac260e", subdir = "supra-framework" }

Contents of a network branch

Each package directory holds Move.toml and sources/. Every Move.toml is byte-identical to the on-chain registry. Every module source is the on-chain source with its specifications removed:

• every spec ... { ... } block that names its target (a function, struct, module, schema, fun or native fun) is removed, with the /// doc comment lines above it, which the compiler attaches to the block across blank lines and // comment lines. Where code or a comment follows the block on its line, the line's indentation is kept;
• every spec { ... } statement in a function body is emptied to spec {}.

The generator fails if a removed block has an attribute, or if the result still holds a specification construct, such as a module-level invariant.

The on-chain sources call specification functions and variables defined in the framework's .spec.move files, which are not stored on chain; without those definitions the specifications do not compile.

A package that depends on a network branch compiles to the same bytecode as it would against the framework's original sources. Specification blocks are not compiled into bytecode. A spec statement in a function body compiles to a Nop, which spec {} keeps, but the locals it reads can decide whether the compiler copies or moves them. Emptying it can therefore change the framework's own bytecode: on Mainnet on 2026-10-16, compiled as the root package, randomness, stake and storage_gas differed from a build of the original sources in that way. That bytecode is not part of a dependent package. The only framework code a dependent package compiles into its own bytecode is the public inline funs it calls and the inline functions those call, directly or through other inline functions. The generator fails if a public inline fun holds a non-empty spec statement or calls an inline function that holds or reaches one.

The registry stores each module's whole source file, so modules published from one file share it, and it is written once, named after the first of them. The following files are not on chain and are generated:

• move-stdlib/sources/unit_test.move: the #[test_only] module std::unit_test, which supra move tool test requires. Test-only modules are not published.
• An empty #[test_only] module at 0x1 for each #[test_only] friend declaration in the framework that names a module not on chain, written once, in the first package in dependency order whose sources name it. Each one carries a comment stating that it is generated.
• registry.json: the network, its chain ID, its genesis hash, the genesis hashes it had before earlier resets, the SHA-256 of the registry's BCS encoding, and each package's upgrade_number and source_digest.
• README.md: a description of the branch.

The branches do not contain the framework's own tests, its .spec.move specification files or its generated documentation, because these are not stored on chain. Packages that depend on the framework compile and test without them, and so does the framework as the root package. The Move Prover cannot verify the framework from these branches.

CLI versions

supra move tool test runs native functions that are built into the supra CLI. Use a CLI release that matches the network whose branch you depend on.

Support

This repository is generated and does not accept changes to the framework. Report problems to support@supra.com.

License

Apache-2.0. See LICENSE.