Lorentz.UStore.Migration.Base

Basic migration primitives.

All primitives in one scheme:

MigrationBlocks (batched migrations writing) /| || muBlock // || mkUStoreBatchedMigration // || // || MUStore || UStore template value (simple migration writing) || (storage initialization) \ || // \ || // mkUStoreMigration \ || // fillUStore | / |/ UStoreMigration (whole migration) || \ || \ migrationToScript || \ compileMigration || \ MigrationBatching || \ (way to slice migration) || \ // || \ // || | |/ || UStoreMigrationCompiled || (sliced migration) || // \ || migrationToScripts \ buildMigrationPlan || // \ migrationStagesNum || // \ ... / |/ | MigrationScript Information about migration (part of migration which (migration plan, stages number...) fits into Tezos transaction)

UStore utilities

data SomeUTemplate

Dummy template for UStore, use this when you want to forget exact template and make type of store homomorphic.

type UStore_ = UStore SomeUTemplate

UStore with hidden template.

Basic migration primitives

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 :: ()

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) :: Type

Methods

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

(Typeable oldStore, Typeable newStore) => TypeHasDoc (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

Methods

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

typeDocMdDescription :: Markdown

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

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

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

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.1.0-1IijY81BuYC4to9wXiBP3G" 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 ToT (MigrationScript oldStore newStore)

Defined in Lorentz.UStore.Migration.Base

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

maNameL :: Lens' MigrationAtom Text

maScriptL :: Lens' MigrationAtom MigrationScript_

maActionsDescL :: Lens' MigrationAtom [DMigrationActionDesc]

type MigrationScriptFrom oldStore = MigrationScript oldStore SomeUTemplate

Corner case of MigrationScript with some type argument unknown.

You can turn this into MigrationScript using checkedCoerce.

type MigrationScriptTo newStore = MigrationScript SomeUTemplate newStore

type MigrationScript_ = MigrationScript SomeUTemplate SomeUTemplate

data MigrationAtom

Minimal possible piece of migration script.

Different atoms can be arbitrarily reordered and separated across migration stages, but each single atom is treated as a whole.

Splitting migration into atoms is responsibility of migration writer.

Constructors

MigrationAtom

Fields

• maName :: Text
• maScript :: MigrationScript_
• maActionsDesc :: [DMigrationActionDesc]

Instances

Show MigrationAtom

Defined in Lorentz.UStore.Migration.Base

Methods

showsPrec :: Int -> MigrationAtom -> ShowS

show :: MigrationAtom -> String

showList :: [MigrationAtom] -> ShowS

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

Keeps information about migration between UStores with two given templates.

Constructors

UStoreMigration :: [MigrationAtom] -> UStoreMigration oldTempl newTempl

newtype MigrationBlocks (oldTemplate :: Type) (newTemplate :: Type) (preRemDiff :: [DiffItem]) (preTouched :: [Symbol]) (postRemDiff :: [DiffItem]) (postTouched :: [Symbol])

A bunch of migration atoms produced by migration writer.

Constructors

MigrationBlocks [MigrationAtom]

Instances

(RequireEmptyDiff d1, t1 ~ t2) => MigrationFinishCheckPosition (MigrationBlocks o n d1 t1 ([] :: [DiffItem]) t2)

This version can be used in mkUStoreMultiMigration as the last migration block.

Defined in Lorentz.UStore.Migration.Blocks

Methods

migrationFinish :: MigrationBlocks o n d1 t1 [] t2

newtype MUStore (oldTemplate :: Type) (newTemplate :: Type) (remDiff :: [DiffItem]) (touched :: [Symbol])

Wrapper over UStore which is currently being migrated.

In type-level arguments it keeps

• Old and new UStore templates - mostly for convenience of the implementation.
• Remaining diff which yet should be covered. Here we track migration progress. Once remaining diff is empty, migration is finished.
• Names of fields which have already been touched by migration. Required to make getters safe.

Constructors

MUStoreUnsafe (UStore oldTemplate)

Instances

Generic (MUStore oldTemplate newTemplate remDiff touched)

Defined in Lorentz.UStore.Migration.Base

Associated Types

type Rep (MUStore oldTemplate newTemplate remDiff touched) :: Type -> Type

Methods

from :: MUStore oldTemplate newTemplate remDiff touched -> Rep (MUStore oldTemplate newTemplate remDiff touched) x

to :: Rep (MUStore oldTemplate newTemplate remDiff touched) x -> MUStore oldTemplate newTemplate remDiff touched

IsoValue (MUStore oldTemplate newTemplate remDiff touched)

Defined in Lorentz.UStore.Migration.Base

Associated Types

type ToT (MUStore oldTemplate newTemplate remDiff touched) :: T

Methods

toVal :: MUStore oldTemplate newTemplate remDiff touched -> Value (ToT (MUStore oldTemplate newTemplate remDiff touched))

fromVal :: Value (ToT (MUStore oldTemplate newTemplate remDiff touched)) -> MUStore oldTemplate newTemplate remDiff touched

type Rep (MUStore oldTemplate newTemplate remDiff touched)

Defined in Lorentz.UStore.Migration.Base

type Rep (MUStore oldTemplate newTemplate remDiff touched) = D1 (MetaData "MUStore" "Lorentz.UStore.Migration.Base" "lorentz-0.1.0-1IijY81BuYC4to9wXiBP3G" True) (C1 (MetaCons "MUStoreUnsafe" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (UStore oldTemplate))))

