Skip to content
Permalink
Browse files

Merge pull request #1792 from input-output-hk/j-mueller/1776-docs

Improve package documentation
  • Loading branch information
j-mueller committed Jan 14, 2020
2 parents d3022c0 + fa2aeab commit bef8c7e6bbb8f2fc295b96f87eb7761497c4f1d0
Showing with 221 additions and 147 deletions.
  1. +32 −146 ARCHITECTURE.adoc
  2. +4 −0 deployment-server/ARCHITECTURE.adoc
  3. +3 −0 deployment/ARCHITECTURE.adoc
  4. +5 −0 docs/ARCHITECTURE.adoc
  5. +5 −0 example/ARCHITECTURE.adoc
  6. +5 −0 extended-utxo-spec/ARCHITECTURE.adoc
  7. +4 −0 iots-export/ARCHITECTURE.adoc
  8. +13 −0 language-plutus-core/ARCHITECTURE.adoc
  9. +3 −0 marlowe-playground-client/ARCHITECTURE.adoc
  10. +7 −0 marlowe-playground-server/ARCHITECTURE.adoc
  11. +4 −0 marlowe-symbolic/ARCHITECTURE.adoc
  12. +3 −0 marlowe-tutorial/ARCHITECTURE.adoc
  13. +4 −0 marlowe/ARCHITECTURE.adoc
  14. +5 −0 metatheory/ARCHITECTURE.adoc
  15. +3 −0 nix/ARCHITECTURE.adoc
  16. +3 −0 papers/ARCHITECTURE.adoc
  17. +3 −0 pkgs/ARCHITECTURE.adoc
  18. +4 −0 playground-common/ARCHITECTURE.adoc
  19. +3 −0 plutus-book/ARCHITECTURE.adoc
  20. +3 −0 plutus-contract-tasty/ARCHITECTURE.adoc
  21. +13 −0 plutus-contract/ARCHITECTURE.adoc
  22. +3 −0 plutus-core-spec/ARCHITECTURE.adoc
  23. +4 −0 plutus-emulator/ARCHITECTURE.adoc
  24. +4 −0 plutus-exe/ARCHITECTURE.adoc
  25. +5 −0 plutus-ir/ARCHITECTURE.adoc
  26. +3 −0 plutus-playground-client/ARCHITECTURE.adoc
  27. +3 −0 plutus-playground-lib/ARCHITECTURE.adoc
  28. +7 −0 plutus-playground-server/ARCHITECTURE.adoc
  29. +4 −0 plutus-tutorial/ARCHITECTURE.adoc
  30. +13 −0 plutus-tx/ARCHITECTURE.adoc
  31. +26 −0 plutus-use-cases/ARCHITECTURE.adoc
  32. +1 −1 plutus-use-cases/src/Language/PlutusTx/Coordination/Contracts/Escrow.hs
  33. +15 −0 plutus-wallet-api/ARCHITECTURE.adoc
  34. +4 −0 web-common/ARCHITECTURE.adoc
@@ -13,29 +13,9 @@ work through those in conceptual order.
Plutus Core is the language that actually goes on the blockchain. Consequently
this is the absolute core of the codebase, and everything depends on it.

=== `language-plutus-core`
include::language-plutus-core/ARCHITECTURE.adoc[]

This package implements the Plutus Core language.

This includes:

- AST types
- Parser
- Various checkers including a typechecker
- Prettyprinter
- Simple evaluator (see `plutus-core-evaluator` for fancier evaluators)
- Support for some standard constructs e.g. the encodings of recursive types
- A number of example programs

=== `plutus-core-intepreter`

This package contains the production evaluator that we use, along with an experimental
lazy evaluator.

=== `plutus-exe`

This package defines a command-line executable that used to typecheck or
evaluate Plutus Core programs.
include::plutus-exe/ARCHITECTURE.adoc[]

== Plutus Tx

