cooked-node-backend

.gitignore

@@ -9,3 +9,4 @@ dist-newstyle
 *.swp
 docs/
 .pre-commit-config.yaml
+.github/copilot-instructions.md

CHANGELOG.md

@@ -4,8 +4,44 @@
 
 ### Added
 
+- New `txSkelOptProceedAfterValidationFailures` boolean option in `TxSkelOpts`
+  (with its `txSkelOptProceedAfterValidationFailuresL` optic). When set to
+  `True`, transaction validation failures no longer abort the mockchain run.
+  Default is `False`.
+- New `UserScriptHash` constructor for `User`, representing an allocation-mode
+  script owner known only by its `Api.ScriptHash` (no script body). It can be
+  used to pay to a bare script hash through `receives` (a new
+  `IsTxSkelOutAllowedOwner Api.ScriptHash` instance). Spending an output owned by
+  such a user requires providing the full script through a matching reference
+  input; otherwise a new `MCESpendingHashOnlyScript` error is raised. The
+  `userVScriptL` optic is now restricted to `User IsScript Redemption`, since an
+  allocation-mode script owner may no longer carry a script body.
+- New `SomeTxSkelOutDatumHash` constructor for `TxSkelOutDatum`, representing an
+  output datum known only by its hash (no datum content). It is mirrored by a
+  new `UtxoPayloadDatumHash` constructor in the resulting `UtxoState`, and a new
+  `MCESpendingHashOnlyDatum` error is raised when attempting to build the
+  spending witness of a script output whose datum is only a hash.
+
 ### Changed
 
+- Time-related primitives have been regrouped into a new dedicated
+  `Cooked.MockChain.Effect.Time.MockChainTime` effect. The time queries
+  (`currentSlot`, `currentMSRange`, `getEnclosingSlot`, `slotToMSRange`,
+  `slotRangeBefore`, `slotRangeAfter`) that used to live in `MockChainReadChain`
+  and the waiting primitives (`waitNSlots`, `awaitSlot`, `awaitEnclosingSlot`,
+  `waitNMSFromSlotLowerBound`, `waitNMSFromSlotUpperBound`) that used to live in
+  `MockChainWrite` are now all provided by `MockChainTime`, with `waitNSlots` as
+  its sole state-modifying primitive.
+- The former `MockChainState` has been split into two independent records, each
+  backed by its own state monad: `EmulatorState` (the emulator `Params` and
+  `EmulatedLedgerState`, only relevant when running against the emulated ledger)
+  and `ChainIndex` (the map of known outputs and the constitution script, which
+  is backend-agnostic and also meaningful for the node backend). Accordingly,
+  `mcstToUtxoState` is now `chainIndexToUtxoState`, the `mcst*L` optics are
+  replaced by `emulatorState*L`/`chainIndex*L`, `MockChainConf` now carries
+  `mccInitialEmulatorState` and `mccInitialChainIndex`, and
+  `RunnableMockChain.runMockChain` takes an `EmulatorState` and a `ChainIndex`.
+
 ### Removed
 
 ### Fixed

CONTRIBUTING.md

@@ -164,6 +164,52 @@ When you are creating an enhancement request, follow these guidelines:
 
 - Document all your functions using [Haddock]'s syntax.
 
+### Module organization (umbrella modules)
+
+Cohesive-but-multi-concern parts of the library are split into focused,
+per-concern submodules that live in a directory, and re-exported from an
+_umbrella module_ bearing the name of that directory (e.g. `Cooked.Tweak`
+re-exports `Cooked.Tweak.Guard`, `Cooked.Tweak.Insert`, ...). Follow these
+conventions when adding or reorganizing modules:
+
+- **One umbrella per directory.** When a directory groups several submodules
+  that form a coherent sub-system, add an umbrella module of the same name that
+  re-exports them all, typically as:
+
+  ```haskell
+  -- | One-line description of the sub-system.
+  module Cooked.Foo (module X) where
+
+  import Cooked.Foo.Bar as X
+  import Cooked.Foo.Baz as X
+  ```
+
+- **Re-export instance-only submodules with `()`.** When a submodule only
+  provides instances (empty export list), import it in the umbrella as
+  `import Cooked.Foo.Bar ()` so its instances are brought in without polluting
+  the export list. If _all_ submodules are instance-only, the umbrella itself
+  has an empty export list (`module Cooked.Foo () where`).
+
+- **Umbrellas are aggregators first.** An umbrella may additionally host the
+  central type or entry point of its sub-system (as `Cooked.Skeleton` hosts
+  `TxSkel` and `Cooked.Automation` hosts `runAutomationPipeline`), but should
+  not accumulate unrelated logic. Everything else belongs in a submodule.
+
+- **Do not systematically nest umbrellas.** A sub-directory whose submodules are
+  a mere refinement of their parent sub-system may be flattened into the parent
+  umbrella rather than getting its own (e.g. `Cooked.Automation.GenerateTx.*`
+  and `Cooked.Effect.Read.*` are re-exported directly from `Cooked.Automation`
+  and `Cooked.Effect`). Add an intermediate umbrella only when the sub-directory
+  is itself an independently meaningful sub-system.
+
+- **Transverse utilities** (type aliases, wallets, low-level helpers) live under
+  `Cooked.Utilities.*` and are re-exported from `Cooked.Utilities`, keeping the
+  top level of `Cooked.*` for the functional pillars of the library.
+
+- The top-level `Cooked` module is the global umbrella: it re-exports the
+  per-directory umbrellas only, never individual submodules. Adding a new
+  sub-system therefore means adding a single import line there.
+
 ### Nix style guide
 
 - All Nix code is formatted with [nixfmt].