type ToT (MUStore oldTemplate newTemplate remDiff touched)

Defined in Lorentz.UStore.Migration.Base

type ToT (MUStore oldTemplate newTemplate remDiff touched) = GValueType (Rep (MUStore oldTemplate newTemplate remDiff touched))

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.

mapMigrationCode :: (forall i o. (i :-> o) -> i :-> o) -> UStoreMigration os ns -> UStoreMigration os ns

Modify all code in migration.

Simple migrations

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.

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.

Batched migrations

data MigrationBatching (structure :: Type -> Type) (batchInfo :: Type)

Way of distributing migration atoms among batches.

This also participates in describing migration plan and should contain information which would clarify to a user why migration is splitted such a way. Objects of type batchInfo stand for information corresponding to a batch and may include e.g. names of taken actions and gas consumption.

Type argument structure stands for container where batches will be put to and is usually a list ('[]').

When writing an instance of this datatype, you should tend to produce as few batches as possible because Tezos transaction execution overhead is quite high; though these batches should still preferably fit into gas limit.

Note that we never fail here because reaching perfect consistency with Tezos gas model is beyond dreams for now, even if our model predicts that some migration atom cannot be fit into gas limit, Tezos node can think differently and accept the migration. If your batching function can make predictions about fitting into gas limit, consider including this information in batchInfo type.

See batching implementations in Lorentz.UStore.Migration.Batching module.

Constructors

MigrationBatching ([MigrationAtom] -> structure (batchInfo, MigrationScript_))

mbBatchesAsIs :: MigrationBatching [] Text

Put each migration atom to a separate batch.

In most cases this is not what you want, but may be useful if e.g. you write your migration manually.

mbNoBatching :: MigrationBatching Identity Text

Put the whole migration into one batch.

compileMigration :: Functor t => MigrationBatching t batchInfo -> UStoreMigration ot nt -> UStoreMigrationCompiled ot nt t batchInfo

Compile migration for use in production.

newtype UStoreMigrationCompiled (oldStore :: Type) (newStore :: Type) (structure :: Type -> Type) (batchInfo :: Type)

Migration script splitted in batches.

This is an intermediate form of migration content and needed because compiling UStoreMigration is a potentially heavyweight operation, and after compilation is performed you may need to get various information like number of migration steps, migration script, migration plan and other.

Constructors

UStoreMigrationCompiled

Fields

• compiledMigrationContent :: structure (batchInfo, MigrationScript oldStore newStore)

mkUStoreBatchedMigration :: MigrationBlocks oldTempl newTempl (BuildDiff oldTempl newTempl) '[] '[] _1 -> UStoreMigration oldTempl newTempl

Version of mkUStoreMigration which allows splitting migration in batches.

Here you supply a sequence of migration blocks which then are automatically distributed among migration stages.

migrationToScripts :: Traversable t => UStoreMigrationCompiled os ns t batchInfo -> t (MigrationScript os ns)

Get migration scripts, each to be executed in separate Tezos transaction.

