Contracts: RequestScript resources on any node

​

Writing a contract

• A path, such as com.example, so its full name is unique on the network.
• A return type, declared after the parameters. It needs RequestScript 1.4.0 or later. The node refuses a contract without one.

contract com.example.Outlook(city: string): string {
    const weather: com.example.Weather
    const today = weather.temperature(city: city)
    if (today.error != null) {
        return "unknown"
    }
    return "${today.value} degrees"
}

​

Deploying a contract

curl -X POST https://node.example.com/v1/contracts \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"source": "contract com.example.Outlook(city: string): string {\n  const weather: com.example.Weather\n  return \"${weather.temperature(city: city).value} degrees\"\n}", "description": "Today in words"}'

{ "path": "com.example", "name": "Outlook", "version": "1", "feeMicroUsd": 1000 }

• Deploying may cost a fee. A node sets what other organizations pay to deploy to it with contractDeployFeeMicroUsd. The fee is paid from your API client’s run, like a paid call, and isn’t charged if the deploy is refused. Deploys with the node’s API key, or by the node’s own organization, are free.
• Peers learn about it right away. The node announces its resources to its peers again after every deploy and delete, so they can call the contract without restarting.
• Names are taken once. A contract can’t use the name of a resource registered on the node, or of a resource the node learned from a peer.

​

Versions and ownership

​

Calling a contract

request Today {
    const outlook: com.example.Outlook

    return outlook.run(city: "Oslo")
}

{ "returnValue": { "value": "12 degrees", "error": null }, "usage": { "tokens": 17 } }

• A contract that fails while running, for example by dividing by zero, comes back as the call’s error. Its tokens are still charged.
• Contracts can call other contracts, at most 8 deep. A deeper call fails, so contracts that call each other in a loop stop.
• A contract called from a script on the same node reads that script’s run token as the built-in variable jwt. Called from another node, jwt is null. Every contract reads caller, whoever called it.

​

Keeping state between calls

contract com.example.Visits(page: string): int32 {
    var state total: int32 = 0
    var state(caller.org) mine: int32 = 0

    total = total + 1
    mine = mine + 1
    return mine
}

• var state name = value is one copy shared by every caller. var state(scope) name = value keeps a copy for each value of scope, any expression that evaluates to a string or an integer. The initializer runs the first time a copy is used. See State variables for the language rules.
• caller is a built-in variable every contract reads: the organization paying for the call and the node that made it, both verified. var state(caller.org) ... gives each paying organization its own copy, which no other caller can reach.
• State is saved only if the call succeeds. A call that fails, or would grow a scope past the node’s maxContractStateBytes (64 KiB by default), saves nothing. Its tokens are still charged.
• Calls to a stateful contract run one at a time on its node, so concurrent calls never lose an update. A call waits at most 30 seconds for earlier ones, and fails if it has to wait longer. A contract that calls itself, directly or through other contracts, fails its outer call rather than lose the inner call’s update.
• State belongs to the contract, not a version. A new version keeps it, and a stored value is converted to the new version’s declared type. A value that doesn’t fit fails the call. Deleting every version of a contract deletes its state.
• State is private. A contract shares it only through what it returns. Its owner and the node’s admin can read all of it with GET /v1/contracts/:ref/state.

​

How a call is paid

1. The caller’s node signs a contract voucher (kind: "contract") for the call, with the node’s advertised price and maxAmount, the most the call may cost. maxAmount is the caller’s contractCostLimitMicroUsd. A call made from a billed run also carries the run’s runId.
2. The hosting node refuses a call without a contract voucher with 402. It checks that the voucher is bound to this exact call, pays its own organization, agrees to at least its current price, hasn’t expired, and is signed by the voucher’s key. If any check fails it responds 400.
3. The node asks the operator to authorize a run for the call. The operator holds up to maxAmount on the caller organization’s available balance or, for a voucher with a runId, out of that run’s hold. It refuses the call if the hold can’t cover the contract’s most tokens at the node’s price. If the caller is in the hosting node’s own organization, the call isn’t billed.
4. The contract runs. Each paid function it calls is paid with a voucher naming the contract’s run, exactly as a billed script’s calls are.
5. The node captures the run with the tokens the contract executed, charged at the node’s price, and never at more than the price the caller signed. What’s left of the hold goes back where it came from: the caller’s balance, or the caller’s run.

CONTRACT_COST_LIMIT_MICRO_USD=50000

​

Hosting contracts