uplc/UPLC.ts
UPLC overview
UPLC (Untyped Plutus Lambda Calculus) Module
Effect Schema-based types and transformations for UPLC programs. Implements the Flat serialization format used by Plutus Core.
Added in v2.0.0
Table of contents
arbitrary
arbitrary
FastCheck arbitrary for generating UPLC programs.
Signature
export declare const arbitrary: FastCheck.Arbitrary<Program>Added in v2.0.0
simpleTermArbitrary
FastCheck arbitrary for generating simple UPLC programs.
Signature
export declare const simpleTermArbitrary: FastCheck.Arbitrary<Term>Added in v2.0.0
cbor
applyDoubleCborEncoding
Apply double CBOR encoding to a hex string if not already encoded. Wraps the bytes in two layers of CBOR bytestring.
Signature
export declare const applyDoubleCborEncoding: (script: string) => stringAdded in v2.0.0
applySingleCborEncoding
Apply single CBOR encoding to a hex string if not already encoded. Wraps the bytes in a CBOR bytestring.
Signature
export declare const applySingleCborEncoding: (script: string) => stringAdded in v2.0.0
getCborEncodingLevel
Get the CBOR encoding level of a script.
Signature
export declare const getCborEncodingLevel: (script: string) => "double" | "single" | "none"Added in v2.0.0
constants
BuiltinFunctions
All builtin functions supported in Plutus V3. Order is significant - index is used in flat encoding.
Signature
export declare const BuiltinFunctions: readonly [
"addInteger",
"subtractInteger",
"multiplyInteger",
"divideInteger",
"quotientInteger",
"remainderInteger",
"modInteger",
"equalsInteger",
"lessThanInteger",
"lessThanEqualsInteger",
"appendByteString",
"consByteString",
"sliceByteString",
"lengthOfByteString",
"indexByteString",
"equalsByteString",
"lessThanByteString",
"lessThanEqualsByteString",
"sha2_256",
"sha3_256",
"blake2b_256",
"verifyEd25519Signature",
"appendString",
"equalsString",
"encodeUtf8",
"decodeUtf8",
"ifThenElse",
"chooseUnit",
"trace",
"fstPair",
"sndPair",
"chooseList",
"mkCons",
"headList",
"tailList",
"nullList",
"chooseData",
"constrData",
"mapData",
"listData",
"iData",
"bData",
"unConstrData",
"unMapData",
"unListData",
"unIData",
"unBData",
"equalsData",
"mkPairData",
"mkNilData",
"mkNilPairData",
"serialiseData",
"verifyEcdsaSecp256k1Signature",
"verifySchnorrSecp256k1Signature",
"bls12_381_G1_add",
"bls12_381_G1_neg",
"bls12_381_G1_scalarMul",
"bls12_381_G1_equal",
"bls12_381_G1_hashToGroup",
"bls12_381_G1_compress",
"bls12_381_G1_uncompress",
"bls12_381_G2_add",
"bls12_381_G2_neg",
"bls12_381_G2_scalarMul",
"bls12_381_G2_equal",
"bls12_381_G2_hashToGroup",
"bls12_381_G2_compress",
"bls12_381_G2_uncompress",
"bls12_381_millerLoop",
"bls12_381_mulMlResult",
"bls12_381_finalVerify",
"keccak_256",
"blake2b_224",
"integerToByteString",
"byteStringToInteger",
"andByteString",
"orByteString",
"xorByteString",
"complementByteString",
"readBit",
"writeBits",
"replicateByte",
"shiftByteString",
"rotateByteString",
"countSetBits",
"findFirstSetBit",
"ripemd_160"
]Added in v2.0.0
DataTypeTags
Type tags for flat encoding.
Signature
export declare const DataTypeTags: {
readonly Integer: 0
readonly ByteString: 1
readonly String: 2
readonly Unit: 3
readonly Bool: 4
readonly Data: 8
}Added in v2.0.0
TermTags
Term tags for flat encoding.
Signature
export declare const TermTags: {
readonly Var: 0
readonly Delay: 1
readonly Lambda: 2
readonly Apply: 3
readonly Constant: 4
readonly Force: 5
readonly Error: 6
readonly Builtin: 7
readonly Constr: 8
readonly Case: 9
}Added in v2.0.0
constructors
applyTerm
Create an application term.
Signature
export declare const applyTerm: (fn: Term, argument: Term) => TermAdded in v2.0.0
builtinTerm
Create a builtin term.
Signature
export declare const builtinTerm: (fn: BuiltinFunction) => TermAdded in v2.0.0
caseTerm
Create a case term.
Signature
export declare const caseTerm: (term: Term, cases: ReadonlyArray<Term>) => TermAdded in v2.0.0
constantTerm
Create a constant term.
Signature
export declare const constantTerm: (valueType: DataType, value: ConstantValue) => TermAdded in v2.0.0
constrTerm
Create a constructor term.
Signature
export declare const constrTerm: (tag: bigint, terms: ReadonlyArray<Term>) => TermAdded in v2.0.0
dataConstant
Create a UPLC Constant term from PlutusData. The data is CBOR-encoded and stored as a constant of type Data.
Uses Aiken-compatible encoding (indefinite-length arrays/maps) by default,
which matches the on-chain format. An optional options parameter allows
customizing the CBOR encoding for testing or compatibility purposes.
Signature
export declare const dataConstant: (data: Data.Data, options?: CBOR.CodecOptions) => TermAdded in v2.0.0
delayTerm
Create a delay term.
Signature
export declare const delayTerm: (term: Term) => TermAdded in v2.0.0
errorTerm
Create an error term.
Signature
export declare const errorTerm: TermAdded in v2.0.0
forceTerm
Create a force term.
Signature
export declare const forceTerm: (term: Term) => TermAdded in v2.0.0
lambdaTerm
Create a lambda term.
Signature
export declare const lambdaTerm: (name: bigint, body: Term) => TermAdded in v2.0.0
makeSemVer
Create a SemVer string.
Signature
export declare const makeSemVer: (major: number, minor: number, patch: number) => SemVerAdded in v2.0.0
varTerm
Create a variable term.
Signature
export declare const varTerm: (name: bigint) => TermAdded in v2.0.0
encoding
toFlatBytes
Encode a UPLC program to flat-encoded bytes.
Signature
export declare const toFlatBytes: (a: Program, overrideOptions?: ParseOptions) => anyAdded in v2.0.0
toFlatHex
Encode a UPLC program to flat-encoded hex string.
Signature
export declare const toFlatHex: (a: Program, overrideOptions?: ParseOptions) => stringAdded in v2.0.0
errors
UPLCError (class)
Error class for UPLC related operations.
Signature
export declare class UPLCErrorAdded in v2.0.0
internal
decodeDoubleCborHexToFlat
Decode a double CBOR-encoded script hex to flat bytes.
Signature
export declare const decodeDoubleCborHexToFlat: (hex: string) => Uint8ArrayAdded in v2.0.0
model
ConstantValue (type alias)
Value types for UPLC constants.
Signature
export type ConstantValue =
| bigint
| Uint8Array
| string
| boolean
| null
| { readonly items: ReadonlyArray<ConstantValue> }
| { readonly index: bigint; readonly fields: ReadonlyArray<ConstantValue> }
| ReadonlyMap<ConstantValue, ConstantValue>Added in v2.0.0
DataType (type alias)
UPLC data type (recursive for pair/list).
Signature
export type DataType =
| PrimitiveDataType
| { readonly pair: readonly [DataType, DataType] }
| { readonly list: DataType }Added in v2.0.0
PrimitiveDataType (type alias)
Primitive UPLC data types.
Signature
export type PrimitiveDataType = "Integer" | "ByteString" | "String" | "Unit" | "Bool" | "Data"Added in v2.0.0
Program (class)
UPLC Program - contains version and body term.
Signature
export declare class ProgramAdded in v2.0.0
toJSON (method)
Signature
toJSON()toString (method)
Signature
toString(): string[Inspectable.NodeInspectSymbol] (method)
Signature
[Inspectable.NodeInspectSymbol](): unknown[Equal.symbol] (method)
Signature
[Equal.symbol](that: unknown): boolean[Hash.symbol] (method)
Signature
[Hash.symbol](): numberSemVer (type alias)
Semantic version for UPLC programs.
Signature
export type SemVer = `${number}.${number}.${number}`Added in v2.0.0
Term (type alias)
UPLC Term - recursive union type. Uses de Bruijn indices (bigint) for variable names.
Signature
export type Term =
| { readonly type: "Var"; readonly name: bigint }
| { readonly type: "Lambda"; readonly name: bigint; readonly body: Term }
| { readonly type: "Apply"; readonly function: Term; readonly argument: Term }
| { readonly type: "Constant"; readonly valueType: DataType; readonly value: ConstantValue }
| { readonly type: "Builtin"; readonly function: BuiltinFunction }
| { readonly type: "Delay"; readonly term: Term }
| { readonly type: "Force"; readonly term: Term }
| { readonly type: "Constr"; readonly tag: bigint; readonly terms: ReadonlyArray<Term> }
| { readonly type: "Case"; readonly term: Term; readonly cases: ReadonlyArray<Term> }
| { readonly type: "Error" }Added in v2.0.0
TermEncoded (type alias)
Encoded Term type (for Schema transformation).
Signature
export type TermEncoded =
| { readonly type: "Var"; readonly name: string }
| { readonly type: "Lambda"; readonly name: string; readonly body: TermEncoded }
| { readonly type: "Apply"; readonly function: TermEncoded; readonly argument: TermEncoded }
| { readonly type: "Constant"; readonly valueType: DataType; readonly value: ConstantValue }
| { readonly type: "Builtin"; readonly function: BuiltinFunction }
| { readonly type: "Delay"; readonly term: TermEncoded }
| { readonly type: "Force"; readonly term: TermEncoded }
| { readonly type: "Constr"; readonly tag: string; readonly terms: ReadonlyArray<TermEncoded> }
| { readonly type: "Case"; readonly term: TermEncoded; readonly cases: ReadonlyArray<TermEncoded> }
| { readonly type: "Error" }Added in v2.0.0
parsing
fromCborHexToProgram
Decode a CBOR-encoded script to UPLC Program. Handles both single and double CBOR encoding automatically.
Signature
export declare const fromCborHexToProgram: (hex: string) => ProgramAdded in v2.0.0
fromDoubleCborEncodedHex
Decode a UPLC program from double CBOR-encoded hex string. This is the format used by compiled Plutus scripts.
Signature
export declare const fromDoubleCborEncodedHex: (hex: string) => ProgramAdded in v2.0.0
fromFlatBytes
Decode a UPLC program from flat-encoded bytes.
Signature
export declare const fromFlatBytes: (i: any, overrideOptions?: ParseOptions) => ProgramAdded in v2.0.0
fromFlatHex
Decode a UPLC program from flat-encoded hex string.
Signature
export declare const fromFlatHex: (i: string, overrideOptions?: ParseOptions) => ProgramAdded in v2.0.0
parseSemVer
Parse version components from SemVer string.
Signature
export declare const parseSemVer: (v: SemVer) => { major: number; minor: number; patch: number }Added in v2.0.0
schemas
FromFlatBytes
Transform from flat-encoded bytes to Program.
Signature
export declare const FromFlatBytes: Schema.transform<
typeof Schema.Uint8ArrayFromSelf,
Schema.SchemaClass<Program, Program, never>
>Added in v2.0.0
FromFlatHex
Transform from flat-encoded hex string to Program.
Signature
export declare const FromFlatHex: Schema.transform<
Schema.Schema<Uint8Array, string, never>,
Schema.SchemaClass<Program, Program, never>
>Added in v2.0.0
TermSchema
Schema for UPLC Term (recursive union).
Signature
export declare const TermSchema: Schema.Schema<Term, TermEncoded, never>Added in v2.0.0
script
applyParamsToScript
Applies a list of parameters (PlutusData values) to a Plutus script.
The function takes a CBOR-encoded script and applies each parameter by wrapping the script body in a series of Application nodes, where each parameter is converted to a UPLC Constant of type Data.
Uses Aiken-compatible encoding (indefinite-length arrays/maps) by default. Pass custom CBOR options for compatibility with other encoding formats.
Signature
export declare const applyParamsToScript: (
plutusScript: string,
params: ReadonlyArray<Data.Data>,
options?: CBOR.CodecOptions
) => stringAdded in v2.0.0
applyParamsToScriptWithSchema
Applies a list of parameters (PlutusData values) to a Plutus script, with an optional schema for type-safe parameter conversion.
Signature
export declare const applyParamsToScriptWithSchema: <T>(
plutusScript: string,
params: ReadonlyArray<T>,
toData: (value: T) => Data.Data
) => stringAdded in v2.0.0
utils
BuiltinFunction (type alias)
Signature
export type BuiltinFunction = (typeof BuiltinFunctions)[number]