10 releases

0.2.0 Dec 1, 2022
0.1.6 Nov 12, 2022
0.1.4 Oct 10, 2022
0.0.4 Sep 27, 2022
0.0.2 Aug 14, 2022

#7 in #off-chain

41 downloads per month
Used in trireme

Apache-2.0

165KB
4K SLoC

Naumachia


🌊 Mock your battles before you're out at sea 🌊

Licence Crates.io Rust Build


Naumachia is a framework for writing Smart Contracts on the Cardano Blockchain using Rust!

Work in Progress :)

Checkout the feature progress roadmap

The Cardano Smart Contract scheme pushes a lot of the code off-chain. Naumachia is designed to make the development of off-chain code as easy as possible, but also give you an environment to test your on-chain code.

Included in the library are the tools for declaratively orchestrating interactions with validator scripts, minting policies, and wallets; building and checking your transaction against your on-chain code; testing all of this code at multiple abstraction layers; deploying, managing, and interacting with your Smart Contract in production.

Intended to be used as the off-chain backend for Aiken or any other on-chain script (UPLC) source :)

Naumachia is meant as an alternative for the Plutus Application Backend (PAB).

Goals

  • Make Cardano Smart Contracts easy
  • Help Smart Contract developers prototype in minutes
  • Make TDD a priority for SC development
    • Enable Unit Tests for your Plutus/Aiken/Helios/Raw UPLC Scripts using the Aiken CEK Machine
    • Enable Unit Tests for your entire Smart Contract with mocked backends
    • Give a clean interface for external parties to write against
  • Provide adaptors for deploying and interacting with your live Smart Contract in production
  • Trireme will be a CLI tool for devs and end-users alike to manage their keys, secrets, and dApps.

Long-term Goals

  • Allow your Smart Contract to be compiled into WASM and injected into your web dApp
    • Provide adaptors for interacting with browser wallets and your chosen external services
  • Auto generate simple UIs, e.g. CLIs, web interfaces, etc

🚣 Trireme 👁

Client-Side FTW

Trireme is a CLI for managing all of your dApps and secrets.

For now, it is just an MVP to allow your Naumachia dApps to interact with the blockchain. Eventually, it will be a full CLI wallet, a package manager for you dApps, and more.

Not stable.

To install locally, run

cargo install --path ./trireme

or install via crates.io

cargo install trireme

Setup with

trireme init

and follow instructions.

⚠️⚠️Your config files will be stored in plain text on your local file system under ~/.trireme. Please use test wallets only while trireme is still new.

Demo

While features are still quite limited, I'm happy to say that Naumachia is working now! You can build, deploy, and interact with your smart contracts on the Testnet. Over time, we'll add more sample dApps that will illustrate more features.

The /sample-dApps directory includes the always-succeeds-contract which you can use as long as you have

  1. Rust v1.64+ toolchain installed on your machine
  2. A Blockfrost API Testnet Project (this is still on the old testnet, but that can change very soon)
  3. A secret phrase for an account with some funds on Testnet. You can use Yoroi, Nami, Flint, or any Cardano wallet to create a new phrase, and fund it with the Testnet Faucet (We'll add the ability to generate a new phrase with Trireme soon, but in the meantime you'll need to build it elsewhere)

I've only tested on Linux.

⚠️⚠️Be very careful to not use your HODL keys! Please only use a secret phrase from a TESTNET wallet with funds you are willing to lose. ⚠️⚠️Naumachia and the Trireme CLI are still under development!

To interact with your contract, you will need to install the trireme cli:

cargo install --path ./trireme

Trireme allows you to manage your secrets for all your Naumachia dApps.

To add your api key and your secret phrase, run:

trireme init

Which will prompt you to enter your information. ⚠️⚠️Your config files will be stored in plain text on your local file system under ~/.trireme.

Use Trireme to check your initial balance!

trireme balance

Now that Trireme is set up, you are ready to interact with the blockchain!

First, install the dApp CLI:

cargo install --path ./sample-dApps/always-succeeds-contract

and try locking 10 ADA at the contract address:

always-cli lock 10

It can take a few minutes for your transaction to show up on chain.

You can trireme balance again to check your balance. Or, use the returned TxId to track on the testnet explorer or in your wallet interface (Yoroi, Nami, etc). Your balance should have decreased by 10 + fees.

Once it has gone through, you can run

always-cli list 5

Which will show the 5 newest locked UTxOs at the script address (feel free to look at more). You will probably see a bunch of other UTxOs locked at the script address. You can try and claim those, but many of them aren't claimable for a number of reasons.

You will need to find yours and include the Output Id info in your claim command. It will look something like:

always-cli claim <tx_hash> <index>

Again, this might take a few minutes to execute. But check trireme balance or your wallet interface to see that your balance has returned to your original balance minus fees for the two txs.

Fin!

Contributions

Excited to accept PRs and general feedback. There is a lot of work to be done to make this the best framework it can be, so I'll try to help onboard anyone interested in contributing.

Big fan of modern programming techniques. I want to prioritize

  1. End user experience (Devs and dApp users)
  2. Contributor experience + Maintainability
  3. Performance, once the other stuff is solid

Feel free to start issues/discussions if there are things you feel are missing or whatever. I love feedback as I'm figuring out a lot of this as I go. I want to get the design right. Questions also welcome.

Check out our architecture diagram.

FYI, CI requires these commands to pass. So, try to run them locally to save yourself some time.

cargo build --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

Dependencies

~15–33MB
~517K SLoC