README.md

@@ -146,7 +146,7 @@ handling fees or balancing.
 6. Submit the transaction:
    ``` haskell
      validateTxSkel_
-       txSkelTemplate
+       txSkelEmulatorTemplate
          { txSkelOuts = [bob `receives` Value (Script.ada 10)],
            txSkelSignatories = txSkelSignatoriesFromList [wallet 1]
          }

cooked-validators.cabal

@@ -21,47 +21,55 @@ library
       Cooked.Attack.RedeemerTampering
       Cooked.Attack.TokenDuplication
       Cooked.Attack.ValidityTampering
-      Cooked.Families
-      Cooked.Ltl
+      Cooked.Automation
+      Cooked.Automation.AutoFilling.Constitution
+      Cooked.Automation.AutoFilling.MinAda
+      Cooked.Automation.AutoFilling.ReferenceScripts
+      Cooked.Automation.AutoFilling.Withdrawals
+      Cooked.Automation.Balancing
+      Cooked.Automation.GenerateTx.Anchor
+      Cooked.Automation.GenerateTx.Body
+      Cooked.Automation.GenerateTx.Certificate
+      Cooked.Automation.GenerateTx.Collateral
+      Cooked.Automation.GenerateTx.Credential
+      Cooked.Automation.GenerateTx.Input
+      Cooked.Automation.GenerateTx.Mint
+      Cooked.Automation.GenerateTx.Output
+      Cooked.Automation.GenerateTx.Proposal
+      Cooked.Automation.GenerateTx.ReferenceInputs
+      Cooked.Automation.GenerateTx.Withdrawals
+      Cooked.Automation.GenerateTx.Witness
+      Cooked.BlockChain
+      Cooked.BlockChain.Config
+      Cooked.BlockChain.Instances
+      Cooked.BlockChain.Run
+      Cooked.Effect
+      Cooked.Effect.Log
+      Cooked.Effect.Misc
+      Cooked.Effect.Override
+      Cooked.Effect.Params
+      Cooked.Effect.Query
+      Cooked.Effect.Submission
+      Cooked.Effect.Time
+      Cooked.Effect.Validation
       Cooked.MockChain
-      Cooked.MockChain.Automation.AutoFilling.Constitution
-      Cooked.MockChain.Automation.AutoFilling.MinAda
-      Cooked.MockChain.Automation.AutoFilling.ReferenceScripts
-      Cooked.MockChain.Automation.AutoFilling.Withdrawals
-      Cooked.MockChain.Automation.Balancing
-      Cooked.MockChain.Automation.GenerateTx.Anchor
-      Cooked.MockChain.Automation.GenerateTx.Body
-      Cooked.MockChain.Automation.GenerateTx.Certificate
-      Cooked.MockChain.Automation.GenerateTx.Collateral
-      Cooked.MockChain.Automation.GenerateTx.Credential
-      Cooked.MockChain.Automation.GenerateTx.Input
-      Cooked.MockChain.Automation.GenerateTx.Mint
-      Cooked.MockChain.Automation.GenerateTx.Output
-      Cooked.MockChain.Automation.GenerateTx.Proposal
-      Cooked.MockChain.Automation.GenerateTx.ReferenceInputs
-      Cooked.MockChain.Automation.GenerateTx.Withdrawals
-      Cooked.MockChain.Automation.GenerateTx.Witness
-      Cooked.MockChain.Common
-      Cooked.MockChain.Effect.Log
-      Cooked.MockChain.Effect.Misc
-      Cooked.MockChain.Effect.Read
-      Cooked.MockChain.Effect.Write
-      Cooked.MockChain.Run.Instances
-      Cooked.MockChain.Run.Runnable
-      Cooked.MockChain.Run.Tweak
-      Cooked.MockChain.Runtime.Error
-      Cooked.MockChain.Runtime.Journal
-      Cooked.MockChain.Runtime.State
+      Cooked.MockChain.Config
+      Cooked.MockChain.Instances
+      Cooked.MockChain.Ltl
+      Cooked.MockChain.Run
       Cooked.MockChain.Testing
-      Cooked.MockChain.UtxoSearch
+      Cooked.MockChain.Tweak
       Cooked.Pretty
       Cooked.Pretty.Class
       Cooked.Pretty.Hashable
       Cooked.Pretty.MockChain
       Cooked.Pretty.Options
       Cooked.Pretty.Plutus
       Cooked.Pretty.Skeleton
-      Cooked.ShowBS
+      Cooked.Runtime
+      Cooked.Runtime.Error
+      Cooked.Runtime.Journal
+      Cooked.Runtime.State
       Cooked.Skeleton
       Cooked.Skeleton.Anchor
       Cooked.Skeleton.Certificate
@@ -85,7 +93,11 @@ library
       Cooked.Tweak.Query
       Cooked.Tweak.Remove
       Cooked.Tweak.Update
-      Cooked.Wallet
+      Cooked.Utilities
+      Cooked.Utilities.Aliases
+      Cooked.Utilities.Families
+      Cooked.Utilities.ShowBS
+      Cooked.Utilities.Wallet
   other-modules:
       Paths_cooked_validators
   autogen-modules:
@@ -127,15 +139,18 @@ library
     , bytestring
     , cardano-api
     , cardano-crypto
+    , cardano-ledger-alonzo
     , cardano-ledger-conway
     , cardano-ledger-core
     , cardano-ledger-shelley
     , cardano-node-emulator
+    , cardano-slotting
     , cardano-strict-containers
     , containers
     , data-default
     , either
     , exceptions
+    , extra
     , http-conduit
     , lens
     , microlens
@@ -154,6 +169,8 @@ library
     , tasty-hunit
     , tasty-quickcheck
     , text
+    , time
+    , witherable
   default-language: Haskell2010
 
 test-suite spec

doc/BALANCING.md

@@ -43,14 +43,14 @@ Our balancing function is signed as follows:
 
 ``` haskell
 balanceTxSkel ::
