Network

Represents a blockchain network.

Description

A Network object contains the desired configuration of a blockchain network and reports its ongoing status via status.

To provision a network, create a network object. The following request will create an Ethereum network with default configurations and install the Chainlink and The Graph plugins:

POST /v1alpha1/workspaces/{workspace}/networks
Content-Type: application/json

{
    "metadata": {
        "name": "octonet",
    }
    "spec": {
        "chain": {
            "type": "Ethereum",
            "ethereum": {
                "plugins": {
                    "chainlink": {},
                    "graph": {}
                }
            }
        }
    }
}

The server responds immediately with 201 Created and background controllers will start the provisioning process. For a full list of supported blockchain platforms and their respective plugins, see Supported chains and plugins.

You may request the network you just created:

GET /v1alpha1/workspaces/{workspace}/networks/octonet

And the server responds with:

{
    "kind": "Network",
    "version": "v1alpha1",
    "metadata": {
        "name": "octonet",
        "workspace": <workspace>,
        "rev": 1,
        "ownerID": <owner_id>,
        "createdAt": "2025-07-14T23:48:01.153Z",
        "updatedAt": "2025-07-14T23:48:01.153Z",
    },
    "spec": {
        "chain": {
            "type": "Ethereum",
            "ethereum": {
                // ...
            }
        }
    },
    "status": {
        "phase": "Pending",
        "message": "Provisioning network",
        "execution": {
            "currentStep": 15,
            "totalSteps": 56,
        },
        "chainSpecHash": "...",
        "lastActivityAt": "2025-07-14T23:48:01.153Z",
        "lastWakeUpAt": "2025-07-14T23:48:01.153Z"
    }
}

Notice how the network status is reported under status.

If you are using forked networks and want to resync to the latest block height, you may send an update network request with spec.maintenanceRequest:

PUT /v1alpha1/workspaces/{workspace}/networks
Content-Type: application/json

{
    "metadata": {
        "name": "octonet",
    }
    "spec": {
        "chain": {
            "type": "Ethereum",
            "ethereum": {
                "plugins": {
                    "chainlink": {},
                    "graph": {}
                }
            },
        },
        "maintenanceRequest": {
            "action": "Resync",
            "nonce": 1
        }
    }
}

Note that nonce must be different from status.observedMaintenanceNonce (0 if not set) for the maintenance action to be applied.

If you no longer need a network, you may delete it:

DELETE /v1alpha1/workspaces/<workspace>/networks/octonet

Supported chains and plugins

We currently support the following chains (or platforms) and plugins:

Type	Description	Plugins Available	Kurtosis package
Ethereum	Full consensus + execution layer	Chainlink, DFNS, Graph, Uniswap, VRF	ethereum-package
Arbitrum	Arbitrum L2 networks	Chainlink, DFNS, Graph, VRF	ethereum-package
Optimism	Optimism L2 networks	Chainlink, DFNS, Graph, VRF	ethereum-package
Polygon	Polygon networks	Chainlink, DFNS, Graph, VRF	ethereum-package
Base	Base L2 networks	Chainlink, DFNS, Graph, VRF	ethereum-package
BNB	BNB Smart Chain	Chainlink, DFNS, Graph, VRF	ethereum-package
Avalanche	Avalanche C-Chain	Chainlink, DFNS, Graph, VRF	ethereum-package
Fantom	Fantom networks	Chainlink, DFNS, Graph, VRF	ethereum-package
Mantle	Mantle networks	Chainlink, DFNS, Graph, VRF	ethereum-package
ZKSync	ZKSync Era networks	Chainlink, DFNS, Graph, VRF	ethereum-package
Solana	Solana networks	N/A	solana-package
LayerZero	Cross-chain infrastructure	Multi-chain configuration	layerzero-package

Persistent network

By default, networks stop shortly after 24 hours since the last wake up. Any activity one the network (viewing, updating, using endpoints) will cause the network to be restarted. At the moment, all data on the network will be lost.

To have networks running permanently with stronger guarantees, set spec.persistent to true, subject to workspace quota limits. For more information about quotas, see Quota. Persistent networks may take longer to provision due to higher compute constraints.

Operations

GET /v1alpha1/workspaces/{workspace}/networks/{name}

Get network name in workspace workspace

Responses

HTTP Code	Response
200 OK	Network
404 Not Found	Error

GET /v1alpha1/workspaces/{workspace}/networks

Get all networks in workspace workspace that the current requester has access to.

Query parameters

ListOptions

Selectable fields: status.phase, spec.chain.type, metadata.ownerID, spec.persistent

Responses

HTTP Code	Response
200 OK	NetworkList
404 Not Found	Error

GET /v1alpha1/workspaces/{workspace}/networks/{name}/endpoints

Get all endpoints that network name exposes.

Responses

HTTP Code	Response
200 OK	EndpointSet
404 Not Found	Error

POST /v1alpha1/workspaces/{workspace}/networks

Create a network in workspace workspace

Request body

Network

{
  "metadata": {
    "name": "octonet"
  },
  "spec": {
    "chain": {
      "type": "Ethereum",
      "ethereum": {
        "plugins": {
          "chainlink": {},
          "graph": {}
        }
      }
    }
  }
}

Responses

HTTP Code	Response
201 Created	Network
400 Bad Request	Error

PUT /v1alpha1/workspaces/{workspace}/networks

Updates network name in full in workspace workspace

