Volt: Open-Source Options Portfolio Logic

Volt deals with a practical nuisance in options software: there is no single representation of a portfolio that is right for every job. A trader needs the exact listed contracts. A payoff search cares about the shape at expiry. A simulator needs to know what happened along the way, and a learning system may want the whole position as a graph.

It is tempting to treat those as different views of the same object and move freely between them. Information gets lost when you do. Two calls can have the same strike and expiry payoff but different contract identifiers; an American option and a European option can agree at expiry yet behave differently before then. Volt keeps the exact position as its starting point and derives the other representations when they are useful.

The project is a Rust library and one of StrategyNet's open-source components. It is released under Apache-2.0. The repository contains the contract rules, simulations, examples, and papers. It does not fetch live quotes or send orders.

Exact position and payoff curve

Volt does not infer contract terms from a display symbol. An OptionContract records the underlying, currency, call or put right, strike, multiplier, exercise dates, and settlement method. Its identifier ties those terms to the listed instrument.

Volt combines positions in the same contract before doing anything else. A long position of two contracts and a short position of one become a single long contract. Zero balances disappear, and the remaining positions are put in a stable order. Conflicting definitions that reuse an identifier are rejected.

This exact record is what Volt uses whenever the identity of the contract matters. Expiry analysis can work with less information, so Volt can also rewrite the position as a payoff function:

\[\text{cash} + \text{underlying units}\times S + \sum_k w_k\max(S-K_k,0).\]

Here \(S\) is the terminal underlying price. Contract identifiers, exercise history, liquidity, and the route taken to expiry are absent.

A repository test constructs two $100 calls called VENUE-A-C100 and VENUE-B-C100. Their payoff functions are identical, but their exact portfolio hashes differ. A search can recognize the duplicate payoff shape; the portfolio record still says which listed contract would have to be traded.

The zap example runs two bounded searches. Its 144 ordered two-action results become 73 exact portfolios after offsets and ordering duplicates are removed. A larger enumeration produces 15,625 exact portfolios but only 13,321 payoff shapes. The gap consists of different listed positions that finish with the same curve. The commands and counts are in the reproducible results.

Before expiry

Take one long, physically settled SPY call with a \(100 strike and a multiplier of 100. Exercising it means paying \)10,000 and receiving 100 SPY shares. Volt posts those movements to the cash and stock ledgers, then reduces the open call position.

The exercise schedule is checked before any posting is made. An American call may be exercised on an allowed date; an attempt to exercise a European call early is rejected. A short option follows a different route because the holder does not control its exercise. In the test for a two-contract short put, an assignment of one contract delivers the shares and cash for that contract while leaving the other short put open.

CogRuntime::transition() returns the updated portfolio together with the action, observation, ledger movements, and hashes before and after the change. Replaying saved inputs calls the same function again. The runtime tests compare the resulting state and journal hashes.

The simulator also distinguishes a valuation mark from a price at which a trade could occur. With CrossAtTouch, a purchase uses the ask and a sale uses the bid. DeclaredMark is reserved for an experiment that explicitly treats its supplied mark as the fill.

One test supplies a \(1.90 bid and a \)2.00 last-trade mark, but no ask. A buy under CrossAtTouch cannot be priced, so the run stops. It does not fall back to \(2.00. A longer fixture opens a call and a short put, closes them against their quoted sides, charges \)0.50 per contract side, and checks that the cash, costs, and leg values add back to the reported result. The complete inputs are in the simulation tests.

Search and graph data

Strategy search starts earlier, before there is an exact contract. A model may ask to add a near-expiry call from a strike bucket. CandidateGrammar resolves that request against the contracts available at the observation time.

In the repository test, a bucket spanning strikes from \(95 to \)110 matches SPY-C-100 and SPY-C-105. Both are returned in a stable order. A request to exercise a short option is rejected, as is an exercise outside the dates allowed by the contract. The candidate tests show the inputs and branches.

Once the contracts have been chosen, PortfolioGraphSample writes the portfolio as typed nodes and edges. The output contains both the exact portfolio hash and the payoff hash, preserving the distinction made at the start of the article. It also requires a mark for every option node.

The graph example uses six contracts and the quantities -1, 0, and 1. All \(3^6=729\) portfolios are written to a JSON Lines file. A sample contains nine nodes and eighteen edges, along with a synthetic training target. Changing the target leaves the portfolio identifier alone.

Examples and papers

The risk and risk_server examples run a four-leg, cash-settled European iron condor. A generated path updates the option marks, Greeks, portfolio value, and expiration diagram. In the recorded run, the underlying moves around a simulated \(98.04 spot and the expiration range runs from a \)309.20 loss to a $190.80 gain. The pricer is a teaching model, so these figures illustrate the program rather than a live market or tested strategy.

The live walkthrough includes the terminal recording and the browser version shown above. The program guide lists the commands for risk, zap, and graph.

The 20-page paper Volt: Options Graph Logic develops the graph representation and its use in portfolio search. You can download the PDF directly. Two shorter papers cover the proposed search and control work: Volt: Strategy Search and Volt: Portfolio Control.

Market-data adapters, account policy, training loops, and brokerage connectivity sit outside this repository. Volt supplies the option definitions and calculations those systems can call; it does not decide that an order should be sent.

The current release is 0.1.1. Its Cargo package is volt-options; Rust code imports the library as volt.

Read Hypercube, the open-source live analytics engine, or browse the Volt source.