Skip to content

Commit

Permalink
Added important Notice about Marlowe transition
Browse files Browse the repository at this point in the history
  • Loading branch information
nhenin committed May 14, 2024
1 parent db62841 commit f7cf37d
Show file tree
Hide file tree
Showing 6 changed files with 104 additions and 78 deletions.
132 changes: 54 additions & 78 deletions README.adoc → README.md
Original file line number Diff line number Diff line change
@@ -1,87 +1,77 @@
= https://github.com/input-output-hk/marlowe-cardano[Marlowe on the Cardano Blockchain]
:email: [email protected]
:author: Input Output HK Limited
:toc: left
:reproducible:

Marlowe is a platform for financial products as smart contracts. Marlowe-Cardano is
an implementation of Marlowe for the Cardano blockchain, built on top of Plutus.
<h2 align="center">
<a href="" target="blank_">
<img src="./doc/image/logo.svg" alt="Logo" height="75">
</a>
<br>
Implementation of Marlowe On Cardano (Runtime)
</h2>
<p align="center">
<a href="https://github.com/input-output-hk/marlowe-cardano/releases"><img src="https://img.shields.io/github/v/release/input-output-hk/marlowe-cardano?style=for-the-badge" /></a>
</p>
<div align="center">
<a href=""><img src="https://img.shields.io/badge/stability-beta-33bbff.svg" alt="Beta"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg"></a>
<a href="https://discord.com/invite/cmveaxuzBn"><img src="https://img.shields.io/discord/826816523368005654?label=Chat%20on%20Discord"></a>
</div>

