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,
localStoragekeyvirtufin.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
(
returnvalue as JSON, ordone) 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
declinedin Changes. - Each write is one entry in your change log (
doneorfailedwith 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.keysreads at most 1000 keys (QueryState).topics.readreturns at most 500 events and waits at most 60 000 ms (countdefault 1,timeoutMsdefault 10 000).triggers.scheduletakes ascheduleor adueTime, not both.