Request body

Network

Responses

HTTP Code	Response
200 OK	Network
400 Bad Request	Error
404 Not Found	Error
409 Conflict	Error

DELETE /v1alpha1/workspaces/{workspace}/networks

Delete network name from workspace workspace

Responses

HTTP Code	Response
200 OK	Network
404 Not Found	Error
409 Conflict	Error

API objects

Network

Field	Type	Required	Notes
metadata	ObjectMeta		Standard object metadata
spec.persistent	boolean		Whether the network should be persistent
spec.maintenanceRequest.action	Restart | ResetState | Resync		Maintenance action to take
spec.maintenanceRequest.nonce	int		Increment to trigger the maintenance action (compare with status.observedMaintenanceNonce)
spec.chain.type	Ethereum | Arbitrum | Optimism | Base | BNB | Avalanche | Fantom | Mantle | ZKSync | Solana | LayerZero	Yes	The chain type of the network
spec.chain.ethereum	EthereumSpec	Yes if spec.chain.type == "Ethereum"	Ethereum chain parameters
spec.chain.arbitrum	Layer2Spec	Yes if spec.chain.type == "Arbitrum"	Arbitrum chain parameters
spec.chain.optimism	Layer2Spec	Yes if spec.chain.type == "Optimism"	Optimism chain parameters
spec.chain.base	Layer2Spec	Yes if spec.chain.type == "Base"	Base chain parameters
spec.chain.bnb	Layer2Spec	Yes if spec.chain.type == "BNB"	BNB chain parameters
spec.chain.avalanche	Layer2Spec	Yes if spec.chain.type == "Avalanche"	Avalanche chain parameters
spec.chain.fantom	Layer2Spec	Yes if spec.chain.type == "Fantom"	Fantom chain parameters
spec.chain.mantle	Layer2Spec	Yes if spec.chain.type == "Mantle"	Mantle chain parameters
spec.chain.zksync	Layer2Spec	Yes if spec.chain.type == "ZKSync"	ZKSync chain parameters
spec.chain.solana	Layer2Spec	Yes if spec.chain.type == "Solana"	ZKSync chain parameters
spec.chain.layerzero	LayerZeroSpec	Yes if spec.chain.type == "LayerZero"	LayerZero chain parameters
status.enclaveID	string		Internal identifier for the running enclave
status.phase	Pending | Operational | Stopping | Stopped | Error		Network phase
status.message	string		Human-readable message of why the network is in this status
status.execution.output	string		The output of the package
status.execution.currentStep	int		Index of the step currently running
status.execution.totalSteps	int		Total number of planned steps
status.chainSpecHash	string		Hash of the applied spec.chain
status.observedMaintenanceNonce	int		Last processed spec.maintenanceRequest.nonce
status.lastActivityAt	string		Last activity time in RFC 3339 format
status.lastStoppedAt	string		When the network last reached Stopped in RFC 3339 format
status.lastWakeUpAt	string		When the network last resumed from Stopped or started for the first time in RFC 3339 format

EthereumSpec

Field	Type	Required	Notes
packageVersion	enum		Kurtosis package version
chainID	string		Autogenerated if omitted on create
blockTime	int		Seconds
gasLimit	int		Genesis block gas limit
churnLimitQuotient	int		Beacon-chain parameter
ejectionBalance	int		Beacon-chain parameter
followDistance	int		Beacon-chain parameter
minWithdrawalDelay	int		Beacon-chain parameter
shardCommitteePeriod	int		Beacon-chain parameter
validatorCount	int		Number of validators seeded
mnemonicRef	LocalObjectReference		24-word seed (EL + CL)
privateKeyRef	LocalObjectReference	Yes	Fund-holding hot key
forking.enabled	boolean		Whether this network will fork data from mainnet
forking.blockHeight	string		Block height to fork up to
plugins.chainlink	object		Chainlink node set-up
plugins.uniswap	object		Uniswap config
plugins.graph	object		The Graph config
plugins.vrf	object		VRF config
plugins.vrf.type	vrfv2plus | mpc		VRF type
plugins.dfns	object		DFNS config
participants	EthereumParticipantSpec[]		Participant parameters

EthereumParticipantSpec

Field	Type	Required	Notes
elType	geth | reth | nethermind | erigon | besu		N/A
elImage	string		N/A
elExtraArgs	string	N/A	Extra arguments to pass to the EL container
clType	lighthouse | teku | nimbus | lodestar | grandine | prysm		N/A
clImage	string		N/A
clExtraArgs	string	N/A	Extra arguments to pass to the CL container
count	int		N/A

Layer2Spec

Field	Type	Required	Notes
chainID	string		Autogenerated if omitted on create
privateKeyRef	LocalObjectReference		Fund-holding hot key
forking.enabled	boolean		Whether this network will fork data from mainnet
forking.blockHeight	string		Block height to fork up to
plugins.chainlink	object		Chainlink node set-up
plugins.graph	object		The Graph config
plugins.vrf	object		VRF config
plugins.vrf.type	vrfv2plus | mpc		VRF type
plugins.dfns	object		DFNS config

LayerZeroSpec

NetworkList

Field	Type	Required	Notes
items	Network[]	Yes	The items of this list
metadata	ListMeta

EndpointSet

Field	Type	Required	Notes
metadata	ObjectMeta		Standard object metadata
map	Record<string, string>	Yes	Maps from service name to their URL