@@ -44,25 +24,9 @@ Core. This is how users actually write Plutus contracts: they write Haskell
programs, part of which is compiled into Plutus Core. The rest of the program
can then use this compiled code when submitting transactions.

=== `plutus-ir`

Plutus IR is a higher-level language that sits between Plutus Tx and Plutus
Core in the compilation pipeline. This package implements the compiler, which
compiles Plutus IR into Plutus Core.

=== `plutus-tx`

This package provides several things:
include::plutus-ir/ARCHITECTURE.adoc[]

- The Plutus Tx compiler, which compiles GHC Core into
Plutus IR.
- A GHC Core plugin, which is the mechanism by which people use
the compiler.
- A couple of special typeclasses which aid with the interface
between Haskell and Plutus Tx, and Template Haskell support for
generating instances.
- It provides a partial replacement Prelude, since many parts of the
normal Haskell Prelude cannot be used with Plutus Tx.
include::plutus-tx/ARCHITECTURE.adoc[]

== Ledger

@@ -75,24 +39,9 @@ running on. There are two reasons for this:
- We want to write tests that simulate the "full" behaviour of contracts, i.e.
across time, in a multi-agent scenario.

=== `plutus-wallet-api`
include::plutus-wallet-api/ARCHITECTURE.adoc[]

This package should probably be split in two!

The `ledger` sublibrary defines our model of an Extended UTXO ledger, including:

- The types that describe transactions, pending transactions, keys, currencies, etc.
- Functions that implement the ledger validation rules.

The rest of the package defines the "wallet API", which was our attempt at
defining the interface that contracts would use to the wallet. As it turns out,
we need to do things somewhat differently, and so `plutus-contract` is the
future, but the functions in here are still used fairly widely.

=== `plutus-emulator`

This package defines the chain emulator, which is used for tests, and to back
the simulations in the Plutus Playground.
include::plutus-emulator/ARCHITECTURE.adoc[]

== Contract modelling

@@ -106,26 +55,13 @@ including both the on-chain code and the eventual contract application.
These packages are geared towards providing the tools to do that, and building
up examples to ensure that we have adequate functionality.

=== `plutus-contract`
include::plutus-contract/ARCHITECTURE.adoc[]

This package has a new API for defining "contracts": bundled applications that
interact with a wallet smart contract backend. This is in many ways the
"successor" to much of `plutus-wallet-api`, and should eventually
replace much of it.
include::plutus-contract-tasty/ARCHITECTURE.adoc[]

=== `plutus-use-cases`
include::plutus-use-cases/ARCHITECTURE.adoc[]

This package contains worked examples of a number of contracts, along with
tests using the emulator. This should always be our "most real" project: this is
where we try and do the things that we think people will really try and do.

It has a few other miscellaneous tests and benchmarks that use the use-cases as
a source of large/real validators.

=== `iots-export`

This package defines a scheme for exporting interfaces to Typescript using IOTS.
This is used by `plutus-contract` to expose an interface for Typescript clients.
include::iots-export/ARCHITECTURE.adoc[]

== Marlowe

@@ -137,112 +73,62 @@ other code in the repository.
. The Marlowe Playground shares code and deployment infrastructure with the
Plutus Playground.

=== `marlowe`

This package contains an implementation of the Marlowe interpreter as a Plutus
contract.
include::marlowe/ARCHITECTURE.adoc[]

=== `marlowe-symbolic`

This package contains a web-service for doing static analysis of Marlowe
programs using symbolic execution.
include::marlowe-symbolic/ARCHITECTURE.adoc[]

== Playgrounds

The Plutus/Marlowe Playgrounds are our web-based environment for developing and
testing basic Plutus and Marlowe contracts. That means they're the main way that
anyone outside the team has interacted with out product!

=== `playground-common`

This package contains some library code which is shared between the Plutus and
Marlowe Playgrounds.

=== `plutus-playground-lib`

This package contains some library code for the Plutus Playground.

=== `plutus-playground-server` and `marlowe-playground-server`
include::playground-common/ARCHITECTURE.adoc[]

