plutonomicon/cardano-transaction-lib

A Purescript library for building smart contract transactions on Cardano

cardano-transaction-lib

cardano-transaction-lib (CTL) is a Purescript framework for building smart contract transactions on Cardano. It belongs to the the same category of tools as Lucid, Mesh.js, Atlas, Plutus Application Backend (PAB).

Table of Contents

• Documentation
• Additional resources/tools:
• Available support channels info
• Funding acknowledgements
• Use in production

Documentation

Please explore our documentation to discover how to use CTL, how to set up its runtime, and how it compares to other tools:

• Super quick start
• Adding CTL as a dependency
• CTL's runtime dependencies
• Blockfrost support
• Getting started writing CTL contracts
• Managing contract environment
• Using CTL from JS
• Importing Plutus Scripts
• Migrating from Plutus Application Backend to CTL
• Overview of testing approaches
  • Testing on local Cardano testnets
  • End-to-end dApp testing with headless browsers
  • Assertion utilities for testing
  • Using a directory with private keys to run tests
• Transaction balancing
• Transaction chaining
• Ada staking support
• Key management
• SECP256k1 support (CIP-49)
• Custom query layers
• Going to production with CTL
• FAQs
• Feature overview video
• Comparison with other frameworks (Lucid)
• Development workflows for CTL

You can also access PureScript documentation for CTL and its dependencies for the most recent develop version, or generate it yourself.

Additional resources/tools:

• cardano-serialization-lib
• Ogmios for chain queries
• Kupo for chain queries
• CIP-30 (wallet interface - Nami partially implements this)
• Nami docs
• Alonzo CDDL spec

Available support channels info

You can find help, more information and ongoing discusion about the project here:

• Plutonomicon Discord
• #ctl channel at MLabs' Slack

Funding acknowledgements

CTL is being developed by MLabs. The following companies/funds have contributed significant resources (development time or funding):

• IOHK
• Catalyst Fund8
• Catalyst Fund9
• Catalyst Fund10
• Intersect MBO
• MLabs
• Indigo Protocol
• Equine
• Liqwid Labs
• PlayerMint
• Fourier Labs
• Ardana

Use in production

• Indigo Protocol
• Liqwid
• Clarity
• PlayerMint
• SingularityNet

cardano-transaction-lib's Issues

complete the `Transaction` type sufficiently for a valid simple transaction

Load different CSL packages depending on environment

We need to figure out a way to either load the Node or browser version of CSL

Potentially fix `datum` type for `OgmiosTxOut` in `Types.JsonWsp`

Currently

type OgmiosTxOut =
  { address :: Address
  , value :: Value
  , datum :: Maybe String
  }

and https://ogmios.dev/ogmios.wsp.json (see "datum") says datum is base64, although the example looks like a hexadecimal (this looks to be the hash of the datum in fact). We may need datum to be a sum type over both possibilities? ATM,txOutRefToTransactionInput :: TxOutRef -> Maybe Transaction.TransactionInput assumes it's a hexadecimal.

CI?

