Catalyst milestone 1: LambdaBuffers Conway support
Outputs
Implementation in repository:
- Implementing codegen for all modules (Haskell, Plutarch, PlutusTx, Rust, TypeScript, PureScript) for all the new Plutus Ledger types. This includes the new governance-related types, delegation types, and updated transaction types.
- Create new golden tests for the above types, for all language modules. For instance, we will have a set of files consisting of known-good JSON-serialized instances, and our testsuite will check that our implementation outputs these serialized values upon execution as expected. Although an exhaustive list of tests is not possible here, there are many Plutus types updated or new in V3 our library will support such as Vote, Voter, TxOutRef, TxInInfo, TxCert, etc and various concrete instantiations of each type to test - e.g., a VoteNo Vote, a VoteYes Vote, and so on.
- Create new roundtrip tests for Eq, Json and PlutusData type classes (where applicable) that will verify our type class instances serialise and deserialize without corruption, loss of information, etc by converting values to JSON and back, PlutusData and back, and verifying equality withstands.
- Implement new Plutus V3 types in plutus-ledger-api-rust and plutus-ledger-api-typescript
- Documentation explaining the updates accomplished towards LambdaBuffers Conways support
Acceptance Criteria
-
All Plutus V3 types are implemented correctly and LambdaBuffers now supports codegen for all the supported language modules for these types:
- Both the Plutus Ledger APIs and codegen configurations are implemented ensuring execution outputs are as intended
-
All Plutus V3 types are covered by the golden tests ensuring execution outputs are as intended
- All languages use the same set of golden files to test against
-
All Plutus V3 have roundtrip tests for Eq, Json and PlutusData type classes (where applicable)
- All languages have roundtrip tests (where applicable) to tests Json and PlutusData serialization
-
The output is suitable for Plutus V3 Types such as Voter, Delegatee and GovernanceActionID etc.
- All new Plutus V3 types have been implemented in the supporting libraries
-
Documentation will cover new type support across Lambda buffer supported languages and will appear on https://mlabs-haskell.github.io/lambda-buffers in the Catalyst Milestone F13 reporting.
- Documentation of the newly implemented Plutus V3 types were auto-generated
Evidence of Milestone Completion
-
Proof of Achievement 1: Codegen implementation will be added to the github.com/mlabs-haskell/lambda-buffers repository and a link will be provided.
- Codegen configuration files for all languages are augmented with the new Plutus V3 types, pointing the opaque types to their respective type declarations in libraries.
Users of the LambdaBuffers library can now use V3 types in their schemas, and generate code for all the supported languages:
- Haskell (with Haskell Prelude) PlutusTx codegen config: lambda-buffers-codegen/data/haskell-plutus-plutustx.json
- Plutarch codegen config: lambda-buffers-codegen/data/plutarch-plutus.json
- PlutusTx (with Plutus Prelude) codegen config: lambda-buffers-codegen/data/plutustx-plutus.json
- Rust codegen config: lambda-buffers-codegen/data/rust-plutus-pla.json
- TypeScript codegen config: lambda-buffers-codegen/data/typescript-plutus.json
- PureScript CTL codegen config: lambda-buffers-codegen/data/purescript-plutus-ctl.json (some types are not supported by CTL itself, so naturally these are marked as NotImplemented in the configuration file)
- Codegen configuration files for all languages are augmented with the new Plutus V3 types, pointing the opaque types to their respective type declarations in libraries.
Users of the LambdaBuffers library can now use V3 types in their schemas, and generate code for all the supported languages:
-
Proof of Achievement 2: Rust plutus-ledger-api types and golden tests will be implemented in https://github.com/mlabs-haskell/plutus-ledger-api-rust and a link will be provided.
- Golden tests for added types can be found here:
- Haskell: Golden files are generated by this module and all the other language modules are reading these. All data types have golden files for Json and PlutusData serialisation. Added data types:
PlutusV3.TxOutRef, PlutusV3.ColdCommitteeCredential, PlutusV3.HotCommitteeCredential, PlutusV3.DRepCredential, PlutusV3.DRep, PlutusV3.Delegatee, PlutusV1.Lovelace, PlutusV3.TxCert, PlutusV3.Voter,
PlutusV3.Vote, PlutusV3.GovernanceActionId, PlutusV3.Committee, PlutusV3.Constitution, PlutusV3.ProtocolVersion, PlutusV3.ChangedParameters, PlutusV3.GovernanceAction, PlutusV3.ProposalProcedure,
PlutusV3.ScriptPurpose, PlutusV3.ScriptInfo, PlutusV3.TxInInfo, PlutusV3.TxInfo, PlutusV3.ScriptContext
- Golden data: testsuites/lbt-plutus/lbt-plutus-haskell/src/Test/LambdaBuffers/Plutus/Golden.hs
- PlutusData tests: testsuites/lbt-plutus/lbt-plutus-haskell/test/Test/LambdaBuffers/Runtime/Plutus/PlutusData.hs
- Json tests: testsuites/lbt-plutus/lbt-plutus-haskell/test/Test/LambdaBuffers/Runtime/Plutus/Json.hs
- CI test logs
- Plutarch: Files are read, deserialised to Plutarch and serialised back again to verify correctness. Only PlutusData serialisation is tested as Plutarch doesn't handle Json.
- PlutusTx: Files are read, deserialised to PlutusData and applied to Plutus Scripts. In these Plutus Scripts, we also do roundtrip tests, deserialising and serialising the data to ensure compatibility. Only PlutusData serialisation is tested as PlutusTx doesn't handle Json.
- Rust: Equivalent Rust golden data is implemented and compared with the ones generated by the Haskell module. Both Json and PlutusData serialisations are tested.
- Golden data: testsuites/lbt-plutus/lbt-plutus-rust/tests/goldens.rs
- PlutusData and Json tests: testsuites/lbt-plutus/lbt-plutus-rust/tests/main.rs
- CI test logs
- TypeScript: Equivalent TypesScript golden data is implemented and compared with the ones generated by the Haskell module. Both Json and PlutusData serialisations are tested.
- PureScript: Unfortunately the PureScript ledger API only partially supports V3 types. Furthermore, it does not have Json and PlutusData instances consistently, thus golden testing was out of scope
- Haskell: Golden files are generated by this module and all the other language modules are reading these. All data types have golden files for Json and PlutusData serialisation. Added data types:
PlutusV3.TxOutRef, PlutusV3.ColdCommitteeCredential, PlutusV3.HotCommitteeCredential, PlutusV3.DRepCredential, PlutusV3.DRep, PlutusV3.Delegatee, PlutusV1.Lovelace, PlutusV3.TxCert, PlutusV3.Voter,
PlutusV3.Vote, PlutusV3.GovernanceActionId, PlutusV3.Committee, PlutusV3.Constitution, PlutusV3.ProtocolVersion, PlutusV3.ChangedParameters, PlutusV3.GovernanceAction, PlutusV3.ProposalProcedure,
PlutusV3.ScriptPurpose, PlutusV3.ScriptInfo, PlutusV3.TxInInfo, PlutusV3.TxInfo, PlutusV3.ScriptContext
- Golden tests for added types can be found here:
-
Proof of Achievement 3: Plutus V3 roundtrip tests located at https://github.com/mlabs-haskell/lambda-buffers repo and a link will be provided.
- Roundtrip tests were implemented and can be found here:
- Haskell
- PlutusData: https://github.com/mlabs-haskell/lambda-buffers/tree/v2.0.0/testsuites/lbt-plutus/lbt-plutus-haskell/test/Test/LambdaBuffers/Runtime/Plutus/PlutusData.hs
- Json: https://github.com/mlabs-haskell/lambda-buffers/tree/v2.0.0/testsuites/lbt-plutus/lbt-plutus-haskell/test/Test/LambdaBuffers/Runtime/Plutus/Json.hs
- Plutarch: testsuites/lbt-plutus/lbt-plutus-plutarch/test/Test/LambdaBuffers/Runtime/Plutarch/PlutusData.hs
- PlutusTx: testsuites/lbt-plutus/lbt-plutus-plutustx/test/Test/LambdaBuffers/Runtime/PlutusTx/PlutusTx.hs
- Rust
- PlutusData and Json: testsuites/lbt-plutus/lbt-plutus-rust/tests/main.rs
- Property based tests for PlutusData: https://github.com/mlabs-haskell/plutus-ledger-api-rust/blob/v3.0.2/plutus-ledger-api/tests/plutus_data.rs
- Property based tests for Json: https://github.com/mlabs-haskell/plutus-ledger-api-rust/blob/v3.0.2/plutus-ledger-api/tests/lbf.rs
- TypeScript
- PlutusData: testsuites/lbt-plutus/lbt-plutus-typescript/src/PlutusData-test.ts
- Json: testsuites/lbt-plutus/lbt-plutus-typescript/src/Json-test.ts
- Property based tests for PlutusData and Json: https://github.com/mlabs-haskell/plutus-ledger-api-typescript/blob/v1.2.1/src/Tests/V3
- PureScript: Unfortunately the PureScript ledger API only partially supports V3 types. Furthermore, it does not have Json and PlutusData instances consistently, thus roundtrip testing was out of scope
- Haskell
- Roundtrip tests were implemented and can be found here:
-
Proof of Achievement 4: Plutus V3 types located at https://github.com/mlabs-haskell/plutus-ledger-api-rust https://github.com/mlabs-haskell/plutus-ledger-api-typescript and links provided.
- Plutus_Ledger API Rust implementation was implemented here: mlabs-haskell/plutus-ledger-api-rust v3.0.2
- Plutus_Ledger API TypeScript implementation was implemented here: mlabs-haskell/plutus-ledger-api-typescript v1.2.1
-
Proof of Achievement 5: Page addressing the new Documentation on types for Catalyst Fund 13 at https://mlabs-haskell.github.io/lambda-buffers
- Documentation of plutus-ledger-api-rust V3 types is located here: https://mlabs-haskell.github.io/plutus-ledger-api-rust/plutus_ledger_api/v3
- Documentation of plutus-ledger-api-typescript V3 types is located here: https://mlabs-haskell.github.io/plutus-ledger-api-typescript/modules/plutus_ledger_api_V3_js
- Conway compatibility report docs/catalyst13-reports/milestone-1.md
- Updated lambda-buffers-for-cardano repository and documentation
- Updated Changelog