Morley.AsRPC

This module contains a type family for converting a type to its RPC representation, and TemplateHaskell functions for deriving RPC representations for custom types.

Documentation

type family TAsRPC t where ...

A type-level function that maps a Michelson type to its Tezos RPC representation.

For example, when we retrieve a contract's storage using the Tezos RPC, all its big_maps will be replaced by nat, representing a big_map ID.

>>> :k! TAsRPC ('TBigMap 'TInt 'TString)
...
= 'TNat

>>> :k! TAsRPC ('TList ('TBigMap 'TInt 'TString))
...
= 'TList 'TNat

>>> :k! TAsRPC ('TPair 'TString ('TPair 'TAddress ('TBigMap 'TInt 'TString)))
...
= 'TPair 'TString ('TPair 'TAddress 'TNat)

NB: As far as we are aware, details of RPC representation of Michelson types are not documented. We know empirically that big_maps are represented as their ids, and are the only type with an explicitly different representation.

Whether TAsRPC needs to propagate into type parameters then depends on whether a value can hold big_map values.

• Values of type option a, list a, pair a b, and or a b can contain big_map values, so their RPC representations are option (TAsRPC a), list (TAsRPC a), pair (TAsRPC a) (TAsRPC b) and or (TAsRPC a) (TAsRPC b).
• The keys of a map k v cannot be big_maps, but the values can, so its RPC representation is map k (TAsRPC v).
• Values of type set a cannot contain big_maps, so its RPC representation is just set a.
• Values of type contract a cannot contain big_maps either, because it's just a wrapper for an address and an entrypoint name, so its RPC representation is just contract a. The same reasoning applies to ticket a and lambda a b.

Equations

TAsRPC 'TKey = 'TKey

TAsRPC 'TUnit = 'TUnit

TAsRPC 'TSignature = 'TSignature

TAsRPC 'TChainId = 'TChainId

TAsRPC ('TOption t) = 'TOption (TAsRPC t)

TAsRPC ('TList t) = 'TList (TAsRPC t)

TAsRPC ('TSet t) = 'TSet t

TAsRPC 'TOperation = 'TOperation

TAsRPC ('TContract t) = 'TContract t

TAsRPC ('TTicket t) = 'TTicket t

TAsRPC ('TPair t1 t2) = 'TPair (TAsRPC t1) (TAsRPC t2)

TAsRPC ('TOr t1 t2) = 'TOr (TAsRPC t1) (TAsRPC t2)

TAsRPC ('TLambda t1 t2) = 'TLambda t1 t2

TAsRPC ('TMap k v) = 'TMap k (TAsRPC v)

TAsRPC ('TBigMap _ _) = 'TNat

TAsRPC 'TInt = 'TInt

TAsRPC 'TNat = 'TNat

TAsRPC 'TString = 'TString

TAsRPC 'TBytes = 'TBytes

TAsRPC 'TMutez = 'TMutez

TAsRPC 'TBool = 'TBool

TAsRPC 'TKeyHash = 'TKeyHash

TAsRPC 'TTimestamp = 'TTimestamp

TAsRPC 'TAddress = 'TAddress

TAsRPC 'TNever = 'TNever

TAsRPC 'TBls12381Fr = 'TBls12381Fr

TAsRPC 'TBls12381G1 = 'TBls12381G1

TAsRPC 'TBls12381G2 = 'TBls12381G2

TAsRPC 'TChest = 'TChest

TAsRPC 'TChestKey = 'TChestKey

TAsRPC ('TSaplingState n) = 'TSaplingState n

TAsRPC ('TSaplingTransaction n) = 'TSaplingTransaction n

class TAsRPC (ToT t) ~ ToT (AsRPC t) => HasRPCRepr (t :: Type)

A type-level function that maps a type to its Tezos RPC representation.

For example, when we retrieve a contract's storage using the Tezos RPC, all its BigMaps will be replaced by BigMapIds.

So if a contract has a storage of type T, when we call the Tezos RPC to retrieve it, we must deserialize the micheline expression to the type AsRPC T.

AsRPC (BigMap Integer MText) ~ BigMapId Integer MText
AsRPC [BigMap Integer MText] ~ [BigMapId Integer MText]
AsRPC (MText, (Address, BigMap Integer MText)) ~ (MText, (Address, BigMapId Integer MText))

The following law must hold:

TAsRPC (ToT t) ~ ToT (AsRPC t)

In other words, ToT and AsRPC/TAsRPC must be commutative.

   Storage ----------(applying ToT)-------------> ToT Storage
      |                                                |
      |                                                |
      |                                                |
(applying AsRPC)                                (applying TAsRPC)
      |                                                |
      |                                                |
      |                                                |
      |                                                V
      |                                        TAsRPC (ToT Storage)
      V                                                ~
AsRPC Storage ------(applying ToT)-----------> ToT (AsRPC Storage)

This law ensures that we can go from some type Storage to AsRPC Storage by composing fromVal . valueAsRPC . toVal.

   Storage ------------(toVal)--------------> Value (ToT Storage)
      |                                                |
      |                                                |
      |                                                |
(fromVal . valueAsRPC . toVal)                    (valueAsRPC)
      |                                                |
      |                                                |
      |                                                |
      |                                                V
      |                                   Value (TAsRPC (ToT Storage))
      V                                                ~
AsRPC Storage <--------(fromVal)--------- Value (ToT (AsRPC Storage))

Associated Types

type AsRPC t :: Type

Instances

HasRPCRepr Bool

Defined in Morley.AsRPC

Associated Types

type AsRPC Bool

HasRPCRepr Integer

Defined in Morley.AsRPC

Associated Types

type AsRPC Integer

HasRPCRepr Natural

Defined in Morley.AsRPC

Associated Types

type AsRPC Natural

HasRPCRepr ()

Defined in Morley.AsRPC

Associated Types

type AsRPC ()

HasRPCRepr ByteString

Defined in Morley.AsRPC

Associated Types

type AsRPC ByteString

HasRPCRepr Chest

Defined in Morley.AsRPC

Associated Types

type AsRPC Chest

HasRPCRepr ChestKey

Defined in Morley.AsRPC

Associated Types

type AsRPC ChestKey

HasRPCRepr Bls12381Fr

Defined in Morley.AsRPC

Associated Types

type AsRPC Bls12381Fr

HasRPCRepr Bls12381G2

Defined in Morley.AsRPC

Associated Types

type AsRPC Bls12381G2

HasRPCRepr Bls12381G1

Defined in Morley.AsRPC

Associated Types

type AsRPC Bls12381G1

HasRPCRepr MText

Defined in Morley.AsRPC

Associated Types

type AsRPC MText

HasRPCRepr KeyHash

Defined in Morley.AsRPC

Associated Types

type AsRPC KeyHash

HasRPCRepr Signature

Defined in Morley.AsRPC

Associated Types

type AsRPC Signature

HasRPCRepr PublicKey

Defined in Morley.AsRPC

Associated Types

type AsRPC PublicKey

HasRPCRepr ChainId

Defined in Morley.AsRPC

Associated Types

type AsRPC ChainId

HasRPCRepr Timestamp

Defined in Morley.AsRPC

Associated Types

type AsRPC Timestamp

HasRPCRepr Mutez

Defined in Morley.AsRPC

Associated Types

type AsRPC Mutez

HasRPCRepr Address

Defined in Morley.AsRPC

Associated Types

type AsRPC Address

HasRPCRepr EpAddress

Defined in Morley.AsRPC

Associated Types

type AsRPC EpAddress

HasRPCRepr Operation

Defined in Morley.AsRPC

Associated Types

type AsRPC Operation

HasRPCRepr a => HasRPCRepr [a]

Defined in Morley.AsRPC

Associated Types

type AsRPC [a]

HasRPCRepr a => HasRPCRepr (Maybe a)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Maybe a)

HasRPCRepr (Set a)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Set a)

HasRPCRepr a => HasRPCRepr (Identity a)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Identity a)

HasRPCRepr (Value t)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Value t)

HasRPCRepr (ContractRef arg)

Defined in Morley.AsRPC

Associated Types

type AsRPC (ContractRef arg)

(HasRPCRepr l, HasRPCRepr r) => HasRPCRepr (Either l r)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Either l r)

(HasRPCRepr a, HasRPCRepr b) => HasRPCRepr (a, b)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b)

HasRPCRepr v => HasRPCRepr (Map k v)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Map k v)

HasRPCRepr (BigMap k v)

Defined in Morley.AsRPC

Associated Types

type AsRPC (BigMap k v)

Each '[HasRPCRepr] '[a, b, c] => HasRPCRepr (a, b, c)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c)

HasRPCRepr a => HasRPCRepr (NamedF Maybe a name)

Defined in Morley.AsRPC

Associated Types

type AsRPC (NamedF Maybe a name)

HasRPCRepr a => HasRPCRepr (NamedF Identity a name)

Defined in Morley.AsRPC

Associated Types

type AsRPC (NamedF Identity a name)

Each '[HasRPCRepr] '[a, b, c, d] => HasRPCRepr (a, b, c, d)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c, d)

Each '[HasRPCRepr] '[a, b, c, d, e] => HasRPCRepr (a, b, c, d, e)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c, d, e)

Each '[HasRPCRepr] '[a, b, c, d, e, f] => HasRPCRepr (a, b, c, d, e, f)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c, d, e, f)

Each '[HasRPCRepr] '[a, b, c, d, e, f, g] => HasRPCRepr (a, b, c, d, e, f, g)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c, d, e, f, g)

data MaybeRPC v where

Represents a value that may or may not be in its RPC representation.

>>> :t NotRPC @(BigMap Integer MText) (mkBigMap @[(Integer, MText)] [])
...
  :: MaybeRPC (BigMap Integer MText)

>>> :t IsRPC @(BigMap Integer MText) (BigMapId 1)
...
  :: MaybeRPC (BigMap Integer MText)

Constructors

NotRPC :: IsoValue v => v -> MaybeRPC v

IsRPC :: (SingI (ToT v), IsoValue (AsRPC v), HasRPCRepr v) => AsRPC v -> MaybeRPC v

Instances

HasNoOp (ToT v) => ToExpression (MaybeRPC v)

Defined in Morley.AsRPC

Methods

toExpression :: MaybeRPC v -> Expression

deriveRPC :: String -> Q [Dec]

Derive an RPC representation for a type, as well as instances for Generic, IsoValue and HasRPCRepr.

data ExampleStorage a b = ExampleStorage
  { esField1 :: Integer
  , esField2 :: [BigMap Integer MText]
  , esField3 :: a
  }
  deriving stock Generic
  deriving anyclass IsoValue

deriveRPC "ExampleStorage"

Will generate:

data ExampleStorageRPC a b = ExampleStorageRPC
  { esField1RPC :: AsRPC Integer
  , esField2RPC :: AsRPC [BigMap Integer MText]
  , esField3RPC :: AsRPC a
  }

instance HasRPCRepr a => HasRPCRepr (ExampleStorage a b) where
  type AsRPC (ExampleStorage a b) = ExampleStorageRPC a b
deriving anyclass instance (IsoValue (AsRPC a), IsoValue (AsRPC b)) => IsoValue (ExampleStorageRPC a b)
instance Generic (ExampleStorageRPC a b) where
  ...

deriveRPCWithStrategy :: String -> GenericStrategy -> Q [Dec]

Same as deriveRPC, but uses a custom strategy for deriving a Generic instance.

deriveManyRPC :: String -> [String] -> Q [Dec]

Recursively enumerate data, newtype and type declarations, and derives an RPC representation for each type that doesn't yet have one.

You can also pass in a list of types for which you _don't_ want an RPC representation to be derived.

In this example, deriveManyRPC will generate an RPC representation for A and B, but not for C (because we explicitly said we don't want one) or D (because it already has one).

data B = B
data C = C
data D = D
deriveRPC "D"

data A = A B C D
deriveManyRPC "A" ["C"]

deriveManyRPCWithStrategy :: String -> [String] -> GenericStrategy -> Q [Dec]

Same as deriveManyRPC, but uses a custom strategy for deriving a Generic instance.

Conversions

valueAsRPC :: HasCallStack => Value t -> Value (TAsRPC t)

Replace all big_maps in a value with the respective big_map IDs.

Throws an error if it finds a big_map without an ID.

replaceBigMapIds

Arguments

:: forall t m. Monad m

=> (forall k v. (SingI k, SingI v) => Natural -> m (Value ('TBigMap k v)))

A function for looking up a bigmap using its ID.

-> Sing t

-> Value (TAsRPC t)

-> m (Value t)

Replaces all bigmap IDs with their corresponding bigmap values. This is the inverse of valueAsRPC.

notesAsRPC :: Notes t -> Notes (TAsRPC t)

Replace all big_map annotations in a value with nat annotations.

Entailments

rpcSingIEvi :: forall (t :: T). SingI t :- SingI (TAsRPC t)

A proof that if a singleton exists for t, then so it does for TAsRPC t.

rpcHasNoOpEvi :: forall (t :: T). (SingI t, HasNoOp t) => HasNoOp t :- HasNoOp (TAsRPC t)

A proof that if t does not contain any operations, then neither does TAsRPC t.

rpcHasNoBigMapEvi :: forall (t :: T). SingI t => Dict (HasNoBigMap (TAsRPC t))

A proof that AsRPC (Value t) does not contain big_maps.

rpcHasNoNestedBigMapsEvi :: forall (t :: T). SingI t => Dict (HasNoNestedBigMaps (TAsRPC t))

A proof that AsRPC (Value t) does not contain big_maps.

rpcHasNoContractEvi :: forall (t :: T). (SingI t, HasNoContract t) => HasNoContract t :- HasNoContract (TAsRPC t)

A proof that if t does not contain any contract values, then neither does TAsRPC t.

rpcStorageScopeEvi :: forall (t :: T). StorageScope t :- StorageScope (TAsRPC t)

A proof that if t is a valid storage type, then so is TAsRPC t.