once we have testing frameworks in place (#13), we'll want some CI checks, namely:

• no compiler warnings
• the package builds and passes tests

Build a `Transaction` through the `QueryM` interface

This is essentially the core of the stage-1 goal (building a transaction in the browser that works with a light wallet). Since we don't have a constraints API, we need to fill in most of the relevant information by hand

The transaction will be very simple -- sending two ada to one's own wallet

Here are the rough steps to accomplish this:

• get the wallet's address through Nami interface embedded in QueryM (e.g. getWalletAddress)
• query the chain with utxosAt to get the inputs
• send two ada back to the aforementioned wallet address in the outputs
• fill in the rest of the UnbalancedTransaction -- this steps depends on how #37 is resolved (see #61)

http query backend

do we have any options to query the chain through just HTTP. if not, do we know why?

Write smart constructors for Value, TokenName and CurrencySymbol

• With Value now defined as a product type of Ada and non-Ada assets, we should provide smart constructors to construct such terms. This should prevent mixing of lovelaces into the non-Ada asset map.
• We should remove the export of such data constructors.
• Remove any newtype instances that would allow us to construct via wrap.
• Reconsider what functions should be exported from Types.Value e.g. flattenValue - perhaps move to balancer and not export.
• See #84 and #97

applyCode

we're going to need to be able to apply arguments to scripts and get the correct resulting hash

example: if a project uses a script that is parameterized over someone's pubkeyhash, then we will need a different version for each pubkey that might need to interact with our dApp.

ideally, we should be working with the stringified, non-CBOR version of the script, and hopefully we can get away with minimal parsing and string manipulation, rather than building out an AST.

we need examples of un-applied and applied scripts to see how to do this properly.

in a worst case scenario we could make this a backend service.

EDIT:

Since we are using the Haskell server for this, there are really two tasks:

• Call applyArgs on the server and respond with the applied script
• Add a QueryM effect to call this on the client side

submit transaction with plutus script and datum using this library

module refactor for query types

Types.JsonWsp -> Types.JsonWsp.UtxoQR, Types.JsonWsp.TxQr, etc.

Ogmios.purs is also getting quite big and should also get it's scope broken down

Define `TransactionUnspentOutput` type and deserialization

Related: #64, #60

Include formatting check in CI checks.

@Benjmhart I guess GH checks would be useful here, but I don't think I have access though.

Originally posted by @adamczykm in #52 (comment)

Integration balancing with fee estimation and signing

After #22 is merged, we will have a balancer with some placeholders remaining

We need to integrate various other parts of the project to complete the UnbalancedTransaction -> Transaction part

This includes

• signing: will be taken care of by #64
• fee estimation: taken care of by #55. We can just use manual HTTP requests for now. In the future we might be able to generate a client with servant-purescript though

Add deserialization for domain types

Quoting @ngua:

Do you think it would be possible and in-scope for this PR to include some conversion functions/effects in the opposite direction, e.g. Value -> Effect T.Value? We will need these as well soon for wallet effects

I.e. to interact with wallets we need to be able to de-serialize things using cardano-serialization-lib.

WS integration with `ogmios-datum-cache`

We'll be using HTTP a websocket interface to query for datums from ogmios-datum-cache

document how to set up private testnet infrastructure locally

the docs now include public testnet infra, but not private. since this library will ultimately need to serve both the front end integration as well as E2E testing, we should probably document how to use the library with the Cardano Wallet Backend as well.

Simplify multisign functionality

CIP-0030 specifies a signTx function that can add a partial set of signatures to a transaction.

As argued here, this functionality would be easier to use if the function took a partially-signed transaction and returned some-more-signed transaction.

testing - helper function for failures

in the parsing test suite, we traverse over arrays of examples, verifying that they fit our schema, and verifying that they parse correctly.

it would be good to have error reporting that returns the index of an offending example, and prints it out on failure

Switch to esbuild

I noticed #62 , and you haven't considered esbuild seemingly.

https://esbuild.github.io/

This is the best bundler I know of.

strip logs

once we have a working prototype, we should remove a bunch of logs that are currently built into the js FFI calls, etc.

ideally the system should work silently except to report errors.

Get private keys for transaction signing

• In MLabs pab, a Map PubKeyHash PrivateKey is obtained for signing the transaction. We need something similar like Map Address PrivateKey, there is currently a placeholder newtype PrivateKey in the BalanceTx.

`UnbalancedTransaction`

Create an UnbalancedTransaction type (e.g. here, note that recent plutus-apps splits PubKeyHash into a few different newtypes). Since we want to replicate the constraints API from Contract the type should match the plutus one pretty closely

Write `buildTxRaw` function for balancing

buildTxRaw is currently undefined in balanceTx.
Investigate:

• https://github.com/Emurgo/cardano-serialization-lib/blob/master/doc/getting-started/generating-transactions.md
• https://github.com/input-output-hk/cardano-node/blob/b6ca519f97a0e795611a63174687e6bb70c9f752/cardano-cli/src/Cardano/CLI/Shelley/Run/Transaction.hs#L312

successfully call Nami wallet with a 'simple' handcrafted transaction (no plutus)

Convert Ogmios types to "internal" Transaction types to use e.g. `utxosAt`

• Currently, the balancer is in terms of "internal" types like Transaction, Value etc. But Ogmios has its own types when querying, we need to convert over to use functionality like utxosAt

Set up infra for Haskell server

Set up the infrastructure for the Haskell server (applyCode, fee estimation, etc...) in this repository

For consideration: Move reencoding of json to Haskell side.

What if we re-parsed and re-encoded the jsons on haskell side just before sending them to frontend? I mean a thin layer in front of ogmios?

Apparently we should be able to traverse the jsons without the need to know the datatype schema that was used to generate them. The advantage is that we would be dealing with already-parsed jsons (as a tree structure), which is more reliable than a custom state machine-based tokenizer of string.

@ngua

Originally posted by @klntsky in #34 (comment)

Pick a JS bundler

We need to decide on which bundler we want to use, then

• add it to the shell to use it manually when needed
• extend the derivations (e.g. bundlePursProject) in nix/lib.nix

We've discussed either using Parcel or Webpack

extend the Transaction type to support plutus scripts + datum

Purescript style guide

We have a Haskell style guide which we can partially follow, but we should probably have one for Purescript code as well (and maybe even for FFI code)

Let's use this issue as a list of conventions we try to follow

• Avoid newtypes when there are no type class instances for the type, except of cases where we want to use newtypes to prevent confusion when working with multiple values of the same type.
• No explicit instance names
• No $ required before do, unlike in Haskell
• Don't mix $ with parentheses where it's possible to use only $s
• Prefer f1 $ f2 $ f3 v over f1 <<< f2 <<< f3 $ v and (f1 <<< f2 <<< f3) v (compose uses more stack and has longer operator name)
• Naming of FFI functions should start with underscore, except of cases when the function is exported right away with no changes to the public interface
• If the goal of an import is just to re-export, use import Foo.Bar (baz) as X, not import Foo.Bar (baz) as Foo.Bar (avoids boilerplate and clearly indicates the purpose of the import)
• Do not export functions more than once from Contract.* modules. The motivation is it would make imports management more complicated for the users (the need to choose between modules). language-server users will have a better UX (there is no need to choose a module if only one module exports an identifier)
• Do not import modules from test/ in src/ (the reason is: spago only looks up for modules from src/ in dependencies of a project, so that would make CTL unusable as dependency).

Fee Estimation function

we need a function to estimate fees, this will be easiest to use a haskell server for now

Add `ogmios-datum-cache` to nix shell environment

Implement core of Nami wallet interface

While we don't need to implement all of Nami's functionality, we do need FFI wrappers around at least the following to build an UnbalancedTx as part of our first goal:

NOTE: Some of the links below are for the deprecated window.cardano injected API. This is because there are no docs for the new injected API; the parameters and return values are the same for the examples below, however, so I linked to them for convenience

• enable (https://github.com/Berry-Pool/nami-wallet#cardanoenable) -- WORKING
• getUsedAddresses (https://github.com/Berry-Pool/nami-wallet#cardanogetusedaddresses; note that Nami only has a single address per wallet but returns an array to follow the CIP) -- WORKING
• getCollateral (https://github.com/Berry-Pool/nami-wallet#apiexperimentalgetcollateral) -- WORKING
• signTx. Nami actually returns a TransactionWitnessSet, but it probably makes more sense to have the action as follows for ease of use

  signTx :: Transaction -> Aff Transaction

  In this case signTx will add the new, returned witness set to the existing transaction

All of these return an Effect (Promise ...) which we can then lift into Aff (i.e. Control.Promise.toAffE. Most of them return a hexadecimal string which needs to be decoded

Related issues/PRs: #60, #31, #44, #49

Update CSL address use sites with the new Address / StakeCred types

#31 introduced more convenient and type-safe API for Address and credential types. But the codebase does not yet use it.

Deserialization for `TransactionWitnessSet`

The type is already defined in Types.Transaction, so we just need the ability to deserialize from CSL. This is required for signTx

To speed this up, there are several Maybe fields we don't care about at the moment that we can just hard-code to Nothing for now (e.g. anything Plutus-related). We can open another issue to revisit that when we start working on Plutus support

This is probably the last deserialization-related thing we need to worry about for stage 1

Aff Interface for Websockets

Currently, the interface for websockets is callback/continuation driven.

this is less than ideal.

our current goal is to have more of an Aff driven interface, probably
ReaderT { WebSocket, Wallet, Etc } Aff a

However this poses some design challenges:

1. Dispatching the correct, corresponding response for a given query - queries are not given an ID and this may cause data races in complex usage of Aff (multiple Fibers in particular would be a problem)
2. It would often be impossible to know where an error arose, since dispatch would presumably need to identify a consumer based on the parsed type alone.

create a `balanceTx` function

there are general instructions on how to balance a tx here: https://docs.google.com/document/d/1B4CBCWETDOGkPtsWxgKZJx6yF_51rp1w35fNVaUQo3U/edit?usp=sharing

add `purty` autoformat script

Add `getTxById` to `Contract` interface

these are currently blocked on Ogmios-datum-cache efforts

however we will need to be able to query tx by txid and datum by datumhash. (ideally against a cache layer.

create and submit a simple address -> address transaction

provide the correct way to go from addr1 format to pubkeyhash

nami wallet provides addr1-formatted addresses

in previous attempts to integrate with Nami, we had difficulty getting the correct pubkeyhash out of this address.

we may need to get the right library functions to do this correctly.

Write tx signing functionality

We need something similar to Tx.addSignature https://playground.plutus.iohkdev.io/doc/haddock/plutus-ledger/html/Ledger-Tx.html#v:addSignature to replace signBy in BalanceTx, also need to determine how signing works for our transaction type, whether sign TxBody or Transaction.

Related issue: #48

Get websockets to work in the browser

Apparently the ws package does not work in the browser (even when polyfilling the packages) and we need to use the browser-native WebSocket object instead

There are some packages like isomorphic-ws, but I don't think that's the best option

JSON / BigInt preprocessor

haskell serializes arbitrary-precision numbers as Integers.

when javascript decodes them as IEEE Floats, we can lose precision.

the argonaut library can't really be used here since it converts all json values into JS values and THEN parses them to PS values.

so we need to roll over json as a string, and whenever we encounter an integer larger than 32 bits, wrap it in quotes so it can be parsed correctly as a BigInt.

Support native assets when decoding Value

• See parseValue function:

(_assetsJson :: {}) <- getField o "assets"

Add serialization-lib fork to nix

We need https://github.com/SundaeSwap-finance/cardano-serialization-lib available in node_modules before #44 can be merged. The upstream version of serialization-lib diverges from it enough to break the test suite.

build a capability to query for UTXO's using ogmios

purescript-bridge tools

we should use purescript-bridge for a collection of plutus common types as well as document how the user can do this for their input types.

we need to make sure that our recommended purescript-bridge setup writes identical (and safe) json and isData instances.

MakeIsDataIndexed implementation?

we're going to need to encode and decode data in a reasonable way. - and to make sure that data instances agree from Haskell -> Purescript.

This might be a place where we can employ Purescript-bridge, which allows you to construct json-compatible purescript types from haskell types.

the package itself is poorly maintained, and implies that there's a strategy pattern of sorts for building custom instances, etc. This does not actually exist and everyone forks it.

here is a good fork i think: https://github.com/input-output-hk/purescript-bridge/

testing framework

we need a testing framework that runs both on CLI and in simulated browser environments.

currently the plan is to pull in scaffolding from the Medea library https://github.com/juspay/medea-ps/blob/master/test/Main.purs
this uses mote and spec and quickcheck together nicely. we may need a browser-specific test framework like Jest to give us everything to simulate browser behaviors.