Lorentz.UStore

This module contains implementation of UStore.

UStore is essentially Store modified for the sake of upgradeability.

In API it differs from Store in the following ways: 1. It keeps both virtual big_maps and plain fields; 2. Neat conversion between Michelson and Haskell values is implemented; 3. Regarding composabililty, one can operate with one UStore and then lift it to a bigger one which includes the former. This allows for simpler management of stores and clearer error messages. In spite of this, operations with UStores over deeply nested templates will still work as before.

We represent UStore as big_map bytes bytes.

• Plain fields are stored as key = pack fieldName; value = pack originalValue.
• Virtual big_maps are kept as key = pack (bigMapName, originalKey); value = pack originalValue.

UStore and related type definitions

data UStore (a :: Type)

Gathers multple fields and BigMaps under one object.

Type argument of this datatype stands for a "store template" - a datatype with one constructor and multiple fields, each containing an object of type UStoreField or |~> and corresponding to single virtual field or BigMap respectively. It's also possible to parameterize it with a larger type which is a product of types satisfying the above property.

Instances

Eq (UStore a)

Defined in Lorentz.UStore.Types

Methods

(==) :: UStore a -> UStore a -> Bool

(/=) :: UStore a -> UStore a -> Bool

Show (UStore a)

Defined in Lorentz.UStore.Types

Methods

showsPrec :: Int -> UStore a -> ShowS

show :: UStore a -> String

showList :: [UStore a] -> ShowS

Generic (UStore a)

Defined in Lorentz.UStore.Types

Associated Types

type Rep (UStore a) :: Type -> Type

Methods

from :: UStore a -> Rep (UStore a) x

to :: Rep (UStore a) x -> UStore a

Semigroup (UStore a)

Defined in Lorentz.UStore.Types

Methods

(<>) :: UStore a -> UStore a -> UStore a

sconcat :: NonEmpty (UStore a) -> UStore a

stimes :: Integral b => b -> UStore a -> UStore a

Monoid (UStore a)

Defined in Lorentz.UStore.Types

Methods

mempty :: UStore a

mappend :: UStore a -> UStore a -> UStore a

mconcat :: [UStore a] -> UStore a

Default (UStore a)

Defined in Lorentz.UStore.Types

Methods

def :: UStore a

Wrapped (UStore a)

Defined in Lorentz.UStore.Types

Associated Types

type Unwrapped (UStore a)

Methods

_Wrapped' :: Iso' (UStore a) (Unwrapped (UStore a))

UStoreTemplateHasDoc template => TypeHasDoc (UStore template)

Defined in Lorentz.UStore.Doc

Associated Types

type TypeDocFieldDescriptions (UStore template) :: FieldDescriptions

Methods

typeDocName :: Proxy (UStore template) -> Text

typeDocMdDescription :: Markdown

typeDocMdReference :: Proxy (UStore template) -> WithinParens -> Markdown

typeDocDependencies :: Proxy (UStore template) -> [SomeDocDefinitionItem]

typeDocHaskellRep :: TypeDocHaskellRep (UStore template)

typeDocMichelsonRep :: TypeDocMichelsonRep (UStore template)

IsoValue (UStore a)

Defined in Lorentz.UStore.Types

Associated Types

type ToT (UStore a) :: T

Methods

toVal :: UStore a -> Value (ToT (UStore a))

fromVal :: Value (ToT (UStore a)) -> UStore a

GetOpHs (UStore a)

Defined in Lorentz.UStore.Types

Associated Types

type GetOpKeyHs (UStore a)

type GetOpValHs (UStore a)

UpdOpHs (UStore a)

Defined in Lorentz.UStore.Types

Associated Types

type UpdOpKeyHs (UStore a)

type UpdOpParamsHs (UStore a)

MemOpHs (UStore a)

Defined in Lorentz.UStore.Types

Associated Types

type MemOpKeyHs (UStore a)

HasTypeAnn (UStore a)