> [!IMPORTANT]
> This Marlowe repository will soon be moved to https://github.com/marlowe-lang. The new repositories will be administered by an independent vehicle, a not-for-profit organization currently being set up by the transition team.<br>
> This will allow us to ensure community representation and stewardship. Future developments and support for Marlowe are transitioning to a community-driven model initially led by [Simon Thompson](https://github.com/simonjohnthompson), [Nicolas Henin](https://github.com/nhenin) and [Tomasz Rybarczyk](https://github.com/paluh). <br>
> See [here](https://github.com/marlowe-lang/.github/blob/main/profile/transition.md) for details.

Marlowe-Cardano is an implementation of Marlowe for the Cardano blockchain, built on top of Plutus.

This repository contains:

* The implementation of the Marlowe domain-specific language.
* The Marlowe Runtime and Marlowe Runtime Web
* The implementation of the Marlowe domain-specific language in Haskell.
* Tools for working with Marlowe, including static analysis.
* A selection of examples using Marlowe, including a number based on the ACTUS financial standard.
* The Marlowe Playground, a web-based playground for learning and writing Marlowe Applications.
[IMPORTANT]
====
The rest of this README is focussed on people who want to develop or contribute to Marlowe.
For people who want to *use* Marlowe, please consult the <<user-documentation>>.
====

[[cache-warning]]
[IMPORTANT]
====
DO NOT IGNORE THIS

If you want to use Nix with this project, make sure to set up the xref:iohk-binary-cache[IOHK binary cache].
If you do not do this, you will end up building GHC, which takes several hours.
If you find yourself building GHC, STOP and fix the cache.
====
## Documentation

== Documentation

=== User documentation
### User documentation

The main documentation for the whole Plutus ecosystem is located https://plutus.readthedocs.io/en/latest/[here].

An index of key documentation for Marlowe development is located at https://developers.cardano.org/docs/smart-contracts/marlowe/#resources-for-developing-and-deploying-marlowe-contracts.

== Working with the project
## Working with the project

=== How to submit an issue
### How to submit an issue

Issues can be filed in the https://github.com/input-output-hk/marlowe-cardano/issues[GitHub Issue tracker].

However, note that this is pre-release software, so we will not usually be providing support.

[[how-to-develop]]
=== How to develop and contribute to the project
### How to develop and contribute to the project

See link:CONTRIBUTING{outfilesuffix}[CONTRIBUTING], which describes our processes in more detail including development environments; and link:ARCHITECTURE{outfilesuffix}[ARCHITECTURE], which describes the structure of the repository.

=== How to depend on the project from another Haskell project
### How to depend on the project from another Haskell project

None of our libraries are on Hackage, unfortunately (many of our dependencies aren't either).
So for the time being, you need to:

. Add `marlowe` as a `source-repository-package` to your `cabal.project`.
. Copy the `source-repository-package` stanzas from our `cabal.project` to yours.
. Copy additional stanzas from our `cabal.project` as you need, e.g. you may need some of the `allow-newer` stanzas.
- Add `marlowe` as a `source-repository-package` to your `cabal.project`.
- Copy the `source-repository-package` stanzas from our `cabal.project` to yours.
- Copy additional stanzas from our `cabal.project` as you need, e.g. you may need some of the `allow-newer` stanzas.

=== How to build the project's artifacts
### How to build the project's artifacts

This section contains information about how to build the project's artifacts for independent usage.
For development work see <<how-to-develop>> for more information.

[[prerequisites]]
==== Prerequisites
#### Prerequisites

The Haskell libraries in the Marlowe project are built with `cabal` and Nix.
The other artifacts (docs etc.) are also most easily built with Nix.

===== Nix
##### Nix

Install https://nixos.org/nix/[Nix] (recommended). following the instructions on the https://nixos.org/nix/[Nix website].

Make sure you have read and understood the xref:cache-warning[cache warning].
DO NOT IGNORE THIS.

See <<nix-advice>> for further advice on using Nix.

===== Non-Nix
##### Non-Nix

You can build some of the Haskell packages without Nix, but this is not recommended and we don't guarantee that these prerequisites are sufficient.
If you use Nix, these tools are provided for you via `nix develop`, and you do *not* need to install them yourself.
Expand All @@ -90,50 +80,40 @@ If you use Nix, these tools are provided for you via `nix develop`, and you do *
* If you want to build our Haskell packages with https://haskellstack.org/[`stack`], then install it.
* If you want to build our Agda code, then install https://github.com/agda/agda[Agda] and the https://github.com/agda/agda-stdlib[standard library].

[[building-with-nix]]
==== How to build the Haskell packages and other artifacts with Nix

Run `nix build .#marlowe-runtime` from the root to build the Marlowe library.
#### How to build the Haskell packages and other artifacts with Nix

See <<nix-build-attributes>> to find out what other attributes you can build.
Run `nix build .#marlowe-runtime` from the root to build the Marlowe library.

==== How to build the Haskell packages with `cabal`
##### How to build the Haskell packages with `cabal`

The Haskell packages can be built directly with `cabal`.
We do this during development (see <<how-to-develop>>).
We do this during development.
The best way is to do this is inside a `nix develop`.

[NOTE]
====
For fresh development setups, you also need to run `cabal update`.
====
>[!NOTE]
> For fresh development setups, you also need to run `cabal update`.

Run `cabal build marlowe` from the root to build the Marlowe library.

See the link:./cabal.project[cabal project file] to see the other packages that you can build with `cabal`.

[NOTE]
====
If you get errors about missing shared libraries, try running `cabal clean` first.
If that fails you might have a corrupt cabal store, in which case you should `rm -rf ~/.cabal/store` and try `cabal build all` again.
====


[[nix-advice]]
>[!NOTE]
> If you get errors about missing shared libraries, try running `cabal clean` first. <br>
> If that fails you might have a corrupt cabal store, in which case you should `rm -rf ~/.cabal/store` and try `cabal build all` again.
This repository uses nix to provide the development and build environment.

For instructions on how to install and configure nix (including how to enable access to our binary caches), refer to link:https://github.com/input-output-hk/iogx/blob/main/doc/nix-setup-guide.md[this document].
For instructions on how to install and configure nix (including how to enable access to our binary caches), refer to link:https://github.com/input-output-hk/iogx/blob/main/doc/nix-setup-guide.md.

If you already have nix installed and configured, you may enter the development shell by running `nix develop`.

[[nix-build-attributes]]
=== Which attributes to use to build different artifacts
### Which attributes to use to build different artifacts

Run `list-flake-outputs` while inside the `nix develop` shell for a list of all the artifacts you can build from this repository

== Docker compose
## Docker compose

There is a `docker compose` setup designed to give a local developer mode of the marlowe runtime components,
configured in link:./nix/marlowe-cardano/compose.nix[`compose.nix`].
Expand Down Expand Up @@ -165,7 +145,7 @@ The following commands may be useful:
* `docker compose exec postgres psql -U postgres -d chain`: Run psql in the `chain` database.
* `docker compose port`, e.g. `docker compose port web 8080` will show the local port that maps to port `8080` for the `web` service

=== Accessing the node socket:
### Accessing the node socket:

The node socket file lives inside a Docker volume. Because it is created by the
container, it is owned by root, and needs elevated permissions (via `sudo`) to
Expand All @@ -179,14 +159,10 @@ maps to the volume (one-liner: `docker volume inspect marlowe-cardano_shared | j

To use this with `cardano-cli`:

----
```bash
export CARDANO_NODE_SOCKET_PATH=$(docker volume inspect marlowe-cardano_shared | jq -r '.[].Mountpoint')
# -E passes the current environment to sudo
sudo -E cardano-cli ...
----
```

== Licensing

You are free to copy, modify, and distribute Marlowe under the terms
of the Apache 2.0 license. See the link:./LICENSE[LICENSE]
and link:./NOTICE[NOTICE] files for details.
Binary file added doc/image/favicon.ico
Binary file not shown.
3 changes: 3 additions & 0 deletions doc/image/github.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions doc/image/logo-header.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/image/logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
31 changes: 31 additions & 0 deletions doc/image/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit f7cf37d

Please sign in to comment.