Contracts

Most resources on Stellarium are TypeScript objects that a node's owner registers before the node starts. A contract is a resource written in RequestScript instead, and deployed to a node that's already running, by its owner or by another organization.

To a script, a contract looks like any other resource. Peers learn about it as soon as it's deployed.

A contract is a RequestScript contract with two requirements:

• A path, such as com.example, so its full name is unique on the network.
• A return type after its parameters. The value it returns is checked against it, and callers see it in the resource listing.

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"
}

This contract calls the paid com.example.Weather resource and turns its answer into words. Like any script, it checks error on a call's result, so a failed call doesn't fail the contract.

Send the source to the node's POST /v1/contracts, with a run token from one of your organization's API clients for that node. Create the API client on the Stellarium Platform. The node's owner can also use its API key.

curl -X POST https://node.example/v1/contracts \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $RUN_TOKEN" \
  -d '{"source": "contract com.example.Outlook(city: string): string { ... }", "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. The fee comes out of your API client's run, and isn't charged if the deploy is refused. Deploying to your own organization's node is free.
• Peers hear about it right away. The node announces its resources again, so other nodes can call the contract without restarting.
• Names are first come, first served. A contract can't take the name of another resource on the network.

If you run a node, these settings control what others can deploy to it:

# What another organization pays to deploy a contract here, in micro-USD.
CONTRACT_DEPLOY_FEE_MICRO_USD=1000
# The largest contract this node accepts. Defaults to 64 KiB.
MAX_CONTRACT_SOURCE_BYTES=65536

A script binds a contract like any resource and calls its run function:

request Today {
  const outlook: com.example.Outlook
  return outlook.run(city: "Oslo")
}

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

Contracts can call other contracts, up to 8 deep, so a loop between them stops. A contract that fails, for example by dividing by zero, comes back as the call's error.

• Versions are immutable. To change a contract, deploy it again with a new version, such as contract com.example.Outlook@2(...). Deploying a version that exists is refused.
• Calls run the latest version. GET /v1/contracts lists every version with its source, so you can read exactly what a call will do.
• The first organization to deploy a contract owns it. Only its API clients can add versions or delete it with DELETE /v1/contracts/com.example.Outlook@2. The node's owner can delete any contract on their node.

A contract can keep values between calls in state variables, declared with var state at the top of its body. Only the contract's own code can change them, so the published source is also the policy for its data: a counter, a quota, a cache, or an agent's memory.

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 is one copy shared by every caller. var state(scope) name keeps a copy for each value of scope, any expression that evaluates to a string or a number.
• caller tells a contract who it runs for: caller.org is the organization paying for the call, and caller.node the node that made it. Both are verified, so state(caller.org) gives each organization a copy no one else can reach.
• State is saved only when a call succeeds. A call that fails, or would grow its state past the node's limit (64 KiB a scope by default), saves nothing.
• Calls to a stateful contract take turns on its node, so concurrent calls never lose an update.
• State outlives versions. A new version keeps it, and deleting the contract deletes it.
• State is private. A contract shares what it returns. Its owner and the node's operator can read the rest for debugging.

Contracts appear in GET /v1/resources with kind: "contract" and their price, alongside every other function. Read the full reference in the stellarium-ts README and the documentation, and learn the language at requestscript.org.