diff --git a/README.adoc b/README.md similarity index 66% rename from README.adoc rename to README.md index a42bf66893..f08dab8a66 100644 --- a/README.adoc +++ b/README.md @@ -1,87 +1,77 @@ -= https://github.com/input-output-hk/marlowe-cardano[Marlowe on the Cardano Blockchain] -:email: plutus@iohk.io -: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. +

+ + Logo + +
+ Implementation of Marlowe On Cardano (Runtime) +

+

+ +

+
+ Beta + + +
+ +> [!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.
+> 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).
+> 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 <>. -==== - -[[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 <> 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 <> 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. @@ -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 <> 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 <>). +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.
+> 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`]. @@ -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 @@ -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. diff --git a/doc/image/favicon.ico b/doc/image/favicon.ico new file mode 100644 index 0000000000..ca7487d104 Binary files /dev/null and b/doc/image/favicon.ico differ diff --git a/doc/image/github.svg b/doc/image/github.svg new file mode 100644 index 0000000000..e6dbc42e58 --- /dev/null +++ b/doc/image/github.svg @@ -0,0 +1,3 @@ + + + diff --git a/doc/image/logo-header.svg b/doc/image/logo-header.svg new file mode 100644 index 0000000000..050e729eea --- /dev/null +++ b/doc/image/logo-header.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/image/logo.png b/doc/image/logo.png new file mode 100644 index 0000000000..f635aae5b4 Binary files /dev/null and b/doc/image/logo.png differ diff --git a/doc/image/logo.svg b/doc/image/logo.svg new file mode 100644 index 0000000000..4d3e8149e1 --- /dev/null +++ b/doc/image/logo.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file