Skip to content

Scripts

Config > Scripts (route /config/scripts) runs TypeScript or JavaScript against the active context, in your browser. A script reaches the platform only through vf: the operation catalog, the same operations the AI assistant uses, with the same input checks and the same write gate.

The view

  • Yours: your saved scripts (kept in this browser, localStorage key virtufin.scripts; not shared with other browsers or users yet).
  • Examples: Stopped workers, Halted scenarios, Next order book events. Opening an example copies it into the editor.
  • Operations: every vf.<group>.<action>(), grouped; catalog with input schemas opens /schemas/operations.v1.json.
  • The editor: a name field, Save (under that name), Delete, and Run on <context> — or Stop while it runs.
  • Output: what the script printed (warnings and errors coloured), then its result (return value as JSON, or done) or its error, with the start time in UTC.
  • Operations called (N, M writes): each call in order, ✓ or ✗, its input, writes marked, the error of a failed one.

The runtime

Aspect Behaviour
Language TypeScript or JavaScript. Types are stripped by sucrase; no imports. The body runs as an async function: use await at the top level and return a result.
Sandbox A hidden iframe with sandbox="allow-scripts" (an opaque origin: no cookies, no access to the app) and a Content-Security-Policy default-src 'none': no network at all (fetch fails).
Platform access Only vf.<group>.<action>(input): a message to the app, which runs the operation and answers. The result is plain JSON (bigints as strings, maps as objects).
Output print(...), console.log / console.info (output), console.warn, console.error. Non-string values are printed as JSON.
Result The return value, shown as JSON; nothing returned shows done. A thrown error ends the run and is shown.
Limit 10 minutes, then stopped after 10 minutes. Stop ends it at once (stopped).
Context The active context when you press Run.

The vf API

vf.<group>.<action>(input) calls the operation <group>.<action> and returns a promise of its result. input is an object checked against the operation's input schema; a mismatch throws <operation>: <path> <problem>; …, every problem at its path. An unknown name throws no operation <name>. The kill switch is for people only: neither scripts nor the AI assistant get it (vf.killSwitch() throws killSwitch is for people only, not for scripts); use the Kill switch button in the header.

Group Operations
workers list (read), start, stop, delete, tag, create, upgrade
registry list (read)
feeds list (read), save, connect, disconnect
triggers list (read), schedule, delete
scenarios list (read), add, setStatus, halt, resume, delete
strategies list (read), compose
state get, keys (reads)
topics list, read (reads)
docs search, read (reads: the Virtufin documentation, see AI)

Inputs, outputs and descriptions: the shared Operations page, or this app's catalog document /schemas/operations.v1.json (Schemas).

Writes

  • Reads run at once.
  • Writes pass the write gate: only admins (a non-admin's write fails with only admins may write); on a protected context the dialog asks first, naming the operation (e.g. workers.stop (Stop a worker)). A No makes the call throw (the script may catch it); the write is recorded as declined in Changes.
  • Each write is one entry in your change log (done or failed with the reason).

Examples

List the workers that are not running (reads only, no confirmation):

const workers = await vf.workers.list()
const stopped = workers.filter(w => w.status !== 'RUNNING')
for (const w of stopped) print(w.status, w.name, w.id)
return { stopped: stopped.length, total: workers.length }

The workers whose code failed to load (status LOAD_FAILED; the statuses are LOADING, RUNNING, STOPPED, LOAD_FAILED):

const failed = (await vf.workers.list()).filter(w => w.status === 'LOAD_FAILED')
for (const w of failed) print(w.name, w.id, w.source)
return failed.length

Stop every running worker of a hypothetical world (writes: on a protected context the first one asks, and the yes covers the writes of the next 5 s):

const workers = await vf.workers.list()
const running = workers.filter(w => w.status === 'RUNNING' && w.tags.world === 'hyp.TEST')
for (const w of running) {
  try {
    await vf.workers.stop({ id: w.id })
    print('stopped', w.name)
  } catch (err) {
    console.error(w.name, String(err))
  }
}
return running.map(w => w.id)

Each scenario's status and trading halt:

const scenarios = await vf.scenarios.list()
for (const s of scenarios) print(s.id, s.entry?.status, s.halt?.halted ? `HALTED (${s.halt.reason})` : 'trading')

The next three events of a topic, waiting at most 10 s:

const events = await vf.topics.read({ topics: ['act.exchange.binance.orderbook.update.BTC_USDT'], count: 3, timeoutMs: 10000 })
print(`${events.length} event(s)`)
return events.map(e => ({ topic: e.topic, time: e.time }))

Keys under a prefix and one value:

const keys = await vf.state.keys({ prefix: 'cfg.scenario.' })
const first = keys.length ? await vf.state.get({ key: keys[0] }) : null
return { keys, first }

Schedule a trigger that fires every minute:

await vf.triggers.schedule({ name: 'every-minute', schedule: '0 * * * * *', targetTopic: 'trigger.everyminute', repeats: 0 })

Limits of the operations

  • state.keys reads at most 1000 keys (QueryState).
  • topics.read returns at most 500 events and waits at most 60 000 ms (count default 1, timeoutMs default 10 000).
  • triggers.schedule takes a schedule or a dueTime, not both.