These packages contain the servers that back the Plutus/Marlowe Playgrounds by
compiling user code and evaluating their simulations.
include::plutus-playground-lib/ARCHITECTURE.adoc[]

They also define executables that generate Purescript bindings for the types that
the Purescript code needs.
include::plutus-playground-server/ARCHITECTURE.adoc[]

=== `plutus-playground-client` and `marlowe-playground-client`
include::marlowe-playground-server/ARCHITECTURE.adoc[]

These contain the Plutus/Marlowe Playground client code, written in Purescript.
include::plutus-playground-client/ARCHITECTURE.adoc[]

=== `web-common`
include::marlowe-playground-client/ARCHITECTURE.adoc[]

This contains some Purescript client code that is shared between the Plutus and
Marlowe Playgrounds.
include::web-common/ARCHITECTURE.adoc[]

=== `deployment`
include::deployment/ARCHITECTURE.adoc[]

This folder contains the nixops/Terraform code used for deploying the Playgrounds.

=== `deployment-server`

This package contains a small server that handles automatic continuous
deployment of the alpha Playground whenever PRs are merged.
include::deployment/ARCHITECTURE.adoc[]

== Documentation

=== `plutus-tutorial` and `marlowe-tutorial`

These packages contains tutorials for Plutus/Marlowe. The Plutus tutorial is a
literate Haskell project, the Marlowe one is not (yet).

=== `plutus-book`
include::plutus-tutorial/ARCHITECTURE.adoc[]

This package contains the Plutus Book. It is a literate Haskell project.
include::marlowe-tutorial/ARCHITECTURE.adoc[]

=== `example`
include::plutus-book/ARCHITECTURE.adoc[]

This contains an example project that is designed to help people get started if
they want to use our libraries locally, rather than in the Playground. This can
otherwise be quite challenging, since our projects aren't on Hackage yet!
include::example/ARCHITECTURE.adoc[]

=== `docs`

This folder contains a variety of miscellaneous documents.

NOTE: Many of these are quite out of date, but can be useful for reference.
include::docs/ARCHITECTURE.adoc[]

== Specification and design

We have done a fair amount of work in specifying and formalizing parts of our
system. At the moment all of this work also lives in the Plutus repository, and
we even have some basic testing of the Haskell implementation against the Agda formalization.

=== `metatheory`

This folder contains the Agda formalization of the Plutus Core metatheory,
including a `plc-agda` executable that is the equivalent of the `plc` executable
from `plutus-exe`. This is used for some basic tests.

=== `papers`

This folder contains our published academic papers.
include::metatheory/ARCHITECTURE.adoc[]

=== `plutus-core-spec`
include::papers/ARCHITECTURE.adoc[]

This folder contains the Plutus Core specification.
include::plutus-core-spec/ARCHITECTURE.adoc[]

=== `extended-utxo-spec`

This folder contains the Extended UTXO model specification.

NOTE: This is more of a design document, really, it's not aiming for full precision.
include::extended-utxo-spec/ARCHITECTURE.adoc[]

== Build tooling

=== `nix`

This contains miscellaneous Nix code.

=== `pkgs`
include::nix/ARCHITECTURE.adoc[]

This contains the generated Nix code representing our Haskell package set.
include::pkgs/ARCHITECTURE.adoc[]
@@ -0,0 +1,4 @@
=== `deployment-server`

This package contains a small server that handles automatic continuous
deployment of the alpha Playground whenever PRs are merged.
@@ -0,0 +1,3 @@
=== `deployment`

This folder contains the nixops/Terraform code used for deploying the Playgrounds.
@@ -0,0 +1,5 @@
=== `docs`

This folder contains a variety of miscellaneous documents.

NOTE: Many of these are quite out of date, but can be useful for reference.
@@ -0,0 +1,5 @@
=== `example`

This contains an example project that is designed to help people get started if
they want to use our libraries locally, rather than in the Playground. This can
otherwise be quite challenging, since our projects aren't on Hackage yet!
@@ -0,0 +1,5 @@
=== `extended-utxo-spec`

