Detailed Feedback

DAML Sandbox¶

The DAML Sandbox, or Sandbox for short, is a simple ledger implementation that enables rapid application prototyping by simulating a Digital Asset Distributed Ledger.

You can start Sandbox together with Navigator using the daml start command in a DAML SDK project. This command will compile the DAML file and its dependencies as specified in the daml.yaml. It will then launch Sandbox passing the just obtained DAR packages. Sandbox will also be given the name of the startup scenario specified in the project’s daml.yaml. Finally, it launches the navigator connecting it to the running Sandbox.

It is possible to execute the Sandbox launching step in isolation by typing daml sandbox.

Sandbox can also be run manually as in this example:

$ daml sandbox Main.dar --scenario Main:example

   ____             ____
  / __/__ ____  ___/ / /  ___ __ __
 _\ \/ _ `/ _ \/ _  / _ \/ _ \\ \ /
/___/\_,_/_//_/\_,_/_.__/\___/_\_\
initialized sandbox with ledger-id = sandbox-16ae201c-b2fd-45e0-af04-c61abe13fed7, port = 6865,
dar file = DAR files at List(/Users/donkeykong/temp/da-sdk/test/Main.dar), time mode = Static, daml-engine = {}
Initialized Static time provider, starting from 1970-01-01T00:00:00Z
listening on localhost:6865

Here, daml sandbox tells the SDK Assistant to run sandbox from the active SDK release and pass it any arguments that follow. The example passes the DAR file to load (Main.dar) and the optional --scenario flag tells Sandbox to run the Main:example scenario on startup. The scenario must be fully qualified; here Main is the module and example is the name of the scenario, separated by a :.

Note

The scenario is used for testing and development only, and is not supported by production DAML Ledgers. It is therefore unadvisable to rely on scenarios for ledger initialization.

submitMustFail is only supported by the test-ledger used by daml test and the IDE, not by the Sandbox.

Running with persistence¶

By default, Sandbox uses an in-memory store, which means it loses its state when stopped or restarted. If you want to keep the state, you can use a Postgres database for persistence. This allows you to shut down Sandbox and start it up later, continuing where it left off.

To set this up, you must:

create an initially empty Postgres database that the Sandbox application can access
have a database user for Sandbox that has authority to execute DDL operations

This is because Sandbox manages its own database schema, applying migrations if necessary when upgrading versions.

To start Sandbox using persistence, pass an --sql-backend-jdbcurl <value> option, where <value> is a valid jdbc url containing the username, password and database name to connect to.

Here is an example for such a url: jdbc:postgresql://localhost/test?user=fred&password=secret

Due to possible conflicts between the & character and various terminal shells, we recommend quoting the jdbc url like so:

$ daml sandbox Main.dar --sql-backend-jdbcurl "jdbc:postgresql://localhost/test?user=fred&password=secret"

If you’re not familiar with JDBC URLs, see the JDBC docs for more information: https://jdbc.postgresql.org/documentation/head/connect.html

Running with authentication¶

By default, Sandbox does not use any authentication and accepts all valid ledger API requests.

To start Sandbox with authentication based on JWT, run daml sandbox --auth-jwt-hs256-unsafe=<secret> where <secret> is the secret used to sign the token with the HMAC256 algorithm. Please note that this option is there _exclusively_ for testing: for production use cases you are advised to use asymmetric key signing, which is currently being worked on.

The JWT payload has the following schema:

{
   "ledgerId": "aaaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "participantId": null,
   "applicationId": null,
   "exp": 1300819380,
   "admin": true,
   "actAs": ["Alice"],
   "readAs": ["Alice", "Bob"],
}

where ledgerId, participantId, applicationId restricts the validity of the token to the given ledger, participant, or application; exp is the standard JWT expiration date; admin determines whether the token bearer is authorized to use admin endpoints of the ledger API; actAs lists all DAML parties the token bearer can act as (e.g., as submitter of a command); and readAs lists all DAML parties the token bearer can read data for.

Command-line reference¶

To start Sandbox, run: sandbox [options] <archive>...

To see all the available options, run daml sandbox --help