Keleusma is a total functional stream processor that compiles to bytecode and runs on a stack-based virtual machine. The language ships with a static worst-case-execution-time bound and a static worst-case-memory-usage bound that a load-time verifier proves before any program runs. The 0.2.0 release covered in an earlier article introduced cryptographic module signing, information-flow labels, newtypes with refinement predicates, and a reset instruction-set architecture. The 0.1.1 pre-release was covered in the first article of this series.
Version 0.2.1 was tagged on 2026-07-08.
It is a consolidation release
that fills gaps in the surface syntax,
adds a general const-generics facility,
turns scripts into first-class shell citizens,
provides source-level debugging support,
tightens the load-time verifier,
and adds an operator-configured deployment policy
for signed and encrypted bytecode.
Version 0.2.2 was tagged on 2026-07-09,
the day after 0.2.1.
It is a build-fix and tooling release
on the self-hosting groundwork line.
It repairs cross-target and continuous-integration regressions
from 0.2.1
that broke the flagship Cortex-M embedded targets
and the verify-without-floats feature combination,
lands the learning guide
as a bilingual mdbook
that is now served
at
the hosted book URL,
lands the initial scaffold
of
the self-hosted-compiler subproject
that the 0.3.0 release will complete,
and codifies the release process
with a mandatory green-continuous-integration gate.
The language surface
is
unchanged from 0.2.1,
and no wire-format or bytecode-version change accompanies the release.
The self-hosting concept was treated
for the software case
in the streaming compilers series conclusion
and for silicon in
the recent hardware article.
Readers who want to try the language without installing anything can use the browser-based playground, which compiles and verifies programs through a WebAssembly build of the compiler and reports worst-case execution time and memory bounds live. The playground is served alongside the hosted book.
This article walks through the material additions of the 0.2.x line with runnable examples, covering the 0.2.1 language features that 0.2.2 preserves and the 0.2.2 tooling additions that are relevant to a getting-started walkthrough. Every code listing below was executed with the version recorded in the Software Versions section, and every reported output is the actual output produced. The article is an on-ramp for readers already familiar with 0.2.0. Readers new to the language should start with the bundled guide and its installation chapter.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-07-10 22:05:01 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 25.5.0: Mon Apr 27 20:38:56 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6000 arm64
# Keleusma
$ keleusma --version
keleusma 0.2.2
Keleusma 0.2.2 is published on crates.io as a library
and as the separate command-line crate keleusma-cli.
The source lives on GitHub
and the application-programming-interface documentation is on docs.rs.
The install path is unchanged from 0.2.0.
The 0.2.2 release additionally repairs
the 32-bit and no_std embedded builds
that 0.2.1 broke,
so a fresh install
from source
on the flagship Cortex-M targets
now succeeds without a manual patch.
git clone https://github.com/sgeos/keleusma
cd keleusma
cargo install --path keleusma-cli --bin keleusma
Confirm the installation.
$ keleusma --version
keleusma 0.2.2
To embed the runtime in a Rust program rather than use the tool, add the library crates to a project.
[dependencies]
keleusma = "0.2"
keleusma-arena = "0.3.1"
The keleusma-arena version requirement
tightens from 0.3 to 0.3.1
in 0.2.2
because the runtime now consumes
additive helpers
that
keleusma-arena 0.3.1
exposes.
Version 0.2.0 added the five bitwise opcodes
BitAnd, BitOr, BitXor, Shl, and Shr
without a grammar to reach them from source.
Version 0.2.1 supplies the grammar
and, in the same pass,
rearranges the boolean operators
so that the two families never disambiguate by operand type.
The bitwise family uses the letter-prefixed names
band, bor, bxor, and the prefix bnot.
The operators apply to Word, Byte, and the parameterized Multiword<N>.
On a Multiword the operation runs limb by limb
with no cross-limb interaction.
On a Byte the operation runs at the byte width,
so bnot 0Byte is 255Byte.
fn main() -> Word {
let mask: Word = 0b1100 band 0b1010;
let all: Word = 0b1100 bor 0b0011;
let flipped: Word = 0b1010 bxor 0b1111;
let inverted: Byte = bnot 0Byte;
mask + all + flipped + (inverted as Word)
}
$ keleusma run 01_bitwise.kel
283
The shift family uses the assembly mnemonics
lsl (logical left),
asl (arithmetic left),
lsr (logical right),
and asr (arithmetic right).
The asl and lsl operators produce the same bit pattern
but asl denotes the multiplicative interpretation x * 2^k
and therefore admits the overflow and underflow arms
of the checked-arithmetic construct.
A variable shift amount is admissible
and the worst-case bound is preserved,
because the multi-word case is unrolled
over the compile-time word count
with runtime index arithmetic
and branch-free bounds guards.
fn main() -> Word {
let left: Word = 1 lsl 4;
let arith_left: Word = 3 asl 2;
let logical_right: Word = 128 lsr 3;
let arith_right: Word = (0 - 8) asr 1;
left + arith_left + logical_right + arith_right
}
$ keleusma run 02_shift.kel
40
The boolean family has two subfamilies.
The eager and, or, xor, and prefix not
always evaluate both operands.
The short-circuit andalso and orelse
skip the right operand
when the left already decides the result.
The eager forms are the branch-free default
because a definitive worst-case-execution-time bound
prefers branch-free code.
The short-circuit forms remain available
for cases where skipping the right operand is intended.
Selection is by operator name
and is never inferred from operand type.
fn main() -> Word {
let a: bool = true and false;
let b: bool = true or false;
let c: bool = true xor true;
let d: bool = not false;
let e: bool = true andalso false;
let f: bool = false orelse true;
let count: Word =
(if a { 1 } else { 0 })
+ (if b { 2 } else { 0 })
+ (if c { 4 } else { 0 })
+ (if d { 8 } else { 0 })
+ (if e { 16 } else { 0 })
+ (if f { 32 } else { 0 });
count
}
$ keleusma run 03_boolean.kel
42
Version 0.2.0 accepted a fixed-point width parameter
on the Multiword<N, F> type as a special case.
Version 0.2.1 replaces the special case
with a general const-generics facility.
A definition may be parameterized
by a compile-time constant of type Word
in addition to its type parameters.
The parameter is introduced by the const keyword
and serves in a type position
as an array length or a Multiword parameter,
and in a value position inside a function body
as an ordinary Word.
fn tag_first<const n: Word>(buf: [Word; n]) -> Word {
buf[0] + buf[n - 1] + n
}
fn main() -> Word {
let five: [Word; 5] = [10, 20, 30, 40, 50];
let three: [Word; 3] = [7, 14, 21];
tag_first::<5>(five) + tag_first::<3>(three)
}
$ keleusma run 04_const_generics.kel
96
Const arguments are always explicit
because they cannot be inferred from value arguments.
A call writes a turbofish f::<8>(...),
a struct construction writes Buf::<8> { ... },
and a type reference writes Buf<8>.
A const argument may be a total arithmetic expression
over +, -, and *,
so Buf<n + 1> and Multiword<2 * n> are admissible.
Division and modulo are excluded from const arithmetic
so evaluation is total.
Monomorphization substitutes every const parameter to a concrete literal
before the load-time analyses run.
Every array length,
every Multiword parameter,
and every loop bound in the specialized code
is therefore a literal,
and the worst-case-execution-time
and worst-case-memory-usage analyses
observe no symbolic constant.
The static bounds are preserved unchanged.
A Keleusma script may begin with a shebang line and become a directly executable file on Unix.
#!/usr/bin/env keleusma
fn main() -> Word {
12 * 42
}
Mark it executable and run it as a command.
$ chmod +x 05_shebang.kel
$ ./05_shebang.kel
504
The keleusma command-line frontend runs a bare path as a run invocation,
and the lexer skips the shebang line
while preserving source line numbers in diagnostics.
Combined with the shell native bundle,
a script becomes a portable command-line orchestrator
that delegates work to POSIX tools,
drives control flow on the returned Word exit codes,
and sets its own process exit code with shell::exit.
The shell bundle exposes a script’s own arguments
through shell::arg(i) and shell::arg_count().
Index zero is the script path,
and indices one and above are the positional arguments
that the launcher passed after it,
mirroring the shell variables $0 and $1.
The shell::arg native returns Option<Text>
so an out-of-range index is a total operation
that the script destructures with match.
#!/usr/bin/env keleusma
use shell::arg
use shell::arg_count
fn label(a: Option<Text>) -> Word {
match a {
Option::Some(_name) => 1,
Option::None => 0,
}
}
fn main() -> Word {
let n: Word = shell::arg_count();
let first_present: Word = label(shell::arg(1));
n * 10 + first_present
}
$ chmod +x 06_args.kel
$ ./06_args.kel alpha beta
31
The output encodes the argument count n = 3
in the tens digit
and the presence of index one
in the ones digit.
The command-line frontend also accepts a -- terminator
after which every token is treated as a script argument
regardless of shape.
A companion native shell::run_full(cmd) -> (Word, Text, Text)
returns the exit code together with both standard-output
and standard-error streams,
complementing shell::run which captures and discards
the error stream.
The new assert statement expresses a compile-out debug assertion
over a bool condition.
An optional message argument attaches a diagnostic string.
fn safe_scale(base: Word, factor: Word) -> Word {
assert factor >= 0, "factor must be non-negative";
base * factor
}
fn main() -> Word {
safe_scale(6, 7)
}
Under a debug build the compiler emits a runtime check
that traps with VmError::AssertionFailed
when the condition is false,
together with a strippable debug record
carrying the source span
and the optional message.
$ keleusma compile 07_assert.kel --debug -o 07_assert.bin
wrote 07_assert.bin (3812 bytes)
$ keleusma run 07_assert.bin
42
The next example flips the argument sign and shows the diagnostic.
fn safe_scale(base: Word, factor: Word) -> Word {
assert factor >= 0, "factor must be non-negative";
base * factor
}
fn main() -> Word {
safe_scale(6, 0 - 7)
}
$ keleusma compile 07b_assert_fail.kel --debug -o 07b_assert_fail.bin
wrote 07b_assert_fail.bin (3892 bytes)
$ keleusma run 07b_assert_fail.bin
error: vm: AssertionFailed
Under an ordinary compile the statement compiles out entirely
and contributes no opcodes.
The assert keyword is not reserved
outside statement position,
so assert(x) at expression position
remains a call to a user-defined function.
The virtual machine also records the source position of the trap
through the internal fault_location field,
which a host program consumes
through the Vm::fault_source_location() application-programming-interface
to map the trap to a source span.
The command-line frontend used for the demonstration above
prints the VmError alone
and leaves the span-resolution step
to a host program that consumes the library directly.
Every mathematically partial operation now has a defined contract
and an opt-in source-level handling construct,
so a program can be made total at the source level
rather than relying on a runtime trap.
Checked arithmetic over Word, Byte, Float, and Fixed<N>
uses the arm family ok, overflow, underflow, and zero_divisor.
An omitted overflow or underflow arm
defaults to two’s-complement wrapping.
Inside an arm body
the keywords saturate_max and saturate_min
stand for the largest and smallest value of the operand type
and let a program clamp an out-of-range result
to the edge of the range.
Array indexing uses invalid_index.
Refinement-newtype construction uses invalid_newtype.
The discriminant-to-enum conversion uses ok,
payload_discriminant,
and invalid_discriminant.
Fallible native calls use error(code),
with the host reporting the Word code
through the new KeleusmaError derive.
fn safe_div(a: Word, b: Word) -> Word {
a / b {
ok(q) => q,
zero_divisor(_n) => 0,
}
}
fn saturate_add_byte(a: Byte, b: Byte) -> Byte {
a + b {
ok(v) => v,
overflow(_) => saturate_max,
}
}
fn main() -> Word {
let q: Word = safe_div(84, 2);
let z: Word = safe_div(10, 0);
let s: Byte = saturate_add_byte(200Byte, 100Byte);
q + z + (s as Word)
}
$ keleusma run 09_partial.kel
297
The three checked operations produce
safe_div(84, 2) = 42,
safe_div(10, 0) = 0 through the zero_divisor arm,
and saturate_add_byte(200Byte, 100Byte) = 255Byte
through the saturating overflow arm,
summing to 297.
The virtual machine traps recoverably
on an unhandled partial operation
through specific VmError variants.
The specification of every runtime fault
lives in the reference document
Handling Partial Operations.
Compiled bytecode can carry optional per-chunk debug metadata
that maps op-stream positions back to source.
The compile flag --debug emits it,
and the new subcommand keleusma strip removes it,
producing a release artefact
byte-identical to a non-debug compile of the same source.
$ keleusma compile 08_strip.kel -o 08_release.bin
wrote 08_release.bin (2456 bytes)
$ keleusma compile 08_strip.kel --debug -o 08_debug.bin
wrote 08_debug.bin (3372 bytes)
$ keleusma strip 08_debug.bin -o 08_stripped.bin
stripped 08_debug.bin -> 08_stripped.bin (2456 bytes)
$ cmp 08_release.bin 08_stripped.bin && echo "IDENTICAL"
IDENTICAL
The metadata lives in a chunk-local pool in the wire format’s auxiliary body and never in the opcode stream. A debug build and a release build therefore share an identical opcode stream for the same source, and stripping is a pure subtraction rather than a transform. The subcommand refuses signed or encrypted input, because rewriting the body invalidates a signature. The supported ordering is compile, then strip, then sign.
The metadata catalogue covers twelve record kinds including source-span records for statements, line-number records, variable-name records, call-site records, type annotations, information-flow-label annotations, generic-instantiation records, verifier witnesses, worst-case-execution-time markers, breakpoint candidates, assertion contexts, and optimisation markers at refinement-elision sites.
Building on the 0.2.0 module-signing facility, the command-line frontend gains an operator-configured execution policy that constrains which bytecode may run, analogous to an enrolled-key model in a firmware trust framework.
Strict signing activates when a trust store is in force.
Configuration is by the environment variable
KELEUSMA_TRUSTED_KEYS_DIR naming a directory of *.pub verifying keys,
or by the platform-conventional directory
/etc/keleusma/trusted_keys,
or by the force flag KELEUSMA_REQUIRE_SIGNED=1.
When strict signing is active,
the frontend rejects source files and unsigned bytecode,
admits signed bytecode only when the signature validates
against an enrolled signer,
and rejects the command-line flag --verifying-key
so an unprivileged operator cannot relax the system-managed trust list.
Strict encryption activates symmetrically
through KELEUSMA_DECRYPTION_KEYS_DIR
and KELEUSMA_REQUIRE_ENCRYPTED.
The two modes compose into four policy states from the permissive default through fully locked-down. The operator manual with air-gapped, production-fleet, and kiosk deployment scenarios is the reference document Security Policy.
Three internal changes in 0.2.1 are worth naming even though the source language is not directly affected.
The composite runtime representation is now flat bytes
resident in the host arena
rather than heap-allocated Vec and String graphs.
The runtime Value slot is thirty-two bytes,
down from forty,
pinned by a compile-time size assertion.
Composite construction is a bump-pointer allocation
in the arena’s transient region
with no global allocator,
so a composite-building script runs on a no_std target
without a global heap.
Worst-case-memory-usage bounds are correspondingly tighter
and now reflect the language’s fixed-size guarantee
rather than the previous Vec and String over-approximation.
The load-time verifier gains a typed operand-stack pass after the manner of the Java Virtual Machine and WebAssembly verifiers. The pass reconstructs the flat shape of every operand-stack entry and local slot by a bytecode-level type-preservation abstract interpretation. It validates every compiler-baked composite, field, and array-element offset against the canonical flat layout of the accessed type, closing several audit findings that were previously trusted at runtime under a debug assertion. It upgrades the operand-depth pass from max-of-branch-depths to an exact-height join. It enforces loop back-edge operand-stack neutrality. And it validates wire-carried shared-slot offsets against the shared-data buffer.
Trait methods on generic structs and enums now resolve
on a concrete, type-generic, or const-generic receiver alike.
Monomorphization specializes each generic implementation once
per concrete instantiation of its target type,
substituting the implementation’s type and const parameters
through the method signatures
and bodies,
so a call on a Cell<Word> receiver reaches the specialized method
even when the source implementation was written against a generic Cell<T>.
Version 0.2.2 lands
the initial scaffold
of
the self-hosted-compiler subproject
that the 0.3.0 release will complete.
The scaffold
lives at
compiler/
in the repository
and comprises
the three-stage loop pipeline skeleton,
namely lexer, parser, and codegen,
along with
a Rust host driver
and
a release-by-release implementation plan.
No stage is implemented in 0.2.2.
The V0.2.x line
lands its prerequisites
across
the operator surface,
the const-generics facility,
the flat-byte composite representation,
the typed operand-stack verifier pass,
the debug metadata,
and
the strict-mode deployment policy
that
the earlier sections of this article
walk through.
Version 0.3.0
will
turn the scaffold
into a working compiler
written in Keleusma
that compiles Keleusma.
The self-hosting concept was treated at length for the software case in the streaming compilers series conclusion, which discusses the coalgebraic fixed-point condition that a self-hosted compiler satisfies. It was treated for the silicon case in the recent article on self-hosted silicon compilation. The Keleusma standardization effort sits on the software side of that boundary and offers a candidate example of a compact-toolchain language design that a self-hosting compiler could reasonably compile itself with.
This article covers the material additions of the 0.2.x line
that are relevant to a getting-started walkthrough.
The complete language reference
is the hosted book,
whose 0.2.2 release migrated
the previously loose Markdown guide
into an mdbook
served
at
https://sgeos.github.io/keleusma/.
The book is bilingual
with English as the source
and Japanese
as
a gettext-based translation
that
0.2.2 also ships.
It teaches Keleusma from first principles
in a forty-chapter track
and covers the embedding surface for Rust hosts
in a second track.
Readers who prefer
to try the language
without installing anything
can use
the browser-based playground,
which
runs the compiler as WebAssembly
in the reader’s browser
and is served
from the hosted book site.
The reference for handling partial operations
is the partial-operations chapter.
The reference for information-flow labels
is the labels chapter.
The reference for deployment-policy configuration
is the Security Policy document.
The reference for shebang-executable scripts
is the Automation and Scripting document.
The bundled example scripts
are the seed material the guide builds on.
Two companion articles apply Keleusma to specific problem shapes. A verifiable control kernel develops the language around a small runtime kernel. Information-flow control, a deep dive develops the language around the security-labelled data model that Version 0.2.0 introduced.
Neither 0.2.1 nor 0.2.2 changes
the central promise the language makes.
Every accepted program still carries a static proof
of bounded execution time
and bounded memory usage.
What 0.2.1 adds
is completeness on the surface syntax
where 0.2.0 left gaps,
a general const-generics facility
that supersedes the earlier special case,
first-class scripting ergonomics
that turn a Keleusma file into a command-line tool,
source-level debugging support
that a debugger or host program can consume,
a tightened load-time verifier
that closes several audit findings,
and an operator-configured deployment policy
for signed and encrypted bytecode.
What 0.2.2 adds
is
the initial scaffold
of the self-hosted-compiler subproject,
the learning guide
as
a bilingual mdbook
that is now
hosted online,
a browser-based playground
that runs the compiler
as WebAssembly,
and a codified release process
with
a mandatory green-continuous-integration gate.
The 0.2.2 release also repairs
build regressions
that 0.2.1 introduced
on 32-bit and no_std embedded targets
and in the verify-without-floats feature combination.
The pattern is consolidation
and tooling maturation,
not a change of direction.
The direction is set
by the 0.3.0 self-hosted-compiler goal
that the 0.2.2 scaffold
lays the groundwork for.
Most programmers have met access control. A file has permissions, a database row has an owner, an endpoint checks a token. Access control answers one question, namely who is allowed to read a piece of data. It says nothing about a second question that matters just as much, namely where that data is allowed to go after an authorized party has read it. A function that is permitted to read a password is not thereby permitted to write that password into a log file, a response body, or an analytics event. Governing that second question is the job of information-flow control, or IFC, and it is a tool most working programmers have never used.
This article is a deep dive. It covers the theory of IFC from the ground up, then explains what a first-class language feature can do that the usual alternatives cannot, and ends with a mechanical section on doing the heavy lifting in Keleusma, a total functional language whose 0.2.0 release makes information-flow labels part of the type system. The Keleusma examples were run with the version shown in the Software Versions section, and the output shown is the actual output. A getting-started tour of the language is available in a companion article, and a worked use of IFC as a governance gate appears in the control-kernel article.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-05-29 09:00:00 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 25.5.0: Mon Apr 27 20:38:56 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6000 arm64
# Keleusma
$ keleusma --version
keleusma 0.2.0
Access control is a gate at the door. It decides whether a principal may read or write a resource. Once the principal is inside with the data in hand, access control has nothing more to say. The data can be copied, transformed, combined with other data, and written anywhere the principal can write. The classic failure is the program that is authorized to read a secret and also authorized to write a public channel, and that, through a bug, copies the one into the other. No access-control check is violated. The leak happens entirely on the authorized side of the gate.
Information-flow control governs the propagation of data rather than the act of reading it. It tracks where information goes, and it enforces a policy on the paths data may take from its sources to its sinks.
The foundational model is due to Dorothy Denning (1976). Each piece of data carries a security class, or label, and the labels form a lattice, a partial order with a least upper bound for any pair. A simple lattice has two points, public below secret. A realistic system has many, one per compartment or category of sensitivity, and the order captures which classes are more restrictive. The rule of secure flow is then stated on the lattice. Information may flow from a lower class to an equal or higher class, never from a higher class to a lower one. Combining two values yields a value labelled with the least upper bound of their labels, so a computation that touches a secret produces a secret. Denning and Denning (1977) showed that a compiler could certify these flows mechanically. Lattice-based access control is the same lattice applied to the access question.
The formal goal that IFC aims at is noninterference, introduced by Goguen and Meseguer (1982). A system is noninterfering when its public outputs do not depend on its secret inputs. Vary the secret inputs however you like, and an observer of the public outputs sees no difference. If that holds, no information about the secrets can be inferred from the public behavior, which is exactly the confidentiality property wanted. Noninterference is the yardstick against which an information-flow mechanism is judged sound.
There are two ways information moves, and the second is the one that catches people out. An explicit flow is a direct assignment of data, copying a secret into a public variable. An implicit flow carries information through control flow. Branch on a secret, and the path taken reveals something about it, so any public value written differently on the two branches leaks a bit of the secret without ever copying it directly. The work of Volpano, Smith, and Irvine (1996) recast Denning’s analysis as a type system and proved that a well-typed program is noninterfering, which requires accounting for both kinds of flow. The survey by Sabelfeld and Myers (2003) is the standard map of the field that grew from this.
An information-flow policy can be enforced at run time or before the program runs. Dynamic enforcement, the family that includes taint tracking, attaches a taint bit to values as the program executes and checks it at sinks. Static enforcement, the language-based approach, encodes labels in the type system and rejects an offending program at compile time. Jif, the information-flow extension of Java built on the decentralized label model of Myers and Liskov, is the best-known static system. Keleusma is a static, type-based system in this lineage.
A policy of pure noninterference is too strict to be useful. A password checker must reveal one bit, namely whether the password matched. A statistics service must reveal an aggregate computed from private records. Every real system deliberately releases some information, and the controlled release is called declassification. Declassification is also the dangerous part, because it is the one place the noninterference guarantee is broken on purpose, and an attacker who can influence it can widen the leak. Sabelfeld and Sands (2009) organized the question into dimensions, namely what is released, who releases it, where in the system, and when. A sound IFC design makes declassification rare, explicit, and auditable.
A first Keleusma example shows a labelled value.
The operator classify attaches a label,
written after the value with an @.
fn main() -> Word@Master {
classify 42@Master
}
$ keleusma run 01_classify.kel
42
Word@Master is a Word carrying the label Master.
In the lattice, an unlabelled value is the public bottom,
and adding a label moves up to a more restrictive class.
The label exists only during checking.
It is erased before the program runs and costs nothing at run time.
A team that wants to control information flow today reaches for one of a few tools. Each falls short in a way a first-class language feature does not.
Taint-tracking libraries, the most common approach, follow explicit flows well. They tend to miss implicit flows, because tracking information through control flow at run time is expensive and is often skipped. A type-based system checks every path at compile time. Here a public output is computed on two branches selected by a secret, an implicit flow that copies nothing.
fn broadcast(x: Word) -> Word {
x
}
fn main() -> Word {
let secret = classify 1@Master;
let derived = if secret > 0 { 100 } else { 200 };
broadcast(derived)
}
$ keleusma run 04_implicit.kel
error: compile: 8:15: type error: argument to `broadcast` expects Word, got Word@Master
The comparison secret > 0 produces a labelled boolean,
the if over a labelled condition produces a labelled result,
and the attempt to broadcast that result is rejected
before the program runs.
A label in Keleusma is not a fence at a single point.
It is a dye that stains every value derived from a labelled one,
through arithmetic, comparison, and branching alike.
Dynamic taint tracking pays for itself on every operation, carrying and checking taint bits as the program runs. Keleusma labels are part of the type and are erased after checking, so the running program is identical to one written without labels. The guarantee is bought entirely at compile time.
A common lightweight approach wraps secret data in a newtype,
a Secret<T> that the type checker will not let you pass
where a plain T is expected.
This stops one mistake, the direct substitution,
but the protection ends the moment the value is unwrapped.
A newtype tracks nothing through a value derived by unwrapping,
computing, and rewrapping, and nothing through control flow.
It is a fence at the wrapper boundary, not a property of the data.
A first-class label propagates through the computation,
so the only way out is the explicit release operator,
not an unwrap method that any caller can invoke.
Manual code review and scattered sanitization
depend on a human noticing every path.
Humans miss implicit flows and derived leaks reliably.
With a first-class feature, the release of confidential data
happens at exactly one operator, declassify,
and a reviewer finds every release by searching for that one word.
fn broadcast(x: Word) -> Word {
x
}
fn main() -> Word {
let take = classify 42@Master;
broadcast(declassify take@Master)
}
$ keleusma run 03_declassify.kel
42
Remove the declassify, and the same program is rejected,
because the labelled value reaches a plain Word parameter.
$ keleusma run 02_leak.kel
error: compile: 7:15: type error: argument to `broadcast` expects Word, got Word@Master
The contrast with access control is worth restating. Access control would have permitted both the read and the write. The leak is on the authorized side of the gate, and only a flow-aware check sees it.
This section is the working reference for doing IFC heavy lifting with the Keleusma grammar. The information-flow chapter of the guide covers the same surface for the script author.
classify expr@Label adds a label to a value.
Adding a label only tightens flow restrictions,
so it is always admitted.
A label set is written in braces,
and the empty set is the public bottom of the lattice.
fn store(x: Word@{Secret, Pii}) -> Word@{Secret, Pii} {
x
}
fn main() -> Word@{Secret, Pii} {
let record = classify 7@{Secret, Pii};
store(record)
}
$ keleusma run 05_label_set.kel
7
Word@{Secret, Pii} carries two labels.
The labels are user-defined names, and their meaning is the programmer’s.
More labels mean a more restrictive class,
which is the powerset lattice of the chosen label names.
A label is part of the type, written T@Label.
The type checker propagates it through operations,
so the result of any expression that touches a labelled value
is itself labelled, as the implicit-flow example showed.
This is what makes the guarantee hold without the programmer
threading the label through by hand.
A flow is checked when a value crosses a boundary.
The boundaries are function parameter and return types,
shared data fields that the host reads and writes,
and private data fields that survive across a yield and resume.
A plain Word parameter accepts only an unlabelled Word,
so handing it a Word@Master is the rejected leak seen above.
Declaring a parameter or return with a label
states the policy at that boundary directly.
declassify expr@Label removes a label.
It is always admitted, but it is the one visible point
where confidential data is released,
and it is the place a review process must scrutinize,
consistent with the dimensions of
Sabelfeld and Sands.
Keep declassification rare and push it to a single chokepoint.
A label set is released the same way,
naming the labels to remove.
The positive label says what a value carries.
The negative label, written with a ! prefix,
says what a boundary refuses.
A parameter typed Word@!Secret accepts any value
that does not carry the Secret label.
fn publish(x: Word@!Secret) -> Word {
x
}
fn main() -> Word {
let value = classify 5@Public;
publish(value)
}
$ keleusma run 06_negative.kel
5
A value that does carry the forbidden label is rejected, with a diagnostic that names the offending label.
$ keleusma run 06b_negative_reject.kel
error: compile: 7:13: type error: argument 1 to `publish` carries the label `Secret` which the parameter's `!`-prefix declaration forbids
Negative labels are admitted only at boundary positions,
namely function parameters and returns and the shared and private
data fields, and only at the top level of a type,
not nested inside a tuple, array, or option.
A single position may not mix positive and negative labels.
Negative labels are a boundary clause rather than a propagating type,
so unlike positive labels they do not stain derived values.
The pattern that does most of the work is small.
Classify confidential data at its source.
Let the labels propagate untouched through the computation.
Type every output boundary so it refuses the labels,
either by leaving the boundary unlabelled
so it accepts only public data,
or by giving it a negative label that names what it forbids.
Release through a single declassify at one reviewed chokepoint.
The compiler then proves, before the program runs,
that no other path carries confidential data to an output.
A few boundaries of the Keleusma model are worth stating plainly.
The labels are user-defined and abstract.
The language enforces the lattice discipline,
but the meaning of each label, and whether it models
confidentiality or integrity, is a convention the programmer supplies.
Positive labels propagate through values,
including through branches, which is the strong part.
Negative labels are checked only at boundaries
and do not propagate through derived values in the 0.2.x line,
so they express what a position refuses rather than tracking absence
through a computation.
And declassification remains trusted.
The compiler guarantees that release happens only at a declassify,
but it cannot judge whether a given release is wise.
That judgment is the reviewer’s,
which is the reason the operator is made so visible.
Information-flow control answers a question access control cannot, namely where data may go after it is read. The theory is fifty years old, from Denning’s lattice through noninterference to the language-based type systems that enforce it, yet it remains absent from most working programmers’ toolkits. A first-class language feature catches the implicit flows that taint libraries miss, costs nothing at run time, cannot be bypassed by unwrapping a value, and reduces every release of a secret to one auditable keyword. Keleusma 0.2.0 puts that feature in the type system, where the guarantee is proved before the program runs.
Keleusma is a total functional stream-processing language that compiles to bytecode and runs on a stack-based virtual machine. It is an embedded language in the sense described in the first chapter of its guide. A Keleusma program is not a whole application. It is the small, exact, predictable part inside a larger host program, and it is built so that several things can be proved before the program ever runs, namely that every turn finishes within a bounded amount of time and a bounded amount of memory. This makes it a fit for embedded targets, real-time audio, game logic, and any setting where deterministic, bounded execution is a hard requirement.
Version 0.2.0 is the first publicly released line. It introduces cryptographic module signing, information-flow labels, newtypes with refinement predicates, and a reset instruction-set architecture. This article is a practical tour of the 0.2.0 release. Every code listing below was run with the version shown in the Software Versions section, and the output shown is the actual output produced. This article is an on-ramp, not a complete reference. The language ships with a forty-chapter guide that teaches Keleusma from first principles using music as its on-ramp, and a separate embedding track for Rust hosts. Readers who want the deep dive should start there. A previous article covered the earlier 0.1.1 pre-release, and a companion article uses Keleusma to build a verifiable control kernel.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-05-28 09:00:00 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 25.5.0: Mon Apr 27 20:38:56 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6000 arm64
# Keleusma
$ keleusma --version
keleusma 0.2.0
Keleusma is published on crates.io as a library,
with the command-line tool distributed as a separate crate,
keleusma-cli.
The source lives on GitHub,
and the API documentation is on docs.rs.
The installation chapter documents the canonical path, which is to install the command-line tool from a source checkout.
git clone https://github.com/sgeos/keleusma
cd keleusma
cargo install --path keleusma-cli --bin keleusma
Confirm the installation.
$ keleusma --version
keleusma 0.2.0
To embed the runtime in a Rust program rather than use the tool, add the library crate to a project instead.
[dependencies]
keleusma = "0.2"
The smallest unit of Keleusma is the fn, an atomic total function.
Atomic means it runs start to finish without pausing.
Total means it always finishes.
A fn takes its inputs, computes, and returns a result.
fn double(n: Word) -> Word {
n + n
}
fn main() -> Word {
double(21)
}
The command-line tool calls main and prints the returned value.
$ keleusma run 01_first_program.kel
42
Keleusma has a small set of primitive types.
Word is the machine integer and is signed.
Byte, Fixed, and Float cover byte-width integers,
fixed-point numbers, and IEEE 754 floating point.
bool is a truth value, and Text is textual data.
A binding is introduced with let and is immutable.
fn main() -> Word {
let count: Word = 6;
let factor: Word = 7;
let enabled: bool = true;
if enabled {
count * factor
} else {
count + factor
}
}
$ keleusma run 02_values.kel
42
A function may return Text, and the tool prints it directly.
fn main() -> Text {
"Keleusma"
}
$ keleusma run 03_text.kel
Keleusma
Keleusma has if and else, and it has match for pattern dispatch
over the variants of an enum.
enum Signal {
Red,
Yellow,
Green,
}
fn delay(s: Signal) -> Word {
match s {
Signal::Red => 30,
Signal::Yellow => 3,
Signal::Green => 25,
}
}
fn main() -> Word {
delay(Signal::Red) + delay(Signal::Green)
}
$ keleusma run 04_decisions.kel
55
Keleusma has for, and every repetition has a count
that is known before the loop begins.
There are no unbounded loops, and there is no recursion.
These omissions are the price of the bounded-execution promise.
Because local bindings are immutable, a for loop inside a fn
does not accumulate a result. Iteration that updates state
belongs in the loop and yield function categories,
which are covered below. The example returns a value
computed by direct indexing.
fn main() -> Word {
let steps = [2, 4, 8, 16];
for s in steps {
let _scaled = s * 10;
}
for i in 0..4 {
let _i2 = i * i;
}
steps[3] + steps[0]
}
$ keleusma run 05_repetition.kel
18
A struct groups named fields.
struct Note {
pitch: Word,
velocity: Word,
}
fn loudness(n: Note) -> Word {
n.pitch + n.velocity
}
fn main() -> Word {
let middle_c = Note { pitch: 60, velocity: 100 };
loudness(middle_c)
}
$ keleusma run 06_structs.kel
160
A function name may have several heads, each with its own
parameter pattern. The runtime tries the heads in source order
and dispatches to the first one whose pattern matches.
A head may carry a when guard after its return type.
fn classify(0) -> Word { 100 }
fn classify(n: Word) -> Word when n > 0 { 1 }
fn classify(n: Word) -> Word { 0 }
fn main() -> Word {
classify(0) + classify(5) + classify(0 - 3)
}
The first call matches the literal head and returns 100. The second matches the guarded head and returns 1. The third fails the guard and falls to the final head, returning 0.
$ keleusma run 07_multiheaded.kel
101
The pipeline operator |> threads the value on its left
as the first argument to the call on its right.
It reads left to right and reduces nesting in transformation chains.
fn inc(x: Word) -> Word { x + 1 }
fn triple(x: Word) -> Word { x * 3 }
fn main() -> Word {
13
|> inc()
|> triple()
}
$ keleusma run 08_pipeline.kel
42
Methods are declared in a trait and implemented for concrete types
in impl blocks. The generics and traits chapter
covers the full surface, including generic type parameters with bounds.
trait Doubler {
fn double(x: Word) -> Word;
}
impl Doubler for Word {
fn double(x: Word) -> Word {
x + x
}
}
fn main() -> Word {
let n: Word = 21;
n.double()
}
$ keleusma run 09_traits.kel
42
A newtype gives an underlying type a distinct name, and it may carry a refinement, a rule that every value must satisfy. The rule is an ordinary predicate function, and it is checked at every construction. A construction that provably breaks the rule is rejected before the program runs.
fn in_range(x: Word) -> bool { x >= 0 and x <= 127 }
newtype Velocity = Word where in_range;
fn raw(v: Velocity) -> Word {
v as Word
}
fn main() -> Word {
let soft = Velocity(40);
raw(soft)
}
$ keleusma run 10_newtype.kel
40
The value of the refinement is what it refuses. A literal that violates the predicate is a compile-time error, not a runtime surprise.
fn main() -> Word {
raw(Velocity(200))
}
$ keleusma run 10b_newtype_reject.kel
error: compile: 4:25: refinement check `in_range` provably fails for newtype `Velocity` at compile time on argument 200
Version 0.2.0 adds information-flow labels.
A type can carry a label, written T@Label, that marks a value.
The operator classify attaches a label,
and declassify removes one. The language follows the label
and refuses, before the program runs, to let a labelled value
flow into a place that does not accept the label.
A reviewer can find every release of confidential data
by searching for declassify.
fn publish(x: Word) -> Word {
x
}
fn main() -> Word {
let secret = classify 42@Private;
publish(declassify secret@Private)
}
$ keleusma run 11_info_flow.kel
42
Remove the declassify, and the leak is proved and rejected.
fn main() -> Word {
let secret = classify 42@Private;
publish(secret)
}
$ keleusma run 11b_info_flow_reject.kel
error: compile: 4:13: type error: argument to `publish` expects Word, got Word@Private
Keleusma arithmetic on Word can be matched against
its overflow behavior. The construct binds the result through
an ok arm when it fits, and through overflow or underflow arms
when it does not, each exposing the high and low halves
of the wider intermediate result. This is the building block
for multi-word and big-number arithmetic.
fn add_checked(a: Word, b: Word) -> Word {
a + b {
ok(v) => v,
overflow(_, l) => l,
underflow(_, l) => l,
}
}
fn main() -> Word {
add_checked(20, 22)
}
$ keleusma run 12_checked.kel
42
Every Keleusma function is exactly one of three kinds, fixed by the word that begins its declaration. The function categories chapter develops this in full.
fn is an atomic total function. It runs straight through
and returns. Every example above is an fn.yield is a non-atomic total function. It may pause,
hand a value to the host, and resume when the host resumes it,
and it must eventually finish.loop is a productive divergent function. It never finishes
and must hand a value to the host on every cycle.A yield or loop program compiles and passes the verifier,
but it is meant to be driven by a host through a call-and-resume
protocol rather than run to a single value. On the 0.2.0
command-line tool, keleusma run drives fn programs.
The yield and loop programs are driven by an embedding host,
which the next section introduces. The tool can still confirm
that such a program lexes, type-checks, and passes the
bounded-execution verifier by compiling it to bytecode.
yield main(tick: Word) -> Word {
let reply = yield tick;
reply
}
$ keleusma compile 14_yield.kel -o out.bin
wrote out.bin (204 bytes)
Before a program runs, the language proves a worst-case
execution-time bound and a worst-case memory bound,
and it proves that every fn finishes.
The budgets chapter explains the two budgets.
A program whose bounds cannot be proved is rejected.
Recursion is one such construct, because it admits unbounded depth.
fn countdown(n: Word) -> Word {
if n <= 0 { 0 } else { countdown(n - 1) }
}
fn main() -> Word {
countdown(5)
}
$ keleusma run 13_recursion_reject.kel
error: verify: VerifyError("countdown: recursive call detected during WCMU topological sort")
The rejection is the safety property. A program the verifier accepts is one whose time and memory bounds are proved, not merely one whose bounds happen to exist.
Version 0.2.0 can sign compiled bytecode with Ed25519,
described in the signed modules chapter.
The signature proves origin and integrity for a module
delivered to a device in the field.
A program opts in with the signed modifier on its entry function.
signed fn main() -> Word {
21 + 21
}
Generate a key pair, compile and sign, then run against the public key.
$ keleusma keygen --seed seed.bin --public pub.bin
wrote seed to seed.bin (32 bytes; keep secret)
wrote public key to pub.bin (32 bytes; distribute to verifiers)
$ keleusma compile signed_demo.kel --signing-key seed.bin -o signed_demo.bin
wrote signed_demo.bin (304 bytes)
$ keleusma run signed_demo.bin --verifying-key pub.bin
42
Run the signed bytecode without the key, and it refuses to load.
$ keleusma run signed_demo.bin
error: load_signed_bytes: LoadError("bytecode signature did not verify against any registered key")
The command-line tool is one host. The runtime library is the product, and the intended use is to embed it in a larger Rust program. The embedding guide documents the full surface. A minimal host lexes, parses, and compiles a script, constructs a virtual machine over an arena, and calls it.
Cargo.toml
[dependencies]
keleusma = "0.2"
src/main.rs
use keleusma::compiler::compile;
use keleusma::lexer::tokenize;
use keleusma::parser::parse;
use keleusma::vm::{Vm, VmState, DEFAULT_ARENA_CAPACITY};
use keleusma::{Arena, Value};
const SOURCE: &str = "fn main() -> Word { 21 + 21 }";
fn main() {
let tokens = tokenize(SOURCE).expect("lex error");
let program = parse(&tokens).expect("parse error");
let module = compile(&program).expect("compile error");
let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
let mut vm = Vm::new(module, &arena).expect("vm construction");
match vm.call(&[]).expect("vm call") {
VmState::Finished(Value::Int(n)) => println!("script returned {n}"),
other => println!("unexpected VM state: {:?}", other),
}
}
$ cargo run --quiet
script returned 42
Vm::call starts execution and returns a VmState.
An fn program returns VmState::Finished.
A yield program returns VmState::Yielded, and the host
calls Vm::resume with a value to continue.
A loop program yields on every cycle and resets at the end of its body,
where a host may hot-swap the module.
This call-and-resume protocol is how a host drives
the yield and loop programs from the previous sections.
The tool also provides a read-evaluate-print loop for trying expressions interactively.
$ keleusma repl
This tour covers enough to read and write Keleusma programs, but it is deliberately shallow. The forty-chapter guide is the place to go next. Its learner track teaches the language from first principles, and its embedding track addresses Rust hosts in depth. The instruction-set reference documents the bytecode, and the example scripts in the repository are the seed material the guide builds on.
Keleusma 0.2.0 trades the unbounded constructs of a general-purpose language for a promise that no other small scripting language makes, namely that every program it accepts is proved, before it runs, to finish within bounded time and bounded memory. Around that core it adds refinement types, information-flow labels, and signed modules, and it is built to be embedded in a Rust host. For a script author, the path forward is the learner track of the guide. For a systems programmer, it is the embedding track.
A companion article argued that an assistant that adheres to the scientific method, values truthfulness over agreement, and declines when declining is honest cannot be a single large language model, and must instead be a compound system in which the model proposes and a deterministic, auditable layer holds the guarantees the model cannot. That argument is developed in the truthful-machine blueprint. This article takes the one layer of that design that can be written as ordinary, verifiable code, namely the control-and-governance kernel, and implements its skeleton in Keleusma, a total functional language whose verifier proves bounded execution before a program ever runs. The Keleusma language itself is introduced in an earlier getting-started article.
A statement of scope is necessary first, because the subject of the blueprint is a machine that does not overclaim. The examples below implement only the kernel. The proposer, the critic ensemble, the retrieval store, the calibration head, and the formal verifier of the blueprint are not written here and cannot be written in Keleusma. They are large or nondeterministic components that live in the host program, and they appear in this article only as host-supplied inputs and external natives. Nothing here demonstrates a working truthful machine. What it demonstrates is that the kernel that would orchestrate and constrain such a machine can be expressed in a form that is proved bounded and total before it runs. That, and only that, is the claim.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-05-27 09:00:00 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 25.5.0: Mon Apr 27 20:38:56 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6000 arm64
# Keleusma
$ keleusma --version
keleusma 0.2.1
The call-yield-resume driver used in the final section arrived in the 0.2.1 release. Everything else in this article also runs unchanged on 0.2.0.
The blueprint’s central principle is that rigidity must live in deterministic machinery outside the stochastic model. Keleusma is built on the same separation. A Keleusma program is the score, and the larger host program is the orchestra. The score does a small, bounded amount of work, hands control back, and waits. The properties Keleusma proves before a program runs, totality and bounded worst-case execution time and memory, are exactly the properties a control kernel needs if its behavior is to be audited rather than trusted. The verifier rejects by default anything it cannot prove bounded, which is the same default-deny posture the governance layer of the blueprint requires.
The sections that follow build the kernel one piece at a time. Each listing was compiled and run with the version shown above, and the output shown is the actual output produced.
The blueprint requires every claim to carry a confidence value that has a meaning. A bare integer cannot enforce the range a confidence must inhabit. A refinement type can, and the check is proved at construction.
fn in_range(x: Word) -> bool { x >= 0 and x <= 100 }
newtype Confidence = Word where in_range;
fn raw(c: Confidence) -> Word {
c as Word
}
fn main() -> Word {
let c = Confidence(64);
raw(c)
}
Running it produces the value.
$ keleusma run 01_typed_claims.kel
64
The value of the refinement is what it refuses. A confidence outside the range is not a runtime error to be caught. It is rejected before the program runs.
fn main() -> Word {
raw(Confidence(150))
}
$ keleusma run 01b_typed_claims_reject.kel
error: compile: 5:9: refinement check `in_range` provably fails for newtype `Confidence` at compile time on argument 150
The rejection is the feature. A claim whose confidence is meaningless cannot be constructed.
The blueprint insists that the controller has no terminal state that means “produce a best guess anyway.” Given a critic verdict and a calibrated confidence, the controller routes to exactly one of four terminal states. The critic is not written here. Its verdict is an input, supplied by the host.
fn in_range(x: Word) -> bool { x >= 0 and x <= 100 }
newtype Confidence = Word where in_range;
enum Verdict {
Refuted,
Unsupported,
IllPosed,
Supported,
}
fn answer_or_hedge(c: Confidence) -> Word {
let n = c as Word;
if n >= 80 { 0 } else { 1 }
}
fn decide(v: Verdict, c: Confidence) -> Word {
match v {
Verdict::Refuted => 2,
Verdict::Unsupported => 2,
Verdict::IllPosed => 3,
Verdict::Supported => answer_or_hedge(c),
}
}
fn main() -> Word {
decide(Verdict::Supported, Confidence(64))
}
The decision codes are 0 for answer, 1 for answer with stated uncertainty, 2 for abstain, and 3 for request reframing. A supported claim at a confidence of 64 falls below the threshold of 80, so the controller answers with stated uncertainty.
$ keleusma run 02_route.kel
1
A refuted or unsupported claim routes to abstention. An ill-posed question routes to a request for reframing. The match is total, so every verdict has a defined terminal state, and the verifier confirms it.
The governance layer must guarantee that an ungrounded claim cannot reach the output without passing an audited gate. Keleusma expresses this with an information-flow label. A label rides on a value, and the language refuses to let a labelled value flow into a place that does not accept the label.
fn commit(x: Word) -> Word {
x
}
fn main() -> Word {
let claim = classify 42@Unverified;
commit(declassify claim@Unverified)
}
The output boundary commit accepts only a plain Word.
The proposer’s claim arrives labelled Unverified.
The single line declassify claim@Unverified
is the one visible, greppable place
where a verified claim is released.
$ keleusma run 03_fact_gate.kel
42
Remove the gate, and the leak is proved before the program runs.
fn main() -> Word {
let claim = classify 42@Unverified;
commit(claim)
}
$ keleusma run 03b_fact_gate_leak.kel
error: compile: 17:12: type error: argument to `commit` expects Word, got Word@Unverified
A reviewer auditing the kernel
finds every release of an unverified claim
by searching for the word declassify.
There is no other way out.
The controller does not run to completion in one piece.
It pauses to let the host run the proposer and the critic,
then resumes with their result and decides.
That is a non-atomic total function,
written with the yield keyword.
fn decide_code(0) -> Word { 2 } // refuted -> abstain
fn decide_code(1) -> Word { 2 } // unsupported -> abstain
fn decide_code(2) -> Word { 3 } // ill-posed -> request reframing
fn decide_code(n: Word) -> Word { 0 } // supported -> answer
yield main(tick: Word) -> Word {
let verdict = yield 1;
decide_code(verdict)
}
The runner drives this lifecycle
through a tick-counter convention
that arrived in the 0.2.1 release.
It calls the entry with tick 1.
The script yields a Word,
the host computes the next tick
as the yielded value plus one,
and resumes the script with that value.
A yield entry point ends
when control returns from the function,
and the runner prints the final value.
Here the script yields 1,
the host resumes with 2,
and the controller routes verdict code 2,
an ill-posed question,
to terminal state 3, request reframing.
$ keleusma run 04_controller_tick.kel
Int(3)
In a real host the resume value is the critic’s verdict rather than a tick counter, and the embedding host drives the same lifecycle through its runtime interface.
The long-running form is a productive divergent function that yields a decision on every cycle and never finishes, the steady beat of a governed agent that runs indefinitely.
fn decide_code(0) -> Word { 2 }
fn decide_code(1) -> Word { 2 }
fn decide_code(2) -> Word { 3 }
fn decide_code(n: Word) -> Word { 0 }
loop main(verdict: Word) -> Word {
let decision = decide_code(verdict);
let _next = yield decision;
decision
}
The runner drives this form continuously,
rate-limited by the --tick-interval flag,
and it stops only when the script calls shell::exit
or the operator interrupts it.
The stock runner does not print the per-cycle decisions,
so a host that consumes them is needed for visible output,
but the verifier still proves the loop
productive and bounded per cycle before it runs.
On the 0.2.0 release the resume driver is absent.
There the yield and loop entry points
still lex, type-check, and pass the verifier,
which keleusma compile confirms by writing the bytecode,
but the stock 0.2.0 runner cannot drive them to completion.
The honest accounting matters more in this subject than in most.
What the kernel shows is that the deterministic spine of the blueprint can be written in a language that proves termination and bounded resources before execution, that typed claims and their confidence ranges can be enforced at construction, that the controller’s terminal states are total with no fall-through to a guess, and that an unverified claim cannot reach the output except through a single audited release point. Keleusma version 0.2.0 also adds cryptographic module signing, so the kernel itself can be delivered as a tamper-evident, origin-authentic artifact, which is the property the blueprint wants for any policy or controller module distributed to a node.
What the kernel does not show is a truthful machine. The proposer, the critics, the retrieval grounding, the calibrator, and the formal prover are absent by necessity. They are tensor-compute and nondeterministic search, and Keleusma deliberately keeps that work on the far side of its external-native boundary. The information-flow guarantee, moreover, is a compile-time property of the score, not of the orchestra. It disciplines what the kernel expresses, not what the host does once a value is released. The refinement checker is conservative as well. It proves decidable predicates, not the rich semantic policies a full verifier would need.
These limits are not failures of the demonstration. They are the boundary the blueprint itself draws, made concrete. The kernel is the part that can be made rigid and auditable, and it is exactly the part shown here. The rest remains, correctly, outside it.
The truthful-machine blueprint is a hypothesis, and this article does not change that. What it establishes is narrower and verifiable. The control-and-governance kernel of that design is expressible today in a language that proves the kernel total and bounded before it runs, that enforces typed claims and an audited fact gate at compile time, and that can ship the kernel as a signed artifact. The neural and symbolic-prover components remain unbuilt and, in Keleusma, unbuildable, which is precisely where the blueprint says they should live. A small, exact, trustworthy core inside a large and untrusted host is the shape of the kernel and the shape of the language alike.
Keleusma is a Total Functional Stream Processor
that compiles to bytecode and runs on a stack-based virtual machine.
It targets no_std + alloc embedded environments
and provides definitive Worst-Case Execution Time
and Worst-Case Memory Usage guarantees through static verification.
The language enforces five guarantees at compile time.
Every function terminates.
Every stream produces output on every tick.
Every execution path has a bounded step count.
Every execution path has a bounded memory footprint.
Running code can be replaced at designated boundaries
without stopping the virtual machine.
The name derives from the Greek word keleusma, meaning a command or rhythmic signal. Ancient rowing masters used the keleusma to synchronize oarsmen on warships. The language applies the same principle to computation. Scripts execute in bounded, predictable cycles synchronized to a host-driven clock.
Keleusma targets applications where deterministic execution is a hard requirement. Audio engines must produce samples every tick without buffer underruns. Game scripting systems must complete logic updates within a fixed frame budget. Safety-critical embedded systems must guarantee worst-case timing for certification. The language addresses these domains by making unbounded computation inexpressible rather than merely discouraged.
This article provides a practical introduction to the Keleusma language and toolchain. It covers installation, the type system, the three function kinds that encode the guarantee taxonomy, pattern matching, the pipeline operator, built-in functions, the interactive read-evaluate-print loop, embedding the virtual machine in a Rust host application, hot code swapping, worst-case analysis, and bytecode compilation. Readers familiar with no_std Rust programming will find the embedding interface straightforward.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-03-14 10:31:00 +0000
# Keleusma Version
$ keleusma --version
keleusma 0.1.1
# Rust Version
$ cargo --version
cargo 1.88.0 (2025-06-25)
$ rustc --version
rustc 1.88.0 (2025-06-25)
Keleusma is available on crates.io
and as source on GitHub.
The command-line interface is distributed
as a separate workspace crate called keleusma-cli.
git clone https://github.com/sgeos/keleusma
cd keleusma
cargo install --path keleusma-cli --bin keleusma
$ keleusma --version
keleusma 0.1.1
$ keleusma --help
keleusma: command-line frontend for the Keleusma scripting language
Usage:
keleusma <subcommand> [options]
keleusma <file>.kel (shorthand for `run`)
Subcommands:
run <file> Compile and execute a script
compile <file> [-o <output>] Compile to bytecode
repl Start interactive REPL
help, --help, -h Show this help
version, --version, -V Show version
Examples:
keleusma run hello.kel
keleusma hello.kel
keleusma compile hello.kel -o hello.kel.bin
keleusma repl
Create a file called hello.kel with the following contents.
fn square(x: i64) -> i64 { x * x }
fn main() -> i64 {
let a: i64 = 3;
let b: i64 = 4;
let sum_of_squares = square(a) + square(b);
sum_of_squares - 1
}
Run the program.
$ keleusma run hello.kel
24
The main function is the entry point.
It computes 3^2 + 4^2 - 1 = 9 + 16 - 1 = 24.
The program compiles to bytecode,
passes through the structural verifier,
and executes on the stack-based virtual machine.
The verifier confirms that every execution path terminates
and that memory usage is bounded
before the virtual machine begins execution.
Keleusma provides five primitive types.
| Type | Description |
|---|---|
i64 |
64-bit signed integer |
f64 |
64-bit floating-point number |
bool |
Boolean value |
String |
UTF-8 string |
() |
Unit type |
All local bindings are immutable. Rebinding a name shadows the previous binding without mutating the original value.
let x: i64 = 42;
let y = 3.14;
let z = x + 1;
Type annotations are optional when the type can be inferred from context.
Keleusma supports standard arithmetic, comparison, and logical operators.
Arithmetic: +, -, *, /, %
Comparison: ==, !=, <, >, <=, >=
Logical: and, or, not
Type cast: as
Pipeline: |>
Logical operators use short-circuit evaluation.
The as operator performs explicit type conversion
between numeric types.
let n: i64 = 42;
let f: f64 = n as f64;
fn abs_value(x: i64) -> i64 {
if x < 0 { 0 - x }
else { x }
}
Conditionals are expressions and evaluate to a value. Both branches must produce the same type.
The for loop iterates over ranges or arrays.
All for loops are bounded by construction
because ranges have a known size
and arrays have a known length.
fn main() -> i64 {
let xs = [10, 20, 30, 40];
for x in xs {
let _doubled = x * 2;
}
for i in 0..4 {
let _squared = i * i;
}
xs[3]
}
The range 0..4 produces values 0, 1, 2, and 3.
The upper bound is exclusive.
The break keyword exits a for loop early.
The central design of Keleusma organizes all functions into three categories that collectively guarantee bounded execution. Each category has a dedicated keyword and a distinct set of obligations.
The fn keyword declares an atomic total function.
An atomic total function must terminate on every input.
It may not yield, may not recurse,
and must return a value.
fn clamp(val: i64, lo: i64, hi: i64) -> i64 {
if val < lo { lo }
else if val > hi { hi }
else { val }
}
The verifier confirms termination statically.
Unbounded recursion and infinite loops
are syntactically impossible in fn bodies.
The yield keyword declares a non-atomic total function.
A non-atomic total function may yield control
back to the host one or more times
but must eventually return a final value.
yield prompt(question: String) -> String {
let answer = yield question;
answer
}
When the function executes yield question,
it suspends and sends question to the host.
The host provides a response,
which becomes the value of the yield expression.
The function must eventually reach a return point.
The loop keyword declares a productive divergent function.
A productive divergent function never returns.
It runs indefinitely, processing a stream of inputs
and producing a stream of outputs.
It must yield on every iteration.
Only one loop function may exist per script.
loop main(input: i64) -> i64 {
let result = input * 2;
let input = yield result;
input
}
The verifier confirms that every control path
from the stream entry point to the reset boundary
contains at least one yield.
This guarantees productivity.
The host drives execution by providing inputs
and consuming outputs at each yield point.
The three-kind taxonomy ensures that the verifier can assign a finite cost to every execution path. Atomic total functions have a fixed step count. Non-atomic total functions have a fixed step count per segment. Productive divergent functions have a fixed step count per tick. Together, these properties enable static computation of worst-case execution time for any single tick of the system.
struct Point { x: i64, y: i64 }
fn manhattan_norm(p: Point) -> i64 {
p.x + p.y
}
fn main() -> i64 {
let origin_offset = Point { x: 3, y: 4 };
manhattan_norm(origin_offset)
}
Structs group named fields into a single value. Field access uses dot notation.
enum Shape {
Circle(i64),
Rectangle(i64, i64),
Square(i64),
}
fn area_estimate(s: Shape) -> i64 {
match s {
Shape::Circle(r) => 3 * r * r,
Shape::Rectangle(w, h) => w * h,
Shape::Square(side) => side * side,
}
}
fn main() -> i64 {
let shape = Shape::Rectangle(20, 5);
area_estimate(shape)
}
Enums define a closed set of variants.
Each variant may carry associated data.
The match expression destructures enum values.
Match expressions must be exhaustive
or include a wildcard _ arm.
let pair: (i64, i64) = (1, 2);
let xs = [10, 20, 30, 40];
let repeated = [0.0; 8];
Tuples group heterogeneous values by position.
Arrays hold homogeneous values of fixed length.
The [value; count] syntax creates an array
filled with count copies of value.
let some_value: Option<i64> = Option::Some(42);
let no_value: Option<i64> = Option::None;
The Option type represents a value that may or may not exist.
The pipeline operator |> threads the result
of the left expression
as the first argument to the right function call.
fn double(x: i64) -> i64 { x + x }
fn add(x: i64, y: i64) -> i64 { x + y }
fn square(x: i64) -> i64 { x * x }
fn main() -> i64 {
6 |> double() |> add(1) |> square()
}
This program produces 169.
The value 6 flows through double to produce 12,
then through add(_, 1) to produce 13,
then through square to produce 169.
For functions where the piped value should not be the first argument, use the underscore placeholder.
value |> insert(collection, _)
The underscore marks where the piped value should be inserted.
A single function name may have multiple heads, each with its own parameter pattern. The runtime tries the heads in source order and dispatches to the first one whose pattern matches.
fn classify(0) -> i64 { 0 }
fn classify(1) -> i64 { 1 }
fn classify(n: i64) -> i64 { n + 10 }
fn main() -> i64 {
let a = classify(0);
let b = classify(1);
let c = classify(11);
let d = classify(7);
a + b + c + d - 28
}
This program produces 11. The first head matches only the literal 0. The second head matches only the literal 1. The third head matches any other integer.
Guard clauses refine pattern matching with additional conditions.
fn sign(x: i64) -> String when x > 0 { "positive" }
fn sign(x: i64) -> String when x < 0 { "negative" }
fn sign(x: i64) -> String { "zero" }
The when clause is evaluated
after the parameter pattern matches.
If the guard fails, dispatch continues
to the next head.
Keleusma supports generic type parameters and trait-based polymorphism. Generics are monomorphized at compile time.
fn id<T>(x: T) -> T { x }
Traits declare a set of function signatures that a type must implement.
trait Doubler {
fn double(x: i64) -> i64;
}
impl Doubler for i64 {
fn double(x: i64) -> i64 { x + x }
}
fn main() -> i64 {
let n: i64 = 42;
n.double()
}
This program produces 84. Method dispatch uses dot notation. The compiler resolves the concrete implementation at compile time through monomorphization.
Trait bounds constrain type parameters.
fn use_doubler<T: Doubler>(x: T) -> i64 {
x.double()
}
Keleusma distinguishes two string categories. Static strings are stored in the read-only data segment and can flow anywhere in the program. Dynamic strings are arena-allocated and cannot cross yield boundaries.
String literals produce static strings.
let msg: String = "hello";
F-string interpolation provides formatted string construction.
The f"..." syntax desugars at lex time
into chains of concat and to_string calls.
Scripts that use f-strings must declare
their dependency on these native functions.
use to_string
use concat
fn add(a: i64, b: i64) -> i64 {
a + b
}
fn main() -> String {
let name = "Keleusma";
let a: i64 = 7;
let b: i64 = 2;
f"hello, {name}! {a} plus {b} is {add(a, b)}"
}
$ keleusma run fstring.kel
hello, Keleusma! 7 plus 2 is 9
The use declarations inform the compiler
that these native functions are provided by the host.
The CLI runner registers two sets of native functions automatically.
| Function | Signature | Description |
|---|---|---|
to_string |
(i64 or f64) -> String |
Convert number to string |
length |
(String or Array) -> i64 |
Get length |
concat |
(String, String) -> String |
Concatenate strings |
slice |
(String, i64, i64) -> String |
Extract substring |
println |
(String) -> () |
Print to standard output |
| Function | Signature | Description |
|---|---|---|
math::sin |
(f64) -> f64 |
Sine |
math::cos |
(f64) -> f64 |
Cosine |
math::pow |
(f64, f64) -> f64 |
Exponentiation |
math::abs |
(f64) -> f64 |
Absolute value |
math::min |
(f64, f64) -> f64 |
Minimum |
math::max |
(f64, f64) -> f64 |
Maximum |
math::clamp |
(f64, f64, f64) -> f64 |
Clamp to range |
math::lerp |
(f64, f64, f64) -> f64 |
Linear interpolation |
| Function | Signature | Description |
|---|---|---|
audio::midi_to_freq |
(i64) -> f64 |
MIDI note to frequency in Hz |
audio::freq_to_midi |
(f64) -> i64 |
Frequency to nearest MIDI note |
audio::db_to_linear |
(f64) -> f64 |
Decibels to linear amplitude |
audio::linear_to_db |
(f64) -> f64 |
Linear amplitude to decibels |
All math and audio functions accept both i64 and f64 arguments.
Integer arguments are widened to floating-point automatically.
The interactive read-evaluate-print loop allows experimentation without creating script files.
$ keleusma repl
> 1 + 2
3
> fn double(x: i64) -> i64 { x + x }
defined: double
> double(21)
42
> :help
:help Show this help
:quit Exit the REPL
:reset Clear all definitions
:show Show defined functions
> :quit
The REPL supports function definitions, expressions,
and colon-prefixed meta-commands.
Definitions persist across evaluations
until :reset is issued.
Keleusma is designed to be embedded in Rust host applications. The library crate provides the full compilation pipeline and virtual machine as a library API.
use keleusma::compiler::compile;
use keleusma::lexer::tokenize;
use keleusma::parser::parse;
use keleusma::vm::{DEFAULT_ARENA_CAPACITY, Vm, VmState};
use keleusma::{Arena, Value};
fn main() {
let source = r#"
fn double(x: i64) -> i64 { x * x }
fn main(n: i64) -> i64 { n |> double() }
"#;
let tokens = tokenize(source).expect("lex");
let program = parse(&tokens).expect("parse");
let module = compile(&program).expect("compile");
let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
let mut vm = Vm::new(module, &arena).expect("verify");
match vm.call(&[Value::Int(21)]).unwrap() {
VmState::Finished(Value::Int(n)) => println!("{}", n),
_ => unreachable!(),
}
}
The host owns the arena allocator. The virtual machine borrows the arena for its operand stack, call frames, and dynamic string storage. The default arena capacity is 64 kilobytes.
Native functions allow scripts to call into host code. The ergonomic typed interface is the recommended approach.
vm.register_fn("add", |a: i64, b: i64| -> i64 { a + b });
vm.register_fn("sin", |x: f64| -> f64 { libm::sin(x) });
For functions that may fail, use the fallible interface.
vm.register_fn_fallible("get_setting", |key: String| -> Result<String, VmError> {
fetch(&key).map_err(|e| VmError::NativeError(format!("{}", e)))
});
Custom struct types can cross the host-guest boundary
using the KeleusmaType derive macro.
use keleusma::KeleusmaType;
#[derive(KeleusmaType, Debug, Clone)]
struct Point { x: f64, y: f64 }
vm.register_fn("midpoint", |a: Point, b: Point| -> Point {
Point { x: (a.x + b.x) / 2.0, y: (a.y + b.y) / 2.0 }
});
The virtual machine transitions between states as it executes scripts.
let state = vm.call(&[Value::Int(input)])?;
loop {
match state {
VmState::Yielded(output) => {
let reply = host_process(output);
state = vm.resume(reply)?;
}
VmState::Reset => {
// Hot swap opportunity
state = vm.resume(next_input)?;
}
VmState::Finished(value) => {
break;
}
}
}
A Yielded state indicates
that the script has produced output
and awaits the next input.
A Reset state indicates a phase boundary
where hot code swapping is permitted.
A Finished state indicates
that the script has returned a final value.
Keleusma supports replacing a running script at designated reset boundaries without stopping the virtual machine. The data segment persists across the swap.
match vm.resume(input)? {
VmState::Reset => {
let new_module = recompile_or_load()?;
let initial_data = vec![Value::Int(0); slot_count];
vm.replace_module(new_module, initial_data)?;
state = vm.call(&[fresh_input])?;
}
_ => { /* continue normal execution */ }
}
Hot code swapping is useful for live development workflows. Audio engines can replace synthesis scripts without interrupting playback. Game scripting systems can reload behavior scripts without restarting the game loop.
The structural verifier computes worst-case execution time and worst-case memory usage for every execution path before the virtual machine starts. If the verifier cannot prove bounded execution, the program is rejected.
Each bytecode instruction has an assigned integer cost. The verifier sums costs along the worst-case path through each function and each stream iteration.
Common instruction costs include the following.
| Cost | Instructions |
|---|---|
| 1 | Constants, local variable access, stack operations, control flow delimiters |
| 2 | Arithmetic, comparisons, indexing, type casts, return |
| 3 | Division, modulo, field access by name, type tests |
| 5 | Struct and enum construction, array and tuple allocation |
| 10 | Function calls, native function calls |
The host must provide an arena large enough for the worst-case memory usage. Three approaches are available.
Default capacity is 64 kilobytes.
let arena = Arena::with_capacity(DEFAULT_ARENA_CAPACITY);
Automatic computation sizes the arena to the verified worst-case memory usage.
let cap = keleusma::vm::auto_arena_capacity_for(&module, &[])?;
let arena = Arena::with_capacity(cap);
Static buffer is suitable for embedded targets without a heap allocator.
static mut ARENA_BUFFER: [u8; 16 * 1024] = [0; 16 * 1024];
let arena = unsafe {
Arena::from_static_buffer(core::ptr::addr_of_mut!(ARENA_BUFFER))
};
Scripts can be compiled to bytecode files for deployment without the source.
$ keleusma compile hello.kel -o hello.kel.bin
The host application loads precompiled bytecode using zero-copy deserialization.
let bytes = std::fs::read("hello.kel.bin")?;
let mut vm = Vm::load_bytes(&bytes, &arena)?;
Precompiled bytecode is useful in embedded deployments where source compilation at runtime is undesirable or impossible. The bytecode format uses rkyv for zero-copy deserialization.
Keleusma provides a scripting language
with static guarantees about termination,
memory usage, and execution time.
The three-function taxonomy of atomic total,
non-atomic total, and productive divergent functions
ensures that the verifier can assign
bounded costs to every execution path.
The no_std + alloc design,
arena-based memory management,
and precompiled bytecode support
make the virtual machine suitable
for resource-constrained embedded targets.
The language repository contains additional example scripts demonstrating language features and Rust embedding examples demonstrating host integration patterns including worst-case memory attestation, yield-based coroutines, string handling, generics, zero-copy bytecode loading, and a full SDL3 audio piano roll with hot code swapping.
The documentation directory contains a complete language grammar specification, instruction set reference, type system documentation, execution model description, and a survey of related work in synchronous reactive languages, coalgebraic stream processing, and worst-case execution time analysis.
Concentrated Liquidity Market Makers (CLMMs) extend the Constant Product model by allowing liquidity providers to allocate capital within a chosen price range rather than across the entire price domain. This post deconstructs the core equations of the Concentrated Liquidity model, the architecture introduced by Uniswap v3 and now the dominant design in decentralized finance.
This article assumes familiarity with the Constant Product AMM Mathematics article, which covers the foundational invariant, liquidity, swap execution, fees, and impermanent loss for the full-range model. The CLMM extends every one of those concepts by restricting the active region of the curve to a finite price interval. This post will first cover CLMM math. After that, it will present the code for the following CLMM calculator widget.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-02-22 10:01:47 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 23.6.0: Mon Jul 29 21:14:30 PDT 2024; root:xnu-10063.141.2~1/RELEASE_ARM64_T6000 arm64
$ sw_vers
ProductName: macOS
ProductVersion: 14.6.1
BuildVersion: 23G93
# Hardware Information
$ system_profiler SPHardwareDataType | sed -n '8,10p'
Chip: Apple M1 Max
Total Number of Cores: 10 (8 performance and 2 efficiency)
Memory: 32 GB
# Shell and Version
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version | head -n 1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
# Rust Installation Versions
$ cargo --version
cargo 1.93.0 (083ac5135 2025-12-15)
At the core of the Constant Product model is the invariant $x \cdot y = L^2$, where $x$ and $y$ are the reserves of the two tokens and $L = \sqrt{x \cdot y}$ is the liquidity. In a full-range Automated Market Maker (AMM), capital is spread across the entire price domain from zero to infinity. The vast majority of that capital sits idle at prices far from the current trading price.
The innovation of concentrated liquidity is to allow each liquidity provider to choose a finite price interval $[p_a, p_b]$ within which their capital is active. Within that interval, the position behaves exactly like a constant product AMM. Outside that interval, the position holds only one token and earns no fees. The result is that a given amount of capital provides substantially deeper liquidity around the current price, improving capital efficiency by orders of magnitude for narrow ranges.
A pool aggregates many individual concentrated positions, each covering potentially different price intervals. The aggregate liquidity at any given price is the sum of all positions whose ranges contain that price.
The starting point is the constant product invariant.
\[x \cdot y = L^2\]The current price $p$ of Token Y in terms of Token X satisfies $p = \frac{y}{x}$. The reserves can be expressed in terms of $L$ and $p$ as follows.
\[x = \frac{L}{\sqrt{p}} \qquad y = L \cdot \sqrt{p}\]These are the virtual reserves on the full unbounded curve. They satisfy $x \cdot y = L^2$ and $\frac{y}{x} = p$.
In a concentrated liquidity position with price range $[p_a, p_b]$, the contract behaves as though the full $x \cdot y = L^2$ curve exists, but only the segment between prices $p_a$ and $p_b$ is funded with real tokens. The virtual reserves at any current price $p$ within the range are as follows.
\[x_v(p) = \frac{L}{\sqrt{p}} \qquad y_v(p) = L \cdot \sqrt{p}\]The real reserves are obtained by translating the constant product curve. The curve segment between $p_a$ and $p_b$ is shifted so that the real reserves reach zero at the range boundaries. The translated invariant is as follows.
\[\left(x_r + \frac{L}{\sqrt{p_b}}\right) \cdot \left(y_r + L \cdot \sqrt{p_a}\right) = L^2\]This is the standard constant product curve shifted left by $\frac{L}{\sqrt{p_b}}$ and down by $L \cdot \sqrt{p_a}$. The real reserves $x_r$ and $y_r$ are what the liquidity provider actually deposits and holds.
Geometric Interpretation: The virtual reserves describe a point on the standard hyperbola $x \cdot y = L^2$. The real reserves represent the same curve translated so that the lower-left corner of the active segment sits at the origin. At price $p_a$, all real reserves are in Token X and $y_r = 0$. At price $p_b$, all real reserves are in Token Y and $x_r = 0$.
When the current price $p$ is within the range $[p_a, p_b]$, the real reserves are as follows.
\[x_r = L \cdot \left(\frac{1}{\sqrt{p}} - \frac{1}{\sqrt{p_b}}\right) = \frac{L \cdot \left(\sqrt{p_b} - \sqrt{p}\right)}{\sqrt{p} \cdot \sqrt{p_b}}\] \[y_r = L \cdot \left(\sqrt{p} - \sqrt{p_a}\right)\]$x_r$ (Token X Real Reserve): The amount of Token X held by the position. This quantity decreases as the price rises and reaches zero when $p = p_b$. [Unit: Token X]
$y_r$ (Token Y Real Reserve): The amount of Token Y held by the position. This quantity increases as the price rises and reaches its maximum when $p = p_b$. [Unit: Token Y]
$L$ (Liquidity): The liquidity of the position, identical in definition to the full-range constant product model. [Unit: $\sqrt{\text{Token X} \cdot \text{Token Y}}$]
$p_a, p_b$ (Price Range Boundaries): The lower and upper bounds of the liquidity position. [Unit: Token Y / Token X]
These are the core equations. They correspond to Equations 6.29 and 6.30 in the Uniswap v3 whitepaper ref_uniswap_v3_whitepaper.
The token amounts held by a position depend on where the current price $p$ falls relative to the range. There are three regimes.
Regime 1. Price below range ($p \le p_a$). The position is entirely Token X and earns no fees.
\[x_r = \frac{L \cdot \left(\sqrt{p_b} - \sqrt{p_a}\right)}{\sqrt{p_a} \cdot \sqrt{p_b}} \qquad y_r = 0\]Regime 2. Price within range ($p_a < p < p_b$). The position holds both tokens and earns fees on swaps.
\[x_r = \frac{L \cdot \left(\sqrt{p_b} - \sqrt{p}\right)}{\sqrt{p} \cdot \sqrt{p_b}} \qquad y_r = L \cdot \left(\sqrt{p} - \sqrt{p_a}\right)\]Regime 3. Price above range ($p \ge p_b$). The position is entirely Token Y and earns no fees.
\[x_r = 0 \qquad y_r = L \cdot \left(\sqrt{p_b} - \sqrt{p_a}\right)\]Note on Regime Transitions: As the price rises through the range from $p_a$ to $p_b$, the position progressively converts Token X into Token Y. When the price crosses a boundary, the position becomes fully denominated in a single token. If the price later re-enters the range, the position resumes earning fees.
Given a deposit of $\Delta x$ of Token X and $\Delta y$ of Token Y at current price $p$ within range $[p_a, p_b]$, the liquidity $L$ is determined by the limiting token.
From the Token X amount, the liquidity implied is as follows.
\[L_x = \frac{\Delta x \cdot \sqrt{p} \cdot \sqrt{p_b}}{\sqrt{p_b} - \sqrt{p}}\]From the Token Y amount, the liquidity implied is as follows.
\[L_y = \frac{\Delta y}{\sqrt{p} - \sqrt{p_a}}\]The effective liquidity of the position is the minimum of the two.
\[L = \min(L_x,\ L_y)\]The minimum is taken because the position is constrained by whichever token is the limiting factor. Any excess of the other token is returned to the depositor.
When the price is at or below $p_a$, only Token X is required and $L = L_x$. When the price is at or above $p_b$, only Token Y is required and $L = L_y$.
Contrast with Full-Range CPAMM: In the Constant Product model, adding liquidity requires both tokens in proportion to the current price ratio. In the Concentrated Liquidity model, the deposit ratio depends on where the current price sits within the chosen range. At the lower bound, the deposit is entirely Token X. At the upper bound, the deposit is entirely Token Y.
Prices in Uniswap v3 are discretized into ticks. Each tick $i$ corresponds to a price as follows.
\[p(i) = 1.0001^i\]Each tick therefore represents a 0.01% multiplicative change in price, equivalent to one basis point. The tick index for a given price is as follows.
\[i = \left\lfloor \frac{\ln(p)}{\ln(1.0001)} \right\rfloor\]The protocol stores $\sqrt{p}$ rather than $p$ directly because the key reserve formulas involve $\sqrt{p}$ and storing the square root avoids computing it on-chain. The square root price from a tick index is as follows.
\[\sqrt{p(i)} = 1.0001^{i/2}\]Tick spacing constrains which ticks can serve as position boundaries. Only tick indices that are multiples of the tick spacing are allowed. Smaller tick spacing permits more precise ranges but increases gas costs because each initialized tick crossed during a swap imposes additional computation.
The standard fee tiers and their corresponding tick spacings are as follows.
| Fee Tier | Basis Points | Tick Spacing |
|---|---|---|
| 0.01% | 1 bp | 1 |
| 0.05% | 5 bp | 10 |
| 0.30% | 30 bp | 60 |
| 1.00% | 100 bp | 200 |
Note on Governance: The 1 basis point fee tier was not in the original Uniswap v3 deployment. It was added by governance vote in March 2022 to improve competitiveness for stablecoin pairs.
A concentrated position in range $[p_a, p_b]$ provides the same depth of liquidity as a full-range position that holds significantly more capital. The intuition is straightforward. A full-range position must hold reserves to cover trading at every possible price. A concentrated position only needs reserves for its chosen range, so the same dollar amount of capital produces proportionally deeper liquidity within that range.
For a position centered at current price $p$ with range $[p_a, p_b]$, the capital efficiency relative to a full-range position is approximately as follows.
\[\text{efficiency} \approx \frac{1}{1 - \left(\frac{p_a}{p_b}\right)^{1/4}}\]For very tight stablecoin ranges, the efficiency multiplier can reach up to 4000x. For example, a position in the range 0.999 to 1.001 for a stablecoin pair provides liquidity equivalent to a full-range position with thousands of times more capital.
Tradeoff: Higher capital efficiency comes with higher risk. A narrower range means the position is more likely to move out of range, at which point it stops earning fees and is fully converted to the less valuable token. Selecting a range is therefore a risk management decision.
Fees in a CLMM are earned only when the position is in range, that is, when $p_a \le p \le p_b$. The protocol tracks fee accumulation using a global variable $f_g$ that records the total fees earned per unit of liquidity since the pool was created.
For each tick boundary, the protocol tracks $f_o$, which records fees accumulated on the other side of that tick. The fees earned within a position’s range are computed as follows.
\[f_{\text{inside}} = f_g - f_{\text{below}}(p_a) - f_{\text{above}}(p_b)\]The fees owed to a specific position are then as follows.
\[\text{fees} = \left(f_{\text{inside}} - f_{\text{inside,last}}\right) \cdot L\]The value $f_{\text{inside,last}}$ is the inside fee growth at the time the position was last updated. A position is updated when it is created, modified, or when fees are collected. The value $L$ is the position’s liquidity.
This design means that positions only need to be updated when their tick boundaries are crossed or when the LP interacts with the position, rather than on every swap.
For a standard full-range constant product position, the impermanent loss as a function of the price ratio $r = \frac{p_{\text{new}}}{p_{\text{old}}}$ is as follows.
\[IL(r) = \frac{2\sqrt{r}}{1 + r} - 1\]Concentrated liquidity amplifies impermanent loss because the position is effectively leveraged. The position converts between Tokens X and Y across a narrower price range, so the same price movement causes a proportionally larger change in portfolio composition.
The value of a concentrated liquidity position at price $p$ when $p_a \le p \le p_b$ is as follows.
\[V(p) = x_r \cdot p + y_r = L \cdot \left(2\sqrt{p} - \frac{p}{\sqrt{p_b}} - \sqrt{p_a}\right)\]The impermanent loss for a concentrated position is the difference between this value and the value of simply holding the initial token quantities at the new price. Qualitatively, a position that is $N$ times more capital-efficient also experiences approximately $N$ times more impermanent loss per unit of capital deployed.
Research by Loesch, Hindman, Richardson, and Welch demonstrates that even when a liquidity range is large enough to accommodate prices doubling or halving, the impermanent loss is nearly four times higher than a full-range position research_loesch_il.
Note on Range Selection: The amplification of impermanent loss is the direct cost of the capital efficiency gained by concentrating liquidity. A liquidity provider must weigh the additional fee income earned from deeper liquidity against the increased impermanent loss risk.
The equations above define the theoretical model. Translating them into code requires handling floating-point arithmetic and user interaction across multiple input modes. The following Rust code implements the CLMM calculator widget shown at the top of this article. Integration and usage assumes familiarity with Rust-based WASM, as documented in a post on the topic.
The calculator supports three update modes. Editing the liquidity or price fields recomputes inventories. Moving the position slider interpolates the current price in $\sqrt{p}$ space. Editing the inventory fields recomputes the liquidity using the $\min(L_x, L_y)$ formula.
Cargo.toml full listing
[package]
name = "post_clmm_mathematics"
version = "0.1.0"
edition = "2024"
[lib]
crate-type = ["cdylib"]
[dependencies]
wasm-bindgen = "0.2.108"
web-sys = { version = "0.3.85", features = ["Document", "Element", "Event", "EventTarget", "HtmlElement", "HtmlInputElement", "Node", "Window"] }
src/lib.rs full listing
use std::rc::Rc;
use wasm_bindgen::JsCast;
use wasm_bindgen::prelude::*;
use web_sys::HtmlInputElement;
struct ClmmCalculatorInputs {
liq: HtmlInputElement,
min_price: HtmlInputElement,
cur_price: HtmlInputElement,
max_price: HtmlInputElement,
slider: HtmlInputElement,
pos_input: HtmlInputElement,
x: HtmlInputElement,
y: HtmlInputElement,
}
enum ClmmCalculatorUpdateMode {
FromPricesAndLiquidity,
FromPositionSlider,
FromReserves,
}
fn parse_f64(input: &HtmlInputElement) -> f64 {
input.value().parse::<f64>().unwrap_or(0.0)
}
fn repopulate(inputs: &ClmmCalculatorInputs, p_a: f64, p_c: f64, p_b: f64, l: f64) {
if p_a <= 0.0 || p_b <= 0.0 || p_b <= p_a || l < 0.0 {
return;
}
inputs.min_price.set_value(&format!("{}", p_a));
inputs.max_price.set_value(&format!("{}", p_b));
inputs.cur_price.set_value(&format!("{:.6}", p_c));
inputs.liq.set_value(&format!("{:.6}", l));
let sqrt_a = p_a.sqrt();
let sqrt_b = p_b.sqrt();
let sqrt_c = p_c.sqrt();
// Position slider value in sqrt price space
let pos = if sqrt_b > sqrt_a {
((sqrt_c - sqrt_a) / (sqrt_b - sqrt_a)).clamp(0.0, 1.0)
} else {
0.5
};
inputs.slider.set_value(&format!("{:.4}", pos));
inputs.pos_input.set_value(&format!("{:.4}", pos));
// Token amounts based on price regime
let (x, y) = if p_c <= p_a {
// Below range: all Token X
let x = l * (sqrt_b - sqrt_a) / (sqrt_a * sqrt_b);
(x, 0.0)
} else if p_c >= p_b {
// Above range: all Token Y
let y = l * (sqrt_b - sqrt_a);
(0.0, y)
} else {
// In range: both tokens
let x = l * (sqrt_b - sqrt_c) / (sqrt_c * sqrt_b);
let y = l * (sqrt_c - sqrt_a);
(x, y)
};
inputs.x.set_value(&format!("{:.2}", x));
inputs.y.set_value(&format!("{:.2}", y));
}
#[wasm_bindgen]
pub fn inject_ui(anchor_id: &str) {
let window = web_sys::window().expect("Missing window");
let document = window.document().expect("Missing document");
let anchor = document
.get_element_by_id(anchor_id)
.expect("Missing anchor");
// UI Container
let container = document.create_element("div").unwrap();
container.set_id(&format!("{}-container", anchor_id));
container.set_attribute("class", "clmm-widget").unwrap();
// Labeled Input Helper
let create_input =
|id: &str, label_text: &str, input_type: &str, css_class: Option<&str>| {
let div = document.create_element("div").unwrap();
if let Some(cls) = css_class {
div.set_attribute("class", cls).unwrap();
} else {
div.set_attribute("class", "clmm-field").unwrap();
}
let label = document.create_element("label").unwrap();
label.set_text_content(Some(label_text));
let input = document
.create_element("input")
.unwrap()
.dyn_into::<HtmlInputElement>()
.unwrap();
input.set_id(&format!("{}-{}", anchor_id, id));
input.set_type(input_type);
div.append_child(&label).unwrap();
div.append_child(&input).unwrap();
(div, input)
};
// Row 1: Liquidity
let (liq_div, liq_input) = create_input("liq", "Liquidity Depth (L)", "text", Some("clmm-row-1"));
container.append_child(&liq_div).unwrap();
// Row 2: Min Price, Current Price, Max Price
let price_row = document.create_element("div").unwrap();
price_row.set_attribute("class", "clmm-row-3").unwrap();
let (min_div, min_input) = create_input("min", "Min Price (p_a)", "text", None);
let (cur_div, cur_input) = create_input("cur", "Current Price (p)", "text", None);
let (max_div, max_input) = create_input("max", "Max Price (p_b)", "text", None);
price_row.append_child(&min_div).unwrap();
price_row.append_child(&cur_div).unwrap();
price_row.append_child(&max_div).unwrap();
container.append_child(&price_row).unwrap();
// Row 3: Position Slider
let (slider_div, slider_input) =
create_input("slider", "Position Slider", "range", Some("clmm-row-slider"));
slider_input.set_min("0");
slider_input.set_max("1");
slider_input.set_step("0.0001");
container.append_child(&slider_div).unwrap();
// Row 4: Token X, Position, Token Y
let inv_row = document.create_element("div").unwrap();
inv_row.set_attribute("class", "clmm-row-3").unwrap();
let (x_div, x_input) = create_input("x", "Token X Inventory", "text", None);
let (pos_div, pos_input) = create_input("pos", "Position (0-1)", "text", None);
let (y_div, y_input) = create_input("y", "Token Y Inventory", "text", None);
inv_row.append_child(&x_div).unwrap();
inv_row.append_child(&pos_div).unwrap();
inv_row.append_child(&y_div).unwrap();
container.append_child(&inv_row).unwrap();
// Anchor Replacement
anchor
.parent_node()
.unwrap()
.replace_child(&container, &anchor)
.unwrap();
// Shared Input State
let inputs = Rc::new(ClmmCalculatorInputs {
liq: liq_input,
min_price: min_input,
cur_price: cur_input,
max_price: max_input,
slider: slider_input,
pos_input: pos_input,
x: x_input,
y: y_input,
});
// Centralized Update Logic
let update_widget = {
let inputs = inputs.clone();
move |mode: ClmmCalculatorUpdateMode| {
let p_a = parse_f64(&inputs.min_price);
let p_b = parse_f64(&inputs.max_price);
match mode {
ClmmCalculatorUpdateMode::FromPricesAndLiquidity => {
let p_c = parse_f64(&inputs.cur_price);
let l = parse_f64(&inputs.liq);
repopulate(&inputs, p_a, p_c, p_b, l);
}
ClmmCalculatorUpdateMode::FromPositionSlider => {
let pos = parse_f64(&inputs.slider);
let sqrt_a = p_a.sqrt();
let sqrt_b = p_b.sqrt();
let sqrt_c = sqrt_a + pos * (sqrt_b - sqrt_a);
let p_c = sqrt_c * sqrt_c;
let l = parse_f64(&inputs.liq);
repopulate(&inputs, p_a, p_c, p_b, l);
}
ClmmCalculatorUpdateMode::FromReserves => {
let p_c = parse_f64(&inputs.cur_price);
let x = parse_f64(&inputs.x);
let y = parse_f64(&inputs.y);
let sqrt_a = p_a.sqrt();
let sqrt_b = p_b.sqrt();
let sqrt_c = p_c.sqrt();
let l = if p_c <= p_a {
x * sqrt_a * sqrt_b / (sqrt_b - sqrt_a)
} else if p_c >= p_b {
y / (sqrt_b - sqrt_a)
} else {
let l_x = x * sqrt_c * sqrt_b / (sqrt_b - sqrt_c);
let l_y = y / (sqrt_c - sqrt_a);
l_x.min(l_y)
};
repopulate(&inputs, p_a, p_c, p_b, l);
}
}
}
};
// Callback Setup
let update_rc = Rc::new(update_widget);
let on_price_liq_change = {
let u = update_rc.clone();
Closure::wrap(Box::new(move |_e: web_sys::Event| {
u(ClmmCalculatorUpdateMode::FromPricesAndLiquidity);
}) as Box<dyn FnMut(_)>)
};
inputs
.liq
.add_event_listener_with_callback("input", on_price_liq_change.as_ref().unchecked_ref())
.unwrap();
inputs
.min_price
.add_event_listener_with_callback("input", on_price_liq_change.as_ref().unchecked_ref())
.unwrap();
inputs
.cur_price
.add_event_listener_with_callback("input", on_price_liq_change.as_ref().unchecked_ref())
.unwrap();
inputs
.max_price
.add_event_listener_with_callback("input", on_price_liq_change.as_ref().unchecked_ref())
.unwrap();
on_price_liq_change.forget();
let on_slider_change = {
let u = update_rc.clone();
let ins = inputs.clone();
Closure::wrap(Box::new(move |_e: web_sys::Event| {
let pos = parse_f64(&ins.slider);
ins.pos_input.set_value(&format!("{:.4}", pos));
u(ClmmCalculatorUpdateMode::FromPositionSlider);
}) as Box<dyn FnMut(_)>)
};
inputs
.slider
.add_event_listener_with_callback("input", on_slider_change.as_ref().unchecked_ref())
.unwrap();
on_slider_change.forget();
let on_pos_input_change = {
let u = update_rc.clone();
let ins = inputs.clone();
Closure::wrap(Box::new(move |_e: web_sys::Event| {
let pos = parse_f64(&ins.pos_input).clamp(0.0, 1.0);
ins.slider.set_value(&format!("{:.4}", pos));
u(ClmmCalculatorUpdateMode::FromPositionSlider);
}) as Box<dyn FnMut(_)>)
};
inputs
.pos_input
.add_event_listener_with_callback("input", on_pos_input_change.as_ref().unchecked_ref())
.unwrap();
on_pos_input_change.forget();
let on_reserve_change = {
let u = update_rc.clone();
Closure::wrap(Box::new(move |_e: web_sys::Event| {
u(ClmmCalculatorUpdateMode::FromReserves);
}) as Box<dyn FnMut(_)>)
};
inputs
.x
.add_event_listener_with_callback("input", on_reserve_change.as_ref().unchecked_ref())
.unwrap();
inputs
.y
.add_event_listener_with_callback("input", on_reserve_change.as_ref().unchecked_ref())
.unwrap();
on_reserve_change.forget();
// Default Values: stablecoin pair range 0.015 to 0.025, position at midpoint
let p_a = 0.015_f64;
let p_b = 0.025_f64;
let initial_stable = 1000.0_f64;
let initial_pos = 0.5_f64;
let initial_l = initial_stable / (p_b.sqrt() - p_a.sqrt());
let sqrt_c = p_a.sqrt() + initial_pos * (p_b.sqrt() - p_a.sqrt());
let p_c = sqrt_c * sqrt_c;
repopulate(&inputs, p_a, p_c, p_b, initial_l);
}
Widget JS Injection Anchor Example
<script type="module" id="clmm_calculator_ui">
import init, { inject_ui } from "/assets/wasm/post_clmm_mathematics/post_clmm_mathematics.js";
async function run() {
await init();
inject_ui("clmm_calculator_ui");
}
run();
</script>
Widget Inline CSS Styling Example
<style>
.clmm-widget {
display: grid;
grid-template-columns: 1fr;
gap: 12px;
padding: 20px;
border: 2px solid #007bff;
border-radius: 8px;
max-width: 750px;
background-color: #ffffff;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
}
.clmm-widget .clmm-row-1 {
display: flex;
flex-direction: column;
gap: 5px;
}
.clmm-widget .clmm-row-3 {
display: grid;
grid-template-columns: 1fr 1fr 1fr;
gap: 12px;
}
.clmm-widget .clmm-row-slider {
display: flex;
flex-direction: column;
gap: 5px;
padding: 10px;
background: #f6f8fa;
border-radius: 6px;
}
.clmm-widget .clmm-field {
display: flex;
flex-direction: column;
gap: 5px;
}
.clmm-widget label {
font-size: 0.85rem;
font-weight: 600;
color: #333;
}
.clmm-widget input[type="text"] {
padding: 8px;
border: 1px solid #ccc;
border-radius: 4px;
font-size: 1rem;
width: 100%;
box-sizing: border-box;
}
.clmm-widget input[type="range"] {
width: 100%;
margin: 5px 0;
}
@media (max-width: 500px) {
.clmm-widget .clmm-row-3 {
grid-template-columns: 1fr;
}
}
</style>
Example index.html for Local Testing Add above CSS styling to commented location.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>CLMM Calculator</title>
<!-- Inline CSS Here -->
<style></style>
</head>
<body>
<h1>CLMM Calculator</h1>
<script type="module" id="clmm_calculator_ui">
import init, { inject_ui } from "./pkg/post_clmm_mathematics.js";
async function run() {
await init();
inject_ui("clmm_calculator_ui");
}
run();
</script>
</body>
</html>
Sample Command to Served Example index.html for Local Testing
# Terminal A
PORT="8000"
python -m http.server "${PORT}"
PORT="8000"
# Terminal B
open "http://localhost:${PORT}"
The mathematics presented in this article cover the core model. Several directions extend this foundation.
Multi-range strategies. Active liquidity management strategies deploy capital across multiple overlapping ranges, rebalancing as the price moves. Academic research on optimal range selection remains an active area.
Just-In-Time liquidity. Sophisticated participants add concentrated liquidity immediately before a large swap and remove it immediately after, capturing fees with minimal impermanent loss exposure. This technique has implications for MEV and fairness.
Options-like payoff analysis. The payoff profile of a concentrated liquidity position resembles a short straddle in options markets. Research by Loesch et al. formalizes this connection, and static replication using European options has been demonstrated for concentrated liquidity positions.
Uniswap v4 hooks. The successor protocol introduces a hook system that allows pool deployers to customize swap logic, fee structures, and oracle behavior. This extensibility changes the design space for concentrated liquidity strategies.
Automated Market Makers (AMMs) revolutionized on-chain liquidity by replacing central limit order books with deterministic mathematical curves. This post deconstructs the core equations of the Constant Product model. This model is the foundation of protocols like Uniswap v2, covering everything from swap mechanics and fees to the linear geometry of liquidity and the risks of impermanent loss.
AMM math is also simpler than Concentrated Liquidity Market Maker (CLMM) math. It is therefore foundational for future study. This post will first cover AMM math. After that, it will present the code for the following AMM calculator widget. Other widgets could be written, but this post is sufficiently long as is.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-01-29 17:08:11 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 23.6.0: Mon Jul 29 21:14:30 PDT 2024; root:xnu-10063.141.2~1/RELEASE_ARM64_T6000 arm64
$ sw_vers
ProductName: macOS
ProductVersion: 14.6.1
BuildVersion: 23G93
# Hardware Information
$ system_profiler SPHardwareDataType | sed -n '8,10p'
Chip: Apple M1 Max
Total Number of Cores: 10 (8 performance and 2 efficiency)
Memory: 32 GB
# Shell and Version
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version | head -n 1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
# Rust Installation Versions
$ cargo --version
cargo 1.93.0 (083ac5135 2025-12-15)
At the core of Decentralized Finance (DeFi) is the Constant Product Market Maker (CPMM). This specific branch of mathematics replaces the traditional order book with an automated peer-to-pool model, ensuring that a trade can be executed at any time, regardless of counterparty availability.
The vast majority of AMMs use the Constant Product Formula to model the smart contract liquidity pool curve. This formula is an industry standard, but its use is not a hard rule. Any smart contract is free to use whatever model it wants, but this post assumes the Constant Product Formula. It dictates that the product of the two asset quantities must remain constant during any trade.
\[x \cdot y = k\]$x$ (Token X Reserve): The total inventory of the first asset (e.g., memecoin or basecoin) currently held in the AMM smart contract. [Unit: Token X]
$y$ (Token Y Reserve): The total inventory of the second asset (e.g., stablecoin or quotecoin) currently held in the AMM smart contract. [Unit: Token Y]
$k$ (Invariant): A fixed value that defines the pool’s pricing curve. This value is a constant during swaps and only changes when liquidity is added to or removed from the pool. [Unit: Token X $\cdot$ Token Y]
Base and Quote Convention: In financial markets, price is a ratio between two assets. The asset being priced is the base, and the currency used to measure it is the quote. By convention, price is expressed as the value of one unit of the base asset in terms of the quote asset. This maps directly to the AMM formula $P = \frac y x$. For example, if your price is quoted as 0.007 MEME/USD, the assignment is:
- x (Base Asset) = MEME
- y (Quote Asset) = USD
If the price is 0.007 MEME/USD, your pool will have a large reserve of MEME, and a small reserve of USD. This is because each MEME is worth very little, the contract must hold a much higher quantity of them to maintain the equilibrium of the constant product.
Concrete Example: Assume we have a pool that swaps PIZZA and USD. Also, assume that the current price of a pizza is $10. Our pool is trading the PIZZA/USD pair. In financial markets, the price is quoted as 10, meaning 10 USD/PIZZA. You may see a price of 10 quoted for the PIZZA/USD pair, and this can be very confusing!
The slash in the pair name is just a separator, while the slash in the price is a mathematical unit. In finance, the first asset in a pair is the base (x) and the second is the quote (y). Because pizza is an expensive asset relative to the dollar, the reserves are weighted toward the quote:
- 1000 Pizza Base Reserves (x)
- 10000 USD Quote Reserves (y)
- 10.00 Price ($P = \frac y x$)
- ~3162.28 Liquidity ($L = \sqrt k = \sqrt{x \cdot y}$)
In modern liquidity pool implementations, Liquidity ($L$) is defined as the square root of the invariant. This representation allows for a more linear understanding of pool depth and simplifies the relationship between the price and reserves.
\[L^2 = k = x \cdot y \quad \Big| \quad L = \sqrt k = \sqrt{x \cdot y} \quad \Big| \quad x = \frac{L}{\sqrt P} \quad \Big| \quad y = L \cdot \sqrt P \quad \Big| \quad P = \frac{y}{x}\]$x, y, k$: Original reserves and invariant as defined in the previous sections.
$L$ (Liquidity): A measure of the pool’s “depth.” This value remains constant during swaps and only changes when liquidity is added or removed. [Unit: $\sqrt{\text{Token X} \cdot \text{Token Y}}$]
$P$ (Spot Price): The current marginal exchange rate of the pool. [Unit: Token Y / Token X]
Technical Insight: The square root operation effectively reduces the two-dimensional area of the invariant ($k$) to a single linear dimension ($L$). This linearizes the relationship between capital and pool depth. For example, doubling the assets in the pool results in a 2x increase in $L$, rather than a 4x increase in $k$.
Liquidity to Reserve Units: L has units of $\sqrt{x \cdot y}$, while the term $\sqrt P = \sqrt \frac y x$ is used to calculate reserves from the liquidity. For y reserves, the units are $\frac{\sqrt{x} \cdot \sqrt{y}}{1} \cdot \frac{\sqrt y}{\sqrt x} = y$. Note that $\frac{1}{\sqrt P}$ is the reciprocal of the price, or $\sqrt{\frac x y}$. The units for x reserves are therefore $\frac{\sqrt{x} \cdot \sqrt{y}}{1} \cdot \frac{\sqrt x}{\sqrt y} = x$.
To maintain the invariant ($k$) when a trader interacts with the pool, we use the Swap Execution Formula. This represents the state of the pool before and after a transaction. When you perform a swap, the smart contract calculates exactly how many tokens to move. This is derived by solving the constant product invariant for the unknown variable ($\Delta x$ or $\Delta y$).
\[(x - \Delta x) \cdot (y + \Delta y) = k \quad \Big| \quad \Delta x = \frac{x \cdot \Delta y}{y + \Delta y} \quad \Big| \quad \Delta y = \frac{y \cdot \Delta x}{x - \Delta x}\]$x, y, k$: Original reserves and invariant as defined in the previous sections.
$\Delta x$ (Swap Output): The number of tokens (e.g., memecoin or basecoin) the trader receives from the pool. [Unit: Token X]
$\Delta y$ (Swap Input): The number of tokens (e.g., stablecoin or quotecoin) the trader deposits into the pool. [Unit: Token Y]
Note on Slippage: Because the denominator of the $\Delta x$ solution includes $\Delta y$, as the input quantity increases, the output does not grow linearly. This mathematical reality is what creates Price Impact. The more you buy, the more expensive each subsequent unit becomes.
The fee calculations extend the ideal Swap Execution Formula. Before the trade is executed, the pool takes a percentage fee ($f$) of the token input before performing the constant product calculation. This creates a divergence between the zero fee ideal swap and the actual net swap that hits the trader’s wallet.
The service fee can be set aside for liquidity providers, or it can be reinvested into the pool, depending on how the smart contract is set up. For real world use cases, see your pool documentation.
\[(x - \Delta x_{net}) \cdot (y + \Delta y_{net}) = k \quad \Big| \quad \Delta x_{net} = \frac{x \cdot \Delta x \cdot (1 - f)}{x - \Delta x \cdot f} = \frac{x \cdot \Delta y \cdot (1 - f)}{y + \Delta y \cdot (1 - f)} \quad \Big| \quad \Delta y_{net} = \Delta y \cdot (1 - f) = \frac{y \cdot \Delta x \cdot (1 - f)}{x - \Delta x}\]$x, y, k$: Original reserves and invariant as defined in the previous sections.
$\Delta x, \Delta y$: Ideal output/input values assuming zero fees, as defined in the previous section.
$f$ (Fee): Service fee taken by the pool (e.g., $0.003$ for $0.3\%$). [Dimensionless]
$\Delta x_{net}$ (Net Swap Output): The actual quantity of tokens (e.g., memecoin or basecoin) the trader receives after fees are deducted from the input. [Unit: Token X]
$\Delta y_{net}$ (Net Swap Input): The portion of the trader’s deposit (e.g., stablecoin or quotecoin) that actually shifts the price. The remainder $(\Delta y \cdot f)$ is the fee collected by the pool. [Unit: Token Y]
After a trade is executed, the balance of the pool has shifted. Because there are now more of Token Y and fewer of Token X, the price of Token X increases. The new spot price represents the marginal price for the very next trader in line.
\[P_{old} = \frac{y}{x} \quad \Big| \quad P_{effective} = \frac{\Delta y}{\Delta x_{net}} \quad \Big| \quad P_{new} = \frac{y + \Delta y}{x - \Delta x_{net}}\]$P_{old}$ (Pre-Trade Spot Price): The market price before the transaction occurs. [Unit: Token Y / Token X]
$P_{effective}$ (Execution Price): The average price paid for the entire swap. Due to slippage, this is always higher than $P_{old}$ and lower than $P_{new}$. Note that although the total gross $\Delta y$ is deposited, only $\Delta x_{net}$ is received by the trader after fees. [Unit: Token Y / Token X]
$P_{new}$ (Post-Trade Spot Price): The updated marginal price of the pool after the reserves have been rebalanced. This assumes the fee is reinvested into the pool. Use $\Delta y_{net}$ in the numerator if fees are paid out to a treasury. [Unit: Token Y / Token X]
$y + \Delta y$: New Reserve of Token Y with reinvestment. Original inventory plus the trader’s total deposit.
$y + \Delta y_{net}$: New Reserve of Token Y without reinvestment. Original inventory plus the trader’s total deposit less fees.
$x - \Delta x_{net}$: New Reserve of Token X. Original inventory minus the trader’s payout.
Note on Price Impact: The difference between $P_{old}$ and $P_{effective}$ is what traders refer to as Price Impact. On large trades, the gap between these three prices widens significantly.
Adding liquidity expands the pool’s reserves of both assets simultaneously. To avoid shifting the market price during a deposit, assets must be provided proportionally to the existing ratio. This action pushes the constant product curve outward, increasing the pool’s invariant ($k$).
\[\Delta k = (x + \Delta x)(y + \Delta y) - xy \quad \Big| \quad \Delta x = \frac{x \cdot \Delta y}{y} \quad \Big| \quad \Delta y = \frac{y \cdot \Delta x}{x}\]$x, y, k$: Original reserves and invariant as defined in the previous sections.
$\Delta x$ (Token X Deposit): The amount of Token X (e.g., memecoin or basecoin) provided by the Liquidity Provider. [Unit: Token X]
$\Delta y$ (Token Y Deposit): The amount of Token Y (e.g., stablecoin or quotecoin) provided by the Liquidity Provider. [Unit: Token Y]
$\Delta k$ (Change in Invariant): The increase in the pool’s product. This represents the added “depth” of the pool. Generally positive, representing pool growth. A negative value indicates liquidity withdrawal. [Unit: Token X $\cdot$ Token Y]
Note on Price Stability: For a standard deposit, the ratio $\frac{\Delta y}{\Delta x}$ must equal the current spot price $\frac{y}{x}$. If a provider deposits a disproportionate amount, they are effectively performing a “swap” against the pool, shifting the price and incurring slippage before their liquidity is staked. Single-asset and disproportionate deposits are mathematically possible, but generally disallowed by AMM smart contracts in practice.
Impermanent Loss (IL) is the difference in value between holding a set of assets in a liquidity pool versus simply holding them in a private wallet. It occurs because the AMM’s constant product formula rebalances your position as prices change, effectively selling the “winner” and buying more of the “loser.”
\[IL(r) = \frac{2\sqrt{r}}{1+r} - 1\]$IL(r)$ (Impermanent Loss): The percentage difference in the total value of your position compared to holding. This result is always $\le 0$ (a loss), though it is “impermanent” because it can disappear if the price ratio returns to its original state. Generally expressed as a percentage. [Dimensionless]
$r$ (Price Ratio): The ratio of the new price to the original price ($P_{new} / P_{old}$). For example, if the meme coin price doubles, $r = 2$. [Dimensionless]
| Price Example ($P_{new}$) | Price Ratio ($r$) | Impermanent Loss |
|---|---|---|
| 0.00700 | 1.00 | 0.0% |
| 0.00875 | 1.25 | -0.6% |
| 0.01050 | 1.50 | -2.0% |
| 0.01225 | 1.75 | -3.8% |
| 0.01400 | 2.00 | -5.7% |
| 0.02100 | 3.00 | -13.4% |
| 0.02800 | 4.00 | -20.0% |
| 0.03500 | 5.00 | -25.5% |
Note on Fees: In practice, LPs provide liquidity to earn trading fees. If the accumulated fees earned during the period are greater than the $IL(r)$, the liquidity provider still walks away with a net profit.
While these equations define the theoretical boundaries of a pool, translating them into code requires careful handling of fixed-point math and rounding errors to prevent dust accumulation or drainage. The code for the AMM calculator is below. Integration and usage assumes familiarity with Rust-based WASM, as documented in a post I wrote on the topic.
Cargo.toml full listing
[package]
name = "post_constant_amm_mathematics"
version = "0.1.0"
edition = "2024"
[lib]
crate-type = ["cdylib"]
[dependencies]
js-sys = "0.3.85"
ra-solana-math = "0.1.1"
wasm-bindgen = "0.2.108"
web-sys = { version = "0.3.85", features = ["Document", "Element", "Event", "EventTarget", "HtmlElement", "HtmlInputElement", "Node", "Window"] }
src/lib.rs full listing
use ra_solana_math::FixedPoint;
use std::rc::Rc;
use wasm_bindgen::JsCast;
use wasm_bindgen::prelude::*;
use web_sys::HtmlInputElement;
struct AmmCalculatorInputs {
liq: HtmlInputElement,
price: HtmlInputElement,
slider: HtmlInputElement,
x: HtmlInputElement,
y: HtmlInputElement,
}
enum AmmCalculatorUpdateMode {
FromLiqPrice,
FromReserves,
}
#[wasm_bindgen]
pub fn amm_calculator_init(anchor_id: &str) {
let window = web_sys::window().expect("Missing window");
let document = window.document().expect("Missing document");
let anchor = document
.get_element_by_id(anchor_id)
.expect("Missing anchor");
// UI Container Setup
let container = document.create_element("div").unwrap();
container.set_id(&format!("{}-container", anchor_id));
container.set_attribute("class", "amm-widget").unwrap();
// Labeled Input Helper
let create_input = |id: &str, label_text: &str, input_type: &str| {
let div = document.create_element("div").unwrap();
let label = document.create_element("label").unwrap();
label.set_text_content(Some(label_text));
let input = document
.create_element("input")
.unwrap()
.dyn_into::<HtmlInputElement>()
.unwrap();
input.set_id(&format!("{}-{}", anchor_id, id));
input.set_type(input_type);
div.append_child(&label).unwrap();
div.append_child(&input).unwrap();
(div, input)
};
let (liq_div, liq_input) = create_input("liq", "Liquidity (L)", "text");
let (price_div, price_input) = create_input("price", "Price (P)", "text");
let (slider_div, slider_input) = create_input("slider", "Price Slider (Log)", "range");
let (x_div, x_input) = create_input("x", "Reserve (X), Meme or Base", "text");
let (y_div, y_input) = create_input("y", "Reserve (Y), Stable or Quote", "text");
// Slider Configuration
slider_input.set_min("-6");
slider_input.set_max("6");
slider_input.set_step("0.01");
container.append_child(&liq_div).unwrap();
container.append_child(&price_div).unwrap();
container.append_child(&slider_div).unwrap();
container.append_child(&x_div).unwrap();
container.append_child(&y_div).unwrap();
// Anchor Replacement
anchor
.parent_node()
.unwrap()
.replace_child(&container, &anchor)
.unwrap();
// Centralized Update Logic
// Wrap inputs in Rc<RefCell> so they can be captured by multiple closures.
let inputs = Rc::new(AmmCalculatorInputs {
liq: liq_input,
price: price_input,
slider: slider_input,
x: x_input,
y: y_input,
});
let update_widget = {
let inputs = inputs.clone();
let zero = FixedPoint::from_int(0); // Reusable zero
move |mode: AmmCalculatorUpdateMode| match mode {
AmmCalculatorUpdateMode::FromLiqPrice => {
let l_f = inputs.liq.value().parse::<f64>().unwrap_or(0.0);
let p_f = inputs.price.value().parse::<f64>().unwrap_or(0.0);
let l = FixedPoint::from_f64(l_f).unwrap_or(zero);
let p = FixedPoint::from_f64(p_f).unwrap_or(zero);
if let Ok(sqrt_p) = p.sqrt() {
let x = l.div(&sqrt_p).unwrap_or(zero);
let y = l.mul(&sqrt_p).unwrap_or(zero);
inputs
.x
.set_value(&format!("{:.6}", x.to_f64().unwrap_or(0.0)));
inputs
.y
.set_value(&format!("{:.6}", y.to_f64().unwrap_or(0.0)));
let p_float = p.to_f64().unwrap_or(0.0);
inputs.slider.set_value(&p_float.log10().to_string());
}
}
AmmCalculatorUpdateMode::FromReserves => {
let x_f = inputs.x.value().parse::<f64>().unwrap_or(0.0);
let y_f = inputs.y.value().parse::<f64>().unwrap_or(0.0);
let l_f = (x_f * y_f).sqrt();
let p_f = if x_f != 0.0 { y_f / x_f } else { 0.0 };
let l = FixedPoint::from_f64(l_f).unwrap_or(zero);
let p = FixedPoint::from_f64(p_f).unwrap_or(zero);
inputs
.liq
.set_value(&format!("{:.6}", l.to_f64().unwrap_or(0.0)));
inputs
.price
.set_value(&format!("{:.6}", p.to_f64().unwrap_or(0.0)));
inputs.slider.set_value(&p_f.log10().to_string());
}
}
};
// Callback Setup
let update_rc = Rc::new(update_widget);
let on_price_change = {
let u = update_rc.clone();
Closure::wrap(Box::new(move |_e: web_sys::Event| {
u(AmmCalculatorUpdateMode::FromLiqPrice);
}) as Box<dyn FnMut(_)>)
};
inputs
.liq
.add_event_listener_with_callback("input", on_price_change.as_ref().unchecked_ref())
.unwrap();
inputs
.price
.add_event_listener_with_callback("input", on_price_change.as_ref().unchecked_ref())
.unwrap();
on_price_change.forget();
let on_slider_change = {
let u = update_rc.clone();
let ins = inputs.clone();
Closure::wrap(Box::new(move |_e: web_sys::Event| {
let val: f64 = ins.slider.value().parse().unwrap_or(0.0);
let price = 10.0_f64.powf(val);
ins.price.set_value(&format!("{:.6}", price));
u(AmmCalculatorUpdateMode::FromLiqPrice);
}) as Box<dyn FnMut(_)>)
};
inputs
.slider
.add_event_listener_with_callback("input", on_slider_change.as_ref().unchecked_ref())
.unwrap();
on_slider_change.forget();
let on_reserve_change = {
let u = update_rc.clone();
Closure::wrap(Box::new(move |_e: web_sys::Event| {
u(AmmCalculatorUpdateMode::FromReserves);
}) as Box<dyn FnMut(_)>)
};
inputs
.x
.add_event_listener_with_callback("input", on_reserve_change.as_ref().unchecked_ref())
.unwrap();
inputs
.y
.add_event_listener_with_callback("input", on_reserve_change.as_ref().unchecked_ref())
.unwrap();
on_reserve_change.forget();
// Default Values
inputs.liq.set_value("1000000.000000");
inputs.price.set_value("0.007000");
update_rc(AmmCalculatorUpdateMode::FromLiqPrice);
}
Widget JS Injection Anchor Example
<script type="module" id="amm_calculator_ui">
import init, { amm_calculator_init } from "/assets/wasm/post_constant_amm_mathematics/post_constant_amm_mathematics.js";
async function run() {
await init();
amm_calculator_init("amm_calculator_ui");
}
run();
</script>
Widget Inline CSS Styling Example
<style>
.amm-widget {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 15px;
padding: 20px;
border: 2px solid red;
border-radius: 8px;
max-width: 500px;
background-color: #ffffff;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
}
.amm-widget div:nth-child(3) {
grid-column: 1 / span 2;
display: flex;
flex-direction: column;
}
.amm-widget div {
display: flex;
flex-direction: column;
gap: 5px;
}
.amm-widget label {
font-size: 0.85rem;
font-weight: 600;
color: #333;
}
.amm-widget input[type="text"] {
padding: 8px;
border: 1px solid #ccc;
border-radius: 4px;
font-size: 1rem;
width: 100%;
box-sizing: border-box;
}
.amm-widget input[type="range"] {
width: 100%;
margin: 10px 0;
}
@media (max-width: 400px) {
.amm-widget {
grid-template-columns: 1fr;
}
.amm-widget div:nth-child(3) {
grid-column: 1;
}
}
</style>
The Constant Product Formula is a masterpiece of simple yet profound engineering. By reducing the complexity of a market to a single invariant ($k$), it created a system where liquidity is always available, prices are mathematically predictable, and anyone can become a market maker. Whether you are building a trading bot or a new DEX, understanding the relationship between reserves, price, and liquidity is the first step toward mastering DeFi.
Jekyll generates static pages from templates. It is often used for blogs, like this one. Sometimes you want to include interactive elements, like calculators.
This post documents how web assembly (WASM) driven UI widget
can be included in a Jekyll blog post with Rust
and wasm-bindgen.
It is a tutorial on getting the WASM to work, not a deep dive
into wasm-bindgen.
The post largely documents the steps taken to get the following UI-widget up and running on this page.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-01-26 04:19:39 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 23.6.0: Mon Jul 29 21:14:30 PDT 2024; root:xnu-10063.141.2~1/RELEASE_ARM64_T6000 arm64
$ sw_vers
ProductName: macOS
ProductVersion: 14.6.1
BuildVersion: 23G93
# Hardware Information
$ system_profiler SPHardwareDataType | sed -n '8,10p'
Chip: Apple M1 Max
Total Number of Cores: 10 (8 performance and 2 efficiency)
Memory: 32 GB
# Shell and Version
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version | head -n 1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
# Rust Installation Versions
$ cargo --version
cargo 1.93.0 (083ac5135 2025-12-15)
First, create a new library project.
PROJECT_NAME="post_webasm_on_jekyll"
cargo new --lib "${PROJECT_NAME}"
cd "${PROJECT_NAME}"
Next, add the js-sys, wasm-bindgen, and web-sys dependencies for this project.
cargo add js-sys
cargo add wasm-bindgen
cargo add web-sys \
-F Document -F Element -F Event -F EventTarget \
-F HtmlElement -F HtmlInputElement -F Node -F Window
WASM needs to be packaged as a dynamic library, so set the library type to a C dynamic library using your editor of choice.
Cargo.toml partial listing
[lib]
crate-type = ["cdylib"]
Your complete Cargo.toml should look something like this.
Cargo.toml full listing
[package]
name = "post_webasm_on_jekyll"
version = "0.1.0"
edition = "2024"
[lib]
crate-type = ["cdylib"]
[dependencies]
js-sys = "0.3.85"
wasm-bindgen = "0.2.108"
web-sys = { version = "0.3.85", features = ["Document", "Element", "Event", "EventTarget", "HtmlElement", "HtmlInputElement", "Node", "Window", ] }
Replace src/lib.rs with the following contents.
src/lib.rs full listing
use wasm_bindgen::prelude::*;
use wasm_bindgen::JsCast;
use web_sys::{HtmlElement, HtmlInputElement, Event};
#[wasm_bindgen]
pub fn inject_ui(anchor_id: &str) {
let document = web_sys::window()
.unwrap()
.document()
.unwrap();
let anchor = document
.get_element_by_id(anchor_id)
.expect("anchor element not found");
let parent = anchor
.parent_node()
.expect("anchor has no parent");
let container = document
.create_element("div")
.unwrap();
container.set_class_name("wasm-greeting-ui");
// --- Line 1: label + input ---
let line1 = document.create_element("div").unwrap();
line1.set_class_name("line1");
let label = document.create_element("label").unwrap();
label.set_text_content(Some("Name: "));
label.set_attribute("for", "name-input").unwrap();
let input: HtmlInputElement = document
.create_element("input")
.unwrap()
.dyn_into()
.unwrap();
input.set_type("text");
input.set_id("name-input");
input.set_placeholder("Enter your name");
// append label + input to line1 container
line1.append_child(&label).unwrap();
line1.append_child(&input).unwrap();
// --- Line 2: message ---
let message: HtmlElement = document
.create_element("div")
.unwrap()
.dyn_into()
.unwrap();
message.set_class_name("line2");
update_message(&message, None);
// Append line1 and line2 to the main container
container.append_child(&line1).unwrap();
container.append_child(&message).unwrap();
// Replace the anchor with the new UI
parent.replace_child(&container, &anchor).unwrap();
// --- Event listener ---
let message_clone = message.clone();
let input_clone = input.clone();
let closure = Closure::wrap(Box::new(move |_event: Event| {
let value = input_clone.value();
if value.trim().is_empty() {
update_message(&message_clone, None);
} else {
update_message(&message_clone, Some(&value));
}
}) as Box<dyn FnMut(Event)>);
input
.add_event_listener_with_callback("input", closure.as_ref().unchecked_ref())
.unwrap();
closure.forget();
}
fn update_message(message: &HtmlElement, name: Option<&str>) {
let name = name.unwrap_or("USERNAME");
message.set_text_content(Some(&format!("Hello, {}!", name)));
}
Install wasm-pack with cargo if you need to.
cargo install wasm-pack
Build the WASM with the following command.
wasm-pack build --target web
wasm-pack produces files in pkg/, which Jekyll will not serve automatically.
tree pkg/
Expected Output
pkg/
├── post_webasm_on_jekyll.d.ts
├── post_webasm_on_jekyll.js
├── post_webasm_on_jekyll_bg.wasm
├── post_webasm_on_jekyll_bg.wasm.d.ts
└── package.json
1 directory, 5 files
To serve these files, they need to be copied into
${JEKYLL_PATH}/assets, ideally in something like the
wasm/${PROJECT_NAME} subdirectory to keep things organized.
Note that you probably do not want to copy the generated .gitignore.
Using pkg/* ensures we copy all build artifacts while ignoring the hidden
.gitignore file that wasm-pack creates, which would otherwise hide your
WASM files from git and complicate deployment.
Use the following command to copy the files.
PROJECT_NAME="post_webasm_on_jekyll"
JEKYLL_PATH="/path/to/jekyll/blog"
mkdir -p "${JEKYLL_PATH}/assets/wasm/${PROJECT_NAME}"
cp -r pkg/* "${JEKYLL_PATH}/assets/wasm/${PROJECT_NAME}/"
If you want to overwrite existing files automatically, add -f.
cp -rf pkg/* "${JEKYLL_PATH}/assets/wasm/${PROJECT_NAME}/"
After copying, all files should be present in the assets directory.
ls -1 "${JEKYLL_PATH}/assets/wasm/${PROJECT_NAME}/"
Expected Output
package.json
post_webasm_on_jekyll.d.ts
post_webasm_on_jekyll.js
post_webasm_on_jekyll_bg.wasm
post_webasm_on_jekyll_bg.wasm.d.ts
Inline an HTML script tag in the blog post to load the WASM.
Note that the id of the script tag is used as an anchor,
which the Rust code will replace with the WASM-driven UI.
Alternatively, you can use an empty div (<div id="wasm_ui"></div>)
or a self-closing tag like <input type="hidden" id="wasm_ui" />
as your anchor if you prefer to keep the script logic and the
UI placement separate.
<script type="module" id="wasm_ui">
import init, { inject_ui } from "/assets/wasm/post_webasm_on_jekyll/post_webasm_on_jekyll.js";
async function run() {
await init();
inject_ui("wasm_ui");
}
run();
</script>
Also, you can add CSS in a style block above the script tag,
or put it in an included external file if you want to style your UI.
<style>
.wasm-greeting-ui {
max-width: 300px;
font-family: sans-serif;
border: 2px solid red; /* red outline */
padding: 0.75rem; /* some space inside the box */
border-radius: 4px; /* optional: slightly rounded corners */
background-color: #fff; /* optional: white background */
}
.wasm-greeting-ui .line1 {
display: flex;
align-items: center;
gap: 0.5rem;
margin-bottom: 0.5rem;
}
.wasm-greeting-ui .line2 {
font-weight: bold;
}
</style>
If you want to explore more about WebAssembly, Rust, and integrating dynamic UIs in static sites, these resources are highly recommended:
Rust and WASM Fundamentals:
Learn how Rust compiles to WebAssembly, how to use wasm-bindgen, and best
practices for building interactive web apps. See the official
Rust and WebAssembly Book.
Jekyll Assets & Static Sites: Tips on structuring static assets in Jekyll, managing JavaScript/CSS, and optimizing for WASM loading can be found in the Jekyll Assets Documentation.
no_std Rust programming involves developing applications
without relying on Rust’s standard library (std). This constraint is typical
in embedded systems, where resources are limited or when direct control over
hardware is required. Why use no_std Rust?
std assumes an operating system, and it has not
been ported to many specialized systems.This post introduces no_std Rust, providing the foundation you need
to start your journey in the world of embedded development with Rust. After that,
it covers how the no_std core and alloc functionality is exposed to std
Rust programs before giving pointers to more in-depth information.
This post assumes a general familiarity with Rust, rustup and cargo.
Readers who are not familiar with Rust and the ecosystem tooling should consider
starting with “The Rust Programming Language Book”.
(rustup and cargo also have extensive
documentation.)
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-01-16 21:40:17 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 23.6.0: Mon Jul 29 21:14:30 PDT 2024; root:xnu-10063.141.2~1/RELEASE_ARM64_T6000 arm64
$ sw_vers
ProductName: macOS
ProductVersion: 14.6.1
BuildVersion: 23G93
# Hardware Information
$ system_profiler SPHardwareDataType | sed -n '8,10p'
Chip: Apple M1 Max
Total Number of Cores: 10 (8 performance and 2 efficiency)
Memory: 32 GB
# Shell and Version
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version | head -n 1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
# Rust Installation Versions
$ cargo --version
cargo 1.92.0 (344c4567c 2025-10-21)
This tutorial aims to guide you through creating a no_std Rust library that performs fundamental rocket calculations. Once the library is developed, we will demonstrate its use through a simple binary application that utilizes these computations.
The thrust $T$, generated by a rocket, is calculated by the following equation:
\[T = \dot{m} \times v_e + (p_e - p_0) \times A_e\]where:
The specific impulse $I_{sp}$, which indicates the efficiency of rocket propellants, can be derived from the thrust and the mass flow rate as follows:
\[I_{sp} = \frac{T}{\dot{m} \times g_0}\]where:
The delta-v $\Delta v$, or change in velocity that a rocket can achieve, is calculated using the Tsiolkovsky rocket equation:
\[\Delta v = I_{sp} \times g_0 \times \ln\left(\frac{m_0}{m_f}\right)\]where:
Start by creating a new Rust project using cargo.
PROJECT="no_std_example"
cargo new --lib "${PROJECT}"
cd "${PROJECT}"
In your lib.rs, declare the project as no_std and start coding.
In the following example, note that the
ideal rocket equation includes a
natural logarithm, so ln needs to be pulled in from libm.
Neither the specific impulse equation
nor the rocket thrust equation use anything beyond
arithmetic, so they do not require the dependency.
// src/lib.rs
#![no_std]
extern crate libm;
/// Standard gravity (m/s^2)
pub const G0: f32 = 9.80665;
/// Calculates the thrust given the mass flow rate of the propellant (m dot),
/// the exhaust velocity (Ve), the pressure at the nozzle exit (Pe),
/// the ambient pressure (P0), and the exit area of the nozzle (Ae).
///
/// # Arguments
///
/// * `m_dot` - Mass flow rate of the propellant (kg/s).
/// * `ve` - Exhaust velocity (m/s).
/// * `pe` - Pressure at the nozzle exit (Pa).
/// * `p0` - Ambient pressure (Pa).
/// * `ae` - Exit area of the nozzle (m^2).
///
/// # Returns
///
/// Thrust in Newtons.
pub fn calculate_thrust(m_dot: f32, ve: f32, pe: f32, p0: f32, ae: f32) -> f32 {
m_dot * ve + (pe - p0) * ae
}
/// Calculates the specific impulse given the thrust and the mass flow rate.
///
/// # Arguments
///
/// * `thrust` - The thrust in Newtons (N).
/// * `m_dot` - The mass flow rate in kilograms per second (kg/s).
///
/// # Returns
///
/// * Specific impulse in seconds (s).
pub fn calculate_specific_impulse(thrust: f32, m_dot: f32) -> f32 {
thrust / (m_dot * G0)
}
/// Calculates the delta-v of a rocket using the Tsiolkovsky rocket equation.
///
/// # Arguments
///
/// * `isp` - The specific impulse in seconds (s).
/// * `m0` - The initial total mass of the rocket (including propellant) in kilograms (kg).
/// * `mf` - The final mass of the rocket (without propellant) in kilograms (kg).
///
/// # Returns
///
/// * Delta-v in meters per second (m/s).
pub fn calculate_delta_v(isp: f32, m0: f32, mf: f32) -> f32 {
isp * G0 * libm::logf(m0 / mf)
}
#[cfg(test)]
mod tests {
use super::*;
const ACCEPTABLE_ERROR: f32 = 1e-3;
#[test]
fn test_calculate_thrust() {
let m_dot = 5.0; // Mass flow rate (kg/s)
let ve = 2500.0; // Exhaust velocity (m/s)
let pe = 101325.0; // Pressure at nozzle exit (Pa) - Atmospheric pressure
let p0 = 101325.0; // Ambient pressure (Pa) - Atmospheric pressure
let ae = 0.1; // Exit area of the nozzle (m^2)
let expected_thrust = 12500.0; // Expected thrust (N)
let thrust = calculate_thrust(m_dot, ve, pe, p0, ae);
// Ensure the calculated thrust is as expected
assert!( (thrust - expected_thrust).abs() < ACCEPTABLE_ERROR);
}
#[test]
fn test_calculate_specific_impulse() {
let thrust = 12500.0; // Thrust (N)
let m_dot = 5.0; // Mass flow rate (kg/s)
let expected_isp = 254.929; // Expected specific impulse (s)
let isp = calculate_specific_impulse(thrust, m_dot);
// Ensure the calculated thrust is as expected
assert!( (isp - expected_isp).abs() < ACCEPTABLE_ERROR);
}
#[test]
fn test_calculate_delta_v() {
let isp = 254.6479; // Specific impulse (s)
let m0 = 1000.0; // Initial mass of the rocket (kg)
let mf = 100.0; // Final mass of the rocket (kg)
let expected_delta_v = 5750.114; // Expected delta-v (m/s)
let delta_v = calculate_delta_v(isp, m0, mf);
// Ensure the calculated delta-v is as expected
assert!( (delta_v - expected_delta_v).abs() < ACCEPTABLE_ERROR);
}
}
Modify your Cargo.toml to pull in the libm dependency.
Also, specify the panic = "abort" strategy.
$ cargo add libm
$ cat <<EOF >> Cargo.toml
[profile.dev]
panic = "abort"
[profile.release]
panic = "abort"
EOF
# Cargo.toml
[package]
name = "no_std_example"
version = "0.1.0"
edition = "2021"
[dependencies]
libm = "0.2.15"
[profile.dev]
panic = "abort"
[profile.release]
panic = "abort"
Test the library.
$ cargo test
Next, add a src/main.rs file that uses the library.
// src/main.rs
#![no_std]
#![no_main]
// Change the following line to use your crate name.
use no_std_example as crate_library;
use libc_print;
#[unsafe(no_mangle)]
pub extern "C" fn main(_argc: i32, _argv: *const *const u8) -> i32 {
// Example values for thrust calculation
let m_dot = 5.0; // Mass flow rate in kg/s
let ve = 2500.0; // Exhaust velocity in m/s
let pe = 101325.0; // Pressure at nozzle exit in Pa
let p0 = 101325.0; // Ambient pressure in Pa
let ae = 0.1; // Exit area of the nozzle in m^2
// Calculating thrust
let thrust = crate_library::calculate_thrust(m_dot, ve, pe, p0, ae);
libc_print::libc_println!("Thrust: {} N", thrust);
// Calculating specific impulse
let isp = crate_library::calculate_specific_impulse(thrust, m_dot);
libc_print::libc_println!("Specific Impulse: {} s", isp);
// Example values for delta-v calculation
let m0 = 1000.0; // Initial total mass in kg
let mf = 100.0; // Final mass in kg
// Calculating delta-v
let delta_v = crate_library::calculate_delta_v(isp, m0, mf);
libc_print::libc_println!("Delta-v: {} m/s", delta_v);
// Return success
0
}
// Panic handling in module for easy conditional exclusion when testing.
// Testing pulls in std, which provides panic handling.
mod panic_handling {
use core::panic::PanicInfo;
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
loop {}
}
// dummy symbol hack for my `aarch64-apple-darwin` host
#[unsafe(no_mangle)]
pub extern "C" fn rust_eh_personality() {}
}
We are using libc_print for output in the above binary, so add it as a
dependency in Cargo.toml.
$ cargo add libc-print
# Cargo.toml, partial listing
[dependencies]
libc-print = "0.1.23"
Generally speaking, libc can used in conjunction with no_std code to
test its functionality on the development host machine. Note that libc
is not always available on development targets. Some systems have a
proprietary library that implements key functionality generally found in
libc, while others have a quirky proprietary libc. In these cases,
it is safe to assume that libc related crates cannot be used.
You can run the no_std binary on the host machine with the following
command.
cargo run
Assuming you are using a modern Stable toolchain and the panic = "abort"
profile is set, the output should look something like this.
Thrust: 12500 N
Specific Impulse: 254.92906 s
Delta-v: 5756.4634 m/s
This concludes the tutorial section of the post.
As illustrated above, standard Rust unit and
integration testing can be
used to validate no_std code.
You might need to simulate or mock the hardware interactions.
Continuous integration
can also be used to ensure that
every change is validated on both host and target platforms.
Real Time Transfer (RTT) is supported by
probe-rs and it can be used to log the state of code
running on an embedded device.
cargo-embed, another probe-rs tool, even supports on device
GDB debugging.
Emulators like QEMU can be used to simulate your target hardware environment, which is especially useful for early development stages. Tools like JTAG, SWD, and hardware debuggers can be used to directly interact with applications running on actual hardware.
Most crates are written assuming std Rust.
These crates can simply not be used in a no_std environment.
no_std alternatives will need to be identified, and you may need to write
your own implemention if your desired functionality is unavailable.
When a program is declard no_std, it automatically pulls in the core crate.
There is no way around this. no_std core is Rust’s minimum feature set.
Everything that relies on heap allocated memory is located in alloc.
Note that you need to supply your own memory allocation strategy when using
alloc in a no_std environment, but there are crates like
embedded_alloc for this.
The good news is that std effectively reexports everything core and alloc.
Therefore, unlike popular third party crates, a lot of the types you are
accustomed to using are actually available in a no_std environment,
especially if core and alloc are available.
There are generally drop in replacements for the types defined in std.
The following table broadly illustrates what is reexported by std and
from where.
| Type Category | Located In | std Re-export |
Notes |
|---|---|---|---|
Primitives (u8, f32, etc.) |
core |
std |
Always available. |
| Option/Result | core |
std |
Always available. |
| Iterators/Markers | core |
std |
Copy, Send, Sync, Iterator. |
| String / Vec | alloc |
std |
Requires a #[global_allocator]. |
| Smart Pointers | alloc |
std |
Box, Arc, Rc. |
| BTreeMap/BTreeSet | alloc |
std |
HashMap is NOT in alloc (needs OS entropy). |
| Networking/Files | std |
N/A | Not available in no_std. |
BTreeMap and BTreeSet are the standard functional alternatives to HashMap
and HashSet when working in a core and alloc environment.
The hashbrown crate is a commonly used no_std HashMap alternative.
It is actually the underlying implementation of std::collections::HashMap.
Note that you must provide your own non-random hasher, like FxHash because
an OS to provide random seeds is unavailable.
In the past, nightly Rust was required to build no_std binaries.
It is still required for tier 3 targets where the -Z build-std flag needs
to be used to build core and alloc from scratch for your chip.
Outside of this toy example, you might need to do other things that require
nightly Rust.
For example, it was required in the past because a proper custom implemention
of eh_personality needed to be supplied, as opposed to the symbol hack I
used in this post.
You might need to use other unstable features, or advanced asm! feature..
The following commands can be used to install the nightly toolchain for the host system and switch to it.
$ rustup toolchain install nightly
$ rustup default nightly
The following command can be used to switch back to stable.
$ rustup default stable
The Embedded Rust Book is an excellent resource for those looking to deepen their understanding of embedded systems programming with Rust. It includes a variety of examples and extensive discussions on interfacing with hardware. Additionally, this book provides a list of useful resources that can help further your learning.
For those eager to purchase hardware to learn on, it’s wise to identify a learning resource and specifically purchase the hardware it recommends. For example, the Discovery Book is highly recommended for beginners. It provides step-by-step instructions and ready-to-run examples that are extremely helpful when you are just starting out. These examples are tailored for specific development boards, ensuring that you can follow along without compatibility issues given the right hardware. Alternatively, the embedded Rust setup explained YouTube video is a good option for those who prefer video tutorials.
The embedded Rust ecosystem is enriched by a variety of libraries that enhance functionality and ease development across different hardware platforms. Below is an overview of some essential libraries, listed alphabetically:
cargo-embed: Facilitates flashing and debugging of
embedded applications, leveraging probe-rs for its backend, and includes
support for RTT (Real-Time Transfer).
drone-os: An embedded operating system written in Rust that runs on ARM Cortex-M processors, suitable for high-performance real-time applications.
Embassy: An asynchronous runtime for embedded systems that aims to make using async/await feasible in no_std environments, with support for a variety of embedded platforms.
embedded-hal: Provides hardware abstraction layers for interfacing with peripherals across different microcontrollers, facilitating portable and reusable code.
heapless: Enables the use of static memory allocation for data structures like vectors, strings, and hash maps, crucial for systems where dynamic memory allocation cannot be used.
probe-rs: A modern debugging and flashing tool that supports a wide range of ARM Cortex-M microcontrollers.
RTIC (Real-Time Interrupt-driven Concurrency): Offers a concurrency framework for building real-time systems in Rust, which is ideal for applications needing high reliability and performance.
rubble: A Bluetooth stack implemented in pure Rust, designed for embedded systems using Bluetooth Low Energy.
svd2rust: Generates Rust API from SVD (System View Description) files, allowing for safe, ergonomic interaction with peripheral registers.
no_std Rust programming opens up a new realm of possibilities for Rust
developers in the embedded world. By understanding the basics and progressively
exploring more complex scenarios, you can leverage Rust’s safety and
performance on platforms where the standard library is not an option.
A single Rust package can contain one library and multiple binaries. Rust dependencies can only be specified at the package level, not for each binary in a package. If multiple binaries require different dependencies, using a cargo workspace is the appropriate way to organize a project.
There are multiple ways to organize a workspace. This post will cover workspace organization for a no_std library that is called from both std and no_std binaries. The library will accept an FFI-safe pointer to a logging function. The binaries will call the library, and log command line arguments using the same function without passing it to the library.
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2022-12-01 18:34:26 +0000
$ uname -vm
Darwin Kernel Version 20.6.0: Thu Sep 29 20:15:11 PDT 2022; root:xnu-7195.141.42~1/RELEASE_X86_64 x86_64
$ ex -s +'%s/<[^>].\{-}>//ge' +'%s/\s\+//e' +'%norm J' +'g/^$/d' +%p +q! /System/Library/CoreServices/SystemVersion.plist | grep -E 'ProductName|ProductVersion' | sed 's/^[^ ]* //g' | sed 'N; s/\n/ /g'
macOS 11.7.1
$ sysctl -n machdep.cpu.brand_string
Intel(R) Core(TM) i7-4790K CPU @ 4.00GHz
$ cargo --version
cargo 1.67.0-nightly (ba607b23d 2022-11-22)First, create workspace directory and add all of the member packages for the project.
mkdir workspace
cd workspace
cargo new pc
cargo new embedded
cargo new core_library --libNext, add a top level Cargo.toml file that lists project level metadata and all of member packages.
Cargo.toml
[workspace.package]
version = "0.1.0"
edition = "2021"
[workspace]
members = [
"pc",
"embedded",
"core_library",
]Move into the core_library package.
cd core_libraryModify Cargo.toml. Note that version and edition are inherited from the workspace.
core_library/Cargo.toml
[package]
name = "core_library"
version.workspace = true
edition.workspace = true
[dependencies]Add the no_std library code. It accepts an FFI-safe logging function and uses it to print a message.
core_library/src/lib.rs
#![no_std]
extern crate alloc;
use alloc::ffi::CString;
use core::ffi::c_char;
#[no_mangle]
pub extern "C" fn run(log: extern "C" fn(*const c_char)) {
let message = CString::new("Hello, core_library!")
.expect("CString::new failed");
log(message.as_ptr());
}It should now be possible to build but not run the library.
cargo buildMove into the pc package.
cd ../pcModify Cargo.toml. Note the core_library sibling dependency, in addition to inherited metadata.
pc/Cargo.toml
[package]
name = "pc"
version.workspace = true
edition.workspace = true
[dependencies]
core_library = { path = "../core_library" }The code for the binary follows. Note that the core_library sibling dependency can be used like any other dependency. The code defines an FFI-safe logging function for the library, and an adapter to the logging function that takes a String for use in local code. It then logs a message, calls the library, and echoes the command line arguments.
pc/src/main.rs
use core_library::run;
use std::{ env, ffi::CStr, ffi::CString, os::raw::c_char, };
extern "C" fn log(message: *const c_char) {
let cstr = unsafe { CStr::from_ptr(message) };
let output = String::from_utf8_lossy(cstr.to_bytes()).to_string();
println!("{}", output);
}
fn local_log(message: String) {
let output = CString::new(message)
.expect("CString::new failed");
log(output.as_ptr());
}
fn main() {
let message = String::from("Hello, pc!");
local_log(message);
run(log);
let args: Vec<String> = env::args().collect();
for i in 1..args.len() {
local_log(format!("{}: {}", i, args[i]));
}
}Run the binary with and without arguments to make sure everything works.
cargo run
cargo run -- a bc defFinally, move into the embedded package.
cd ../embeddedModify Cargo.toml. This binary depends on libc_alloc because it is a core+alloc no_std binary.
embedded/Cargo.toml
[package]
name = "embedded"
version.workspace = true
edition.workspace = true
[dependencies]
core_library = { path = "../core_library" }
libc_alloc = "1.0.3"The code for the binary does exactly the same thing as the std Rust code. Lacking std results in more verbose code that is a little harder to follow.
embedded/src/main.rs
#![no_std]
#![no_main]
#![feature(lang_items)]
#![feature(rustc_private)]
#![feature(default_alloc_error_handler)]
#[global_allocator]
static ALLOCATOR: ::libc_alloc::LibcAlloc = ::libc_alloc::LibcAlloc;
#[macro_use]
extern crate alloc;
extern crate libc;
use alloc::{ ffi::CString, string::String, string::ToString };
use core::{ ffi::c_char, ffi::CStr, };
use core_library::run;
use libc::c_int;
pub extern "C" fn log(message: *const c_char) {
let format = format!("%s\n\0");
unsafe {
libc::printf(
format.as_ptr() as *const _,
message,
);
}
}
fn local_log(message: String) {
let output = CString::new(message)
.expect("CString::new failed");
log(output.as_ptr());
}
#[no_mangle]
pub extern "C" fn main(argc: c_int, argv: *const *const c_char) -> c_int {
let message = String::from("Hello, embedded!");
local_log(message);
run(log);
for i in 1..argc {
let cstr = unsafe { CStr::from_ptr(*argv.offset(i as isize)) };
let safe_string = String::from_utf8_lossy(cstr.to_bytes()).to_string();
let output = format!("{}: {}", i, safe_string);
local_log(output);
}
return 0;
}
#[panic_handler]
fn panic(_: &core::panic::PanicInfo) -> ! {
loop {}
}
#[lang = "eh_personality"]
extern "C" fn eh_personality() {}It should run just like the std version, with slightly different output.
cargo run
cargo run -- a bc defCommands like cargo build will operate on the curent package, or on all package if in the top level of the workspace. The –workspace command-line flag can be used to build all targets from anywhere in the workspace, and the -p or –package flag can be used to specify a particular package.
# return to the top level of the workspace
cd ..
# this is where built targets live
ls target/debug/
# remove all built targets to verify that they are rebuilt
cargo clean
# run the following commands from anywhere in the workspace
cargo build --workspace
cargo build -p core_library
cargo run --package pc
cargo run --package pc -- one two three
cargo run -p embedded
cargo run -p embedded -- one two threeThe Cargo and Rust Programming Language books have sections on workspaces. The documentation for std::ffi can be useful for FFI work involving strings. Note that the types are reexported to std, but they need to be pulled in from core or alloc in no_std Rust. The Embedded Rust Book is a good place to get started with no_std Rust.