Skip to content

feat: expose a stable TRE instance identifier#33

Open
nahimterrazas wants to merge 1 commit into
mainfrom
feat/tre-instance-id
Open

feat: expose a stable TRE instance identifier#33
nahimterrazas wants to merge 1 commit into
mainfrom
feat/tre-instance-id

Conversation

@nahimterrazas

Copy link
Copy Markdown
Collaborator

Summary

Adds hre.tre.instanceId(): a stable identifier for the specific TRE node the active network points at, and exposes it to upgrades tooling by answering hardhat_metadata on tron-typed networks.

What instanceId() returns

A string that identifies one running TRE instance. It is resolved once and cached per (network, url).

  • Container-identity derivation (plugin-managed TRE). When this plugin launched the container (auto-start on hardhat test / node / compile, or a keepRunning restart), the id is 0x + sha256(<docker container id> + "|" + <State.StartedAt>). The container id changes on every fresh docker run and StartedAt changes on every docker start, so the id is distinct for each boot even when the chain is otherwise byte-for-byte deterministic.
  • External-TRE fallback + limitation. For a TRE this plugin did not launch (already reachable when a task started, a manual docker-compose up, or a parallel-test runner pointing at its own TRE_URL), the container identity is unknown, so the id falls back to the genesis block hash. Because a TRE booted from identical config reproduces the same genesis block, two deterministic restarts of an external TRE will share an id. This limitation is documented on the API type; let the plugin manage the container lifecycle if you need a guaranteed-fresh id per restart.

This replaces deriving the id from the genesis hash alone, which could not tell two deterministic restarts of the same chain apart.

Provider metadata exposure

An extendProvider hook makes tron-typed networks answer the hardhat_metadata JSON-RPC method, mirroring the built-in Hardhat Network. The response reports the chain id (read from eth_chainId, so it always matches) and the instance id above. Tooling such as @openzeppelin/upgrades-core probes this method to key its per-instance deployment manifests; exposing the id at the shared network provider lets that tooling isolate a restarted local chain's records through its own internal manifest resolution, instead of reusing a manifest keyed by chain id alone. Only tron-typed networks are wrapped; every other network's provider is returned untouched, and no other RPC behavior changes.

Test coverage

  • A docker-gated suite boots two fresh TRE instances sequentially, tears each down, and asserts their ids differ while their genesis blocks are identical — the property the genesis-hash derivation could not provide.
  • The end-to-end suite asserts the network provider answers hardhat_metadata with a chainId matching eth_chainId and an instanceId equal to hre.tre.instanceId(), and that the external-TRE path falls back to the genesis-derived id.

Both are gated the same way as the existing e2e tests, so CI without a container runtime stays green.

Add hre.tre.instanceId(): a stable identifier for the specific TRE node the
active network points at.

When the plugin launched the TRE container, the id is derived from the
container's own identity (docker container id + StartedAt), hashed. Both change
on a fresh `docker run` and StartedAt also changes on `docker start`, so the id
distinguishes one boot from the next even when the chain is byte-for-byte
deterministic. This replaces deriving the id from the genesis block hash, which
a TRE booted from identical config reproduces on every restart and so cannot
tell two restarts apart. The genesis hash is kept only as a fallback for an
externally-provided TRE (one the plugin did not launch); its limitation for
deterministic external restarts is documented on the API.

Also answer `hardhat_metadata` on tron-typed networks via an extendProvider
hook, mirroring the built-in Hardhat Network. Upgrades tooling probes this RPC
to key its per-instance deployment manifests; exposing the instance id at the
shared network provider lets that tooling isolate a restarted local chain's
records natively, through its own internal manifest lookups, instead of reusing
a stale manifest keyed by chain id alone.

Tested: a docker-gated suite boots two fresh TRE instances sequentially and
asserts their ids differ while their genesis blocks match; the e2e suite checks
the provider answers hardhat_metadata with a chainId matching eth_chainId and
the same instance id.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant