License	Apache-2.0
Safe Haskell	None
Language	GHC2021

Singular.Registry.Application

Contents

The pin
The value
The concrete parts
Generic datum bytes, hashes and JSON (no application named)
Deriving from a pin

Description

A registry pins one application policy at boot (#157 genesis-policy-pins). This module carries what the registry needs to know of an application without naming any: a name for receipts and refusals, the executable that folds its terminations, how the policy is fixed, and the decoder and holding rules. Each executable composes its value and hands it to the library.

The pin has four forms: a hash given as input (a registry booted for an application whose script does not depend on the registry identity), a blueprint validator title applied to the registry identity (the state policy then the token name), a blueprint validator title pinned as compiled (the parameterless form the tests use; production registries are always identity-scoped), or read from the state datum of a registry that already exists. applyPin derives the pinned bytes and codes for the first three; the fourth needs the datum, so only resolveRegistry passes it after reading the datum, and configForApplication refuses it by name.

Slice 2: the decoder reads a datum into a holding view (or names why it cannot); the holding rules find this registry's holding of a key among the outputs at the application address (refusing a foreign or duplicate one), release a termination (script, redeemer, recipient and amount), add the application's part to the fold context, and check a request's carried datum before an insertion is folded. The neutral value carries none of them; the application value fills them from the envelope and release.

Synopsis

data ApplicationPin
- = PinByHash ShortByteString
- | PinByScript Text
- | PinAsCompiled Text
- | PinFromState
data Application = Application {
- appName :: Maybe Text
- appExecutable :: Maybe Text
- appPin :: ApplicationPin
- appDecoder :: Maybe Decoder
- appHolding :: Maybe HoldingRules
}
neutralApplication :: Application
hashPinnedApplication :: ShortByteString -> Application
data DecodedHolding = DecodedHolding {
- dhDatumData :: Data
- dhDatumCbor :: ByteString
- dhDatumHash :: ByteString
- dhKey :: ByteString
- dhDeposit :: Integer
- dhController :: ByteString
- dhPayload :: Data
- dhDatumJson :: Value
- dhPayloadJson :: Value
}
newtype Decoder = Decoder {
- runDecoder :: TxOut ConwayEra -> Either Text DecodedHolding
}
data HoldingRules = HoldingRules {
- hrCheckCarried :: OnChainRequest -> Either Text Data
- hrFindHoldings :: CageConfig -> TokenId -> ByteString -> [(TxIn, TxOut ConwayEra)] -> [((TxIn, TxOut ConwayEra), DecodedHolding)]
- hrLiveOutputFor :: CageConfig -> TokenId -> ByteString -> [(TxIn, TxOut ConwayEra)] -> Either Text ((TxIn, TxOut ConwayEra), DecodedHolding)
- hrReleaseOf :: ShortByteString -> (TxIn, TxOut ConwayEra) -> Either Text (TxIn, HolderRelease)
- hrWithApplication :: ShortByteString -> Maybe (TxIn, TxOut ConwayEra) -> [(TxIn, TxOut ConwayEra)] -> RegistryContext -> Either Text RegistryContext
}
datumCbor :: Data -> ByteString
datumHash :: Data -> ByteString
txOutDatum :: TxOut ConwayEra -> Maybe (ByteString, ByteString)
datumToJson :: Data -> Value
datumFromJson :: Value -> Either String Data
applyPin :: ApplicationPin -> ByteString -> NamingCodes -> (ShortByteString, NamingCodes)

The pin

data ApplicationPin Source #

How the registry's application policy is fixed.

Constructors

PinByHash ShortByteString	A 28-byte policy hash given as input
PinByScript Text	The blueprint validator title, applied to the registry identity
PinAsCompiled Text	The blueprint validator title, pinned as compiled: the parameterless form the tests use, never a production registry
PinFromState	Read from the state datum of the registry being attached to

Instances

Instances details

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

The value

data Application Source #

What the registry knows of an application: a name for receipts and refusals, the executable that folds its terminations, how the policy is fixed, and the decoder and holding rules. The neutral value carries none of the last three; a named value carries all of them.

Constructors

Application
Fields appName :: Maybe Text What receipts and refusals call the application; none is neutral appExecutable :: Maybe Text The binary that folds this application's terminations appPin :: ApplicationPin appDecoder :: Maybe Decoder Reads a datum into a holding view; absent on the neutral value appHolding :: Maybe HoldingRules Finds and releases this registry's holding; absent on neutral

Instances

Instances details

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

neutralApplication :: Application Source #

The value singular folds with: no name, no executable, no decoder, no holding rules; the pin is read from the state datum.

hashPinnedApplication :: ShortByteString -> Application Source #

The neutral value with the pin fixed to the given 28-byte policy hash.

The concrete parts

data DecodedHolding Source #

What the registry knows of a holding: the datum it carries and what the application protects in it. The open datum fills this from the envelope (control + payload); a future application fills it from its own datum. The library never names either.

Constructors

DecodedHolding

Fields

dhDatumData :: Data
The full datum, as data
dhDatumCbor :: ByteString
Its CBOR, as the ledger hashes it
dhDatumHash :: ByteString
Its BLAKE2b-256, as requests and journals name it
dhKey :: ByteString
The key the holding belongs to
dhDeposit :: Integer
The protected deposit, in lovelace
dhController :: ByteString
The controller's payment key hash
dhPayload :: Data
The payload the application leaves unread by the registry
dhDatumJson :: Value
The datum as detailed-schema JSON (for receipts)
dhPayloadJson :: Value
The payload as detailed-schema JSON (for receipts)

Instances

Instances details

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

newtype Decoder Source #

How the application reads a datum: into a holding view, or a named reason.

Constructors

Decoder
Fields runDecoder :: TxOut ConwayEra -> Either Text DecodedHolding

Instances

Instances details

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

data HoldingRules Source #

How the application holds keys: what the registry needs to fold without naming the application. Absent on the neutral value; the open datum fills every field from the envelope and release.

Constructors

HoldingRules

Fields

hrCheckCarried :: OnChainRequest -> Either Text Data
The datum an insertion's request must carry to be folded
hrFindHoldings :: CageConfig -> TokenId -> ByteString -> [(TxIn, TxOut ConwayEra)] -> [((TxIn, TxOut ConwayEra), DecodedHolding)]
This registry's holdings of a key among the outputs at the application address (a foreign envelope is not one of them)
hrLiveOutputFor :: CageConfig -> TokenId -> ByteString -> [(TxIn, TxOut ConwayEra)] -> Either Text ((TxIn, TxOut ConwayEra), DecodedHolding)
The key's one live holding, or why there is none (foreign or duplicate)
hrReleaseOf :: ShortByteString -> (TxIn, TxOut ConwayEra) -> Either Text (TxIn, HolderRelease)
How the fold spends one live output: script, redeemer, recipient, amount
hrWithApplication :: ShortByteString -> Maybe (TxIn, TxOut ConwayEra) -> [(TxIn, TxOut ConwayEra)] -> RegistryContext -> Either Text RegistryContext
The fold context with the application's part added

Instances

Instances details

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

Generic datum bytes, hashes and JSON (no application named)

datumCbor :: Data -> ByteString Source #

The CBOR of a datum, by the same builtin a script's serialise_data runs. Generic: the library names no application to name it.

datumHash :: Data -> ByteString Source #

The BLAKE2b-256 of a datum's CBOR: the datum hash a request names. Generic: the same bytes envelopeHash hashes, so an application datum hash equals its envelope hash byte for byte.

txOutDatum :: TxOut ConwayEra -> Maybe (ByteString, ByteString) Source #

An output's inline datum, as bytes and hash, when it carries one.

datumToJson :: Data -> Value Source #

The detailed-schema JSON of a datum, naming no application. Byte-identical to the open datum's dataToJson on the same datum.

datumFromJson :: Value -> Either String Data Source #

A datum from its detailed-schema JSON, or where it is wrong. Byte-identical to the open datum's dataFromJson on the same JSON.

Deriving from a pin

applyPin Source #

Arguments

:: ApplicationPin
-> ByteString	The registry identity: state policy then state token name
-> NamingCodes	The application and witness codes as the blueprint carries them
-> (ShortByteString, NamingCodes)

The pinned policy bytes and the codes as the registry runs them, for a pin that carries its own derivation. PinFromState needs the state datum, which this function is never given, so it is refused by name; resolveRegistry reads the datum first and passes its pin as PinByHash.