Skip to main content
A ref is a dotpath string wrapped in { "$ref": "…" }. It binds an input port of a Call to a value produced elsewhere in the Flow: a declared input, an earlier call’s output, or a runtime context value. The SDK writes refs for you from typed handles; you write them by hand only for raw wire Flows and the raw.ref escape hatch.

The three ref scopes

1. input.<name>

References an input declared in flow.inputs:

2. context.<key>

References a runtime context value. Two keys exist, and any other key under context.* is rejected: See Write the destination flow for the other destination flow rules.

3. <nodeId>.<port>

Any ref whose prefix is not input or context references another call’s output port. <nodeId> is the id you gave the node, so builder.lifi.swap('swap', …) produces refs of the form swap.<port>:
Three rules apply to output refs:
  • The ref must point to an earlier node in nodes.
  • A ref splits at the first dot. Everything after it is the port name, so p.parts.1 addresses port parts.1 of node p. That is how you reference one instance of an output family such as core.partition’s parts (see Output families). A ref past the last instance fails as an unresolved ref.
  • A misspelled prefix becomes an output ref. inputs.amountIn or contxt.sender reads as an output of a node called inputs or contxt, then fails with a validation_error because no such node exists. The SDK’s builder.inputs and builder.context handles avoid hand-typing these paths.

Reserved prefixes

input, context and literal cannot be used as node ids. The empty string and __proto__ are rejected as node ids with a decode_error, including inside a continuation.settle node’s destination flow. literal is not a ref scope. A literal value in bind is a LiteralBinding:

How SDK handles become refs

The SDK gives you typed handles and converts them to refs when it serialises the Flow:

Raw refs (escape hatch)

builder.untypedOp(id, op, { bind, config }) adds a node for an op or config field the typed builder methods do not cover yet. It returns nothing and takes raw Ref values in bind, with no type checks. To feed its output into a typed call, wrap the path with raw.ref<T>(path), which is accepted by any Bindable<T> slot:
some.op stands for whichever manifest op you call untyped. raw.ref does no runtime validation: you choose the type parameter, and the validator rejects the flow at compile time if it does not match the port. Prefer typed builder methods whenever they exist.

Refs in forward targets

The to of an epilogue forward, the epilogue remainder and run.sweepTo accept only a literal address or { "$ref": "context.sender" }. See The flow epilogue.

See also