migrationToScriptsList :: Traversable t => UStoreMigrationCompiled os ns t batchInfo -> [MigrationScript os ns]

Get migration scripts as list.

migrationToInfo :: Traversable t => UStoreMigrationCompiled ot nt t batchInfo -> t batchInfo

Get information about each batch.

migrationStagesNum :: Traversable t => UStoreMigrationCompiled ot nt t batchInfo -> Int

Number of stages in migration.

buildMigrationPlan :: (Traversable t, Buildable batchInfo) => UStoreMigrationCompiled ot nt t batchInfo -> Builder

Render migration plan.

Manual migrations

manualWithOldUStore :: ('[UStore oldStore] :-> '[UStore oldStore]) -> MigrationScript oldStore newStore

manualWithNewUStore :: ('[UStore newStore] :-> '[UStore newStore]) -> MigrationScript oldStore newStore

manualConcatMigrationScripts :: [MigrationScript os ns] -> MigrationScript os ns

Merge several migration scripts. Used in manual migrations.

This function is generally unsafe because resulting migration script can fail to fit into operation size limit.

manualMapMigrationScript :: (('[UStore_] :-> '[UStore_]) -> '[UStore_] :-> '[UStore_]) -> MigrationScript oldStore newStore -> MigrationScript oldStore newStore

Extras

data DMigrationActionType

An action on storage entry.

Constructors

DAddAction Text

Some sort of addition: "init", "set", "overwrite", e.t.c.

DDelAction

Removal.

Instances

Show DMigrationActionType

Defined in Lorentz.UStore.Migration.Base

Methods

showsPrec :: Int -> DMigrationActionType -> ShowS

show :: DMigrationActionType -> String

showList :: [DMigrationActionType] -> ShowS

Buildable DMigrationActionType

Defined in Lorentz.UStore.Migration.Base

Methods

build :: DMigrationActionType -> Builder

data DMigrationActionDesc

Describes single migration action.

In most cases it is possible to derive reasonable description for migration atom automatically, this datatype exactly carries this information.

Constructors

DMigrationActionDesc

Fields

• manAction :: DMigrationActionType

  Action on field, e.g. "set", "remove", "overwrite".

• manField :: Text

  Name of affected field of UStore.

• manFieldType :: T

  Type of affected field of UStore in new storage version.

Instances

Show DMigrationActionDesc

Defined in Lorentz.UStore.Migration.Base

Methods

showsPrec :: Int -> DMigrationActionDesc -> ShowS

show :: DMigrationActionDesc -> String

showList :: [DMigrationActionDesc] -> ShowS

DocItem DMigrationActionDesc

Defined in Lorentz.UStore.Migration.Base

Associated Types

type DocItemPosition DMigrationActionDesc = (pos :: Nat)

type DocItemPlacement DMigrationActionDesc :: DocItemPlacementKind

Methods

docItemSectionName :: Maybe Text

docItemSectionDescription :: Maybe Markdown

docItemSectionNameStyle :: DocSectionNameStyle

docItemRef :: DMigrationActionDesc -> DocItemRef (DocItemPlacement DMigrationActionDesc)

docItemToMarkdown :: HeaderLevel -> DMigrationActionDesc -> Markdown

docItemDependencies :: DMigrationActionDesc -> [SomeDocDefinitionItem]

docItemsOrder :: [DMigrationActionDesc] -> [DMigrationActionDesc]

type DocItemPlacement DMigrationActionDesc

Defined in Lorentz.UStore.Migration.Base

type DocItemPlacement DMigrationActionDesc = DocItemInlined

type DocItemPosition DMigrationActionDesc

Defined in Lorentz.UStore.Migration.Base

type DocItemPosition DMigrationActionDesc = 105010

attachMigrationActionName :: (KnownSymbol fieldName, SingI (ToT fieldTy)) => DMigrationActionType -> Label fieldName -> Proxy fieldTy -> s :-> s

Add description of action, it will be used in rendering migration plan and some batching implementations.

Internals

formMigrationAtom :: Maybe Text -> Lambda UStore_ UStore_ -> MigrationAtom

Create migration atom from code.

This is an internal function, should not be used for writing migrations.

Orphan instances

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

We allow casting between UStore_ and UStore freely.

Methods

castDummy :: ()