Author a token with a state machine and Script

Build a token definition whose first owner text note increments a stored counter and ends the machine. The contract, machine, and embedded expression are supplied as complete files. The XML and core calculation have been tested locally with Waher.Script 2.15.0. Token creation and the first transition still need to be tested on your development Neuron.

Prerequisites

Complete contract authoring and submission.
Obtain an approved Creator Legal Identity, its signing key, and access to token and state-machine Agent API operations.
Confirm the provider supports this token creation vocabulary and the selected schema set.
Arrange the TrustProvider role, template approval, any creation charge, and the provider’s signing procedure. You cannot sign the provider’s role with your Creator key.
Confirm an accepted value, currency, commission percentage, and expiration date. Zero value in the sample request is a placeholder choice, not a guarantee of free creation.

1. Start with the complete definition

Save the complete definition below as note-token.xml, or download the XML file.

Complete token creation contract

<?xml version="1.0" encoding="utf-8"?>
<contract xmlns="urn:nf:iot:leg:sc:1.0"
          canActAsTemplate="true" visibility="CreatorAndParts"
          duration="P1M" archiveReq="P1M" archiveOpt="P1M">
  <Create xmlns="https://paiwise.tagroot.io/Schema/NeuroFeatures.xsd">
    <TokenID><Random /></TokenID>
    <Creator><RoleReference role="Creator" /></Creator>
    <Owner><RoleReference role="Creator" /></Owner>
    <TrustProvider><RoleReference role="TrustProvider" /></TrustProvider>
    <Value><ParameterReference parameter="Value" /></Value>
    <Currency><ParameterReference parameter="Currency" /></Currency>
    <CommissionPercent><ParameterReference parameter="CommissionPercent" /></CommissionPercent>
    <Expires><ParameterReference parameter="Expires" /></Expires>
    <Definition>
      <StateMachine xmlns="https://paiwise.tagroot.io/Schema/StateMachines.xsd" startState="Waiting">
        <Variable id="Count"><Number>0</Number></Variable>
        <State id="Waiting">
          <OnEvent actionRef="RecordNote" newState="Complete" failureState="Failed">
            <OnTextNote />
          </OnEvent>
        </State>
        <State id="Complete"><OnEnter actionRef="Stop" /></State>
        <State id="Failed"><OnEnter actionRef="Stop" /></State>
        <Action id="RecordNote">
          <Script>NextCount:=Count+1</Script>
          <PersistVariable name="Count" value="{NextCount}" onlyIfChanged="true" />
        </Action>
        <Action id="Stop"><End /></Action>
      </StateMachine>
    </Definition>
    <FriendlyName><ParameterReference parameter="FriendlyName" /></FriendlyName>
    <Category><String>Documentation example</String></Category>
    <Description><String>Records the first owner text note as a single completed step.</String></Description>
    <Glyph contentType="image/png">iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNQbnr4HwAE2AKGjcL8KQAAAABJRU5ErkJggg==</Glyph>
  </Create>
  <role name="Creator" minCount="1" maxCount="1">
    <description xml:lang="en"><paragraph><text>Creates and initially owns the token.</text></paragraph></description>
  </role>
  <role name="TrustProvider" minCount="1" maxCount="1">
    <description xml:lang="en"><paragraph><text>Approves and hosts token creation under its service rules.</text></paragraph></description>
  </role>
  <parts><templateOnly /></parts>
  <parameters>
    <numericalParameter name="Value" min="0" minIncluded="true">
      <description xml:lang="en"><paragraph><text>Initial value accepted by the provider.</text></paragraph></description>
    </numericalParameter>
    <stringParameter name="Currency" minLength="1">
      <description xml:lang="en"><paragraph><text>Currency or value unit accepted by the provider.</text></paragraph></description>
    </stringParameter>
    <numericalParameter name="CommissionPercent" min="0" minIncluded="true">
      <description xml:lang="en"><paragraph><text>The provider's required creation commission percentage.</text></paragraph></description>
    </numericalParameter>
    <dateTimeParameter name="Expires">
      <description xml:lang="en"><paragraph><text>Token expiration within the creation contract's valid period.</text></paragraph></description>
    </dateTimeParameter>
    <stringParameter name="FriendlyName" minLength="1" maxLength="80">
      <description xml:lang="en"><paragraph><text>The display name of the demonstration token.</text></paragraph></description>
    </stringParameter>
  </parameters>
  <humanReadableText xml:lang="en">
    <paragraph><text>The Creator requests one token named </text><parameter name="FriendlyName" /><text> and will be its initial owner. The TrustProvider must approve its creation.</text></paragraph>
    <paragraph><text>The initial value is </text><parameter name="Value" /><text> </text><parameter name="Currency" /><text>. The creation commission is </text><parameter name="CommissionPercent" /><text> percent. The token expires at </text><parameter name="Expires" /><text>.</text></paragraph>
    <paragraph><text>The machine starts in Waiting with Count equal to zero. The first owner text note runs a calculation and persists Count as one, then enters Complete and ends. If the action fails, it enters Failed and ends. Later notes do not repeat this machine step. No external-note event or payment action is defined by the machine.</text></paragraph>
    <paragraph><text>The creation contract lasts one month, followed by one month of required archival and one month of optional archival. Provider rules and approval apply; this demonstration has not been verified on your service.</text></paragraph>
  </humanReadableText>
</contract>

Three namespaces separate the contract, token creation instruction, and machine definition. Keep them exactly as supplied.

Contract section	Meaning
`Create/TokenID/Random`	Request a generated token identifier. Do not confuse it with the creation contract ID.
`Creator` and `Owner`	Both refer to the `Creator` role for this example.
`TrustProvider`	Refers to the provider’s Legal Identity assigned to that role.
`Value`, `Currency`, `CommissionPercent`, `Expires`	Read the matching contract parameters.
`Definition/StateMachine`	Define the token’s custom automated behavior.
`FriendlyName`, `Category`, `Description`, `Glyph`	Supply display metadata. The included glyph is a minimal one-pixel PNG.
Roles and human-readable text	Explain the parties, value, commission, expiration, and machine behavior before signing.

2. Understand the transition

The machine initializes Count to zero. In Waiting, OnTextNote invokes RecordNote. A successful action enters Complete; a failed action enters Failed. Both states invoke End.

<Action id="RecordNote">
  <Script>NextCount:=Count+1</Script>
  <PersistVariable name="Count" value="{NextCount}" onlyIfChanged="true" />
</Action>

This is a fragment inside the machine namespace. Script contains raw Neuron Script. The value attribute uses braces to evaluate an expression. NextCount is a calculation variable; PersistVariable records Count for subsequent machine state. An ordinary assignment alone does not replace that persistence step. The expected successful result is Count = 1. Later notes should not repeat this ended machine’s step. This is a design expectation to verify on your provider, not a general duplicate-event guarantee. Read Script syntax and execution contexts when changing the calculation. If you add a less-than comparison in an XML attribute, escape it as <.

3. Validate before proposing

Validate the complete file against the contract, token, and state-machine schemas, following local validation. Check that each state and action reference names a definition in the same machine. Expected result: the schema set compiles, the XML validates, and all explicit machine references resolve. The core expression Count:=0; NextCount:=Count+1; NextCount returns 1; see Script expressions. Neither check approves the template or runs the machine in its host context.

4. Obtain creation attributes and template approval

Send the following requests over HTTPS with your account’s exact host, JWT, and application URL as Referer. Replace every placeholder before sending a request.

POST /Agent/Tokens/GetCreationAttributes HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{}

Get Creation Attributes returns currency, commission, and trustProvider. A missing provider identity is a provisioning issue to resolve before creation. Confirm how these values apply to the accepted template and charges. Base64-encode the complete note-token.xml file’s UTF-8 bytes and propose it:

POST /Agent/Legal/ProposeTemplate HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "templateBase64": "<BASE64_OF_COMPLETE_UTF8_XML>"
}

Record the returned Template identifier and follow the sandbox automatic review or operator approval process. Use Legal/GetContract with that identifier as contractId to observe the template lifecycle. Continue only with an approved, usable template. Template approval does not supply the TrustProvider signature required by this creation contract.

5. Create and sign the creation contract

Prepare the creation request:

Set the approved template ID.
Assign Creator to your approved Legal Identity and TrustProvider to the provider’s approved identity.
Set Value and CommissionPercent as JSON numbers. Replace the quoted commission placeholder with an actual number.
Set Currency to the accepted string and Expires to an ISO 8601 date-time accepted by the provider within the creation contract’s valid period.
Choose FriendlyName, from 1 to 80 characters.

POST /Agent/Legal/CreateContract HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "templateId": "<APPROVED_NOTE_TOKEN_TEMPLATE_ID>",
  "visibility": "CreatorAndParts",
  "Parts": [
    { "role": "Creator", "legalId": "<CREATOR_LEGAL_ID>" },
    { "role": "TrustProvider", "legalId": "<TRUST_PROVIDER_LEGAL_ID>" }
  ],
  "Parameters": [
    { "name": "Value", "value": 0 },
    { "name": "Currency", "value": "<PROVIDER_CURRENCY>" },
    { "name": "CommissionPercent", "value": "<PROVIDER_COMMISSION_AS_JSON_NUMBER>" },
    { "name": "Expires", "value": "<ISO_8601_EXPIRATION_ACCEPTED_BY_PROVIDER>" },
    { "name": "FriendlyName", "value": "My first note token" }
  ]
}

