6. Author bindings in the Studio editor
Previous: Operations and upgrades · Learning path · Next: Admission rules
Studio’s Bindings page is a guided editor for the same composite binding documents you write in YAML. Forms are backed by an authoring catalog exported from your real plugin bundles, so you pick events, commands and fields instead of typing them. Studio never compiles or runs anything: the version-matched CLI validates and rehearses the document, and Studio explains the reports it writes.
Studio is static. It makes no network requests beyond its own files, installs no plugins, signs nothing, submits nothing and stores nothing in the browser. Download your work before closing the tab.
1. Open the editor and load a starter
Section titled “1. Open the editor and load a starter”Studio is the static site in the distribution’s studio/ directory. Serve it
locally from the distribution’s top-level directory, as in
Chapter 1, for example with
python3 -m http.server 8230 --bind 127.0.0.1 --directory studio (any free
port works), open http://127.0.0.1:8230/ and choose Bindings in the
header. Browsers block Studio’s
modules when the page is opened directly from disk. Choose Registry to audit under Starter and
select Load starter. The starter is the same document as
your first workflow: a registry put appends an audit
entry in the same atomic cascade.
The page has four views of one draft:
| View | Use it to |
|---|---|
| Form | Edit components, bindings, conditions, mappings, admission rules and limits |
| YAML | Read or edit the exact document text |
| Graph | See components and bindings in execution order; arrange the drawing |
| Validate | Get CLI commands, import CLI reports and read rehearsal outcomes |
Everything is reachable with the keyboard. The graph has a textual equivalent below the drawing.
2. Choose the right catalog
Section titled “2. Choose the right catalog”The left column shows the authoring catalog. Studio ships a bundled reference catalog for the first-party machines under the tutorial context only. For your own chain, export a catalog from the exact plugin directory and context you will deploy with:
./yano.sh appchain bindings catalog bindings.yaml \ --plugins-directory /absolute/path/to/plugins --context context.json \ > catalog.jsonProbing constructs the installed plugins with their own code, unsandboxed, exactly
as compilation does: export catalogs only from bundles you trust. The command
describes the document’s own components; add --machine <selector> for machines
you have not used yet, or --all for every installed selector.
Import catalog.json with Import catalog JSON. A catalog describes each
machine for one exact configuration: Studio never fills in or normalizes
settings. If you change a component’s settings, the form says the configuration
is not described; export the catalog again for the edited document. Without a
matching descriptor, fields become free text and checks are limited.
3. Edit with forms
Section titled “3. Edit with forms”- Components are named instances in declaration order. Rename… previews every reference it updates. Renaming changes the component’s state namespace and default topic, so it changes a deployed chain’s committed profile.
- Bindings run in list order. Move earlier and Move later change the committed program.
- Conditions are field comparisons, state lookups or restricted CEL expressions. All of them must hold.
- Mappings list the target command’s fields with their type, whether they are required, and whether they are evidence. Evidence must be copied directly from an event field. Sources are event fields, typed literals (bytes are explicit hexadecimal), documented functions nested at most two levels, or expressions.
- Admission rules are listed under their own heading. A rule form edits the
deny code, an optional command selector (only commands of attached components
that rules can select are offered), typed parameters with optional defaults, and
the clauses: restricted CEL expressions or state lookups. Insert a readable
field lists what the rule can read for its attached components: step context,
the selected command’s data fields, parameters, configuration and the verified
facts the catalog declares. A rule takes effect only where a component attaches
it: each component form has an Admission rules section to attach, order and
detach rules and to state parameter values. An omitted value uses the rule’s
default. Renaming a rule updates its attachments; renaming a binding updates
bindingparameters that name it. See Admission rules. - Reads and write views. A rule form’s Reads section declares up to four
exact-key reads: a name, the component, one of the namespaces its catalog
value views offer, and a key. Insert a readable field then also lists
reads.<name>.presentand the view’s fields. When every component the rule is attached to declares a write view, it lists the write-element fields too, forwrites.all(w, …)andwrites.exists(w, …). A rule with reads runs at block time only. See Typed views. - Limits and activation shows every committed limit. Empty means omitted: the default applies and is not written into your document.
Text values and expressions with line breaks are edited in multi-line fields.
Browser fields cannot hold carriage returns exactly, single-line fields cannot
hold line breaks, and name fields trim what you type. So a value with a carriage
return, or a name with a line break or surrounding spaces, is shown and edited as
a quoted JSON string instead, for example "line 1\r\nline 2", and nothing is
lost. Typing in the YAML view keeps the document’s line endings.
The first form edit of an imported document rewrites it as canonical YAML, which drops comments. Studio asks first, and Download original always returns the file exactly as imported. Reset draft discards every edit.
If you edit the YAML text into something that is not a valid document, the forms keep the last valid draft and are disabled, and Download bindings.yaml is refused until you fix the text or choose Revert to the last valid draft. Reverting writes that draft back as canonical YAML, without comments; Download original still returns the imported file. A document that uses a construct Studio cannot edit exactly opens read-only.
Advisory checks in the right column point at likely mistakes and open the relevant form field. They never mean the document is valid.
4. Hand off to the CLI
Section titled “4. Hand off to the CLI”Open Validate. Choose the scenario, for example Validate and rehearse 1
block, then download bindings.yaml and bindings-handoff.txt. The commands
use fixed file names only. They call ./yano.sh, so run them from the
distribution’s top-level directory with the downloaded files beside you (or
replace ./yano.sh with the script’s full path), and replace
<plugins-directory> with your plugin directory, for example plugins:
./yano.sh appchain bindings catalog bindings.yaml \ --plugins-directory <plugins-directory> --context context.json > catalog.json./yano.sh appchain bindings validate bindings.yaml \ --plugins-directory <plugins-directory> --context context.json \ --report validate-report.json./yano.sh appchain bindings dry-run bindings.yaml \ --plugins-directory <plugins-directory> --context context.json \ --fixture fixture-1.json --report dry-run-report-1.json > result-1.json--report writes an editor report beside the normal output; the normal output
and exit codes are unchanged. A report matches only a catalog exported by the same
CLI from the same plugin directory and context, so the catalog command comes
first: import its catalog.json before the reports. The bundled reference catalog
assists editing but will not match reports from your installation.
For the starters, Download tutorial context.json gives a synthetic context and
Download example fixtures gives public, synthetic fixture-N.json blocks; the
distribution also ships them under examples/bindings/fixtures/. Their
authentication proofs are placeholders, which dry runs accept because they assume
authenticated inputs.
5. Read the results
Section titled “5. Read the results”Import the report files with Import report files. Import the fixture files too, so Studio can confirm that each rehearsal used them. Importing a fixture with the same file name replaces the earlier one, and rehearsals of the replaced content become stale; the status line counts the blocks that are stale or unverified. After rerunning the CLI, import the new report too. Earlier reports stay visible as history. Studio links continuations by the preceding height and state digest, so alternate reports at the same height do not disrupt a verified chain. A continuation needs at least one matching predecessor whose own chain is verified. The status line says what Studio can claim:
| Status | Meaning |
|---|---|
| Draft with local checks only | No CLI report describes this draft |
| Imported matching CLI report | A report says the CLI validated exactly this document, context, plugin catalog and tool |
| The CLI rejected exactly the current inputs | A matching report says compiling or validating the document failed; its diagnostics link to the form |
| Rehearsed source outcomes | Reports give the real engine’s results for these exact, assumed fixture inputs; the line adds how many blocks are stale or unverified |
| Stale or unverifiable report | Something differs; the report is history, not a result for this draft |
The status considers every imported report, in any order. A dry-run that failed
only on its fixture or continuation is listed separately and never counts as a
rejection of the document. For a composite opened from an application draft
(<app>.draft.yaml) the wording never says “validated”: the CLI checked the
extracted composite under the context you supplied, and appchain seal, with
the context it derives from the application, decides.
A report is an unauthenticated file: anyone can edit one. Studio decodes every receipt from its canonical bytes and rejects reports that contradict themselves, but a match only shows the same inputs were used. It is not an attestation, a finality certificate or deployment approval.
For a validation failure, Show in the form opens the recorded location, or its closest control, when the report matches. Rehearsals are shown block by block, including empty blocks, with each block’s assumed timestamp, prior root and pending effects. Every source message says what happened:
- Accepted: every recorded step committed together in the rehearsal.
- Rejected: nothing from the cascade committed, including the source command. Planned steps are shown as planned, not committed.
- Refused by admission rule: a rule refused a step, so nothing from the cascade committed. The outcome names the rule, its deny code and the step.
- Replay or duplicate: the receipt belongs to an earlier message; nothing ran again.
Conditions show whether a binding ran, which clause was false, or where an
evaluation failed when the receipt proves it. Studio numbers conditions and
clauses from 1, as people count, while receipts and CLI JSON record them from
0: Studio’s “clause 2” is index 1, shown as "failedClause": 1 in an editor
report and "clause": 1 in dry-run output. Each step also shows its admission
rules: how many held, and the rule, clause and deny code that refused it. A
refusal of a derived step says that the whole cascade, including the source
command, was rolled back. The Procurement admission rules starter’s fixtures
include block-time refusals. The Transfer limit rule starter’s third fixture
is an over-limit transfer that the static rule refuses before any block, so that
dry-run fails on the fixture, as a node refuses it at submission. A target
component can reuse a framework rejection code, so Studio never guesses a location
the receipt does not record.
6. Multi-block approvals
Section titled “6. Multi-block approvals”Load Approval to audit. A proposal and each vote are separate messages from
different senders in separate blocks, as in approval workflows.
Choose Validate and rehearse 4 blocks, or select Download example fixtures,
which saves fixture-1.json to fixture-4.json (a proposal, a first vote, an
empty block and a second vote) and selects four blocks. The commands chain each
block’s --prior-result into the next. After importing the catalog, the four
reports and the four fixtures, Studio checks that heights are consecutive and that
each block continues the previous block’s state. The example fixtures carry
placeholder authentication proofs and synthetic senders; two browser tabs or two
fixture senders are not two consensus members or real business actors.
7. Composite files and layout
Section titled “7. Composite files and layout”Import a setup draft opens a chain’s inline composite from a setup draft
(<app>.draft.yaml). Downloading it again (as app.draft.yaml; rename it back)
replaces only that composite, then re-reads the file to prove that every other
chain and field is unchanged; otherwise it refuses, and you can download the
composite document alone. An unedited file downloads byte for byte. A draft chain that names its
composite with bindings: <file> has no inline composite to open: open that
bindings file directly instead.
Graph positions are presentation only. Drag nodes or focus one and use the arrow
keys; Download layout saves a separate bindings.layout.json. Layout never
changes the document, its compiled program or its identity.
8. After export
Section titled “8. After export”- The document goes back through the setup workflow. Use the downloaded
file with
appchain bindingscommands, then deploy it as a chain of an application:appchain new <app> --chain <id>=bindings:<file>, orbindings: ./<file>(or the body undercomposite:) for a chain in the setup draft.appchain sealcompiles it and copies it into the sealed<app>.chainfile; it is not a live include, and nothing Studio does changes a running chain. See deploying a document. - Changing a deployed workflow is an upgrade. Renaming a component or binding,
reordering bindings or changing a limit changes the committed program. Follow
changing a workflow and the
retained-chain upgrade reference;
profile-checkis a reconstruction preflight, not proof of migration or replay safety. - Real actors need real proofs. Dry runs assume authenticated inputs. For business actors in different organizations, use the actor-signed policy path.
Return to the learning path, or read the CLI reference for the catalog and report file formats.