Module cubist_config::network

Expand description

This module exposes the Cubist network configuration interface NetworkProfile.

A NetworkProfile provides configuration for each Target chain in use.

A portion of that configuration is common to all chains (see CommonConfig) and it includes:

url: URL of the chain endpoint
autostart: whether to start a local instance of the chain at url (applies only if url is a localhost address)
proxy: whether and how to start a Cubist Proxy in front or url (applies only if autostart is false)

Autostart Local Networks

If autostart is true (default) and url is a localhost address, Cubist (the cubist start command, to be precise) will automatically start a local instance of the specified chain. For example,

{
  "ethereum": { "url": "http://localhost:8545", "autostart": true },
  "polygon": { "url": "http://localhost:9545", "autostart": true }
}

will instruct Cubist to launch anvil (an Ethereum implementation) and make its JSON RPC endpoint available at http://localhost:8545, as well as bor (a Polygon implementation) and make its JSON RPC endpoint available at http://localhost:9545.

Cubist exposes different customization options for different target chains: EthereumConfig, PolygonConfig, and AvalancheConfig. Here are some examples:

Create funded accounts on Ethereum

The following configuration snippet will bootstrap anvil with 2 funded accounts generated from a specific mnemonic. The mnemonic is read from the ETHEREUM_MNEMONIC environment variable (.env files are supported).

{
  "url": "http://localhost:8545",
  "autostart": true,
  "bootstrap_mnemonic": {
    "seed": { "env": "ETHEREUM_MNEMONIC" },
    "account_count": 2
  }
}

Create funded accounts on Polygon

The following configuration snippet will bootstrap bor with 2 funded accounts, one generated from a given mnemonic (read from the POLYGON_MNEMONIC env var) and one from a given private key (read from the .polygon.secret file).

{
  "url": "http://localhost:8545",
  "autostart": true,
  "local_accounts": [
    { "mnemonic":    { "seed": { "env": "POLYGON_MNEMONIC" } } },
    { "private_key": { "hex":  { "file": ".polygon.secret" } } }
   ]
}

Connect to a Public Network

Before discussing how to configure Cubist to connect to public networks, we must first introduce Cubist Proxy.

Cubist Proxy

Cubist Proxy is a component that sits between the client dApp and an actual chain endpoint node and automatically signs every transaction submitted via eth_sendTransaction. All other JSON RPC requests (with a few exceptions) are forwarded to the real endpoint (see CommonConfig::url) as is.

This is very useful when connecting to a public network, because all credentials can be securely managed by Cubist Proxy. Consequently, the client-side app doesn’t have to worry about managing secrets, signing, computing nonces, etc.

Proxy configuration is specified via the ProxyConfig struct and it includes:

port: localhost port on which the proxy will be listening for requests
chain_id: id of the target chain (so that Cubist Proxy can automatically set it if not set by the client app)
creds: credentials to use.

For every eth_sendTransaction request it receives, Cubist Proxy:

extracts the sender field from it,
looks up the credentials for that sender,
populates any missing transaction parameters (e.g., chain id, nonce, etc.),
signs the transaction on behalf of sender (using whatever signing mechanism is configured for that sender in ProxyConfig::creds), and finally
forwards the signed transaction to the endpoint via eth_sendRawTransaction.

Example: Connecting to a Public Testnet

When using local chains only, no explicit account/authentication configuration needs to be provided by the user. That’s because Cubist will use a default account to start each local chain, and Cubist Proxy will use that same account to automatically sign transactions targeting that chain.

In contrast, when connecting to a public network, the user must already have an account set up with that network provider. If that network only accepts signed transactions (and most likely it does), Cubist must be configured to sign transactions using that existing account. Because the Cubist SDK does not deal with signing at all (by design!), the solution is to configure and run a Cubist Proxy in front of the remote endpoint.

The CommonConfig::url field is used to specify a public network endpoint, e.g., wss://polygon-mumbai.g.alchemy.com/v2/${{env.ALCHEMY_MUMBAI_API_KEY}}¹. Additionally, Cubist Proxy must be configured with at least one credential (see ProxyConfig::creds), which it will use to sign all transactions. The following example specifies a bip39 mnemonic; for other kinds of credentials, see CredConfig.

{
  "url": "wss://polygon-mumbai.g.alchemy.com/v2/${{env.ALCHEMY_MUMBAI_API_KEY}}",
  "proxy": {
     "port": 9545,
     "chain_id": 80001,
     "creds": [{
       "mnemonic": { "seed": { "env": "MUMBAI_ACCOUNT_MNEMONIC" } }
     }]
  }
}

Note the use of ${{env.ALCHEMY_MUMBAI_API_KEY}}: instead of hardcoding the secret API key into the plain-text config file, we use the special ${{env.VAR_NAME}} syntax to instruct Cubist to read it from the environment. ↩