Skip to content

env.md

Latest commit

 

History

History
352 lines (233 loc) · 12 KB

env.md

File metadata and controls

352 lines (233 loc) · 12 KB

Agoric SDK Environment Variables

process.env.DOCUMENTATION // for power users

This file describes environment variables that influence the execution of the Agoric SDK.

AGORIC_NET

Affects: CLIs (agoric etc.), ymax-planner, other uses of @agoric/client-utils

Purpose: specify the chain/endpoint for outbound queries and transactions

Description: if nonempty, its contents must use one of the following formats:

  • "$subdomain": a subdomain of agoric.net that is expected to respond to an HTTP request for /network-config (e.g., "local" or "main" or a network listed at https://all.agoric.net/ ) with a JSON MinimalNetworkConfig object containing at least the following properties:
  • "$subdomain,$chainId": a single-word subdomain of rpc.agoric.net that is expected to respond to cosmos-sdk RPC requests, and a Cosmos Chain ID to associate with it
  • "$fqdn,$chainId": a fully-qualified domain name that is expected to respond to cosmos-sdk RPC requests, and a Cosmos Chain ID to associate with it

The default is usually 'local', which uses RPC endpoint http://0.0.0.0:26657 and chain ID "agoriclocal".

Lifetime: probably forever

CHAIN_BOOTSTRAP_VAT_CONFIG

Affects: ag-chain-cosmos, ag-solo

Purpose: to set the specifier for the chain/sim-chain's vatconfig.json

Description: defaults to @agoric/vm-config/decentral-core-config.json

Lifetime: until we don't want to allow user control of the chain's vat config

CXXFLAGS

Affects: yarn, agoric install

Purpose: add compilation flags to Node.js C++ addons

Description: defaults to -std=c++14 if not set (empty string doesn't default)

Lifetime: probably forever (until all supported Node versions work with CXXFLAGS='')

DEBUG

Affects: agoric (CLI), ag-chain-cosmos, ag-solo

Purpose: to change the meaning of console.log and other console methods

Description: uses anylogger to change whether the following methods are active for a given context, in order of increasing severity:

  1. console.debug
  2. console.log
  3. console.info
  4. console.warn
  5. console.error

If $DEBUG is unset or non-empty, then default (console.log and above) logging is enabled. (console.debug logging is disabled.)

If $DEBUG is set to an empty string, then quiet (console.info and above) logging is enabled. (console.log and console.debug logging is disabled.)

Otherwise, set to a comma-separated list of strings.

If one of those strings is

  • agoric:${level}, then don't print agoric-sdk console messages below ${level}.
  • agoric:none, then silence all agoric-sdk console messages.
  • agoric (an alias for agoric:debug) print all agoric-sdk console messages.
  • track-turns, then log errors at the top of the event-loop that may otherwise be unreported. See also the TRACK_TURNS environment variable below.
  • label-instances, then log exo instances with a unique label per instance. HAZARD This causes an information leak in the messages of thrown errors, which are available even to code without access to the console. Use with care.

For each of those strings beginning with a prefix recognized as indicating what console messages to enable, pass it to makeConsole. For example:

  • DEBUG=SwingSet:ls enable all console messages for liveslots, regardless of vat.
  • DEBUG=SwingSet:ls:v13 enable for liveslots in vat 13.
  • DEBUG=SwingSet:vat enable for user code, regardless of vat.
  • DEBUG=SwingSet:vat,SwingSet:ls enable for liveslots and user code, all vats

ENDO_DELIVERY_BREAKPOINTS

The value of this option should be a JSON string identifying for which eventual-send message deliveries should a JS debugger; statement be executed. The format of the JSON string is

{
  <class-like>: {
    <method-like>: <countdown>,
    <method-like>: <countdown>,
    ...
  },
  <class-like>: {
    <method-like>: <countdown>
    ...
  },
  ...
}

Where

  • <class-like> is either "*" or an alleged string tag of the receiving remotable (exo or far) object
  • <method-like> is either "*" or a method name. There is not yet a syntax for symbols to name symbol-named methods, but there may eventually be.
  • <countdown> is either "*" or a non-negative integer saying how many occurrences to ignore before breakpointing.

When the program is run under a debugger, it will breakpoint when the JS debugger; statement is executed. When run normally without a debugger, the debugger; statement will have no effect. The debugger; statement is executed before the method is entered.

See https://github.com/endojs/endo/blob/master/packages/pass-style/test/prepare-breakpoints.js for an example.

ENDO_SEND_BREAKPOINTS

The value of this option is a JSON string identifying for which eventual sends should a JS debugger; statement be executed. The format is the same as shown for ENDO_DELIVERY_BREAKPOINTS above, but the breakpoint happens when and where the message is sent, rather than when and where it is delivered.

END_BLOCK_SPIN_MS

Affects: cosmic-swingset

Purpose: simulating load to explore scalability of the Cosmos SDK.

Description: Number of milliseconds to busy-wait during every block's end-of-block processing for ag-chain-cosmos and the sim-chain.

Lifetime: until we have a more consistent load testing regimen

FAKE_CURRENCIES

Affects: cosmic-swingset

Purpose: allow the creation of pretend tokens

Description: When nonempty, create pretend prepopulated tokens like "moola" and "simoleans".

Lifetime: until chain is mature enough not to need any pretend tokens

LOCKDOWN_*

For the environment variables beginning with LOCKDOWN_ , see lockdown Options.

ONLY_WELL_FORMED_STRINGS_PASSABLE

As part of the OCapN standards process, we have agreed that only so-called "well formed" unicode strings should be considered Passable. However, we are not yet confident about the performance impact of enforcing this ban, so it is "disabled" by default for now. To turn it on, set this option to "enabled". See https://github.com/endojs/endo/blob/master/packages/pass-style/NEWS.md#v130-2024-03-19 for more explanation.

OTEL_EXPORTER_PROMETHEUS_PORT

Affects: cosmic-swingset

Purpose: enabling Prometheus metrics exports

Description: When set, metrics will be exposed in the Prometheus text-based format via HTTP on this port (or the default port 9464 when the value is not a number) for the host specified by OTEL_EXPORTER_PROMETHEUS_HOST (or default host 0.0.0.0) at default path "/metrics". See also README-telemetry.md.

Lifetime: until we decide not to support Prometheus for metrics export

SLOGFILE

Affects: cosmic-swingset

Purpose: record an on-chain Swingset LOG file

Description: when nonempty, use the value as an absolute path to which SwingSet debug logs should be written.

Lifetime: ?

SLOGSENDER

Affects: cosmic-swingset

Purpose: intercept the SwingSet LOG file in realtime

Description: when nonempty, use the value as a list of module specifiers separated by commas ,. @agoric/telemetry/src/make-slog-sender.js export makeSlogSender loads each module via dynamic import and calls its exported makeSlogSender function to construct a slogSender that will be called with each new slog entry (fanning such objects out to each module). Prefixing a module specifier with - causes it to be excluded, and can be used to suppress otherwise automatic use of modules for e.g. writing slogfiles and exporting Prometheus metrics.

The default is '@agoric/telemetry/src/flight-recorder.js', which writes to an mmap'ed circular buffer.

SLOGSENDER_AGENT

Affects: cosmic-swingset

Purpose: selects the agent type used to handle the SwingSet LOG

Description: if empty or 'self' slog senders are loaded in the same process and thread as the SwingSet kernel. If 'process', slog senders are loaded in a sub-process which receives all SLOG events over an IPC connection.

The default is 'self'.

SLOGSENDER_AGENT_*

A SLOGSENDER_AGENT_ prefix may be used to set variables in the environment of slog sender modules. The name prefix is stripped, allowing slog senders to see a different value for e.g. OTEL_EXPORTER_PROMETHEUS_PORT.

SLOGSENDER_FAIL_ON_ERROR

Affects: cosmic-swingset

Purpose: causes failures of the slogSender to be fatal

Description: if set (to a non empty value), a failure of the slogSender flush operation will result in a rejection instead of mere logging. Can be used to validate during tests that complex slog senders like the otel converter do not have any unexpected errors.

The default is undefined.

SOLO_BRIDGE_TARGET

Affects: solo

This enables a proxy so that the solo bridge interface (/wallet-bridge.html) is backed by the smart wallet (/wallet/bridge.html). Dapps designed for the solo bridge can enable this until they connect to the smart wallet directly.

BRIDGE_TARGET=http://localhost:3001 make BASE_PORT=8002 scenario3-run

Lifetime: smart wallet transition period

SOLO_MAX_DEBUG_LENGTH

Affects: solo

Purpose: reduce the size of each individual console.debug output

Description: defaults to no limit, set to a decimal byte count to reduce the output

Lifetime: Until CI no longer balks on long output, or our source bundles aren't delivered via messages to the sim-chain

SOLO_MNEMONIC

Affects: solo init

Seed phrase for HD key derivation.

SOLO_OTEL_EXPORTER_PROMETHEUS_PORT

Affects: solo

Same as OTEL_EXPORTER_PROMETHEUS_PORT, but for solo instead of chain.

Lifetime: ?

SOLO_SLOGFILE

Affects: solo

Same as SLOGFILE, but for solo instead of chain.

Lifetime: ?

SOLO_SLOGSENDER

Affects: solo

Same as SLOGSENDER, but for solo instead of chain.

Lifetime: ?

SOLO_*

A SOLO prefix may be used to set variables used only by solo processes. The name prefix is stripped, allowing such variables to be set in a shell environment without affecting cosmic-swingset.

SWINGSET_WORKER_TYPE

Affects: solo, unit tests

Purpose: select the default Worker type (default local)

Description: The SwingSet kernel launches each vat into a "worker" of a particular type. The local workers run in the same Node.js process as the kernel (which facilitates debugging). The xsnap workers run in a child process under the XS engine (which provides metering and heap snapshots, as well as more consistent GC behavior). xs-worker is an alias for xsnap.

Applications and unit tests may specify which type of worker they use for all vats in their config.defaultManagerType record, especially if they need a specific type for some reason. If they do not specify it there, the environment variable will supply a default. The full hierarchy of controls are:

  • config.vats.NAME.creationOptions.managerType (highest priority, but only for static vats)
  • config.defaultManagerType (applies to both static and dynamic vats)
  • env.SWINGSET_WORKER_TYPE
  • use a 'local' worker (lowest priority)

The environment variable exists so CI commands (e.g. 'yarn test:xs') can run a batch of unit tests under a different worker, without editing all their config records individually. config.defaultManagerType has a higher priority so that tests which require a specific worker (e.g. which exercise XS heap snapshots, or metering) can override the env var, so they won't break under yarn test:xs.

TRACK_TURNS

Log the deep causality stack behind logged errors if possible. See also the DEBUG setting DEBUG=track-turns above.