Variables

Hardcoded values are great for quick prototyping and iteration, but chances are that you will at some point need to inject some variables into your Numscript files.

Here is an example using definitions of all the supported variable types:

vars {
  monetary $price
  account $trade
  portion $commission
  asset $pair
  number $id
  string $reference
}\n
send $price (
  source = @world
  destination = {
    $commission to @platform
    remaining to $trade
  }
)\n
set_tx_meta("asset", $asset)
set_tx_meta("id", $id)
set_tx_meta("reference", $reference)

Injections of variables can be done at execution, by using the POST /{ledger}/transactions endpoint. The script.vars field in the request body is used to inject variable values:

{
    "script": {
        "vars": {
            "price": {
                "amount": 100,
                "asset": "USD/2"
            },
            "trade": "trades:108391999",
            "commission": "15%",
            "pair": "EUR/2",
            "id": 108391999,
            "reference": "USD/EUR:108391999"
        }
    }
}

Variable names must be lowercase and start with at least one letter or _. They can contain letters, digits, and _.

Account type

This type represents account names. They must start with at least one letter or _. They can contain letters, digits, _, and :.

Asset type

This type represents asset names. They can contain uppercase letters, digits and /.

Monetary type

This type represents an positive integer amount associated with an asset.

{
    "amount": 100,
    "asset": "USD/2"
}

It is possible to pull the balance of an account and inject it in a monetary variable by using the balance(_account_, _asset_) statement. The balance pulled needs to be non-negative, or the script will fail to execute. Here is an example:

vars {
    monetary $initial = balance(@A, USD/2)
}
send [USD/2 100] (
    source = {
        @A
        @C
    }
    destination = {
        max $initial to @B
        remaining to @D
    }
)

Portion type

This type represents portions of monetary values. They can be expressed in 2 different ways:

• As a percentage: 15%
• As a fraction: 15/100

Their computed values must be between 0 and 1 (inclusive).

info

Variables can also be pulled from account metadata, as per described in the metadata section in the next page.