Skip to content

Commit b911fcd

Browse files
szg251szg251
authored
Merge pull request #182 from mlabs-haskell/szg251/catalyst-reports
Catalyst reports
2 parents 4357f15 + 1c1e09b commit b911fcd

15 files changed

+609
-4
lines changed

‎docs/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/book
2+
/api.md

‎docs/SUMMARY.md

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,30 @@
1+
<!-- markdownlint-disable-file single-title -->
12
# Summary
23

4+
# User Guide
5+
36
- [Introduction](introduction.md)
7+
- [Using LambdaBuffers](using-lambdabuffers.md)
8+
- [LambdaBuffers to Haskell](haskell.md)
9+
- [LambdaBuffers to Purescript](purescript.md)
10+
- [LambdaBuffers to Plutarch](plutarch.md)
11+
- [LambdaBuffers to Rust](rust.md)
12+
13+
# Reference Guide
14+
415
- [Getting started](getting-started.md)
5-
- [LambdaBuffers to Haskell](haskell.md)
6-
- [LambdaBuffers to Purescript](purescript.md)
7-
- [LambdaBuffers for Plutarch](plutarch.md)
8-
- [LambdaBuffers for Rust](rust.md)
916
- [Design](design.md)
1017
- [API](api.md)
1118
- [LambdaBuffers Frontend (.lbf) syntax](syntax.md)
1219
- [Compiler](compiler.md)
1320
- [Codegen](codegen.md)
1421
- [Command line interface](command-line-interface.md)
1522
- [Comparison matrix](comparison-matrix.md)
23+
- [Catalyst reports](catalyst-reports.md)
24+
- [Catalyst 9 reports](catalyst09-reports/README.md)
25+
- [Milestone 1: Research](catalyst09-reports/milestone-1.md)
26+
- [Milestone 2: End to end proof of concept](catalyst09-reports/milestone-2.md)
27+
- [Milestone 3: Testing and documentation](catalyst09-reports/milestone-3.md)
28+
- [Milestone 4: Project adoption](catalyst09-reports/milestone-3.md)
29+
- [Catalyst 10 reports](catalyst10-reports/README.md)
30+
- [Milestone 1: Rust support](catalyst10-reports/milestone-1.md)

‎docs/catalyst-reports.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Catalyst reports
2+
3+
Our project was funded by Catalyst. As a proof of completion, we collected our reports of
4+
finished Catalyst projects here:
5+
6+
- [Catalyst 9 reports](catalyst09-reports)
7+
- [Milestone 1: Research](catalyst09-reports/milestone-1.md)
8+
- [Milestone 2: End to end proof of concept](catalyst09-reports/milestone-2.md)
9+
- [Milestone 3: Testing and documentation](catalyst09-reports/milestone-3.md)
10+
- [Milestone 4: Project adoption](catalyst09-reports/milestone-3.md)
11+
- [Catalyst 10 reports](catalyst10-reports)
12+
- [Milestone 1: Rust support](catalyst10-reports/milestone-1.md)

‎docs/catalyst09-reports/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Catalyst 9 reports
2+
3+
- [Milestone 1: Research](catalyst09-reports/milestone-1.md)
4+
- [Milestone 2: End to end proof of concept](catalyst09-reports/milestone-2.md)
5+
- [Milestone 3: Testing and documentation](catalyst09-reports/milestone-3.md)
6+
- [Milestone 4: Project adoption](catalyst09-reports/milestone-3.md)

