Imported Contracts

Imported Contracts are your Stagenet’s registry of the smart contracts it knows about — their ABIs, bytecode, storage layouts, and link references.

When a contract is deployed to a Stagenet, the chain matches its deployed bytecode against this registry. If it matches, the Stagenet activates a Workspace — a dedicated dashboard for that contract.

To illustrate:

1. You compile Vault.sol
2. You import that contract, giving your Stagenet its ABI + bytecode
3. An inactive Workspace appears
4. You deploy Vault to the Stagenet
5. You Stagenet matches deployed bytecode
6. The Workspace activates for that address

Imported Contracts are what turn anonymous bytecode into named, decodable contracts on your Stagenet.

How to import contracts

There are two ways to add contracts to the registry:

• CLI — npx contract.dev push-contracts uploads compiled artifacts from your Hardhat or Foundry project on demand.
• GitHub CI/CD — connect a repository and the Stagenet compiles it on every push, importing the resulting artifacts automatically.

Both produce Imported Contracts. The rest of this page applies to either source.

Identity and versioning

Each unique contract becomes one Imported Contract, keyed by name within its source (the CLI project or the connected repository). Every import re-evaluates the bytecode of each contract and produces one of three outcomes:

• created — first time the Stagenet has seen this contract. A new Imported Contract is registered.
• new_version — the contract’s bytecode changed since the previous import. A new version is appended; previous versions are retained.
• unchanged — bytecode matches the latest version. No new version is created.

Versioning is by bytecode, not by source. A whitespace-only or comment-only change in source produces unchanged because the compiler emits identical bytecode. A logic change produces new_version.

Each version stores its ABI, creation bytecode, deployed bytecode, storage layout, and link references — everything needed to decode transactions and inspect state for any deployment that matches it.

Workspace activation

When a contract is deployed to your Stagenet, the chain compares the deployed bytecode against every version of every Imported Contract:

• Match → the matching Imported Contract’s Workspace activates for the new deployment.
• No match → the deployment is recorded but no Workspace is created automatically. You can still create one manually.

Because matching is on deployed bytecode, deploying the same contract multiple times all attach to the same Imported Contract — each deployment is its own Workspace, but they share the same Imported Contract record.

When versions matter

The retained version history is what makes deploys traceable: a Workspace remembers which version of the contract it was deployed from, even if newer versions have been imported since. If you deploy Vault v1, then push a change and import Vault v2, the original Workspace continues to use v1’s ABI and storage layout — it doesn’t silently switch to v2.

Removing Imported Contracts

Imported Contracts are tied to the source that produced them:

• CI/CD repositories — disconnecting a repository from its Settings tab removes its Imported Contracts.
• CLI imports — re-running push-contracts after removing a contract from your project’s source directory will not delete the existing record. To stop importing a specific contract, narrow your Artifact Selection patterns (CI/CD) or remove the contract from your source path (CLI).

Already-active Workspaces created from removed Imported Contracts remain — each Workspace stores the ABI it needs, so it keeps working independently.