Skip to main content
The XML on this page has not been tested with a supported Neuron and approved creation contract. Confirm the schema and lifecycle behavior before using it to create a Neuro-Feature.
A Neuro-Feature creation contract can embed a state-machine definition in the token’s machine-readable Definition. The machine is optional. When present, the Trust Provider creates it as the token batch is created and links it to the creation contract and the first token in the batch. Use a state machine when a token must react predictably to time, payments, contract signatures, notes, transfers, destruction, or persistent-data events.

​
Definition namespace

The root element uses the following schema namespace:
The smallest useful definition has a required startState, at least one State, and any referenced Action elements:
This fragment belongs inside the Neuro-Feature Create element of a smart contract; it is not a complete contract by itself. ISO 8601 duration PT1H means one hour.

​
Evaluation model

The machine follows this sequence:
  1. Resolve initial variables from constants, token properties, token tags, or Script expressions.
  2. Enter startState and execute its OnEnter action references.
  3. Register the active state’s event handlers.
  4. When an event matches, evaluate beforeActionScript, run actionRef, and move to newState.
  5. Run the old state’s OnLeave actions and the new state’s OnEnter actions.
  6. Sample the state and persisted variables unless sampling is explicitly suppressed.
An OnEvent may set failureState for action failures and suppressSample when a transition should not create the normal audit sample. Treat both as advanced controls: hiding samples weakens the history available to reviewers.

​
Variables and values

Top-level Variable elements initialize machine context. Their values can be:
  • A token tag through TagReference
  • A built-in token property through TokenProperty
  • Typed literals: String, Number, Boolean, Uri, Binary, Date, DateTime, Time, or Duration
  • A Script expression through Calc
Common token properties include TokenId, CreatorJid, OwnerJid, TrustProviderJid, Value, Currency, Created, Updated, Expires, CreationContract, OwnershipContract, FriendlyName, Ordinal, and BatchSize. Variables changed while an action runs are ephemeral unless the action uses PersistVariable. Persisted variables are sampled for audit and survive subsequent actions:
The attribute values above are Script expressions. Set suppressSample only when a separate operation deliberately controls sampling.

​
Event types

Events can be declared inline under OnEvent, or declared once as an Event and reused through EventReference. XML-note and contract events can filter on localName and namespace. External-note events can also require a privilege; use that instead of accepting arbitrary external senders. OnTime and OnDateTime accept time coordinates such as Local, UTC, or a quarter-hour UTC offset. Prefer UTC for workflows that cross legal or geographic boundaries.

​
Action types

An Action is an ordered sequence. The schema supports:
  • Payments: Payment, ReserveAmount, ReleaseAmount, BuyEDaler, and SellEDaler
  • Notes and authorization: TextNote, XmlNote, AuthorizeSource, and UnauthorizeSource
  • Communication: HttpPost, XmppMessage, XmppIqGet, XmppIqSet, and MailMessage
  • Runtime data: PersistVariable, CreateEntry, PersistHash, and LogEvent
  • Control flow: If, IfHash, Switch, For, ForEach, While, Do, and Try/Catch/Finally
  • Composition and lifecycle: Script, CallAction, ScheduleAction, End, Destroy, and Fail
Values can be supplied as attributes when simple, or as typed child elements when they are calculated. Response-producing actions such as HttpPost and XMPP IQ can store their result in a named variable.
State-machine actions can transfer value, disclose data, call remote systems, and destroy tokens. Review every transition as production code. In particular, constrain external-note sources, validate remote responses, and make retry behavior safe.

​
Singleton machines and token batches

One creation contract can produce a batch of tokens. The embedded definition creates one state-machine for that batch, not one independent machine per token. Use SingletonMachineId with a tag reference when multiple token creations must resolve to the same logical machine identifier. Token properties such as Ordinal and BatchSize let actions reason about the current token in a batch.

​
Note commands

NoteCommand describes a client-facing command that generates a token note. It can provide localized Title, ToolTip, Confirmation, Success, and Failure text; typed parameters; a context Script; and a note-generation Script. The flags determine where the generated note may be used:
  • ownerNote: add the note as the token owner.
  • externalNote: submit it from an authorized external source.
  • personal: mark the note as personal rather than generally visible.
The resulting text or XML note can trigger a matching note event in the machine. Validate generated XML against its namespace schema before exposing the command to users.

​
Reports and inspection

Use the Agent API to inspect a running machine: Definitions can also include ReportPresent and ReportHistory Script templates to control human-readable report content.

​
Implementation checklist

  • Validate the complete contract and embedded machine against their XML schemas.
  • Confirm every startState, newState, failureState, actionRef, and eventRef resolves.
  • Use explicit namespaces for XML and contract event filters.
  • Persist only values required across actions; name audit-relevant values clearly.
  • Decide how every remote call behaves on timeout, rejection, and retry.
  • Generate present, history, state-diagram, and profiling reports in a staging environment.
  • Exercise payment, signature, note, transfer, and terminal paths before signing the creation contract.