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.
@fadroma/connect package library
serves as an index of all supported connection targets.
package implements support for Secret Network.
Planned. See issue #148.
The default structure of a project is implemented by the
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
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
From the project's root directory, you can enter the project's 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.
implements a family of procedural macros for clean, boilerplate-free implementation
of smart contract internals,
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
The Fadroma Build Guide contains more info on configuring builds.
Fadroma Ensemble is a library for for integration testing of multiple contracts.
fadroma deploy command deploys the current project:
$ npm exec fadroma deploy
Note: the above will fail if the
is not set.
For convenience, the project creation tool registers aliases
scripts field of the project's
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
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
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
as well as defining new ones.
@fadroma/agent package is our core library
The Fadroma Agent Guide describes it in more detail.
Deployment class, as extended in the default project's
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
Did you know? This document is also part of our test suite. These imports add the rest of the guides to the test run:
await import('./spec/Agent.test.ts') await import('./spec/Build.test.ts') await import('./spec/Deploy.test.ts') await import('./spec/Devnet.test.ts') await import('./spec/Mocknet.test.ts') await import('./spec/Project.test.ts') await import('./spec/Scrt.test.ts') await import('./spec/Upload.test.ts') await import('./spec/Connect.spec.ts.md') await import('./spec/CW.spec.ts.md') await import('./spec/Factory.spec.ts.md')