This folder contains the Extended UTXO model specification.

NOTE: This is more of a design document, really, it's not aiming for full precision.
@@ -0,0 +1,4 @@
=== `iots-export`

This package defines a scheme for exporting interfaces to Typescript using IOTS.
This is used by `plutus-contract` to expose an interface for Typescript clients.
@@ -0,0 +1,13 @@
=== `language-plutus-core`

This package implements the Plutus Core language.

This includes:

- AST types
- Parser
- Various checkers including a typechecker
- Prettyprinter
- Evaluator
- Support for some standard constructs e.g. the encodings of recursive types
- A number of example programs
@@ -0,0 +1,3 @@
=== `marlowe-playground-client`

The Marlowe Playground client code, written in Purescript.
@@ -0,0 +1,7 @@
=== `marlowe-playground-server`

This packages contains the server that backs the Marlowe Playground by
compiling user code and evaluating their simulations.

It also defines an executable that generates Purescript bindings for the types that
the Purescript code needs.
@@ -0,0 +1,4 @@
=== `marlowe-symbolic`

This package contains a web-service for doing static analysis of Marlowe
programs using symbolic execution.
@@ -0,0 +1,3 @@
=== `marlowe-tutorial`

This package contains a tutorial for Marlowe.
@@ -0,0 +1,4 @@
=== `marlowe`

This package contains an implementation of the Marlowe interpreter as a Plutus
contract.
@@ -0,0 +1,5 @@
=== `metatheory`

This folder contains the Agda formalization of the Plutus Core metatheory,
including a `plc-agda` executable that is the equivalent of the `plc` executable
from `plutus-exe`. This is used for some basic tests.
@@ -0,0 +1,3 @@
=== `nix`

This contains miscellaneous Nix code.
@@ -0,0 +1,3 @@
=== `papers`

This folder contains our published academic papers.
@@ -0,0 +1,3 @@
=== `pkgs`

This contains the generated Nix code representing our Haskell package set.
@@ -0,0 +1,4 @@
=== `playground-common`

This package contains some library code which is shared between the Plutus and
Marlowe Playgrounds.
@@ -0,0 +1,3 @@
=== `plutus-book`

This package contains the Plutus Book. It is a literate Haskell project.
@@ -0,0 +1,3 @@
=== `plutus-contract-tasty`

Implements the `Language.Plutus.Contract.Test.TracePredicate` type. Trace predicates are expectations about the mockchain after running a contract trace. They can be turned into unit tests (with `tasty-hunit`) and produce useful debug output about the trace and the state of the contract.
@@ -0,0 +1,13 @@
=== `plutus-contract`

This package has a new API for defining "contracts": bundled applications that
interact with a wallet smart contract backend. This is in many ways the
"successor" to much of `plutus-wallet-api`, and should eventually
replace much of it.

Noteworthy modules:

* `Language.Plutus.Contract`: Exports the `Contract` type which encodes the client (off-chain) part of Plutus contracts, including blockchain queries, user-facing endpoints, and the ability to submit transactions to the ledger
* `Language.Plutus.Contract.StateMachine`: State machine client library, building on the `Contract` type and on the (mostly) on-chain code in `Language.PlutusTx.StateMachine`
* `Language.Plutus.Contract.Trace`: The `ContractTrace` type for describing sequences of emulator actions that can be used in the Playgound and in unit tests.
* `Language.Plutus.Contract.App`: Exposes a wrapper to turn `Contract` values into standalone executables, to be consumed by the SCB
@@ -0,0 +1,3 @@
=== `plutus-core-spec`

This folder contains the Plutus Core specification.
@@ -0,0 +1,4 @@
=== `plutus-emulator`

This package defines the chain emulator, which is used for tests, and to back
the simulations in the Plutus Playground.

0 comments on commit bef8c7e

Please sign in to comment.
You can’t perform that action at this time.