API Reference

AbstractPrice

An abstract type representing price of a currency pair.

For types using this interface the following methods must be defined:

• from_asset
• to_asset
• price

AbstractCtx

An abstract type representing workspace context.

Price <: AbstractPrice

A type representing the price of currency pair.

Fields

• from_asset::String: Base currency name.
• to_asset::String: Quote currency name.
• price::Float64: The currency pair price.

from_asset(x::AbstractPrice) -> String

Returns the name of the base currency of x.

to_asset(x::AbstractPrice) -> String

Returns the name of the quote currency of x.

price(x::AbstractPrice) -> Float64

Returns price of the currency pair x.

price(ctx::AbstractCtx, x::AbstractPrice) -> Float64

Advanced function for getting the price of a currency pair x that can take into account the context of the ctx.

FXGraph

This type describes a weighted directed graph in which:

• The nodes are currencies.
• The edges between such nodes represent a currency pair.
• The direction of the edge determines the base and quote currency.
• The weight of the edge is determined by the conversion price of the currency pair.

Fields

• edge_prices::Dict{NTuple{2,Int64},Vector{AbstractPrice}}: Dictionary containing information about conversion prices between nodes.
• node_ids::Dict{String,Int64}: A dictionary containing the names of currencies as keys and their identification numbers as values.
• graph::Graphs.SimpleGraph{Int64}: A graph containing basic information about vertices and edges.

conv_ccys(fx::FXGraph) -> Vector{String}

Returns the names of all currencies stored in the graph fx.

Base.push!(fx::FXGraph, node::AbstractPrice)

Adds a new edge to the graph fx corresponding to the currency pair node.

Base.append!(fx::FXGraph, nodes::Vector{AbstractPrice})

Does the same as push! but can pass several currency pairs nodes at once.

ConvRate

An object describing the price and conversion path between two currencies.

Fields

• from_asset::String: The name of an initial currency.
• to_asset::String: The name of a target currency.
• conv::Float64: Total currency conversion price.
• chain::Vector{AbstractPrice}: Chain of currency pairs involved in conversion.

conv_value(x::ConvRate) -> Float64

Returns the convert rate of x.

conv_safe_value(x::ConvRate) -> Float64

Asserts that the conversion rate of x is not a NaN value and then returns it. Otherwise throws an AssertionError.

conv_chain(x::ConvRate) -> Vector{AbstractPrice}

Returns the path chain of x.

AStar

Algorithm type for state-space A* pathfinding. Default algorithm for conv.

DFS

Algorithm type for exhaustive depth-first search pathfinding.

conv(fx::FXGraph, from_asset::String, to_asset::String, [::AStar]; ctx::AbstractCtx = MyCtx()) -> ConvRate

Finds the conversion path with the minimum product rate between from_asset and to_asset in graph fx.

Uses state-space A* over log(rate)-weighted edges: the search runs on a lifted graph whose vertices are (currency, visited_set) pairs, so every walk is a simple path in the original graph by construction. This means the algorithm returns the same answer as the exhaustive DFS on every graph, including those with arbitrage cycles. A min-edge-weight admissible heuristic prunes branches that cannot improve the best path found so far.

The minimum-product simple path is NP-hard in general, so the worst-case state count is O(V * 2^V); in practice the priority-queue ordering and admissible heuristic let it beat the exhaustive DFS on most inputs. For graphs with more than 64 currencies the implementation falls back to DFS (the bitmask representation no longer fits).

Examples

julia> crypto = FXGraph();

julia> append!(
           crypto,
           [
               Price("ADA",  "USDT", 0.4037234),
               Price("USDT", "BTC",  0.0000237),
               Price("BTC",  "ETH",  18.808910),
               Price("ETH",  "ALGO", 14735.460),
           ],
       );

julia> result = conv(crypto, "ADA", "BTC");

julia> conv_value(result)
0.000009582698067

julia> conv_chain(result)
2-element Vector{CcyConv.AbstractPrice}:
 Price("ADA",  "USDT", 0.4037234)
 Price("USDT", "BTC",  0.0000237)

conv(fx::FXGraph, from_asset::String, to_asset::String, ::DFS; ctx::AbstractCtx = MyCtx()) -> ConvRate

Finds the conversion path with the minimum product rate between from_asset and to_asset. Uses exhaustive DFS over all simple paths in graph fx.

(fx::FXGraph)(ctx::AbstractCtx, path_alg::Function, from_asset::String, to_asset::String) -> ConvRate

Applies algorithm path_alg to find a path on graph fx between base currency from_asset and target currency to_asset using context ctx.