License	Apache-2.0
Safe Haskell	None
Language	GHC2021

Singular.Registry.TxBuilder.Update

Description

Builds the oracle update transaction that processes the pending requests for a token: every one, or a chosen non-empty set of them (updateTokenSelected). Consumes the State UTxO and exactly those request UTxOs, applies each operation speculatively through the trie to generate proofs, then outputs a new State UTxO with the updated root and per-request refund outputs; its validity upper bound is the earliest deadline among the requests it folds.

This module is the fold's public orchestration and its compatibility surface: the six exports every caller imports are re-exported unchanged, and the two entry points coordinate the three owners the fold's work is divided into (#267):

Singular.Registry.TxBuilder.Update.Context — the registry context, its queries, the ordered speculative proofs, the state continuation and the validity slot;
Singular.Registry.TxBuilder.Update.Duties — what the fold's requests owe (mints, destinations, custody, returns, signatures);
Singular.Registry.TxBuilder.Update.Build — the evaluation adapter and the one transaction story language program a fold submits.

No algorithm lives here; each decision has exactly one owner above.

Synopsis

updateTokenImpl :: CageConfig -> Session NoWitness IO -> TrieManager IO -> TokenId -> Addr -> IO ConwayTx
updateTokenWithDuties :: CageConfig -> Session NoWitness IO -> TrieManager IO -> TokenId -> Addr -> RegistryContext -> IO ConwayTx
updateTokenWithTrieState :: CageConfig -> Session NoWitness IO -> TrieSnapshot IO -> TokenId -> Addr -> RegistryContext -> IO ConwayTx
updateTokenSelected :: CageConfig -> Session NoWitness IO -> TrieSnapshot IO -> TokenId -> Addr -> RegistryContext -> NonEmpty TxIn -> IO ConwayTx
emptyRegistryContext :: RegistryContext
data RegistryDuties = RegistryDuties {
- rdMints :: [ConnectedMint]
- rdOutputs :: [TxOut ConwayEra]
- rdSpends :: [ConnectedSpend]
- rdSigners :: [KeyHash 'Guard]
- rdInputs :: [(TxIn, TxOut ConwayEra)]
}
data RegistryContext = RegistryContext {
- rcWitnessScripts :: Map Integer (Script ConwayEra)
- rcCageScript :: Maybe (Script ConwayEra)
- rcCageUtxos :: [(TxIn, TxOut ConwayEra)]
- rcAllowInadmissible :: Bool
- rcHolderUtxos :: [(TxIn, TxOut ConwayEra)]
- rcHolderReleases :: Map TxIn HolderRelease
- rcRefUtxos :: [(TxIn, TxOut ConwayEra)]
}
data HolderRelease = HolderRelease {
- hrRedeemer :: Data
- hrScript :: Script ConwayEra
- hrRecipient :: ByteString
- hrReleased :: Integer
}
registryDuties :: CageConfig -> PParams ConwayEra -> OnChainTokenState -> RegistryContext -> [(TxIn, TxOut ConwayEra)] -> [Bool] -> Either String RegistryDuties
data NoCtx (a :: k)
mkEvalTx :: Session NoWitness IO -> ConwayTx -> IO (Map (ConwayPlutusPurpose AsIx ConwayEra) (Either String ExUnits))

Documentation

updateTokenImpl :: CageConfig -> Session NoWitness IO -> TrieManager IO -> TokenId -> Addr -> IO ConwayTx Source #

Build an update-token transaction (fair fee).

updateTokenWithDuties :: CageConfig -> Session NoWitness IO -> TrieManager IO -> TokenId -> Addr -> RegistryContext -> IO ConwayTx Source #

Fold the pending requests, discharging every obligation the edges they take create (#157 mint-matches-edge-deltas, token-destinations-and-refunds, T1-T6).

updateTokenWithTrieState :: CageConfig -> Session NoWitness IO -> TrieSnapshot IO -> TokenId -> Addr -> RegistryContext -> IO ConwayTx Source #

The current command path obtains its consumed proof bytes and new root from the selected capability snapshot. Transaction duties and provider reads remain in the same shared builder as the retained lower-level adapters.

updateTokenSelected :: CageConfig -> Session NoWitness IO -> TrieSnapshot IO -> TokenId -> Addr -> RegistryContext -> NonEmpty TxIn -> IO ConwayTx Source #

Fold the chosen pending requests and no other, from the selected capability snapshot; the validity upper bound is the earliest deadline among them.

emptyRegistryContext :: RegistryContext Source #

The context a fold of tree edges needs beyond the registry's own configuration: the three token policies' scripts and the cage script that custody spends run. A delivered output's datum is the one its request carries.

emptyRegistryContext carries none of it, which is right for a caller that folds only rejections — and refuses loudly, naming the missing script, for one that folds an edge without it.

data RegistryDuties Source #

Everything an edge owes a fold beyond the trie: what must move under the active token policy, where a registration lands, and which holder a retirement consumes.

The cage computes these from the requests it consumes (dutiesOf, dutyOk); this recomputes them from the same requests so a fold can be built that discharges them. The two are deliberately separate derivations — a builder that agrees with the validator by construction would not catch a disagreement.

Constructors

RegistryDuties

Fields

rdMints :: [ConnectedMint]
rdOutputs :: [TxOut ConwayEra]
rdSpends :: [ConnectedSpend]
rdSigners :: [KeyHash 'Guard]
rdInputs :: [(TxIn, TxOut ConwayEra)]
#177 I177-BUILDER: ordinary (non-script) inputs the edge needs the transaction to consume. A retirement of an active key burns an asset it does not create, so the holder UTxO carrying that asset has to ride in as an input; a mint of `-1` with nothing to burn is a transaction whose only possible outcome is a refusal.

Instances

Instances details

Monoid RegistryDuties Source #
Instance details Defined in Singular.Registry.TxBuilder.Update.Duties Methods mempty :: RegistryDuties Source # mappend :: RegistryDuties -> RegistryDuties -> RegistryDuties Source # mconcat :: [RegistryDuties] -> RegistryDuties Source #
Semigroup RegistryDuties Source #
Instance details Defined in Singular.Registry.TxBuilder.Update.Duties Methods (<>) :: RegistryDuties -> RegistryDuties -> RegistryDuties Source # sconcat :: NonEmpty RegistryDuties -> RegistryDuties Source # stimes :: Integral b => b -> RegistryDuties -> RegistryDuties Source #

data RegistryContext Source #

What a fold needs in hand to discharge the obligations: the three token policies' scripts by kind, the cage script (custody spends run it), and the UTxOs sitting at the cage address (custody lives among them). A delivered output's datum is the one its request carries (#419), so nothing beyond the chain is in hand.

Constructors

RegistryContext

Fields

rcWitnessScripts :: Map Integer (Script ConwayEra)
rcCageScript :: Maybe (Script ConwayEra)
rcCageUtxos :: [(TxIn, TxOut ConwayEra)]
rcAllowInadmissible :: Bool
Build a fold even when a request takes no admissible edge, so a row that exists to watch the chain REFUSE one can produce the transaction it submits. An honest builder leaves this off and fails early, naming the request.
rcHolderUtxos :: [(TxIn, TxOut ConwayEra)]
#177 I177-BUILDER: the candidate inputs a burn may be sourced from — the outputs that actually HOLD registry witnesses. A retirement or an active deletion destroys an asset it does not create, so the fold has to consume the holder's own UTxO; with nothing in this inventory the builder fails naming the key rather than emitting a mint the cage refuses `token-missing`. Left empty, the builder queries the fold's own wallet address.
rcHolderReleases :: Map TxIn HolderRelease
#299: holders that sit at an application script rather than a key. A burn sourced from one of them spends it with the application's own witness instead of as a plain input, and the application's release is owed to its recipient together with every other obligation of the fold to that key. Empty for key-held witnesses.
rcRefUtxos :: [(TxIn, TxOut ConwayEra)]
Outputs carrying the fold's scripts as reference scripts. The state validator alone is fifteen kilobytes, so a fold that attaches it, the request script and a token policy does not fit in a transaction; with references every purpose resolves through them instead.

data HolderRelease Source #

How an application-held burn source is spent, and what its spend releases (#299): the redeemer and script that witness the spend, and the lovelace owed to the recipient's key because the holder is released.

Constructors

HolderRelease
Fields hrRedeemer :: Data hrScript :: Script ConwayEra hrRecipient :: ByteString The payment key hash the release is owed to hrReleased :: Integer Lovelace owed to it, over every other obligation to that key

Instances

Instances details

Show HolderRelease Source #
Instance details Defined in Singular.Registry.TxBuilder.Update.Context Methods showsPrec :: Int -> HolderRelease -> ShowS Source # show :: HolderRelease -> String Source # showList :: [HolderRelease] -> ShowS Source #
Eq HolderRelease Source #
Instance details Defined in Singular.Registry.TxBuilder.Update.Context Methods (==) :: HolderRelease -> HolderRelease -> Bool Source # (/=) :: HolderRelease -> HolderRelease -> Bool Source #

registryDuties Source #

Arguments

:: CageConfig
-> PParams ConwayEra
-> OnChainTokenState
-> RegistryContext
-> [(TxIn, TxOut ConwayEra)]
-> [Bool]	Whether each request is PROCESSED by this fold. A rejected request takes no edge: it owes its owner a refund, and the approval that certified it was never spent.
-> Either String RegistryDuties

The obligations this set of requests creates, or the reason they cannot be met. A fold whose duties cannot be built is a fold that would be refused on chain; failing here names why, in the builder, where it is cheap.

data NoCtx (a :: k) Source #

Empty query generalized algebraic data type (no context needed).

mkEvalTx :: Session NoWitness IO -> ConwayTx -> IO (Map (ConwayPlutusPurpose AsIx ConwayEra) (Either String ExUnits)) Source #

Wrap the view's script evaluation for the story language.