Michelson injection
If you have an existing piece of Michelson code that you want to use as-is, LIGO provides the ability to embed (inject) Michelson code. This feature can be useful when you need to have a deep level of control over the generated code, for example for optimisation, or if you need to use a feature from Michelson that is not yet supported by high-level constructions in LIGO.
Internal injection
The syntax for embedding Michelson is by means of the (Michelson
...)
hook. The ellipsis is meant to denote a verbatim string
annotated with a type, which contains the Michelson code to be
injected in the generated Michelson and the type (that of a function)
of the Michelson code.
Note that the type annotation is required, because the embedded Michelson code is not type-checked by the LIGO compiler, which therefore assumes that the given type is correct.
In the example above, the notation ` ... `
is used to represent a
verbatim string literal, that is, an uninterpreted string, which here
contains a piece of Michelson code. The type annotation describes the
behaviour of the Michelson code:
It starts working on a stack consisting of a tuple of
nat
s:[ nat * nat ]
.The tuple is destructured using
UNPAIR
:[ nat ] [ nat ]
.The two top values of the stack are added using
ADD
, and stops working on a stack consisting of a singlenat
:[ nat ]
.
The compiler will prevent changes to the embedded Michelson code if the function resulting from the embedded code is not applied. For example, let us see what happens when we compile an embedded Michelson expression that pushes some value on the stack, then drops it immediately, and then continues as a regular increment function.
The following command-line:
outputs:
{ PUSH nat 42 ; DROP ; PUSH nat 1 ; ADD }
As we can see, the embedded Michelson code was not modified. However, if the resulting function is applied, then the embedded Michelson code could be modified/optimised by the compiler. To demonstrate this behaviour, a function call can be introduced in the example above by creating a lambda around the Michelson code. In this case, the first two instructions will be removed by the LIGO compiler because they have no effect on the final result.
The following command-line:
outputs:
{ PUSH nat 1 ; ADD }
External injection
Sometimes the Michelson code we wish to inject is better maintained externally, perhaps by a third-party, in which case we need to load the Michelson code in order to inject it.
This is achieved by the special hook (of_file ...)
, where the
ellipsis is a verbatim string containing a file path to a Michelson
file with extension .tz
.
Injection of Michelson contracts
This is achieved by the special hook (create_contract_of_file ...)
,
where the ellipsis is a verbatim string containg the file path to a
Michelson file with extension .tz
.
where compiled.tz
contains