Pure Routes

Pure routes are stateless computations exposed as entry points. They have no access to entity state and cannot perform side effects. Use them when callers need a pure calculation via the same route interface as other operations.

Syntax

Pure routes are declared with the pure keyword and must specify a return type:

pure compute_fee(amount: U256, rate: u64) -> U256 => [
    return(amount * (rate as U256) / 10000)
]

Restrictions

Pure routes have the strictest constraints of any route kind:

Allowed	Forbidden
Parameters	Read member values
Arithmetic, logic	Write member values
`if`/`else`, `match`	Send messages (`~>`)
`let` bindings	Deploy entities
`return(value)`	Platform / host effects
Call pure functions	Access `msg::sender`, `sys::now`

A pure route behaves identically regardless of entity state or message context. Its return value depends only on its parameters.

Use Cases

Pure routes are useful for:

Fee calculations that callers can query before a mutating call.
Encoding/decoding helpers exposed as routes.
Mathematical formulas that other entities need to invoke.

pure max(a: u64, b: u64) -> u64 => [
    return(if a >= b { a } else { b })
]

pure min(a: u64, b: u64) -> u64 => [
    return(if a <= b { a } else { b })
]

pure clamp(val: u64, lo: u64, hi: u64) -> u64 => [
    return(if val < lo { lo } else if val > hi { hi } else { val })
]

Pure Routes vs. Pure Functions

Cambrian has two forms of pure computation:

Feature	Pure Route	Pure Function
Declaration	Inside `routes { }` with `pure`	Top-level with `pure fn`
Callable externally	Yes (via message)	No
Callable internally	As a route	Yes, from any expression
Syntax	`pure name(params) -> T => [...]`	`pure fn name(params) -> T { }`

Use a pure route when external callers need to invoke the computation. Use a pure function when the computation is only needed internally within the same file.

Example

entity PriceOracle {
    routes {
        pure convert(amount: U256, rate: U256, decimals: u64) -> U256 => [
            let factor = 10 as U256;
            return(amount * rate / factor)
        ]

        pure percentage(value: U256, bps: u64) -> U256 => [
            return(value * (bps as U256) / 10000)
        ]
    }
}

No Member Transforms

Like view routes, pure routes do not appear in member transform blocks. Since they cannot access state, no member can declare a transform in a pure route.

Keyboard shortcuts