scalus.compiler.sir.lowering

LoweredValue for case on boolean builtins (PlutusV4 feature).

In PlutusV4, Case can be used directly on boolean constants: Case(bool, [falseBranch, trueBranch]) where False = index 0 and True = index 1.

LoweredValue for Case on Data (PlutusV4+).

Data has 5 constructors with different bound variables:

• Constr (index 0): receives tag (Integer) and args (List[Data])
• Map (index 1): receives entries (List[(Data, Data)])
• List (index 2): receives elements (List[Data])
• I (index 3): receives value (Integer)
• B (index 4): receives value (ByteString)

Each branch is a lambda that receives the appropriate arguments.

LoweredValue for case on integer builtins (PlutusV4 feature).

In PlutusV4, Case can be used directly on integer constants when the cases form a contiguous sequence starting from 0: Case(int, [branch0, branch1, ..., branchN]) where integer value i selects branch i.

Note: This only works when cases are 0, 1, 2, ..., n without gaps. For integers outside this range, behavior is undefined (will error at runtime).

LoweredValue for case on list builtins (PlutusV4 feature).

In PlutusV4, Case can be used directly on list constants: Case(list, [consBranch, nilBranch]) where Cons = index 0 (receives head and tail as arguments) and Nil = index 1 (no arguments).

The consBranch must be a lambda that accepts head and tail: λhead.λtail.body

NOTE: This type is only correct for SumBuiltinList scrutinees (Plutus Constant.List). For native SumUplcConstr lists, Cek dispatches by constructor tag (Nil=0, Cons=1), which requires the opposite branch order. Intrinsic/match lowerings that may produce either kind should keep list matches at the SumBuiltinList boundary.

LoweredValue for Case on Pair (PlutusV4+).

In PlutusV4, Case can be used directly on pair constants: Case(pair, [branch]) where the branch receives fst and snd as arguments.

The branch must be a lambda that accepts fst and snd: λfst.λsnd.body

LoweredValue for ChooseList builtin (PlutusV1-V3).

Uses the ChooseList builtin with delayed branches: Force(ChooseList list (Delay nil) (Delay cons))

ComplexLoweredValue is a base trait for lowered values that consist of multiple subvalues. ownVars - var that used in subvalues but defined in this value. (i.e. not propagated up in dominatedUplevelVars)

Represent a variable which is dependent on another variable. i.e. var x1 = (toOtherReperesentation(y))

Values with id which can be represented by variables (if needed).

Identificatin is id.

Resolves intrinsic implementations for method calls based on argument representation and protocol version.

When the lowering encounters a method call like list.isEmpty, the resolver checks if there is an optimized intrinsic implementation for the argument's runtime representation (e.g., SumDataList). If found, it substitutes the provider's body (with the actual argument SIR) and re-lowers it. Already-lowered arguments are tracked via the annotation-keyed argCache mechanism (see LoweringContext.argCache), so re-lowering the substituted SIR returns the pre-lowered value without recomputation.

The registry is hardcoded — adding new intrinsic providers requires editing the registry and creating the @Compile provider object.

Representation for lambda function. By default, lanbda-s accept default reperesentation for input and output types. But when we pass functions to type-parametrized functions, then calling party does not know about real parameter types and can't use default representation, so pass parameters as packed data.

So, we translate higher-order functions to packed data representation when pass as arguments to type-parametrized functions.

But some builtin function accept more then one representations, because they poplymorhiocj on plutus level. (i.e. have builtin type variables). For example: makeCons work with SumDataList and SumPairDataList, so we need to reevaluate representation when argument type is known.

Leaf values have no subvalues and no uplevel variable dependencies. Constants, errors, and builtin refs are all leaves.

SEA of nodes - like representation. E.e. each value is node, which manage dependencies. LoweredValue:

• represents a value in lowered SIR, which is
• a generator of a block of code with generate specific SIRType in specific representation. -- (representation is LoweredValueRepresentation, which can be term or data in specific encoding)
• some lowered values can be named (see IdentifiableLoweredValue and maintain a set of dependencies) The idea of SEA of nodes -- than we can generate code 'by need' based on dependencies. I.e. if value not used at all - code will not be generated, if value used once -- no intermediate construction will be created and code will be generated directly in place of usage. If value used multiple times -- it will be generated near the usage (i.e. in the nearest block, which contains all depended).

The idea of SEA of nodes described in the paper: Cliff Click. 1995. Global code motion/global value numbering. SIGPLAN Not. 30, 6 (June 1995), 246–257. "https://doi.org/10.1145/223428.207154"

We have a quite different code (non-SSA form, only dominators), but the main idea of relaxing order is the same,

representation, depends on the type of the value.

Equality lowering — recognizes equalsRepr(a, b) (and the FunctionalInterface Eq path) and emits the most efficient comparison for the lhs/rhs representation pair.

Dispatch order in generateEqualsForRepr:

• Primitives (Integer, ByteString, String): specialized builtins
• BLS curve elements: bls12_381_G1/G2_equal
• BLS MlResult, Fun: compile error (no equality)
• @UplcRepr(UplcConstr) products: field-by-field via generateProdUplcConstrEquals
• @UplcRepr(UplcConstr) sums: native letrec via generateSumUplcConstrEquals
• Everything else: convert to Data, equalsData

Proxy wrapping the value's sirType with an outer TypeLambda binding free TypeVars not bound by any inner TypeLambda. When the underlying value is a Lambda, its LambdaRepresentation.funTp is rewrapped consistently so representation.funTp == sirType. Used when an inlined intrinsic body has dropped its outer TypeLambda and downstream lvApply.reprFun needs the bound TypeVars to resolve element reprs.

Mixin for representations that always store values as Data at the UPLC level.

Dispatch layer for product-typed operations. Single entry point for Prod-side toRepresentation. Routing typegens (ProductCase*, OneElementWrapperEmitter) extend the base SirTypeUplcGenerator only — they don't have toRepresentation at all, so direct calls are compile-time errors. See docs/local/claude/compiler/sum-prod-dispatch-design.md.

Proxy whose sirType is origin.sirType with an @UplcRepr annotation derived from the value's actual representation, attached at the return / scalar position. representation is inherited from origin, so the annotation can never drift from the emitted bytes.

A proxy which change only the representation of the input value (without changing the underlying generated code)

Lowered value which exists to create a scope for the set of variables. Need to prevent pulling out variables outsiode scope from lambda-s, while we have not yet full tracking of control-flow dependencies. (i.e. variables defined inside scope should not be pulled outside of it automatically by lambda barrier logic)

Dispatch layer for sum-typed operations. Single entry point for Sum-side toRepresentation; routing typegens (DataConstrEmitter, SumCaseUplcConstr*, SumListEmitterCommon subclasses, plus the Prod typegens that delegate via ProdDispatch) extend the base SirTypeUplcGenerator only — they don't have toRepresentation at all, so direct calls are compile-time errors. See docs/local/claude/compiler/sum-prod-dispatch-design.md.

A proxy which changes the input value to be specific type and representation.

TypeVarRepresentation is used for type variables. Usually this is a synonym for some other specific-type representation.

• Transparent: builtin UPLC type variable, can be freely used in any representation
• Fixed: Scala type variable with native representation
• Fixed: Scala type variable that flows into list element position, uses Data representation (explicit per-element representation requires an @UplcRepr annotation).