Importing Contracts

Imported Contracts are the contract definitions your Stagenet uses to recognise and understand contracts deployed on it.

When you import a contract, your Stagenet saves its metadata: ABI, bytecode, storage layout, and source code.

When you deploy a contract to your Stagenet, it checks whether it matches any Imported Contract. If it does, the new contract is recorded as a deployment of that Imported Contract.

When this happens, a Workspace is activated for that deployment, which uses the imported ABI and storage layout to provide analytics for it.

Why imports matter

Without Imported Contracts, your Stagenet deployments are just bytecode at an address.

Your Stagenet can still execute it, but contract.dev cannot fully understand what it is or how to display it.

Importing contracts lets contract.dev:

• Show contract names instead of raw addresses
• Decode function calls and events
• Display the contract’s storage layout
• Track balances, storage values, and function outputs over time
• Record every matching deployment of the contract
• Create Workspaces automatically when matching contracts are deployed

From import to Workspace

Importing a contract gives a Stagenet the metadata it needs to recognise and understand that contract.

The flow is:

1. You import a compiled contract to your Stagenet via GitHub CI/CD or CLI.
2. It stores its ABI, bytecode, storage layout, and source code.
3. You deploy that contract to your Stagenet.
4. It detects it as a deployment of the imported contract and creates a Workspace for it.

Import contract → Deploy contract → Workspace created

Versions, deployments, and Workspaces

Imported Contracts are organised around how smart contracts are developed.

You usually edit a contract over time, creating updated contract versions. You may also deploy the same version multiple times to test different configurations or scenarios.

contract.dev models that into versions and deployments:

• A contract can have many versions, each with a distinct bytecode.
• A version can have many deployments, each at a separate address.
• Each deployment gets its own Workspace.

Imported Contract
  └─ Version
       └─ Deployment
            └─ Workspace

How to import contracts

There are two ways to import contracts into a Stagenet.

GitHub CI/CD

Connect a GitHub repository containing a Hardhat or Foundry project. It will be compiled automatically and have its contracts imported.

CLI

Run import-contracts from a local Hardhat or Foundry project.

npx contract.dev import-contracts