-  (Members '[MockChainRead, MockChainLog, Error MockChainError, Error P.Ledger.ToCardanoError, Fail] effs) =>
+  (Members '[Query, Log, Error ChainError, Error P.Ledger.ToCardanoError, Fail] effs) =>
   TxSkel ->
   Sem effs ExtendedTxSkel
 ```
 
 The library is built on [Polysemy] effects rather than a concrete monad, so the
 balancing capabilities are expressed as the effect constraints
-`Members '[MockChainRead, MockChainLog, Error MockChainError, Error
+`Members '[Query, Log, Error ChainError, Error
 P.Ledger.ToCardanoError, Fail] effs` and the result lives in `Sem effs`.
 
 This function takes a skeleton and returns an `ExtendedTxSkel`, a record bundling
@@ -379,7 +379,7 @@ signature:
 
 ``` haskell
 reachValue ::
-  (Members '[MockChainRead, Error P.Ledger.ToCardanoError] effs) =>
+  (Members '[Query, Error P.Ledger.ToCardanoError] effs) =>
   Utxos ->                -- candidate utxos, type Utxos = [(Api.TxOutRef, TxSkelOut)]
   Api.Value ->            -- the target value to reach
   Integer ->             -- the maximum number of utxos allowed in a subset
@@ -476,7 +476,7 @@ within this interval. The function that performs this computation is
 
 ``` haskell
 computeFeeAndBalance ::
-  (Members '[MockChainRead, Error MockChainError, Error P.Ledger.ToCardanoError, Fail] effs) =>
+  (Members '[Query, Error ChainError, Error P.Ledger.ToCardanoError, Fail] effs) =>
   Peer ->                          -- the balancing user
   Fee ->                           -- lower bound of the search interval
   Fee ->                           -- upper bound of the search interval