Lorentz.StoreClass

This module provides storage interfaces.

Class

class StoreHasField store fname ftype | store fname -> ftype where

Provides operations on fields for storage.

Methods

storeFieldOps :: StoreFieldOps store fname ftype

Instances

HasUField fname ftype templ => StoreHasField (UStore templ) fname ftype

Defined in Lorentz.UStore.Instances

Methods

storeFieldOps :: StoreFieldOps (UStore templ) fname ftype

data StoreFieldOps store fname ftype

Datatype containing the full implementation of StoreHasField typeclass.

We use this grouping because in most cases the implementation will be chosen among the default ones, and initializing all methods at once is simpler and more consistent. (One can say that we are trying to emulate the DerivingVia extension.)

Constructors

StoreFieldOps

Fields

• sopToField :: forall s. Label fname -> (store ': s) :-> (ftype ': s)
• sopSetField :: forall s. Label fname -> (ftype ': (store ': s)) :-> (store ': s)

class StoreHasSubmap store mname key value | store mname -> key value where

Provides operations on submaps of storage.

Methods

storeSubmapOps :: StoreSubmapOps store mname key value

Instances

HasUStore mname key value templ => StoreHasSubmap (UStore templ) mname key value

Defined in Lorentz.UStore.Instances

Methods

storeSubmapOps :: StoreSubmapOps (UStore templ) mname key value

(key ~ key', value ~ value', NiceComparable key) => StoreHasSubmap (Map key' value') name key value

Map can be used as standalone key-value storage if very needed.

Defined in Lorentz.StoreClass

Methods

storeSubmapOps :: StoreSubmapOps (Map key' value') name key value

(key ~ key', value ~ value', NiceComparable key) => StoreHasSubmap (BigMap key' value') name key value

BigMap can be used as standalone key-value storage, name of submap is not accounted in this case.

Defined in Lorentz.StoreClass

Methods

storeSubmapOps :: StoreSubmapOps (BigMap key' value') name key value

data StoreSubmapOps store mname key value

Datatype containing the full implementation of StoreHasSubmap typeclass.

We use this grouping because in most cases the implementation will be chosen among the default ones, and initializing all methods at once is simpler and more consistent. (One can say that we are trying to emulate the DerivingVia extension.)

Constructors

StoreSubmapOps

Fields

• sopMem :: forall s. Label mname -> (key ': (store ': s)) :-> (Bool ': s)
• sopGet :: forall s. KnownValue value => Label mname -> (key ': (store ': s)) :-> (Maybe value ': s)
• sopUpdate :: forall s. Label mname -> (key ': (Maybe value ': (store ': s))) :-> (store ': s)
• sopDelete :: forall s. Maybe (Label mname -> (key ': (store ': s)) :-> (store ': s))
• sopInsert :: forall s. Maybe (Label mname -> (key ': (value ': (store ': s))) :-> (store ': s))

class StoreHasEntrypoint store epName epParam epStore | store epName -> epParam epStore where

Provides operations on stored entrypoints.

store is the storage containing both the entrypoint epName (note: it has to be in a BigMap to take advantage of lazy evaluation) and the epStore field this operates on.

Methods

storeEpOps :: StoreEntrypointOps store epName epParam epStore

data StoreEntrypointOps store epName epParam epStore

Datatype containing the full implementation of StoreHasEntrypoint typeclass.

We use this grouping because in most cases the implementation will be chosen among the default ones, and initializing all methods at once is simpler and more consistent. (One can say that we are trying to emulate the DerivingVia extension.)

Constructors

StoreEntrypointOps

Fields

• sopToEpLambda :: forall s. Label epName -> (store ': s) :-> (EntrypointLambda epParam epStore ': s)
• sopSetEpLambda :: forall s. Label epName -> (EntrypointLambda epParam epStore ': (store ': s)) :-> (store ': s)
• sopToEpStore :: forall s. Label epName -> (store ': s) :-> (epStore ': s)
• sopSetEpStore :: forall s. Label epName -> (epStore ': (store ': s)) :-> (store ': s)

Useful type synonyms

type EntrypointLambda param store = Lambda (param, store) ([Operation], store)

Type synonym for a Lambda that can be used as an entrypoint

type EntrypointsField param store = BigMap MText (EntrypointLambda param store)

Type synonym of a BigMap mapping MText (entrypoint names) to EntrypointLambda.

This is useful when defining instances of StoreHasEntrypoint as a storage field containing one or more entrypoints (lambdas) of the same type.

Expressing constraints on storage

data k ~> v infix 9

Indicates a submap with given key and value types.

data param ::-> store infix 9

Indicates a stored entrypoint with the given param and store types.

type family StorageContains store (content :: [NamedField]) :: Constraint where ...

Concise way to write down constraints with expected content of a storage.

Use it like follows:

type StorageConstraint store = StorageContains store
  [ "fieldInt" := Int
  , "fieldNat" := Nat
  , "epsToNat" := Int ::-> Nat
  , "balances" := Address ~> Int
  ]

Equations

StorageContains _ '[] = ()

StorageContains store ((n := (k ~> v)) ': ct) = (StoreHasSubmap store n k v, StorageContains store ct)

StorageContains store ((n := (ep ::-> es)) ': ct) = (StoreHasEntrypoint store n ep es, StorageContains store ct)

StorageContains store ((n := ty) ': ct) = (StoreHasField store n ty, StorageContains store ct)

Methods to work with storage

stToField :: StoreHasField store fname ftype => Label fname -> (store ': s) :-> (ftype ': s)

Pick storage field.

stGetField :: StoreHasField store fname ftype => Label fname -> (store ': s) :-> (ftype ': (store ': s))

Get storage field, preserving the storage itself on stack.

stSetField :: StoreHasField store fname ftype => Label fname -> (ftype ': (store ': s)) :-> (store ': s)

Update storage field.

stMem :: StoreHasSubmap store mname key value => Label mname -> (key ': (store ': s)) :-> (Bool ': s)

Check value presence in storage.

stGet :: (StoreHasSubmap store mname key value, KnownValue value) => Label mname -> (key ': (store ': s)) :-> (Maybe value ': s)

Get value in storage.

stUpdate :: StoreHasSubmap store mname key value => Label mname -> (key ': (Maybe value ': (store ': s))) :-> (store ': s)

Update a value in storage.

stDelete :: forall store mname key value s. (StoreHasSubmap store mname key value, KnownValue value) => Label mname -> (key ': (store ': s)) :-> (store ': s)

Delete a value in storage.

stInsert :: StoreHasSubmap store mname key value => Label mname -> (key ': (value ': (store ': s))) :-> (store ': s)

Add a value in storage.

stInsertNew :: StoreHasSubmap store mname key value => Label mname -> (forall s0 any. (key ': s0) :-> any) -> (key ': (value ': (store ': s))) :-> (store ': s)

Add a value in storage, but fail if it will overwrite some existing entry.

stEntrypoint :: StoreHasEntrypoint store epName epParam epStore => Label epName -> (epParam ': (store ': s)) :-> (([Operation], store) ': s)

Extracts and executes the epName entrypoint lambda from storage, returing the updated full storage (store) and the produced Operations.

stToEpLambda :: StoreHasEntrypoint store epName epParam epStore => Label epName -> (store ': s) :-> (EntrypointLambda epParam epStore ': s)

Pick stored entrypoint lambda.

stGetEpLambda :: StoreHasEntrypoint store epName epParam epStore => Label epName -> (store ': s) :-> (EntrypointLambda epParam epStore ': (store ': s))

Get stored entrypoint lambda, preserving the storage itself on the stack.

stSetEpLambda :: StoreHasEntrypoint store epName epParam epStore => Label epName -> (EntrypointLambda epParam epStore ': (store ': s)) :-> (store ': s)

Stores the entrypoint lambda in the storage. Fails if already set.

stToEpStore :: StoreHasEntrypoint store epName epParam epStore => Label epName -> (store ': s) :-> (epStore ': s)

Pick the sub-storage that the entrypoint operates on.

stGetEpStore :: StoreHasEntrypoint store epName epParam epStore => Label epName -> (store ': s) :-> (epStore ': (store ': s))

Get the sub-storage that the entrypoint operates on, preserving the storage itself on the stack.

stSetEpStore :: StoreHasEntrypoint store epName epParam epStore => Label epName -> (epStore ': (store ': s)) :-> (store ': s)

Update the sub-storage that the entrypoint operates on.

Implementations

storeFieldOpsADT :: HasFieldOfType dt fname ftype => StoreFieldOps dt fname ftype

Implementation of StoreHasField for case of datatype keeping a pack of fields.

storeEntrypointOpsADT :: (HasFieldOfType store epmName (EntrypointsField epParam epStore), HasFieldOfType store epsName epStore, KnownValue epParam, KnownValue epStore) => Label epmName -> Label epsName -> StoreEntrypointOps store epName epParam epStore

Implementation of StoreHasEntrypoint for a datatype keeping a pack of fields, among which one has contains the entrypoint and another is what such entrypoint operates on.

storeEntrypointOpsFields :: (StoreHasField store epmName (EntrypointsField epParam epStore), StoreHasField store epsName epStore, KnownValue epParam, KnownValue epStore) => Label epmName -> Label epsName -> StoreEntrypointOps store epName epParam epStore

Implementation of StoreHasEntrypoint for a datatype that has a StoreHasField for an EntrypointsField that contains the entrypoint and a StoreHasField for the field such entrypoint operates on.

storeEntrypointOpsSubmapField :: (StoreHasSubmap store epmName MText (EntrypointLambda epParam epStore), StoreHasField store epsName epStore, KnownValue epParam, KnownValue epStore) => Label epmName -> Label epsName -> StoreEntrypointOps store epName epParam epStore

Implementation of StoreHasEntrypoint for a datatype that has a StoreHasSubmap that contains the entrypoint and a StoreHasField for the field such entrypoint operates on.

storeFieldOpsDeeper :: (HasFieldOfType storage fieldsPartName fields, StoreHasField fields fname ftype) => Label fieldsPartName -> StoreFieldOps storage fname ftype

Implementation of StoreHasField for a data type which has an instance of StoreHasField inside. For instance, it can be used for top-level storage.

storeSubmapOpsDeeper :: (HasFieldOfType storage bigMapPartName fields, StoreHasSubmap fields mname key value) => Label bigMapPartName -> StoreSubmapOps storage mname key value

Implementation of StoreHasSubmap for a data type which has an instance of StoreHasSubmap inside. For instance, it can be used for top-level storage.

storeEntrypointOpsDeeper :: (HasFieldOfType store nameInStore substore, StoreHasEntrypoint substore epName epParam epStore) => Label nameInStore -> StoreEntrypointOps store epName epParam epStore

Implementation of StoreHasEntrypoint for a data type which has an instance of StoreHasEntrypoint inside. For instance, it can be used for top-level storage.

storeFieldOpsReferTo :: Label name -> StoreFieldOps storage name field -> StoreFieldOps storage desiredName field

Pretend that given StoreFieldOps implementation is made up for field with name desiredName, not its actual name. Logic of the implementation remains the same.

See also storeSubmapOpsReferTo.

storeSubmapOpsReferTo :: Label name -> StoreSubmapOps storage name key value -> StoreSubmapOps storage desiredName key value

Pretend that given StoreSubmapOps implementation is made up for submap with name desiredName, not its actual name. Logic of the implementation remains the same.

Use case: imagine that your code requires access to submap named X, but in your storage that submap is called Y. Then you implement the instance which makes X refer to Y:

instance StoreHasSubmap Store X Key Value where
  storeSubmapOps = storeSubmapOpsReferTo #Y storeSubmapOpsForY

storeEntrypointOpsReferTo :: Label epName -> StoreEntrypointOps store epName epParam epStore -> StoreEntrypointOps store desiredName epParam epStore

Pretend that given StoreEntrypointOps implementation is made up for entrypoint with name desiredName, not its actual name. Logic of the implementation remains the same.

See also storeSubmapOpsReferTo.

composeStoreFieldOps :: Label nameInStore -> StoreFieldOps store nameInStore substore -> StoreFieldOps substore nameInSubstore field -> StoreFieldOps store nameInSubstore field

Chain two implementations of field operations.

Suits for a case when your store does not contain its fields directly rather has a nested structure.

composeStoreSubmapOps :: Label nameInStore -> StoreFieldOps store nameInStore substore -> StoreSubmapOps substore mname key value -> StoreSubmapOps store mname key value

Chain implementations of field and submap operations.

composeStoreEntrypointOps :: Label nameInStore -> StoreFieldOps store nameInStore substore -> StoreEntrypointOps substore epName epParam epStore -> StoreEntrypointOps store epName epParam epStore

Storage generation

mkStoreEp :: Label epName -> EntrypointLambda epParam epStore -> EntrypointsField epParam epStore

Utility to create EntrypointsFields from an entrypoint name (epName) and an EntrypointLambda implementation. Note that you need to merge multiple of these (with <>) if your field contains more than one entrypoint lambda.