‎docs/catalyst09-reports/milestone-1.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Catalyst milestone 1: Research
2+
3+
## Outputs
4+
5+
- [x] A report summarizing user interviews and containing a qualitative analysis of the discovered use cases.
6+
- **STATUS**: Done (#17)
7+
- An interview with 3 MLabs engineers was performed (1.5h) who's work span multiple Cardano dApp projects. Their [feedback](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/feedback/interview-notes.md) is made available in the repo.
8+
- Additionally, a survey was sent out to MLabs engineers and their [feedback](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/feedback/questionnaire-results.pdf) is made available in the repo.
9+
- [x] An architecture design document.
10+
- **STATUS**: Done (#17)
11+
- Extensive documentation on [design](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/design.md), [compiler](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/compiler.md) and [codegen](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/codegen.md) is made available in the repo.
12+
- [x] A language specification document elaborating on the data type model features.
13+
- **STATUS**: Done (#17)
14+
- Extensive documentation on [design](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/design.md), [compiler](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/compiler.md) and [codegen](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/codegen.md) is made available in the repo.
15+
- [x] A related work document comparing the proposed technology via a feature matrix with others in the same space.
16+
- **STATUS**: Done (#17, #18)
17+
- [Document](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/comparison-matrix.md) comparing different schema techologies to LambdaBuffers is made available in the repo
18+
- [x] An initial compiler implementation that performs some basic checks in accordance with the language specification.
19+
- **STATUS**: Done (#10)
20+
- The [initial compiler implementation perform](https://github.com/mlabs-haskell/lambda-buffers/blob/main/lambda-buffers-compiler) `kind checking` is made available in the repo.
21+
22+
## Acceptance Criteria
23+
24+
- [x] At least 3 users/projects have been interviewed about their desired use case for this technology.
25+
- An interview with 3 MLabs engineers was performed (1.5h) who's work span multiple Cardano dApp projects. Their [feedback](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/feedback/interview-notes.md) is made available in the repo.
26+
- Additionally, a survey was sent out to MLabs engineers and their [feedback](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/feedback/questionnaire-results.pdf) is made available in the repo.
27+
- [x] The architecture design document is completed and available in the project repository.
28+
- Extensive documentation on [design](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/design.md), [compiler](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/compiler.md) and [codegen](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/codegen.md) is made available in the repo.
29+
- [x] The initial compiler implementation is completed, capturing SOME of the intended language semantics as described in the Language Specification
30+
- The [initial compiler implementation perform](https://github.com/mlabs-haskell/lambda-buffers/blob/main/lambda-buffers-compiler) `kind checking` is made available in the repo.
31+
32+
## Evidence of Milestone Completion
33+
34+
- [x] Completed and reviewed design document is available in the project repository.
35+
- Extensive documentation on [design](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/design.md), [compiler](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/compiler.md) and [codegen](https://github.com/mlabs-haskell/lambda-buffers/blob/main/docs/codegen.md) is made available in the repo.
36+
- [x] Completed and reviewed initial version of the compiler command line tool made available in the project repository.
37+
- The [Frontend CLI](https://github.com/mlabs-haskell/lambda-buffers/blob/main/lambda-buffers-frontend) called `lambda-buffers-frontend-cli` is made available in the repo and is currently able to parse, validate and format `.lbf` documents that contain the LambdaBuffers type modules:
38+
39+
```shell
40+
lambda-buffers/lambda-buffers-frontend$ cabal run
41+
Usage: lambda-buffers-frontend-cli COMMAND
42+
43+
LambdaBuffers Frontend command-line interface tool
44+
45+
Available options:
46+
-h,--help Show this help text
47+
48+
Available commands:
49+
compile Compile a LambdaBuffers Module (.lbf)
50+
format Format a LambdaBuffers Module (.lbf)
51+
```
52+
53+
There's ongoing work to integrate the [Compiler CLI](lambda-buffers-compiler) in the Frontend CLI.
54+
55+
- [x] Test case: Compiler is able to validate a schema that uses a subset of types and capabilities from the spec.
56+
- Both the [Frontend](https://github.com/mlabs-haskell/lambda-buffers/blob/main/lambda-buffers-frontend) and the [Compiler](https://github.com/mlabs-haskell/lambda-buffers/blob/main/lambda-buffers-compiler) components are accompanied by a test suite that is routinely run by the projects' CI system.
57+
- A [corpus of `lbf`](https://github.com/mlabs-haskell/lambda-buffers/blob/main/lambda-buffers-frontend/resources) files is made available in the repo and used in the test suite to ensure correct document handling.
58+
- The [compiler tests on the kind checking machinery](https://github.com/mlabs-haskell/lambda-buffers/blob/main/lambda-buffers-compiler/test/Test/KindCheck.hs) is also made available in the repo.
59+
60+
## References
61+
62+
- [Catalyst project sheet](https://docs.google.com/spreadsheets/d/16dTxgGsxHvcMe5aCgFPDYEJKgX_VQiNAcwhp2RyA48o/edit#gid=1672366179)

‎docs/catalyst09-reports/milestone-2.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Catalyst milestone 2: End to end proof of concept
2+
3+
## Outputs
4+
5+
- [x] A configuration DSL for specifying domain data types.
6+
- LambdaBuffers **Frontend** supports specifying modules with **type definitions** with **opaque**, **product/record** and **sum** types. Additionally, type **class definitions** are supported as well as type **class rule definitions** using the 'instance clause' and 'derive' syntax.
7+
- Refer to the standard LambdaBuffers library [lbf-base](https://github.com/mlabs-haskell/lambda-buffers/tree/8b0900ebdd526ed042040d5bc9cef5a5b0281e98/experimental/lbf-base) to get a sense of what the language looks like.
8+
- [x] A compiler tool that outputs the interpreted configuration.
9+
- The Compiler is exposed via an [Google Protobuffers based API](https://github.com/mlabs-haskell/lambda-buffers/blob/main/lambda-buffers-proto/compiler.proto). The Codegen shares the same API types and is exposed in a similar fashion. The Frontend communicates with these components via the API.
10+
- The API documentation is made available via [LambdaBuffers Github Pages](https://mlabs-haskell.github.io/lambda-buffers/compiler-api.html).
11+
- [x] A Codegen module that takes in the interpreted configuration and outputs a Haskell+PlutusTx (was Plutarch) Cabal project containing all the types and necessary type class wiring.
12+
- The module implementation is in [lambda-buffers-codegen/src/LambdaBuffers/Codegen/Haskell](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/src/LambdaBuffers/Codegen/Haskell).
13+
- The auto-generated Haskell files can be viewed in [lambda-buffers-codegen/data/goldens/haskell-autogen/LambdaBuffers](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/data/goldens/haskell-autogen/LambdaBuffers).
14+
- Codegen module outputs Haskell type definitions, and [Prelude.Eq](https://hackage.haskell.org/package/base-4.15.0.0/docs/Data-Eq.html#t:Eq) and [PlutusTx.ToData](https://github.com/input-output-hk/plutus/blob/848ec58de981a144226ee203c46144c0f3213f26/plutus-tx/src/PlutusTx/IsData/Class.hs#L34) type class implementations automatically.
15+
- Plutarch Codegen module is suspended for the current milestone (as communicated with the Catalyst team). Plutarch is a Haskell EDSL for writing Plutus (UPLC) programs, and can be considered a completely separate backend/target language.
16+
- [x] A Codegen module that takes in the interpreted configuration and outputs a Purescript+CTL Spago project containing all the types and necessary wiring.
17+
- The module implementation is in [lambda-buffers-codegen/src/LambdaBuffers/Codegen/Purescript](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/src/LambdaBuffers/Codegen/Purescript).
18+
- The auto-generated Purescript files can be viewed in [lambda-buffers-codegen/data/goldens/purescript-autogen/LambdaBuffers](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/data/goldens/purescript-autogen/LambdaBuffers).
19+
- Codegen module outputs Purescript type definitions and [Prelude.Eq](https://pursuit.purescript.org/packages/purescript-prelude/3.1.0/docs/Data.Eq#t:Eq) and [Ctl.Internal.ToData
20+
](https://github.com/Plutonomicon/cardano-transaction-lib/blob/b565f4b1ec877c671ec4ffc13b1b89dbe498bceb/src/Internal/ToData.purs#L73) type class implementations.
21+
22+
## Acceptance Criteria
23+
24+
- [x] The generated Haskell+Plutarch Cabal project can successfully be built.
25+
- [x] The generated Purescript+CTL Spago project can successfully be built.
26+
- [x] All the above codegen modules are reviewed and made available in the project repository.
27+
28+
## Evidence of Milestone Completion
29+
30+
- [x] Project repository is equipped with continuous integration tooling.
31+
- The repository has been consistently built with [HerculesCI](https://hercules-ci.com/) since the beginning.
32+
- [x] Completed and reviewed Haskell+Plutarch codegen module is made available in the project repository and the CI builds it successfully.
33+
- The auto-generated Haskell files can be viewed in [lambda-buffers-codegen/data/goldens/haskell-autogen/LambdaBuffers](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/data/goldens/haskell-autogen/LambdaBuffers).
34+
- Additionally, the auto generated Haskell files used during the demo can be found in [experimental/plutustx-env/autogen/LambdaBuffers](
35+
https://github.com/mlabs-haskell/lambda-buffers/tree/8b0900ebdd526ed042040d5bc9cef5a5b0281e98/experimental/plutustx-env/autogen/LambdaBuffers).
36+
- Codegen module outputs Haskell type definitions, and [Prelude.Eq](https://hackage.haskell.org/package/base-4.15.0.0/docs/Data-Eq.html#t:Eq) and [PlutusTx.ToData](https://github.com/input-output-hk/plutus/blob/848ec58de981a144226ee203c46144c0f3213f26/plutus-tx/src/PlutusTx/IsData/Class.hs#L34) type class implementations automatically.
37+
- Plutarch Codegen module is suspended for the current milestone (as communicated with the Catalyst team). Plutarch is a Haskell EDSL for writing Plutus (UPLC) programs, and can be considered a completely separate backend/target language.
38+
- [x] Completed and reviewed Purescript+CTL codegen module is made available in the project repository and the CI builds it successfully.
39+
- The module implementation is in [lambda-buffers-codegen/src/LambdaBuffers/Codegen/Purescript](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/src/LambdaBuffers/Codegen/Purescript).
40+
- The auto-generated Purescript files can be viewed in [lambda-buffers-codegen/data/goldens/purescript-autogen/LambdaBuffers](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/data/goldens/purescript-autogen/LambdaBuffers).
41+
- Additionally, the auto generated Purescript files used during the demo can be found in [experimental/ctl-env/autogen/LambdaBuffers](
42+
https://github.com/mlabs-haskell/lambda-buffers/tree/8b0900ebdd526ed042040d5bc9cef5a5b0281e98/experimental/ctl-env/autogen/LambdaBuffers).
43+
- Codegen module outputs Purescript type definitions and [Prelude.Eq](https://pursuit.purescript.org/packages/purescript-prelude/3.1.0/docs/Data.Eq#t:Eq) and [Ctl.Internal.ToData
44+
](https://github.com/Plutonomicon/cardano-transaction-lib/blob/b565f4b1ec877c671ec4ffc13b1b89dbe498bceb/src/Internal/ToData.purs#L73) type class implementations.
45+
- [x] Test case: Compiler is able to output a valid module with types from a schema in Haskell+Plutarch.
46+
- The auto-generated Haskell files can be viewed in [lambda-buffers-codegen/data/goldens/haskell-autogen/LambdaBuffers](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/data/goldens/haskell-autogen/LambdaBuffers).
47+
- [x] Test case: Compiler is able to output a valid module with types from a schema in PureScript.
48+
- The auto-generated Purescript files can be viewed in [lambda-buffers-codegen/data/goldens/purescript-autogen/LambdaBuffers](https://github.com/mlabs-haskell/lambda-buffers/tree/43d53222756e7b9bff836ec56e1a9b838678632e/lambda-buffers-codegen/data/goldens/purescript-autogen/LambdaBuffers).
49+
50+
## Demo recordings
51+
52+
- Introduction, working with the LambdaBuffers CLI tools and Frontend overview.
53+
- <https://www.youtube.com/watch?v=KnznwIdkFLM>
54+
- Codegen into Haskell
55+
- <https://www.youtube.com/watch?v=WhZU66fcnig>
56+
- Codegen into Purescript
57+
- <https://www.youtube.com/watch?v=tXnjt5h7D9w>
58+
59+
Demo files:
60+
61+
- LambdaBuffers [Citizen.lbf](https://github.com/mlabs-haskell/lambda-buffers/blob/8b0900ebdd526ed042040d5bc9cef5a5b0281e98/experimental/plutustx-env/api/Citizen.lbf) module.
62+
- Purescript demo files [ctl-env](https://github.com/mlabs-haskell/lambda-buffers/tree/8b0900ebdd526ed042040d5bc9cef5a5b0281e98/experimental/ctl-env/autogen/LambdaBuffers).
63+
- Haskell demo files [plutustx-env](https://github.com/mlabs-haskell/lambda-buffers/tree/8b0900ebdd526ed042040d5bc9cef5a5b0281e98/experimental/plutustx-env).
64+
65+
## References
66+
67+
- [Catalyst project sheet](https://docs.google.com/spreadsheets/d/16dTxgGsxHvcMe5aCgFPDYEJKgX_VQiNAcwhp2RyA48o/edit#gid=1672366179)

0 commit comments

Comments
 (0)