Fadroma is an application framework for the CosmWasm Compute module. Fadroma includes Rust libraries for writing smart contracts and a TypeScript system for building, deploying, and interacting with them.
Our operational model treats the blockchain as a seamless compute substrate, and contracts as akin to persistent objects.
Unlike microservices, smart contracts exist in a "post-POSIX" environment, where platform details are abstracted away. Contracts are Internet-native, but shed most of the baggage characteristic for Web 2.0 backends. Therefore interoperation with Web 2.0 systems can be non-trivial.
Unlike cloud functions, smart contracts are individually stateful, and exist permanently on an append-only ledger. While the distributed transaction-based architecture guards the system's state from spontaneous inconsistencies, extra care must be taken in orchestrating deployments and migrations.
The above properties make CosmWasm smart contracts a very interesting proposition for running standalone business logic with programmable privacy/transparency properties. Fadroma provides the orchestration system for leveraging the full capabilities of smart contract-based systems over the entire development lifecycle.
The @fadroma/connect package library
serves as an index of all supported connection targets.
The @fadroma/scrt package
package implements support for Secret Network.
Planned. See issue #148.
Under consideration.
The default structure of a project is implemented by the
Project class.
Projects created by Fadroma are polyglot Rust/TypeScript repositories.
The Rust side is structured as a Cargo workspace, where each contract corresponds to a crate.
The TypeScript side is structured as single NPM package,
which exports an api.ts module (the client library for your project),
and also contains an ops.ts module (where your project, and any custom
extensions to the workflow, are defined).
See the Fadroma Project Guide for more info.
If you have Node.js set up, you can use the npx command to create a new Fadroma project:
$ npx @hackbg/fadroma@latest create
This will download the latest version of the @hackbg/fadroma package,
and run the fadroma create command from it, which will create a new project
using an interactive console-based wizard.
When creating a project, you will be able to define an initial set of contracts.
Nix is a functional package manager. Fadroma can optionally use Nix to provide you with a stable development environment.
If you use Nix, you can create a project with:
$ nix-shell https://fadroma.tech/nix -c fadroma create
A temporary Fadroma shell can be entered with with:
$ nix-shell https://fadroma.tech/nix
The project wizard creates Fadroma projects with a default shell.nix.
From the project's root directory, you can enter the project's Nix shell
with just:
$ nix-shell
Or, from any other directory:
$ nix-shell /my/project/shell.nix
Nix will download tools like Node, Rust, Fadroma, etc., and will start a new shell session in an environment where these tools are available globally.
A contract is your basic unit of domain logic. They are very much like persistent objects that communicate with each other, and respond to the outside world, via message passing.
The fadroma-dsl crate
implements a family of procedural macros for clean, boilerplate-free implementation
of smart contract internals,
The fadroma crate contains
a set of libraries for writing smart contracts.
Having written a contract, you need to compile it and instantiate it on a chain.
To build the entire project:
$ npm exec fadroma build
To build specific contracts:
$ npm exec fadroma build CONTRACT [CONTRACT...]
In the above invocation, CONTRACT corresponds to a key of templates in
the project's fadroma.json.
The Fadroma Build Guide contains more info on configuring builds.
Fadroma Ensemble is a library for for integration testing of multiple contracts.
The fadroma deploy command deploys the current project:
$ npm exec fadroma deploy
Note: the above will fail if the FADROMA_CHAIN variable
is not set.
For convenience, the project creation tool registers aliases
in the scripts field of the project's package.json with
corresponding values of FADROMA_CHAIN, so that you can deploy with:
$ npm run mainnet deploy
$ npm run testnet deploy
$ npm run devnet deploy
$ npm run mocknet deploy
The @hackbg/ganesha package
enables Fadroma CLI to compile TypeScript on demand. You can use TypeScript
seamlessly in your deploy procedures:
$ fadroma run script.js
$ fadroma run script.ts
The @hackbg/cmds package
allows Fadroma CLI to parse commands. This is a simple and loose command parser which
descends a tree of command definitions, and maps to a regular JS function call.
The default project contains examples for extending project commands (such as deploy),
as well as defining new ones.
The @fadroma/agent package is our core library
for interfacing with blockchains and smart contracts from JavaScript or TypeScript.
The Fadroma Agent Guide describes it in more detail.
The Deployment class, as extended in the default project's api.ts,
is the backbone of the Fadroma Deploy API.
The Fadroma Deploy Guide describes that part of the functionality.
By default, Fadroma deploys to a devnet: a local instance of a blockchain, running in a Docker or Podman container.
The Fadroma Devnet Guide has more info on the subject of devnets.
The Fadroma Mocknet guide describes
our simulated environment for fast full-stack testing of production WASM builds.
Mocknet is built into @fadroma/agent.