Inspired by the popular Truffle framework and developed in Typescript, Lamington makes smart contract development simple for any level of EOSIO developer.
The Lamington library includes CLI tools and JavaScript utilities to streamline the smart contract building, testing and deployment pipeline.
- Skill level agnostic
- TypeScript ready
- Containerized development
- Common JavaScript testing frameworks
- Multi-environment support
- Simple CLI commands
- Easily configurable
Lamington requires Docker and NodeJS to be installed before it can be used.
- Docker: We recommend installing Docker with the standard installer for your platform.
- NodeJS: We recommend installing NodeJS with NVM.
Lamington includes command line tools and JavaScript utilities for EOSIO contract development. We recommend installing the framework as a development dependency within your project. This lets you run commands like lamington test in your project.
$ npm install --save-dev github:Alien-Worlds/lamington#v1.4.0
Install from this repository, not from npm. The
lamingtonpackage on npm is the original CoinageCrypto project and has not been published since1.0.0-alpha.6. This fork is consumed by git ref, so pin a tag to keep builds reproducible.
From there you just need to add node scripts to your package.json file that trigger lamington actions, for example:
{
...
"scripts": {
"build": "lamington build",
"start": "lamington start eos",
"stop": "lamington stop eos",
"test": "lamington test"
},
...
}
If you'd like the convenience of using the lamington command without adding it as a project dependency, you can install it on your system globally, just be mindful that this can create trouble if you use lamington with multiple projects simultaneously and don't have them all ready for the same version.
To install globally, run:
$ npm install -g github:Alien-Worlds/lamington#v1.4.0
Lamington is super simple! Whether you're migrating from Solidity, or a seasoned EOSIO developer deploying a complex decentralized application (dApp) you'll find yourself right at home in no time.
Compiling your smart contracts with Lamington is as simple as;
$ lamington build
Lamington automatically searches for all files with the .cpp file extension before batch compiling within a docker container. Compiling within a docker container with locked configuration ensures contracts compile consistently and clean every time.
Not every .cpp file is a contract, so we added an additional exclude to the configuration file .lamingtonrc. This exclude option takes an array of globular patterns as files and patterns you don't want added to your build process. We've added the command line method lamington ignore to generate a .lamingtonrc file with default settings.
If you'd like to run builds on specific contracts, an additional contract identifier can be specified like so;
$ lamington build [identifier]
Replace the [identifier] with the relative path to the contract with or without the .cpp extension.
Lamington was built with testing in mind. We considered the most commonly used testing libraries like Mocha when developing the Lamington toolset. Running your test suit is as easy as;
$ lamington test
For a full list of available JavaScript utilities, see the API documentation.
Initially setting up a project can be tedious and repetitive, so we've created a simple CLI method to setup a boilerplate EOSIO project with Lamington integration.
$ lamington init
This creates a .lamingtonrc file in your current directory with default Lamington settings.
$ lamington init [PROJECT_NAME]
Optionally you can provide and additional PROJECT_NAME to create a project directory and initialize a boilerplate project within.
Lamington ships with a default configuration to make getting started simple and setup free. However, as your project grows, so will your need for additional Lamington configuration. For example, deployment to a testnet or the live network will require environment setup. Additionally, you'll need customize your configuration if you'd like to control Lamington's fine grained settings. Fortunately we've made a simple tool to get you started, simply run lamington init in your project directory to create a default .lamingtonrc configuration file.
The .lamingtonrc file allows you to configure additional settings using JSON syntax. We're working on provide allot more settings, like defining multiple environments for each stage of your pipeline.
{
...
"keepAlive":true,
...
}
The keepAlive setting prevents Lamington from stopping the EOSIO container between each build, allowing you to develop faster and compile often.
By default every project uses the container name lamington and the standard
ports, so two projects cannot run at once. Override the name and the host ports
to run a second chain alongside an existing one:
{
"containerName": "my-project",
"rpcPort": 8889,
"stateHistoryPort": 18081,
"p2pPort": 19876
}
| Setting | Default | Description |
|---|---|---|
imageRegistry |
ghcr.io/alien-worlds |
Registry holding a prebuilt chain image. Set to "" to always build locally |
containerName |
lamington |
Name of the docker container running the chain |
rpcPort |
8888 |
Host port mapped to the chain's RPC port |
stateHistoryPort |
8080 |
Host port mapped to the state history port |
p2pPort |
9876 |
Host port mapped to the p2p port |
These are host-side ports only. Inside the container the chain always listens on its standard ports, so no other configuration needs to change. Tests pick the RPC port up automatically.
The first run needs a docker image containing nodeos and the contract
toolchain. Building it takes several minutes, and on an Apple Silicon machine
the amd64 build runs under emulation, so it takes considerably longer.
Lamington tries to pull a prebuilt image for your exact toolchain from
imageRegistry before falling back to building one. The image tag encodes the
eos, cdt and contracts versions, so changing any of them simply misses the
pull and builds, rather than silently using a stale image.
Set "imageRegistry": "" to always build locally, for example when working
offline.
Lamington ships with a pinned toolchain, so a new project works without specifying versions:
{
"cdt": "https://github.com/EOSIO/eosio.cdt/releases/download/v1.8.1/eosio.cdt_1.8.1-1-ubuntu-18.04_amd64.deb",
"eos": "https://github.com/AntelopeIO/leap/releases/download/v5.0.3/leap_5.0.3_amd64.deb",
"contracts": "v1.9.2"
}
The eos default is Leap rather than a legacy EOSIO release because the bundled
system contracts import host functions (set_parameters_packed and
set_wasm_parameters_packed) that were added after EOSIO 2.0. On an older
nodeos the system contract cannot be linked and installation fails, leaving a
chain that cannot run the tests. If you override eos, use a build that is new
enough for the system contracts you intend to install.
Changing any of these three values changes the docker image name, so a new image is pulled or built rather than a stale one reused.
$ yarn test # fast: unit and load smoke tests
$ yarn verify:package # packs the module and installs it into an empty project
$ yarn test:integration # drives a real chain in docker, takes a few minutes
yarn test:integration drives a real container and asserts that startEos
returns a chain that is genuinely usable: eosio.system installed and the
protocol features activated. That is not cosmetic -- v1.4.0 returned about 19
seconds early and was unusable for consumers. It uses its own container name and
ports, so it will not disturb a chain you already have running. It needs docker,
and fails rather than skipping if docker is missing.
We welcome contributions of all types, even down to typo fixes. All help is very welcome!
If you're not sure where to start, the best resource for you is our Contributing to Lamington guide, and if you're still stuck, please reach out to us on Slack.
You can find more information about the Lamington tool-set and join our growing community of developers by visiting any of the following links;
This fork is maintained by Alien Worlds.
This project is proudly supported by Coinage.