Agoric Platform SDK
This repository contains most of the packages that make up the Agoric platform. If you want to build on top of this platform, you don't need this repository: instead you should follow our instructions for getting started with the Agoric SDK.
But if you are improving the platform itself, this is the repository to use.
- Node.js (version 11 or higher)
- Yarn (
npm install -g yarn)
You don't need Golang if you just want to test contracts and run the
"scenario3" simulator. Golang (1.13 or higher) is needed only if you
want to build/debug Cosmos SDK support. (The
1.12 release will work, but
it will modify
packages/cosmic-swingset/go.mod upon each build (by adding
a dependency upon
1.13 release will leave the
file correctly unmodified.
Any version of Yarn will do: the
.yarnrc file should ensure that all
commands use the specific checked-in version of Yarn (stored in
.yarn/releases/), which we can update later with PRs in conjunction with
any necessary compatibility fixes to our
From a new checkout of this repository, run:
yarn install is done, the top-level
node_modules/ will contain
all the shared dependencies, and each subproject's
contain only the dependencies that are unique to that subproject (e.g. when
the version installed at the top level does not meet the subproject's
constraints). Our goal is to remove all the unique-to-a-subproject deps.
When one subproject depends upon another,
node_modules/ will contain a
symlink to the subproject (e.g.
ERTP depends upon
node_modules/@agoric/marshal is a symlink to
yarn workspaces info to get a report on which subprojects (aka
"workspaces") depend upon which others. The
section tells us when symlinks could not be used (generally because e.g.
packages/marshal/package.json says it's
0.2.0). We want to get rid of all mismatched dependencies.
yarn build step generates kernel bundles.
To run all unit tests (in all packages):
yarn test(from the top-level)
To run the unit tests of just a single package (e.g.
Run the larger demo
make scenario2-run-chain(in one shell)
make scenario2-run-client(in a second shell)
- modify something in e.g.
yarn build(at the top level or in
- re-run tests or setup/run-chain/run-client
yarn build in
SwingSet creates the "kernel bundle", a single file
that rolls up all the kernel sources. This bundle file is needed by callers
cosmic-swingset) before they can invoke
buildVatController. If you
yarn build, then changes to the SwingSet kernel code will be
- All work should happen on branches. Single-commit branches can land on
trunk without a separate merge, but multi-commit branches should have a
separate merge commit. The merge commit subject should mention which
packages were modified (e.g.
(SwingSet,cosmic-swingset) merge 123-fix-persistence)
- Keep the history tidy. Avoid overlapping branches. Rebase when necessary.
- All work should have an Issue. All branches names should include the issue
number as a prefix (e.g.
123-description). Use "Labels" on the Issues to mark which packages are affected.
- Add user-visible changes to a new file in the
changelogs/directory, named after the Issue number. See the README in those directories for instructions.
- Unless the issue spans multiple packages, each branch should only modify a single package.
- Releases should be made from the package subdirectories, with a tag like
eventual-send-v0.4.5. Retain mutual compatibility between all packages in the monorepo (run
yarn workspaces infoand make sure there are no
mismatchedWorkspaceDependencies). Do not use post-release
-dev.0suffixes. Merge all the
changelogs/*fragment files together and add to the
NEWS.mdfile, then delete the fragments.
Adding a new package
To create a new (empty) package (e.g. spinning Zoe out from ERTP):
- add your sources/tests/etc to
- populate a new
packages/zoe/package.json, using other packages as a template
- edit the top-level
yarn install, and commit the resulting changes to
- check the output of
yarn workspaces infoto make sure there are no
mismatchedWorkspaceDependencies, adjust the new package's dependencies until they are correctly satisfied by the other local packages
.github/workflows/test-all-packages.ymlto add a clause that tests the new package
- commit everything to a new branch, push, check the GitHub
Actionstab to make sure CI tested everything properly
- merge with a PR