Lorentz.Extensible

This module contains implementation of Extensible values.

Extensible values are an alternative representation of sum-types for Michelson. Instead of representing them as nested options, we treat them as (Natural, ByteString) pair, where the first element of the pair represents the constructor index, while the second is a packed argument.

With such a representation sum types can be easily upgraded: it is possible to add new elements to the sum type, and the representation would not change.

However, such representation essentially limits the applicability of the values. This module does not provide Michelson-level function to unwrap the value because it would require traversing all the possible options in the contract code. While this is possible, it is very inefficient. Up to this moment, we have not come up with a decent reason to allow such behavior, so Extensible types are write-only in Michelson code. They can be unwrapped off-chain with fromExtVal.

In order to preserve previous values during migrations, users should ONLY APPEND items to the underlying sum type. Changing, reordering and deleting items is not allowed and would lead to compatibility breakage. Currently, this restriction in not enforced. Only no-argument and one-argument constructors are supported.

GOOD: -- `Extensible GoodSumTypeV1` is backwards compatible -- with `Extensible GoodSumTypeV2` data GoodSumTypeV1 = A Natural | B data GoodSumTypeV2 = A Natural | B | C MText

BAD: -- `Extensible BadSumTypeV1` is NOT backwards compatible -- with `Extensible BadSumTypeV2` data BadSumTypeV1 = A | B data BadSumTypeV2 = A Natural | B | C MText

Documentation

newtype Extensible x

Constructors

Extensible (Natural, ByteString)

Instances

Eq (Extensible x)

Defined in Lorentz.Extensible

Methods

(==) :: Extensible x -> Extensible x -> Bool

(/=) :: Extensible x -> Extensible x -> Bool

Show (Extensible x)

Defined in Lorentz.Extensible

Methods

showsPrec :: Int -> Extensible x -> ShowS

show :: Extensible x -> String

showList :: [Extensible x] -> ShowS

Generic (Extensible x)

Defined in Lorentz.Extensible

Associated Types

type Rep (Extensible x) :: Type -> Type

Methods

from :: Extensible x -> Rep (Extensible x) x0

to :: Rep (Extensible x) x0 -> Extensible x

(ExtensibleHasDoc x, ReifyList DocumentCtor (EnumerateCtors (GetCtors x))) => TypeHasDoc (Extensible x)

Defined in Lorentz.Extensible

Associated Types

type TypeDocFieldDescriptions (Extensible x) :: FieldDescriptions

Methods

typeDocName :: Proxy (Extensible x) -> Text

typeDocMdDescription :: Markdown

typeDocMdReference :: Proxy (Extensible x) -> WithinParens -> Markdown

typeDocDependencies :: Proxy (Extensible x) -> [SomeDocDefinitionItem]

typeDocHaskellRep :: TypeDocHaskellRep (Extensible x)

typeDocMichelsonRep :: TypeDocMichelsonRep (Extensible x)

IsoValue (Extensible x)

Defined in Lorentz.Extensible

Associated Types

type ToT (Extensible x) :: T

Methods

toVal :: Extensible x -> Value (ToT (Extensible x))

fromVal :: Value (ToT (Extensible x)) -> Extensible x

HasAnnotation (Extensible x)

Defined in Lorentz.Extensible

Methods

getAnnotation :: Notes (ToT (Extensible x))

Wrappable (Extensible x)

Defined in Lorentz.Extensible

Associated Types

type Unwrappable (Extensible x)

type Rep (Extensible x)

Defined in Lorentz.Extensible

type Rep (Extensible x) = D1 ('MetaData "Extensible" "Lorentz.Extensible" "lorentz-0.5.0-inplace" 'True) (C1 ('MetaCons "Extensible" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Natural, ByteString))))

type TypeDocFieldDescriptions (Extensible x)

Defined in Lorentz.Extensible

type TypeDocFieldDescriptions (Extensible x) = '[] :: [(Symbol, (Maybe Symbol, [(Symbol, Symbol)]))]

type ToT (Extensible x)

Defined in Lorentz.Extensible

type ToT (Extensible x) = GValueType (Rep (Extensible x))

type Unwrappable (Extensible x)

Defined in Lorentz.Extensible

type Unwrappable (Extensible x)

data ExtConversionError

Errors related to fromExtVal conversion

Constructors

ConstructorIndexNotFound Natural

ArgumentUnpackFailed

Instances

Eq ExtConversionError

Defined in Lorentz.Extensible

Methods

(==) :: ExtConversionError -> ExtConversionError -> Bool

(/=) :: ExtConversionError -> ExtConversionError -> Bool

Show ExtConversionError

Defined in Lorentz.Extensible

Methods

showsPrec :: Int -> ExtConversionError -> ShowS

show :: ExtConversionError -> String

showList :: [ExtConversionError] -> ShowS

Buildable ExtConversionError

Defined in Lorentz.Extensible

Methods

build :: ExtConversionError -> Builder

type ExtVal x = (Generic x, GExtVal x (Rep x))

class Typeable x => ExtensibleHasDoc x where

Information to be provided for documenting some Extensible x.

Minimal complete definition

extensibleDocName, extensibleDocMdDescription

Methods

extensibleDocName :: Proxy x -> Text

Implementation for typeDocName of the corresponding Extensible.

extensibleDocDependencies :: Proxy x -> [SomeDocDefinitionItem]

Implementation for typeDocDependencies of the corresponding Extensible.

default extensibleDocDependencies :: (Generic x, GTypeHasDoc (Rep x)) => Proxy x -> [SomeDocDefinitionItem]

extensibleDocMdDescription :: Markdown

Overall description of this type.

toExtVal :: ExtVal a => a -> Extensible a

Converts a value from a Haskell representation to its extensible Michelson representation (i.e. (Natural, Bytestring) pair).

fromExtVal :: ExtVal a => Extensible a -> Either ExtConversionError a

Converts a value from an extensible Michelson representation to its Haskell sum-type representation. Fails if the Michelson representation points to a nun-existent constructor, or if we failed to unpack the argument.

wrapExt :: forall t (n :: Nat) name field s. WrapExtC t n name field s => Label ("c" `AppendSymbol` name) -> AppendCtorField field s :-> (Extensible t ': s)

Wraps an argument on top of the stack into an Extensible representation

type WrapExtC t n name field s = ('Ctor n name field ~ LookupCtor name (EnumerateCtors (GetCtors t)), WrapExt field, KnownNat n)