Record the returned Contract ID. Retrieve the instance:

POST /Agent/Legal/GetContract HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "contractId": "<CONTRACT_ID>"
}

Have the Creator review the complete terms, parameters, and assigned role. After confirmation, calculate the contract signatures using the Creator’s key metadata, key password, account password, and a fresh nonce. Submit:

POST /Agent/Legal/SignContract HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "keyId": "<SIGNER_KEY_ID>",
  "legalId": "<SIGNER_LEGAL_ID>",
  "contractId": "<REVIEWED_CONTRACT_ID>",
  "role": "Creator",
  "nonce": "<FRESH_NONCE>",
  "keySignature": "<CALCULATED_KEY_SIGNATURE>",
  "requestSignature": "<CALCULATED_REQUEST_SIGNATURE>"
}

Retrieve the instance again with Legal/GetContract and the same contract ID. Coordinate the provider’s required signature separately. Observe all required signatures and the creation contract’s final state. Do not assume your first signature creates the token.

6. Find the created token

Retrieve tokens associated with the creation contract:

POST /Agent/Tokens/GetContractTokens HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "contractId": "<CREATION_CONTRACT_ID>",
  "offset": 0,
  "maxCount": 20,
  "references": true
}

Inspect the returned Tokens structure for the token associated with this creation contract. Preserve the exact identifier. An empty list can mean creation is pending or failed; inspect the contract and provider result before submitting another creation request. Use the returned token identifier to retrieve the token and machine state:

POST /Agent/Tokens/GetToken HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "tokenId": "<TOKEN_ID>"
}

POST /Agent/StateMachines/GetCurrentState HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "tokenId": "<TOKEN_ID>"
}

Verify the token’s owner, creation contract, metadata, and current machine state. The expected starting machine state is Waiting with Count = 0. The state response contains CurrentState; use its returned structure rather than assuming an invented flat state field.

7. Send an owner note and observe the result

Send this request with the account that owns the token, using the same token ID. The request sets personal to false.

POST /Agent/Tokens/AddTextNote HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "tokenId": "<TOKEN_ID>",
  "note": "First owner note",
  "personal": false
}

Repeat StateMachines/GetCurrentState above, and retrieve the event history:

POST /Agent/Tokens/GetTokenEvents HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "tokenId": "<TOKEN_ID>"
}

The note response contains Note. A note being accepted is separate from confirming the intended machine outcome. Retrieve the state and event history until the provider’s documented completion window, with bounded polling in your application. For this example, verify Complete, the persisted Count = 1, and the corresponding note/action history. Record actual results and the Neuron build before treating the workflow as tested. If you receive Failed, preserve the returned diagnostic/history information and resolve the action failure before adapting the template.

Diagnose and adapt

Situation	What to do
Provider identity is absent	Resolve provider provisioning before assigning roles.
No token after signatures	Inspect contract state and provider execution; do not repeat creation blindly.
Note rejected	Check token ownership or approved external-source permissions. This example listens for an owner note, not an external note.
State-machine not found	Verify token ID, creation result, definition, and enabled capability.
Action fails	Inspect the reported Script error, variable types, and persistence result. Local core-expression success does not prove host permission.
Write times out	Reconcile notes/events and current state before resending; the operation does not document an idempotency guarantee.

When adapting this example, keep role references, parameter names, state IDs, and action references aligned. Update human-readable terms whenever automated behavior changes, validate the new file, and obtain a newly reviewed template when required by your provider. Retain the creation contract ID, token ID, template revision, input values, and observed state/history. Ending this custom machine does not itself destroy the token or delete its contract. Follow the asset’s supported expiration and retention rules; transfer and destruction require their own approved behavior.

Build an application

Verified identity

Sign-in and signatures

Contracts and agreements

Tokens and digital assets

Wallets and payments

Other application tasks

Prerequisites

1. Start with the complete definition

2. Understand the transition

3. Validate before proposing

4. Obtain creation attributes and template approval

5. Create and sign the creation contract

6. Find the created token

7. Send an owner note and observe the result

Diagnose and adapt

​Prerequisites

​1. Start with the complete definition

​2. Understand the transition

​3. Validate before proposing

​4. Obtain creation attributes and template approval

​5. Create and sign the creation contract

​6. Find the created token

​7. Send an owner note and observe the result

​Diagnose and adapt

Prerequisites

1. Start with the complete definition

2. Understand the transition

3. Validate before proposing

4. Obtain creation attributes and template approval

5. Create and sign the creation contract

6. Find the created token

7. Send an owner note and observe the result

Diagnose and adapt