Defined in Lorentz.UStore.Types

Methods

getTypeAnn :: Notes (ToT (UStore a))

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

Defined in Lorentz.UStore.Instances

Methods

storeFieldOps :: StoreFieldOps (UStore templ) fname ftype

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

Defined in Lorentz.UStore.Instances

Methods

storeSubmapOps :: StoreSubmapOps (UStore templ) mname key value

SameUStoreTemplate template1 template2 => CanCastTo (UStore template1 :: Type) (UStore template2 :: Type)

We allow casting between UStore_ and UStore freely.

Defined in Lorentz.UStore.Migration.Base

Methods

castDummy :: Proxy (UStore template1) -> Proxy (UStore template2) -> ()

type Rep (UStore a)

Defined in Lorentz.UStore.Types

type Rep (UStore a) = D1 ('MetaData "UStore" "Lorentz.UStore.Types" "lorentz-0.4.0-4bB2PLHB7038abCZLw1vnA" 'True) (C1 ('MetaCons "UStore" 'PrefixI 'True) (S1 ('MetaSel ('Just "unUStore") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (BigMap ByteString ByteString))))

type Unwrapped (UStore a)

Defined in Lorentz.UStore.Types

type Unwrapped (UStore a) = GUnwrapped (Rep (UStore a))

type TypeDocFieldDescriptions (UStore template)

Defined in Lorentz.UStore.Doc

type TypeDocFieldDescriptions (UStore template) = '[] :: [(Symbol, (Maybe Symbol, [(Symbol, Symbol)]))]

type ToT (UStore a)

Defined in Lorentz.UStore.Types

type ToT (UStore a) = ToT (BigMap ByteString ByteString)

type GetOpKeyHs (UStore a)

Defined in Lorentz.UStore.Types

type GetOpKeyHs (UStore a) = GetOpKeyHs (BigMap ByteString ByteString)

type GetOpValHs (UStore a)

Defined in Lorentz.UStore.Types

type GetOpValHs (UStore a) = GetOpValHs (BigMap ByteString ByteString)

type UpdOpKeyHs (UStore a)

Defined in Lorentz.UStore.Types

type UpdOpKeyHs (UStore a) = UpdOpKeyHs (BigMap ByteString ByteString)

type UpdOpParamsHs (UStore a)

Defined in Lorentz.UStore.Types

type UpdOpParamsHs (UStore a) = UpdOpParamsHs (BigMap ByteString ByteString)

type MemOpKeyHs (UStore a)

Defined in Lorentz.UStore.Types

type MemOpKeyHs (UStore a) = MemOpKeyHs (BigMap ByteString ByteString)

newtype k |~> v

Describes one virtual big map in the storage.

Constructors

UStoreSubMap

Fields

• unUStoreSubMap :: Map k v

Instances

(Eq k, Eq v) => Eq (k |~> v)

Defined in Lorentz.UStore.Types

Methods

(==) :: (k |~> v) -> (k |~> v) -> Bool

(/=) :: (k |~> v) -> (k |~> v) -> Bool

(Show k, Show v) => Show (k |~> v)

Defined in Lorentz.UStore.Types

Methods

showsPrec :: Int -> (k |~> v) -> ShowS

show :: (k |~> v) -> String

showList :: [k |~> v] -> ShowS

(Ord k, Arbitrary k, Arbitrary v) => Arbitrary (k |~> v)

Defined in Lorentz.UStore.Types

Methods

arbitrary :: Gen (k |~> v)

shrink :: (k |~> v) -> [k |~> v]

Default (k |~> v)

Defined in Lorentz.UStore.Types

Methods

def :: k |~> v

newtype UStoreFieldExt (m :: UStoreMarkerType) (v :: Type)

Describes plain field in the storage.

Constructors

UStoreField

Fields

• unUStoreField :: v

Instances

Eq v => Eq (UStoreFieldExt m v)

Defined in Lorentz.UStore.Types

Methods

(==) :: UStoreFieldExt m v -> UStoreFieldExt m v -> Bool

(/=) :: UStoreFieldExt m v -> UStoreFieldExt m v -> Bool

Show v => Show (UStoreFieldExt m v)

Defined in Lorentz.UStore.Types

Methods

showsPrec :: Int -> UStoreFieldExt m v -> ShowS

show :: UStoreFieldExt m v -> String

showList :: [UStoreFieldExt m v] -> ShowS

Arbitrary v => Arbitrary (UStoreFieldExt m v)

Defined in Lorentz.UStore.Types

Methods

arbitrary :: Gen (UStoreFieldExt m v)

shrink :: UStoreFieldExt m v -> [UStoreFieldExt m v]

type UStoreField = UStoreFieldExt UMarkerPlainField

Just a plain field used as data.

type UStoreMarkerType = UStoreMarker -> Type

Specific kind used to designate markers for UStoreFieldExt.

We suggest that fields may serve different purposes and so annotated with special markers accordingly, which influences translation to Michelson. See example below.

This Haskell kind is implemented like that because we want markers to differ from all other types in kind; herewith UStoreMarkerType is still an open kind (has potentially infinite number of inhabitants).

class KnownUStoreMarker (marker :: UStoreMarkerType) where

Allows to specify format of key under which fields of this type are stored. Useful to avoid collisions.

Minimal complete definition

Nothing

Associated Types

type ShowUStoreField marker v :: ErrorMessage

Display type-level information about UStore field with given marker and field value type. Used for error messages.

type ShowUStoreField marker v = 'Text "field of type " :<>: 'ShowType v

Methods

mkFieldMarkerUKey :: MText -> ByteString

By field name derive key under which field should be stored.

default mkFieldMarkerUKey :: MText -> ByteString

Instances

KnownUStoreMarker UMarkerPlainField

Defined in Lorentz.UStore.Types

Associated Types

type ShowUStoreField UMarkerPlainField v :: ErrorMessage

Methods

mkFieldMarkerUKey :: MText -> ByteString

Type-lookup-by-name

type GetUStoreKey store name = MSKey (GetUStore name store)

Get type of submap key.

type GetUStoreValue store name = MSValue (GetUStore name store)

Get type of submap value.

type GetUStoreField store name = FSValue (GetUStore name store)

Get type of plain field. This ignores marker with field type.

type GetUStoreFieldMarker store name = FSMarker (GetUStore name store)

Get kind of field.

Instructions

ustoreMem :: forall store name s. KeyAccessC store name => Label name -> (GetUStoreKey store name ': (UStore store ': s)) :-> (Bool ': s)

ustoreGet :: forall store name s. (KeyAccessC store name, ValueAccessC store name) => Label name -> (GetUStoreKey store name ': (UStore store ': s)) :-> (Maybe (GetUStoreValue store name) ': s)

ustoreUpdate :: forall store name s. (KeyAccessC store name, ValueAccessC store name) => Label name -> (GetUStoreKey store name ': (Maybe (GetUStoreValue store name) ': (UStore store ': s))) :-> (UStore store ': s)

ustoreInsert :: forall store name s. (KeyAccessC store name, ValueAccessC store name) => Label name -> (GetUStoreKey store name ': (GetUStoreValue store name ': (UStore store ': s))) :-> (UStore store ': s)

ustoreInsertNew :: forall store name s. (KeyAccessC store name, ValueAccessC store name) => Label name -> (forall s0 any. (GetUStoreKey store name ': s0) :-> any) -> (GetUStoreKey store name ': (GetUStoreValue store name ': (UStore store ': s))) :-> (UStore store ': s)

Insert a key-value pair, but fail if it will overwrite some existing entry.

ustoreDelete :: forall store name s. KeyAccessC store name => Label name -> (GetUStoreKey store name ': (UStore store ': s)) :-> (UStore store ': s)

ustoreToField :: forall store name s. FieldAccessC store name => Label name -> (UStore store ': s) :-> (GetUStoreField store name ': s)

Like toField, but for UStore.

This may fail only if UStore was made up incorrectly during contract initialization.

ustoreGetField :: forall store name s. FieldAccessC store name => Label name -> (UStore store ': s) :-> (GetUStoreField store name ': (UStore store ': s))

Like getField, but for UStore.

This may fail only if UStore was made up incorrectly during contract initialization.

ustoreSetField :: forall store name s. FieldAccessC store name => Label name -> (GetUStoreField store name ': (UStore store ': s)) :-> (UStore store ': s)

Like setField, but for UStore.

Instruction constraints

type HasUStore name key value store = (KeyAccessC store name, ValueAccessC store name, GetUStoreKey store name ~ key, GetUStoreValue store name ~ value)

This constraint can be used if a function needs to work with big store, but needs to know only about some submap(s) of it.

It can use all UStore operations for a particular name, key and value without knowing whole template.

type HasUField name ty store = (FieldAccessC store name, GetUStoreField store name ~ ty)

This constraint can be used if a function needs to work with big store, but needs to know only about some field of it.

type HasUStoreForAllIn store constrained = (Generic store, GHasStoreForAllIn constrained (Rep store))

Write down all sensisble constraints which given store satisfies and apply them to constrained.

This store should have |~> and UStoreField fields in its immediate fields, no deep inspection is performed.

UStore composability

liftUStore :: (Generic template, RequireAllUniqueFields template) => Label name -> (UStore (GetFieldType template name) ': s) :-> (UStore template ': s)

Lift an UStore to another UStore which contains all the entries of the former under given field.

This function is not intended for use in migrations, only in normal entry points.

Note that this function ensures that template of resulting store does not contain inner nested templates with duplicated fields, otherwise UStore invariants could get broken.

unliftUStore :: Generic template => Label name -> (UStore template ': s) :-> (UStore (GetFieldType template name) ': s)

Unlift an UStore to a smaller UStore which is part of the former.

This function is not intended for use in migrations, only in normal entry points.

Surprisingly, despite smaller UStore may have extra entries, this function is safe when used in contract code. Truly, all getters and setters are still safe to use. Also, there is no way for the resulting small UStore to leak outside of the contract since the only place where big_map can appear is contract storage, so this small UStore can be either dropped or lifted back via liftUStore to appear as part of the new contract's state.

When this function is run as part of standalone instructions sequence, not as part of contract code (e.g. in tests), you may get an UStore with entries not inherent to it.

Documentation

class Typeable template => UStoreTemplateHasDoc template where

Information for UStore template required for documentation.

You only need to instantiate this for templates used directly in UStore, nested subtemplates do not need this instance.

Minimal complete definition

ustoreTemplateDocDescription

Methods

ustoreTemplateDocName :: Text

UStore template name as it appears in documentation.

Should be only 1 word.

default ustoreTemplateDocName :: (Generic template, KnownSymbol (GenericTypeName template)) => Text

ustoreTemplateDocDescription :: Markdown

Description of template.

ustoreTemplateDocContents :: Markdown

Description of template entries.

default ustoreTemplateDocContents :: UStoreTraversable DocumentTW template => Markdown

ustoreTemplateDocDependencies :: [SomeTypeWithDoc]

default ustoreTemplateDocDependencies :: UStoreTraversable DocumentTW template => [SomeTypeWithDoc]

Instances

UStoreTemplateHasDoc ()

Defined in Lorentz.UStore.Doc

Methods

ustoreTemplateDocName :: Text

ustoreTemplateDocDescription :: Markdown

ustoreTemplateDocContents :: Markdown

ustoreTemplateDocDependencies :: [SomeTypeWithDoc]

UStoreTemplateHasDoc SomeUTemplate

Defined in Lorentz.UStore.Migration.Base

Methods

ustoreTemplateDocName :: Text

ustoreTemplateDocDescription :: Markdown

ustoreTemplateDocContents :: Markdown

ustoreTemplateDocDependencies :: [SomeTypeWithDoc]

class KnownUStoreMarker marker => UStoreMarkerHasDoc (marker :: UStoreMarkerType) where

Instantiated for documented UStore markers.

Methods

ustoreMarkerKeyEncoding :: Text -> Text

Specifies key encoding.

You accept description of field name, and should return how is it encoded as key of big_map bytes bytes.

Instances

UStoreMarkerHasDoc UMarkerPlainField

Defined in Lorentz.UStore.Doc

Methods

ustoreMarkerKeyEncoding :: Text -> Text

UStore management from Haskell

mkUStore :: UStoreTraversable MkUStoreTW template => template -> UStore template

Make UStore from separate big_maps and fields.

ustoreDecompose :: forall template. UStoreTraversable DecomposeUStoreTW template => UStore template -> Either Text (UStoreContent, template)

Decompose UStore into separate big_maps and fields.

Since this function needs to UNPACK content of UStore to actual keys and values, you have to provide UnpackEnv.

Along with resulting value, you get a list of UStore entries which were not recognized as belonging to any submap or field according to UStore's template - this should be empty unless UStore invariants were violated.

ustoreDecomposeFull :: forall template. UStoreTraversable DecomposeUStoreTW template => UStore template -> Either Text template

Like ustoreDecompose, but requires all entries from UStore to be recognized.

fillUStore :: UStoreTraversable FillUStoreTW template => template -> UStoreMigration () template

Make migration script which initializes UStore from scratch.

data MkUStoreTW

Declares handlers for UStore creation from template.

Instances

UStoreTraversalWay MkUStoreTW

Defined in Lorentz.UStore.Haskell

Associated Types

type UStoreTraversalArgumentWrapper MkUStoreTW :: Type -> Type

type UStoreTraversalMonad MkUStoreTW :: Type -> Type

(NicePackedValue k, NicePackedValue v) => UStoreTraversalSubmapHandler MkUStoreTW k v

Defined in Lorentz.UStore.Haskell

Methods

ustoreTraversalSubmapHandler :: forall (name :: Symbol). MkUStoreTW -> Label name -> UStoreTraversalArgumentWrapper MkUStoreTW (Map k v) -> UStoreTraversalMonad MkUStoreTW (Map k v)

NicePackedValue val => UStoreTraversalFieldHandler MkUStoreTW marker val

Defined in Lorentz.UStore.Haskell

Methods

ustoreTraversalFieldHandler :: forall (name :: Symbol). KnownUStoreMarker marker => MkUStoreTW -> Label name -> UStoreTraversalArgumentWrapper MkUStoreTW val -> UStoreTraversalMonad MkUStoreTW val

type UStoreTraversalArgumentWrapper MkUStoreTW

Defined in Lorentz.UStore.Haskell

type UStoreTraversalArgumentWrapper MkUStoreTW = Identity

type UStoreTraversalMonad MkUStoreTW

Defined in Lorentz.UStore.Haskell

type UStoreTraversalMonad MkUStoreTW = Const (Map ByteString ByteString) :: Type -> Type

data DecomposeUStoreTW

Declares handlers for UStore conversion to template.

Instances

UStoreTraversalWay DecomposeUStoreTW

Defined in Lorentz.UStore.Haskell

Associated Types

type UStoreTraversalArgumentWrapper DecomposeUStoreTW :: Type -> Type

type UStoreTraversalMonad DecomposeUStoreTW :: Type -> Type

(Ord k, NiceUnpackedValue k, NiceUnpackedValue v) => UStoreTraversalSubmapHandler DecomposeUStoreTW k v

Defined in Lorentz.UStore.Haskell

Methods

ustoreTraversalSubmapHandler :: forall (name :: Symbol). DecomposeUStoreTW -> Label name -> UStoreTraversalArgumentWrapper DecomposeUStoreTW (Map k v) -> UStoreTraversalMonad DecomposeUStoreTW (Map k v)

NiceUnpackedValue val => UStoreTraversalFieldHandler DecomposeUStoreTW marker val

Defined in Lorentz.UStore.Haskell

Methods

ustoreTraversalFieldHandler :: forall (name :: Symbol). KnownUStoreMarker marker => DecomposeUStoreTW -> Label name -> UStoreTraversalArgumentWrapper DecomposeUStoreTW val -> UStoreTraversalMonad DecomposeUStoreTW val

type UStoreTraversalArgumentWrapper DecomposeUStoreTW

Defined in Lorentz.UStore.Haskell

type UStoreTraversalArgumentWrapper DecomposeUStoreTW = Const () :: Type -> Type

type UStoreTraversalMonad DecomposeUStoreTW

Defined in Lorentz.UStore.Haskell

type UStoreTraversalMonad DecomposeUStoreTW

data FillUStoreTW

Declares handlers for UStore filling via lambda.

Instances

UStoreTraversalWay FillUStoreTW

Defined in Lorentz.UStore.Haskell

Associated Types

type UStoreTraversalArgumentWrapper FillUStoreTW :: Type -> Type

type UStoreTraversalMonad FillUStoreTW :: Type -> Type

(NiceConstant k, NiceConstant v) => UStoreTraversalSubmapHandler FillUStoreTW k v

Defined in Lorentz.UStore.Haskell

Methods

ustoreTraversalSubmapHandler :: forall (name :: Symbol). FillUStoreTW -> Label name -> UStoreTraversalArgumentWrapper FillUStoreTW (Map k v) -> UStoreTraversalMonad FillUStoreTW (Map k v)

NiceConstant v => UStoreTraversalFieldHandler FillUStoreTW marker v

Defined in Lorentz.UStore.Haskell

Methods

ustoreTraversalFieldHandler :: forall (name :: Symbol). KnownUStoreMarker marker => FillUStoreTW -> Label name -> UStoreTraversalArgumentWrapper FillUStoreTW v -> UStoreTraversalMonad FillUStoreTW v

type UStoreTraversalArgumentWrapper FillUStoreTW

Defined in Lorentz.UStore.Haskell

type UStoreTraversalArgumentWrapper FillUStoreTW = Identity

type UStoreTraversalMonad FillUStoreTW

Defined in Lorentz.UStore.Haskell

type UStoreTraversalMonad FillUStoreTW = Const (Endo [MigrationAtom]) :: Type -> Type

Migrations

newtype MigrationScript (oldStore :: Type) (newStore :: Type)

Code of migration for UStore.

Invariant: preferably should fit into op size / gas limits (quite obvious). Often this stands for exactly one stage of migration (one Tezos transaction).

Constructors

MigrationScript

Fields

• unMigrationScript :: Lambda UStore_ UStore_

Instances

CanCastTo (Lambda (UStore ot1) (UStore nt1)) (Lambda (UStore ot2) (UStore nt2)) => CanCastTo (MigrationScript ot1 nt1 :: Type) (MigrationScript ot2 nt2 :: Type)

Defined in Lorentz.UStore.Migration.Base

Methods

castDummy :: Proxy (MigrationScript ot1 nt1) -> Proxy (MigrationScript ot2 nt2) -> ()

Show (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

Methods

showsPrec :: Int -> MigrationScript oldStore newStore -> ShowS

show :: MigrationScript oldStore newStore -> String

showList :: [MigrationScript oldStore newStore] -> ShowS

Generic (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

Associated Types

type Rep (MigrationScript oldStore newStore) :: Type -> Type

Methods

from :: MigrationScript oldStore newStore -> Rep (MigrationScript oldStore newStore) x

to :: Rep (MigrationScript oldStore newStore) x -> MigrationScript oldStore newStore

Wrapped (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

Associated Types

type Unwrapped (MigrationScript oldStore newStore)

Methods

_Wrapped' :: Iso' (MigrationScript oldStore newStore) (Unwrapped (MigrationScript oldStore newStore))

Each '[Typeable :: Type -> Constraint, UStoreTemplateHasDoc] '[oldStore, newStore] => TypeHasDoc (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

Associated Types

type TypeDocFieldDescriptions (MigrationScript oldStore newStore) :: FieldDescriptions

Methods

typeDocName :: Proxy (MigrationScript oldStore newStore) -> Text

typeDocMdDescription :: Markdown

typeDocMdReference :: Proxy (MigrationScript oldStore newStore) -> WithinParens -> Markdown

typeDocDependencies :: Proxy (MigrationScript oldStore newStore) -> [SomeDocDefinitionItem]

typeDocHaskellRep :: TypeDocHaskellRep (MigrationScript oldStore newStore)

typeDocMichelsonRep :: TypeDocMichelsonRep (MigrationScript oldStore newStore)

IsoValue (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

Associated Types

type ToT (MigrationScript oldStore newStore) :: T

Methods

toVal :: MigrationScript oldStore newStore -> Value (ToT (MigrationScript oldStore newStore))

fromVal :: Value (ToT (MigrationScript oldStore newStore)) -> MigrationScript oldStore newStore

HasTypeAnn (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

Methods

getTypeAnn :: Notes (ToT (MigrationScript oldStore newStore))

type Rep (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

type Rep (MigrationScript oldStore newStore) = D1 ('MetaData "MigrationScript" "Lorentz.UStore.Migration.Base" "lorentz-0.4.0-4bB2PLHB7038abCZLw1vnA" 'True) (C1 ('MetaCons "MigrationScript" 'PrefixI 'True) (S1 ('MetaSel ('Just "unMigrationScript") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Lambda UStore_ UStore_))))

type Unwrapped (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

type Unwrapped (MigrationScript oldStore newStore) = GUnwrapped (Rep (MigrationScript oldStore newStore))

type TypeDocFieldDescriptions (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

type TypeDocFieldDescriptions (MigrationScript oldStore newStore) = '[] :: [(Symbol, (Maybe Symbol, [(Symbol, Symbol)]))]

type ToT (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

type ToT (MigrationScript oldStore newStore) = GValueType (Rep (MigrationScript oldStore newStore))

type MigrationScript_ = MigrationScript SomeUTemplate SomeUTemplate

data UStoreMigration (oldTempl :: Type) (newTempl :: Type)

Keeps information about migration between UStores with two given templates.

Instances

MapLorentzInstr (UStoreMigration os ns)

Defined in Lorentz.UStore.Migration.Base

Methods

mapLorentzInstr :: (forall (i :: [Type]) (o :: [Type]). (i :-> o) -> i :-> o) -> UStoreMigration os ns -> UStoreMigration os ns

migrationToScript :: UStoreMigration os ns -> MigrationScript os ns

Get migration script in case of simple (non-batched) migration.

migrationToScriptI :: UStoreMigration os ns -> Identity (MigrationScript os ns)

Get migration script in case of simple (non-batched) migration.

migrationToLambda :: UStoreMigration oldTemplate newTemplate -> Lambda (UStore oldTemplate) (UStore newTemplate)

Turn Migration into a whole piece of code for transforming storage.

This is not want you'd want to use for contract deployment because of gas and operation size limits that Tezos applies to transactions.

mkUStoreMigration :: Lambda (MUStore oldTempl newTempl (BuildDiff oldTempl newTempl) '[]) (MUStore oldTempl newTempl '[] _1) -> UStoreMigration oldTempl newTempl

Safe way to create migration scripts for UStore.

You have to supply a code which would transform MUStore, coverring required diff step-by-step. All basic instructions work, also use migrate* functions from this module to operate with MUStore.

This method produces a whole migration, it cannot be splitted in batches. In case if your migration is too big to be applied within a single transaction, use mkUStoreBatchedMigration.

mustoreToOld :: RequireBeInitial touched => (MUStore oldTemplate newTemplate remDiff touched ': s) :-> (UStore oldTemplate ': s)

Get the old version of storage.

This can be applied only in the beginning of migration.

In fact this function is not very useful, all required operations should be available for MUStore, but leaving it here just in case.

migrateGetField :: forall field oldTempl newTempl diff touched fieldTy s. (HasUField field fieldTy oldTempl, RequireUntouched field (field `IsElem` touched)) => Label field -> (MUStore oldTempl newTempl diff touched ': s) :-> (fieldTy ': (MUStore oldTempl newTempl diff touched ': s))

Get a field present in old version of UStore.

migrateAddField :: forall field oldTempl newTempl diff touched fieldTy newDiff marker s. ('(UStoreFieldExt marker fieldTy, newDiff) ~ CoverDiff 'DcAdd field diff, HasUField field fieldTy newTempl) => Label field -> (fieldTy ': (MUStore oldTempl newTempl diff touched ': s)) :-> (MUStore oldTempl newTempl newDiff (field ': touched) ': s)

Add a field which was not present before. This covers one addition from the diff and any removals of field with given name.

This function cannot overwrite existing field with the same name, if this is necessary use migrateOverwriteField which would declare removal explicitly.

migrateRemoveField :: forall field oldTempl newTempl diff touched fieldTy newDiff marker s. ('(UStoreFieldExt marker fieldTy, newDiff) ~ CoverDiff 'DcRemove field diff, HasUField field fieldTy oldTempl) => Label field -> (MUStore oldTempl newTempl diff touched ': s) :-> (MUStore oldTempl newTempl newDiff (field ': touched) ': s)

Remove a field which should not be present in new version of storage. This covers one removal from the diff.

In fact, this action could be performed automatically, but since removal is a destructive operation, being explicit about it seems like a good thing.

migrateExtractField :: forall field oldTempl newTempl diff touched fieldTy newDiff marker s. ('(UStoreFieldExt marker fieldTy, newDiff) ~ CoverDiff 'DcRemove field diff, HasUField field fieldTy oldTempl, RequireUntouched field (field `IsElem` touched)) => Label field -> (MUStore oldTempl newTempl diff touched ': s) :-> (fieldTy ': (MUStore oldTempl newTempl newDiff (field ': touched) ': s))

Get and remove a field from old version of UStore.

You probably want to use this more often than plain migrateRemoveField.

migrateOverwriteField :: forall field oldTempl newTempl diff touched fieldTy oldFieldTy marker oldMarker newDiff newDiff0 s. ('(UStoreFieldExt oldMarker oldFieldTy, newDiff0) ~ CoverDiff 'DcRemove field diff, '(UStoreFieldExt marker fieldTy, newDiff) ~ CoverDiff 'DcAdd field newDiff0, HasUField field fieldTy newTempl) => Label field -> (fieldTy ': (MUStore oldTempl newTempl diff touched ': s)) :-> (MUStore oldTempl newTempl newDiff (field ': touched) ': s)

Remove field and write new one in place of it.

This is semantically equivalent to dip (migrateRemoveField label) >> migrateAddField label, but is cheaper.

migrateModifyField :: forall field oldTempl newTempl diff touched fieldTy s. (HasUField field fieldTy oldTempl, HasUField field fieldTy newTempl) => Label field -> (fieldTy ': (MUStore oldTempl newTempl diff touched ': s)) :-> (MUStore oldTempl newTempl diff touched ': s)

Modify field which should stay in new version of storage. This does not affect remaining diff.

Extras

type PickMarkedFields marker template = GPickMarkedFields marker (Rep template)

Collect all fields with the given marker.

type UStoreTraversable way a = (Generic a, GUStoreTraversable way (Rep a), UStoreTraversalWay way)

Constraint for UStore traversal.