Add Data.Value to PlutusLedgerAPI
#6143
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
ana-pantilie
commented
May 31, 2024
| @@ -0,0 +1,2 @@ | |||
| ({cpu: 27490443 | |||
| | mem: 64380}) | |||
There was a problem hiding this comment.
Non-data version:
({cpu: 26667308
| mem: 102924})
There was a problem hiding this comment.
That's a surprisingly negligible difference in CPU units. Well, at least MEM is 1.6x lower.
| @@ -0,0 +1 @@ | |||
| (con integer 3636) | |||
There was a problem hiding this comment.
Same as non-data version ✔️
There was a problem hiding this comment.
I suggest you to rewrite this test not to use golden file but to directly compare with constant, for example:
testRatioInterop :: TestTree
testRatioInterop = testCase "ratioInterop" do
runExceptT (runUPlc [getPlcNoAnn roundPlc, snd (Lift.liftProgramDef (Ratio.fromGHC 3.75))])
>>= \case
Left e -> assertFailure (show e)
Right r -> r @?= Core.mkConstant () (4 :: Integer)There was a problem hiding this comment.
Thanks, that's a good point. Also, we should also test that the two Value types are functionally equivalent. I decided not to focus on this in this PR in order to avoid it getting too large. Once I have a data-backed version of the ScriptContext, I will be able to see the bigger picture and start refactoring things to reduce code duplication and improve our tests. I'll add your suggestion to the list of things to do once I have this.
There was a problem hiding this comment.
I suggest you to rewrite this test not to use golden file but to directly compare with constant
Normally I'd agree, but given that here we can instead check this same result in two different golden tests, I'd suggest we do that instead. But it's fine either way.
| @@ -0,0 +1,2 @@ | |||
| ({cpu: 739705185 | |||
| | mem: 1839010}) | |||
There was a problem hiding this comment.
Non-data version:
({cpu: 234326645
| mem: 870930})
There was a problem hiding this comment.
A 3.15x reduction in CPU and a 2.11x reduction in MEM! That's pretty cool.
There was a problem hiding this comment.
I wish that were true, unfortunately it's the other way around @effectfully @bezirg .
As I mentioned in the description, I wasn't able yet to find a way to optimise geq and the other comparison functions the same way I did with eq (which does show some improvement, as you noticed!).
I will definitely come back to this, but I decided to not dwell on it longer than a couple of days at this point because I ultimately don't know how much geq etc. are really used in practice.
| @@ -0,0 +1 @@ | |||
| (constr 0) | |||
| @@ -0,0 +1,2 @@ | |||
| ({cpu: 783201675 | |||
| | mem: 1959530}) | |||
There was a problem hiding this comment.
Non-data version:
({cpu: 252364563
| mem: 941642})
| @@ -0,0 +1 @@ | |||
| (constr 1) | |||
| @@ -0,0 +1,2 @@ | |||
| ({cpu: 823509793 | |||
| | mem: 2056794}) | |||
There was a problem hiding this comment.
Non-data version:
({cpu: 266270723
| mem: 984270})
| @@ -0,0 +1 @@ | |||
| (constr 0) | |||
| ({cpu: 10186791 | mem: 31548}) | ||
| ({cpu: 2768528655 | mem: 4789358}) | ||
| ({cpu: 10186791 | mem: 31548}) | ||
| ({cpu: 789262389 | mem: 1142358}) |
There was a problem hiding this comment.
Non-data version:
({cpu: 3007736773 | mem: 11157042})
({cpu: 712988980 | mem: 3097504})
({cpu: 2101129911 | mem: 7793754})
({cpu: 587638980 | mem: 2552504})
({cpu: 2101129911 | mem: 7793754})
({cpu: 462012980 | mem: 2006304})
({cpu: 1194523049 | mem: 4430466})
({cpu: 462150980 | mem: 2006904})
({cpu: 2101129911 | mem: 7793754})
({cpu: 462012980 | mem: 2006304})
({cpu: 1194523049 | mem: 4430466})
({cpu: 336662980 | mem: 1461304})
({cpu: 1194523049 | mem: 4430466})
({cpu: 211036980 | mem: 915104})
({cpu: 287916187 | mem: 1067178})
There was a problem hiding this comment.
Funny, I thought these tests were complete garbage (when I wrote them I had the wrong assumptions about what Value was, so the tests aren't testing anything sensible really), but here they kinda show us that the new version computes more than necessary? All these old mem: 31548 vs new mem: 1461304 etc.
There was a problem hiding this comment.
Actually, those are the tests which show improvement! Some of them are worse, yes, but I'm pretty sure it's because of geq etc. which I will come back to in a future PR.
| ({cpu: 146217283 | mem: 380844}) | ||
| ({cpu: 183786078 | mem: 470500}) | ||
| ({cpu: 73253295 | mem: 204964}) | ||
| ({cpu: 789262389 | mem: 1142358}) |
There was a problem hiding this comment.
Non-data version:
({cpu: 4370100 | mem: 19100})
({cpu: 5888100 | mem: 25700})
({cpu: 8301491 | mem: 34902})
({cpu: 10016980 | mem: 41104})
({cpu: 12016371 | mem: 48506})
({cpu: 14260860 | mem: 57008})
({cpu: 19387076 | mem: 76712})
({cpu: 20506174 | mem: 81612})
({cpu: 23042467 | mem: 91314})
({cpu: 19324850 | mem: 77610})
({cpu: 34128486 | mem: 133124})
({cpu: 20816294 | mem: 85508})
({cpu: 48929385 | mem: 188538})
({cpu: 58404649 | mem: 221950})
({cpu: 67450806 | mem: 257556})
({cpu: 77432070 | mem: 293168})
({cpu: 89687541 | mem: 340178})
({cpu: 94462030 | mem: 359680})
({cpu: 115639590 | mem: 436404})
({cpu: 89068795 | mem: 361540})
({cpu: 287916187 | mem: 1067178})
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
effectfully
reviewed
Jun 3, 2024
There was a problem hiding this comment.
I don't like the test duplication. I can see how we need to duplicate Plutus Tx code due to performance reasons, but why do we need to duplicate all the tests instead of trying to reuse them as much as possible? Or is the idea that we're going to get rid of non-Data-backed Value completely? In that case we should preserve the comments in the complicated eq function.
| {-# OPTIONS_GHC -fexpose-all-unfoldings #-} | ||
| -- We need -fexpose-all-unfoldings to compile the Marlowe validator | ||
| -- with GHC 9.6.2. | ||
| -- TODO. Look into this more closely: see PLT-7976. |
There was a problem hiding this comment.
Replace that reference with a reference to a GitHub issue if it exists?
There was a problem hiding this comment.
Moved the issue to GitHub #6172 and linked it here.
| You may want to add checks for its invariants. See the | ||
| [Shelley ledger specification](https://github.com/IntersectMBO/cardano-ledger/releases/download/cardano-ledger-spec-2023-04-03/shelley-ledger.pdf). | ||
| -} | ||
| newtype CurrencySymbol = CurrencySymbol { unCurrencySymbol :: PlutusTx.BuiltinByteString } |
There was a problem hiding this comment.
Is this duplicated too? Why does it need to be?
There was a problem hiding this comment.
I don't know at this point if I need it to be duplicated or not.
There was a problem hiding this comment.
I don't see a reason to duplicate this. It is literally the same type as the existing one.
| You may want to add checks for its invariants. See the | ||
| [Shelley ledger specification](https://github.com/IntersectMBO/cardano-ledger/releases/download/cardano-ledger-spec-2023-04-03/shelley-ledger.pdf). | ||
| -} | ||
| newtype TokenName = TokenName { unTokenName :: PlutusTx.BuiltinByteString } |
There was a problem hiding this comment.
Ditto. And the functions over them. And why is it placed in a Value module?
There was a problem hiding this comment.
Keeping the module in sync with the other one until I know more.
| valueOf :: Value -> CurrencySymbol -> TokenName -> Integer | ||
| valueOf (Value mp) cur tn = | ||
| case Map.lookup cur mp of | ||
| Nothing -> 0 :: Integer |
There was a problem hiding this comment.
We need a type annotation here?
| -- null l2 case | ||
| (\() -> True) | ||
| -- non-null l2 case | ||
| (\ _ _ -> Map.all is0 (Map.unsafeFromBuiltinList l2 :: Map.Map BuiltinData BuiltinData)) |
There was a problem hiding this comment.
You decided not to preserve the comments?
There was a problem hiding this comment.
I think I forgot I deleted it, thanks for pointing this out!
| @@ -0,0 +1 @@ | |||
| (con integer 3636) | |||
There was a problem hiding this comment.
I suggest you to rewrite this test not to use golden file but to directly compare with constant
Normally I'd agree, but given that here we can instead check this same result in two different golden tests, I'd suggest we do that instead. But it's fine either way.
| @@ -0,0 +1,2 @@ | |||
| ({cpu: 739705185 | |||
| | mem: 1839010}) | |||
There was a problem hiding this comment.
A 3.15x reduction in CPU and a 2.11x reduction in MEM! That's pretty cool.
| ({cpu: 10186791 | mem: 31548}) | ||
| ({cpu: 2768528655 | mem: 4789358}) | ||
| ({cpu: 10186791 | mem: 31548}) | ||
| ({cpu: 789262389 | mem: 1142358}) |
There was a problem hiding this comment.
Funny, I thought these tests were complete garbage (when I wrote them I had the wrong assumptions about what Value was, so the tests aren't testing anything sensible really), but here they kinda show us that the new version computes more than necessary? All these old mem: 31548 vs new mem: 1461304 etc.
There was a problem hiding this comment.
I'm really not a fan of duplicating those. Is it hard to make the test suite generic over the Value type?
There was a problem hiding this comment.
I really don't want to refactor anything at this point. I have no idea what the end result will be, if we keep both Value and Data.Value, or if we keep just the data one (if we are to be very optimistic). Once I have added the new data ScriptContext I will have a much better idea of what needs to be kept and where I can reduce all the duplication. This will be the next PR I have up. I am taking note of everything that I should change after I know what the final result will be, so I do appreciate the comments.
There was a problem hiding this comment.
This is Haskell, you can simply generate a non-Data-backed Value and convert it to the Data-backed one without copy-pasting the whole generation code.
There was a problem hiding this comment.
|
@effectfully thank you for you review. I will address some of your comments tomorrow. Regarding reducing duplication, I would postpone that until after I know more (until I have the next PR, also see https://github.com/IntersectMBO/plutus/pull/6143/files#r1624835478). I normally wouldn't be happy with this, but I am doing this to make things easier to review (for both me and the reviewers), I really want to avoid absolutely huge PRs because they make things so much slower and more painful to maintain! I think this PR is well-scoped enough (it just adds the new |
zliu41
approved these changes
Jun 3, 2024
| You may want to add checks for its invariants. See the | ||
| [Shelley ledger specification](https://github.com/IntersectMBO/cardano-ledger/releases/download/cardano-ledger-spec-2023-04-03/shelley-ledger.pdf). | ||
| -} | ||
| newtype CurrencySymbol = CurrencySymbol { unCurrencySymbol :: PlutusTx.BuiltinByteString } |
There was a problem hiding this comment.
I don't see a reason to duplicate this. It is literally the same type as the existing one.
I'm OK with keeping test duplication if you want that, but I'd still much prefer not to duplicate the module with the |
11 tasks
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
joseph-fajen
pushed a commit
that referenced
this pull request
Jun 7, 2024
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
joseph-fajen
added a commit
that referenced
this pull request
Jun 9, 2024
This reverts commit 5e29c87.
|
@ana-pantilie Sorry, I failed to look at this PR when it was in review. However, I just happened to be looking at Value.hs and I got very confused when I saw Data/Value.hs, which at first sight looks like an exact duplicate. It might be helpful to have a comment at the top of both files pointing out that they're similar and saying what each should be used for. I think you're planning another PR soon so maybe that issue will go away anyway. |
|
@kwxm That's a good point, sorry about that. I'll open a separate PR which adds some documentation to the Data version, until we decide on whether we keep both implementations or just the Data version. |
ramsay-t
added a commit
that referenced
this pull request
Aug 6, 2024
* Trace removal re-implemented as a IR rewrite rule (#5907) * refactor: Internal module for RewriteRules, Monoid Instance * Trace removal re-implemented as a IR rewrite rule * Test case for an impure trace message, added note. * CIP-0057 Howto: exporting a Plutus contract blueprint (#5817) * Howto: exporting a Plutus contract blueprint * howto/exporting-a-blueprint uses literal includes * Changelog record * Paragraph about `deriveArgumentBlueprint` / `deriveParameterBlueprint` * Include plutus.json literally * [Release] 1.26.0.0 (#5914) Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com> * A quick isabelle experiment. (#5913) * PLT-8171: Combine PIR, PLC, and UPLC into a single executable (#5699) Acked-by: Nikolaos Bezirgiannis <bezirg@users.noreply.github.com> Co-authored-by: Nikolaos Bezirgiannis <bezirg@users.noreply.github.com> * chore(deps): bump slackapi/slack-github-action from 1.25.0 to 1.26.0 (#5915) Bumps [slackapi/slack-github-action](https://github.com/slackapi/slack-github-action) from 1.25.0 to 1.26.0. - [Release notes](https://github.com/slackapi/slack-github-action/releases) - [Commits](slackapi/slack-github-action@v1.25.0...v1.26.0) --- updated-dependencies: - dependency-name: slackapi/slack-github-action dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Kwxm/plc spec/bitwise conversions (#5911) * Intial text for bitwise conversions * Intial text for bitwise conversions * Updates * Tidying up * Tidying up * Deal with edge cases more concisely * More tidying up * Rearrange some cases * Almost done * More clarification * Update specification date * Some clarification after PR comments * Use Int64 in CostModelParams (#5920) * Change CMTooFewParamsError to a warning (#5912) * [Costing] Provide support for multiple 'CostModel's (#5851) * CaseOfCase kind mismatch error fix (#5923) * Fix issue #5922 * test_extractTyArgs * CaseOfCase: cover types with two type args * Fix some Notes so they pass the check (#5930) * Restore old cost model param names (#5932) * Tidy up SimpleJSON.hs (#5936) * chore: formatting (#5937) * 1.27.0.0 (#5938) * Do not build the plutus executable if GHC <9.6 (#5940) * Update CONTRIBUTING.adoc (#5950) * Add 'Note [Table of all possible ledger's states w.r.t. cost model parameters update]' (#5935) * Remove annoying error message (#5956) * Add plutus-tx-template Release Instructions and GH Workflow (#5952) * [StdLib] Strictify 'fix' (#5939) This makes `fix` stricter so that the body of the function that it takes always gets forced regardless of whether the necessary argument is provided or not. Resolves #5961. --------- Co-authored-by: Yura Lazaryev <Yuriy.Lazaryev@iohk.io> * [PIR] Don't generate 'fixBy' if you don't need to (#5954) Removes unnecessary generation of `fixBy` when we only need `fix`. * Chore: formatting, imports, pragmas. (#5965) * CaseOfCase UPLC transformation tests. (#5960) * Avoid evaluating `nilCase` strictly in `matchList`, and rename the original `matchList` to `matchList'` (#5901) * Improvements to plutus-metatheory site (#5959) * Improvements to plutus-metatheory site * Added markdown titles to markdown files so they get built properly. Not all of the titles are very interesting. --------- Co-authored-by: Ramsay Taylor <ramsay.taylor@iohk.io> * chore(deps): bump nixbuild/nix-quick-install-action from 27 to 28 (#5951) Bumps [nixbuild/nix-quick-install-action](https://github.com/nixbuild/nix-quick-install-action) from 27 to 28. - [Release notes](https://github.com/nixbuild/nix-quick-install-action/releases) - [Changelog](https://github.com/nixbuild/nix-quick-install-action/blob/master/RELEASE) - [Commits](nixbuild/nix-quick-install-action@v27...v28) --- updated-dependencies: - dependency-name: nixbuild/nix-quick-install-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * [Build] Remove the doctests runner of 'prettyprinter-configurable' (#5974) * Kwxm/mainnet script budgets (#5973) * Mainnet script budget analysis * Comment * Add a comment * Release 1.28.0.0 (#5975) * [PlutusTx] [Builtins] Split 'FromBuiltin' and 'ToBuiltin' (#5971) This addresses the [inconsistencies](#5547 (comment)) that we got from using the now retired `FromBuiltin`/`ToBuiltin` classes for two mutually exclusive purposes. Now we have two versions of those classes: one is used for converting builtins to Plutus Tx types and back, while the other one is for making builtins transparent/opaque within Plutus Tx. These two purposes are very similar, but also subtly different and that is explained in the docs. * Update README.md (#5997) * chore(deps): bump cachix/install-nix-action from 26 to 27 (#5999) Bumps [cachix/install-nix-action](https://github.com/cachix/install-nix-action) from 26 to 27. - [Release notes](https://github.com/cachix/install-nix-action/releases) - [Commits](cachix/install-nix-action@v26...V27) --- updated-dependencies: - dependency-name: cachix/install-nix-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Script to prepare binary executables for uploading to the github release page. (#6015) * Kwxm/mainnet script budgets 2 (#6057) * Get the script analysis executable to print out actual execution costs * Tidying up * Empty comment * Dot * Output evaluation status too * Oops * Add integerToByteString and byteStringToInteger to PlutusV2 at PV10 (#6056) * [Refactoring] Remove 'UnknownBuiltin' and 'UnknownBuiltinType' (#6064) * Conditionally add 'triage' label to new issues (#6061) * Add triage label only when the issue does not have any of the 'Internal' labels * Fix bug in add-triage-label.yml (#6067) * chore(deps): bump benchmark-action/github-action-benchmark (#6058) Bumps [benchmark-action/github-action-benchmark](https://github.com/benchmark-action/github-action-benchmark) from 1.19.3 to 1.20.3. - [Release notes](https://github.com/benchmark-action/github-action-benchmark/releases) - [Changelog](https://github.com/benchmark-action/github-action-benchmark/blob/master/CHANGELOG.md) - [Commits](benchmark-action/github-action-benchmark@v1.19.3...v1.20.3) --- updated-dependencies: - dependency-name: benchmark-action/github-action-benchmark dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Add integerToByteString and byteStringToInteger to V2.ParamName (#6065) * Add PlutusTx Map backed by Data (#5927) Co-authored-by: Ziyang Liu <unsafeFixIO@gmail.com> Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com> * Let nightly.yml accept hedgehog-tests input (#6062) * Let nightly.yml accept hedgehog-tests input * Default tests from 10k to 50k * Remove obsolete defer-plugin-errors flag (#6080) * Add a Plutus Tx test utility package (#6086) Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com> * [Errors] polish evaluation errors (#6043) We have this distinction of "user" vs "internal" errors that made some sense when TPLC was what was evaluated, but now that it's UPLC, all of those are "user" errors. So I was going to remove the distinction entirely just to realize that it in fact still makes sense, it's just now "operational" vs "structural". This PR clarifies this. I've also tweaked errors a bit while I was here, plus removed a bunch of unsafe functions from the CEK machine API (they were convenient when they were exposed from a single module, but now that we have several of them, it's no longer worth the trouble, plus we really should use some different approach to calling the CEK machine in the benchmarks, but that's not within the scope of this PR). * [Test] Add do-notation support for 'TestNested' (#5948) This refactors the `TestNested` machinery, so that 1. it supports listing tests in a `do`-block, which is something that I need in a different PR to update a huge `do`-block so that some of the tests there become golden 2. the API is more granular and pushes the user in the right direction I've also improved some of the tests while I was there and unified the formatting. Most of the tests we have use 4 spaces instead of 2, so I preserved that, we're probably going to run `fourmolu` over all the files eventually anyway and that'll make the indentation 2-space-based. * Run nightly tests on plutus-benchmark (#6091) * [Exe] Generalize 'withL' to 'withLangGeneral' (#5918) * Kwxm/provisional conway cost model (#6087) * Rename semantics variants * Change some names * Get uplc to use correct cost model for semvar * Dumping cost models * Dumping cost models * Tidy up exports and tests * Move a function * More updates * Fix some typos * Update models.R * Add updated cost models * Add updated cost models * Update test results * Remove obsolete entries from V3.ParamName * Fix cost model interface test * Fix (sort of) plutus-ledger-api tests * Various small fixes * Forgot to update parameters * Add changelog entries * Fix the changelog entries * Address PR review comments * Add costs for new builtins to V1 and V2 cost model files * Fix some dependencies in plutus-benchmark * Fix partial reversion of #6086 caused by merge * Remove old cost model files * Update/rename benchmark CSV files * Update issue templates (#6037) * Remove reference to benching.csv in plutus-core.cabal (#6149) * PlutusV3: Datum/Redeemer in ScriptContext, Datum Optional, Unified Script Type (#5934) * Kwxm/costing/reduce CEK CPU step costs B (#6153) * Make CEK step costs for models B anc C identical * Add changelog entry * Add changelog entry * [Test] Dump UPLC for 'strictLetRec' (#5963) * Use the most recent evaluation context for most of the benchmarks (#6152) * [Builtins] Polish handling of integral types (#6036) This - adds support for throwing operational unlifting errors in the builtins machinery, which allows us to attach a message to an unlifting failure. Unfortunately this is still not enough to propagate proper error messages to the user, because they get erased by the evaluation machinery down the line, this is our 2018's legacy of the stupid idea to have raw evaluation failures that don't carry any content - makes handling of integral types in `PlutusCore.Default.Universe` uniform (it was a mess before with a weird partial set of instances and morally the same instances being implemented differently) * Tests for the `preserve-logging` flag. (#6162) * Require PlutusV3 scripts to evaluate to BuiltinUnit (#6159) * Quadratic costing for integer division functions (#6161) * Quadratic costing for integer division functions * Correct some typos * Agda typo * Fix V2's costModelParamsForTesting (#6166) * Release 1.29.0.0 (#6170) * Update update-version.sh to match package names less greedily (#6174) * Update update-version.sh to match package names less greedily * Allow whitespace after comma * Allow whitespace after comma * Clarify comment * More error checking (#6179) * Reorganized Plutus user guide on the Docusaurus platform initial deployment (#6177) * Initial Docusaurus Setup * uploaded docs files and images * added code files and images * cleaned up mermaid diagrams for platform page * committed yarn.lock file * Add markdown link styling * Update Plutus styling and add GA plugin * updating yarn.lock file * CSV Rendering component * adding cost model parameters page that imports CSV files * Fix gradient overflow on tables for dark mode * changing title to Plutus user guide * Update favicon and social card assets * Remove landing page and set /docs to base path * Update literal include roots * Rename Haddock workflow and update to include Docusaurus build * Update docusaurus/README.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr-index.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr-index.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr-index.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr2.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/essential-concepts/language-versions.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/essential-concepts/language-versions.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/essential-concepts/language-versions.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/essential-concepts/language-versions.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Update docusaurus/docs/adr/adr1.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * committing after running pre-commit run --all-files command to fix build errors --------- Co-authored-by: ianhanssoniohk <ian.hansson@iohk.io> Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * Initial version of new combined-haddock.yml workflow (#6182) * [Builtins] Make 'BuiltinSuccess' the first constructor (#5885) This makes `BuiltinSuccess` the first constructor of `BuiltinResult`, see the comment there of why we want that. See [this](#5885 (comment)) comment for the very ambiguous benchmarking results. * [PlutusLedgerApi] [Refactoring] Polish imports and exports (#6178) This - resolves #6098 - moves a bunch of stuff shared among `V1`/`V2`/`V3` into `Common` (see the PR review) - makes all imports in the `Common`/`V1`/`V2`/`V3` modules qualified so that it's clear where definitions come from and whether they are inherited from `Common` or an earlier ledger language - fixes some formatting, adds a definition for consistency etc * Adding link to Haddock documentation to index.md (#6187) * removing outdated and incorrect content from the Plutus platform page (#6188) * Add `Data.Value` to `PlutusLedgerAPI` (#6143) Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com> * added the term Haddock where the public Plutus code libraries are mentioned since it is a term likely to be used in searches (#6190) * Refactored Serialise/Flat-Via. Fixes #6083 (#6144) Co-authored-by: Nikolaos Bezirgiannis <bezirg@users.noreply.github.com> * Add Redeemer to V3 ScriptContext Pretty instance (#6191) * Logical operations (#5970) * Initial port of logical ops * Add PlutusTx correspondents to the new builtins * Tests for logical operations * Rest of tests * Formatting of denotations * Rename byteStringReplicate to replicateByteString * Correct references to CIP-121 * Changelogs, document tests * Note commutativity for new operations * Properly rename replicate builtin, add to plutus-tx-plugin * Make new logical builtins available in V3 * Fix links to CIP-122, use toOpaque and fromOpaque instead * Correct all references to CIP-122 * Rename bitwise builtins, use proper costing * Bitwise primops will not be in Conway * Rename tests to suit new primop names * Combined Haddock Generation (#6146) * Run nightly tests on plutus-shared instead of plutus-benchmark (#6195) * Run combined-haddock.yml workflow on plutus-shared instead of plutus-runner (#6196) * Fix combined_haddock.sh script (#6199) * [Test] [Builtins] Add golden tests with unlifting errors (#6189) This refactors a file with tests so that unit tests that are supposed to result in evaluation failure also become golden tests with the error message printed to a golden file. Need it to demonstrate that #6181 does indeed allow us to preserve operational unlifting errors. * Changed the term "Documentation" to "User guide" in the upper left area of the docs site (#6200) * Styling updates to docusaurus site * Changed the term Documentation to User guide in the upper left corner of the docs site next to the PLUTUS wordmark logo. * Add .yarn to .gitignore --------- Co-authored-by: ianhanssoniohk <ian.hansson@iohk.io> * Update Alert Message in longitudinal-benchmark.yml (#6201) * [Test] Add missing bitwise builtins golden files (#6204) * [Errors] Preserve operational unlifting errors (#6181) * Docs raise visibility code libraries (#6203) * added more visibility to Haddock Plutus code libraries on index.md page * adding new Haddock documentation page under the Reference nav menu * updated Reference top-level page description * minor style edit update docusaurus/docs/index.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * style edits update docusaurus/docs/reference/haddock-documentation.md Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> --------- Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> * [Test] [Builtin] Polish 'MakeRead' tests (#6202) * Remove AssocMap comparison instances (#6173) Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com> * Update README.adoc (#6206) Updated the link in README to point to the Plutus docs site on the docusaurus platform instead of Read the docs. * Remove PyF as it depends on GHC and causes depenecy conflicts downstream. (#6208) * Bitwise operations (#6090) * Initial bitwise primitives * Wire up new builtins * Tests * Changelogs * Fix failing goldens * Fix cost model for tests * Bitwise primitives are not in Conway * Finish shift tests * Fix goldens * Rest of tests * Rename operations * Note about split composition for shift property * Explain bitwise tests in comments, remove AND and OR tests for finding and counting bits * Goldens for bitwise primops * Chop down property test running times a bit * Add test for finding first in zero byte string, rename some tests for clarity * Clarify implementation choices in the comments * Tidy up helpers for property tests * Consolidate all bitwise ops, retarget links to CIPs * Reduce coverage limits for signature verification tests (#6209) * moved the Getting Started page to immediately follow the Introduction page (#6211) * Haskell Eq for AssocMap (#6213) Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com> * Shorten some filenames in the conformance tests (#6214) Shorten some file names * MK-5422 move getting started page fixing link (#6215) * moved the Getting Started page to immediately follow the Introduction page * fixed broken link * [Evaluation] Move stuff under `enterComputeCek` (#6156) This polishes the structure of the CEK machine code a little: moves definitions having CEK-specific constraints around (as per `Note [Compilation peculiarities]`), removes outdated comments and moves pragmas around. * Release 1.30.0.0 (#6216) * plutus-ir: fix redundant imports (#6218) * Fix incorrect Note reference (#6217) * Add documentation to `Data.Value` (#6220) * [Builtins] Replace 'EvaluationResult' with 'BuiltinResult' (#5926) This replaces several `Emitter (EvaluationResult a)` occurrences with `BuiltinResult`, something that I missed the last [time](#5728). In addition to that, it also replaces `EvaluationResult` with `BuiltinResult` in general. It doesn't matter performance-wise (modulo a regression that we didn't notice some time ago), but `BuiltinResult`, unlike `EvaluationResult`, allows one to attach an error message to a failure, which we do in this PR as well, meaning we now get better error messages. And we also now respect the operational vs structural evaluation errors distinction. The PR also replaces `Emitter` with `BuiltinResult`. And makes the GHC Core of builtins smaller by making error-throwing functions (not) inline (see `Note [INLINE and OPAQUE on error-related definitions]` for details). * New `./scripts/combined-haddock.sh` (#6205) * Add workflow for publishing Agda Metatheory site (#6223) * Add workflow for publishing AGDA metatheory site * wip * wip * Fixes to `metatheory-site.yml` workflow (#6228) * Final changes to `metatheory-site.yml` workflow (#6229) * Update RELEASE.adoc with instructions to delete unused branches and tags (#6230) * Complete Migration from RDT to Docusaurus (#6227) - Delete the contents of doc/read-the-docs-site, only keeping the README with a migration notice. - Move docusaurus folder into doc folder. - Update the GH workflows for publishing the haddock site and docusaurus site. - Delete GH web hook and update redirects on RTD site. - Remove mentions of read-the-docs and combined-haddock from nix code - Update release process, mentioning how to publish Docusaurus and the Haddock site - Update links in Docusaurus mentioning the new haddock site * Fix broken links in docusaurus docs (#6232) * Add flake.nix for doc/docusaurus (#6233) * New shell for Docusaurus * Fix broken links * making a spelling correction on the doc/docusaurus README file (#6235) * [Builtins] Remove 'Emitter' and 'MonadEmitter' (#6224) * Refactor GitHub Workflows (#6124) * Fix & simplify SOP encoding example comment (#6231) Here's a small fix for the comment: - use one variable for the type everywhere - fix ordering of `constr` arguments Additionally, - align the corresponding parts in the text * Update github-action-benchmark version (#6238) * Make it build with ghc 9.10 (#6079) * Make it build with ghc 9.10 * Nix updates * Disable failing test (cseExpensive test in untyped-plutus-core-test suite) * plutus-tx-plugin-tests: Accept some CSE golden changes * Update version of github-action-benchmark to v1.20.3 (#6240) * Update version of github-action-benchmark to v1.20.3 * Fix bug in triage-label.yml * Add workflows to check broken links and deploy papers to GH Pages (#6236) * Add workflows to check broken links and deploy papers to GH Pages * Publish papers and specs on push to master only (#6246) * Cabal project to compile docusaurus examples. (#6239) * Added cardano-constitution package (#6234) * Added cardano-constitution package * Remove cardano-constitution checks from CI * Restrist x-compiling --------- Co-authored-by: Nikolaos Bezirgiannis <bezirg@users.noreply.github.com> Co-authored-by: zeme <lorenzo.calegari@iohk.io> * [Test] Turn off CSE for problematic tests (#6249) * [Test] Turn off CSE for the 'patternMatching' test (#6251) * [Optimization] Remove case-of-case (#6248) * Spec that verifies various script sizes (#6247) * Add cardano-constitution-tests and slack-message-broker workflows (#6253) * Updates to slack-message-broker.yml (#6258) * Update slackapi/slack-github-action version -> v1.26.0 (#6259) * Improve messages in slack-message-broker.yml (#6260) * Fix error message in slack-message-broker.yml (#6261) * Fix another error in slack-message-broker.yml (#6262) * Fix "un-rolling" a list type. (#6165) * Fix "un-rolling" a list type. * Un-roll other general types: [], Maybe, (,), BuiltinUnit, BuiltinPair * constitution: Add executable that creates json envelope (#6267) Co-authored-by: Jamie Bertram <jamie.bertram@tweag.io> * Fix bug in ./script/combined-haddock.sh (#6263) * Update baseUrl in docusaurus.config.ts (#6275) * Improvements to haddock-site.yml (support auto-publish on push to master) (#6276) * Better messages in slack-message-broker.yml (#6280) * Remove --ignore-url's from linkchecker step in combined-haddock.sh (#6281) * Add cabal update step in combined-haddock.sh (#6283) * Fix CsvTable.tsx and LiteralInclde.tsx in docusaurus (#6282) * Fix haddock documentation for cardano-constitution (#6284) * Stronger docusaurus builds and general QOL improvements (#6287) * Move package-lock.json from top-level to scripts/blueprints (#6289) * Fix editUrl in docusaurus.config.ts (#6291) * chore(deps): bump JamesIves/github-pages-deploy-action (#6292) Bumps [JamesIves/github-pages-deploy-action](https://github.com/jamesives/github-pages-deploy-action) from 4.6.1 to 4.6.3. - [Release notes](https://github.com/jamesives/github-pages-deploy-action/releases) - [Commits](JamesIves/github-pages-deploy-action@v4.6.1...v4.6.3) --- updated-dependencies: - dependency-name: JamesIves/github-pages-deploy-action dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Fix typos (#6288) * fix typo * fix typos * fix typo * fix typo * Detect broken links for haddock,metatheory,docusaurus + local repo files (#6294) * Fix broken linkchecker workflows (#6295) * Add .github/linkchecker/action.yml * Add support for ghc910 to hydraJobs (#6293) * Disable linkchecker on live sites (#6298) * [Bug] Fix 'isNormalType' and add 'prop_normalizedTypeIsNormal' (#6272) * Analyse script events supports PlutusLedgerLanguage V3 (#6300) * fix: parameter 33 should be a Rational (#6302) * Address guardrail script audit comments (#6305) * All names are printed with their unique values by default. (#5972) * chore: explicit imports * Test demonstrates that without printed unique value a name won't roundtrip printing/parsing * Pretty-printing with indexes by default, simple representation by opt-in. * Updated golden files * fix: types in defaultConstitution (#6307) More descriptive type names in the defaultConstitution Co-authored-by: Nikolaos Bezirgiannis <329939+bezirg@users.noreply.github.com> * Fix overflow bug in shiftByteString, rotateByteString, add tests to ensure it stays fixed (#6309) * Fix overflow bug in shiftByteString, add tests to ensure it stays fixed * Fix similar issue in rotations * Add shift wrapper for bounds checks * Fix rotations similarly, note in docs * Fix typo, note about fromIntegral * Release 1.31.0.0 (#6312) * Re-export bitwise builtins from PlutusTx.Prelude (#6313) * [Costing] Increase the cost of constructors of '[]' (#6285) * Change writeBits to take changelists as two separate lists (#6317) * fix: types in defaultConstitution (#6307) More descriptive type names in the defaultConstitution Co-authored-by: Nikolaos Bezirgiannis <329939+bezirg@users.noreply.github.com> * Fix overflow bug in shiftByteString, rotateByteString, add tests to ensure it stays fixed (#6309) * Fix overflow bug in shiftByteString, add tests to ensure it stays fixed * Fix similar issue in rotations * Add shift wrapper for bounds checks * Fix rotations similarly, note in docs * Fix typo, note about fromIntegral * Release 1.31.0.0 (#6312) * Modify writeBits to use two lists as arguments * Fix writeBits in PlutusTx to match new API * Fix goldens --------- Co-authored-by: Romain Soulat <117812549+RSoulatIOHK@users.noreply.github.com> Co-authored-by: Nikolaos Bezirgiannis <329939+bezirg@users.noreply.github.com> Co-authored-by: Yura Lazarev <1009751+Unisay@users.noreply.github.com> * [Costing] Remove the 'ExMemoryUsage' instance for 'SomeTypeIn' (#6318) * feat: New version of VT-CC-01 (#6320) Signed Changed the defaultConstitution.json (+ random fixes in some $comment) Changed the tests values Changed the traceability documents and updated the versioning New golden test values "All 654 tests passed (99.02s)" * [Test] Make tests take reasonable time (#6286) This dramatically reduces the number of tests run locally making evaluation times of plutus-test drop by more than 10x. The reduced number of tests run locally is balanced by running the old amount of tests in the nightly test suite. * fix: haddock error (#6323) * Reverse hunk test_multiSplitSound (#6324) Co-authored-by: Nikolaos Bezirgiannis <bezirg@users.noreply.github.com> * Kwxm/costing/bitwise 4 (#6301) * Costing for new bitwise builtins * Fix alignment problem * Add changelog entry * Update some CIP URLs * Update some CIP URLs * Remove outdated comment * Address some review comments * Address some review comments * Fix for changes in main branch * Update costing for revised version of writeBits * Fix benchmark tests for integer division builtins * Fix comments * Update benchmark results for writeBits split updates * Try removing zip in writeBits * Remove wrapper * Rearrange code again * Tidying up * Fix plutus-tx * Make some helpers INLINEABLE * Rearrange code again * Simplify known type instances for 'ListCostedByLength' --------- Co-authored-by: effectfully <effectfully@gmail.com> * 8-queens using bitwise primops benchmark (#6311) * Milestone 3 benchmark, test * Fix cabal file * Update writeBits use in NQueens * [Plinth] [Builtins] Fix 'writeBits' (#6329) * [Plinth] Ban using 'toBuiltin' and 'fromBuiltin' (#6342) It used to be possible to use `toBuiltin`/`fromBuiltin` within a smart contract, but this is no longer the case, but this isn't obvious to the users as they already have code with `toBuiltin`/`fromBuiltin` that now just misbehaves instead of throwing a type error or breaking compilation some other way. This fixes the problem by throwing on any usage of `toBuiltin`/`fromBuiltin` with a suggestion to use `toOpaque`/`fromOpaque` instead. * Kwxm/bitwise/enable nqueens benchmark (#6343) This enables the bitwise `nqueens` benchmark following the fix for `writeBits` in Plinth in #6309. ``` $ cabal bench bitwise-bench Build profile: -w ghc-9.6.6 -O1 In order, the following will be built (use -v for more details): - plutus-benchmark-0.1.0.0 (bench:bitwise-bench) (first run) Preprocessing benchmark 'bitwise-bench' for plutus-benchmark-0.1.0.0... Building benchmark 'bitwise-bench' for plutus-benchmark-0.1.0.0... Running 1 benchmarks... Benchmark bitwise-bench: RUNNING... benchmarking 8-queens time 683.4 ms (681.5 ms .. 685.0 ms) 1.000 R² (1.000 R² .. 1.000 R²) mean 678.6 ms (674.1 ms .. 680.4 ms) std dev 3.211 ms (92.63 μs .. 3.978 ms) variance introduced by outliers: 19% (moderately inflated) Benchmark bitwise-bench: FINISH ``` * [plc] Support for `Natural` numbers in the default universe, backed by `Integer`. (#6346) Co-authored-by: Nikolaos Bezirgiannis <bezirg@users.noreply.github.com> * nothunks ^>= 0.2 (#6349) * Make NumBytesCostedAsNumWords use Integer instead of Int (#6350) The `NumBytesCostedAsNumWords` wrapper contained an `Int`, but this changes it to `Integer` for consistency with the other wrappers. This change also affects the type of `Bitwise.replicateByte`. * [Benchmark] Reduce the number of benchmarks (#6328) * [Test] Improve distribution of generated integers (#6315) This improves distribution of generated integers, so that we more often hit important edge cases such as `2 ^ 16`, `2 ^ 32 - 1`, `2 ^ 32`, `2 ^ 64` etc. * [Plinth] [Builtins] Add a general 'mkNil' (#6347) This replaces the `mkNilInteger`, `mkNilData` etc boilerplate with a single `mkNil` function at the expense of moving the boilerplate to the compiler code. * [Refactoring] Use 'KnownBuiltinTypeIn' instead of 'HasConstant' consistently (#6353) * Restore auto generation of compiler option table (#6373) * Add the bitwise builtins to the metatheory (#6368) * Initial metatheory for rest of bitwise builtins * Separate lists of expected failures for evaluation tests and budget tests * Remove temporary test data * Fix memory usage for lists in Agda * Forgot about haskell-steppable-conformance * Remove suprious s * Restore CI checks for doc site code (#6376) * andByteString conformance cases (#6356) * andByteString conformance cases * Move each case to its own directory * Update goldens for merge * Conformance cases for complementByteString (#6359) * Conformance for orByteString (#6357) * Conformance cases for readBit (#6360) * Conformance for shiftByteString (#6363) * Conformance for findFirstSetBit (#6366) * Conformance for xorByteString (#6358) * Conformance for countSetBits (#6365) --------- Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Yura Lazarev <Unisay@users.noreply.github.com> Co-authored-by: Ana Pantilie <45069775+ana-pantilie@users.noreply.github.com> Co-authored-by: Nikolaos Bezirgiannis <329939+bezirg@users.noreply.github.com> Co-authored-by: Nikolaos Bezirgiannis <bezirg@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Kenneth MacKenzie <kwxm@inf.ed.ac.uk> Co-authored-by: Ziyang Liu <unsafeFixIO@gmail.com> Co-authored-by: effectfully <effectfully@gmail.com> Co-authored-by: Yura Lazarev <1009751+Unisay@users.noreply.github.com> Co-authored-by: zeme-wana <15709674+zeme-wana@users.noreply.github.com> Co-authored-by: Yura Lazaryev <Yuriy.Lazaryev@iohk.io> Co-authored-by: Joseph Fajen <104791413+joseph-fajen@users.noreply.github.com> Co-authored-by: ianhanssoniohk <ian.hansson@iohk.io> Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Co-authored-by: Koz Ross <koz.ross@retro-freedom.nz> Co-authored-by: Samuel Leathers <samuel.leathers@iohk.io> Co-authored-by: Vladimir Kalnitsky <klntsky@gmail.com> Co-authored-by: Erik de Castro Lopo <erikd@mega-nerd.com> Co-authored-by: zeme <lorenzo.calegari@iohk.io> Co-authored-by: Jamie Bertram <jamie.bertram@tweag.io> Co-authored-by: omahs <73983677+omahs@users.noreply.github.com> Co-authored-by: Romain Soulat <117812549+RSoulatIOHK@users.noreply.github.com>
effectfully
pushed a commit
that referenced
this pull request
Aug 6, 2024
Signed-off-by: Ana Pantilie <ana.pantilie95@gmail.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #6094
Done in this PR:
Valuetype in the ledger APIValuetest suite for the new data-backedValueThe next PR in this series will provide access to a version of the ledger API with the data-backed
Value.How to interpret performance results:
eqwas optimised in this PRgeq/gt/... were not, my experiments failed so I think I should focus on this another time; added it to Data map tech debt #6142Pre-submit checklist: