v0.1

.github/workflows/CI.yml

@@ -0,0 +1,73 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.7'
+          - 'nightly'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+        with:
+          coverage: true
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v2
+        with:
+          files: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+      - run: |
+          julia --project=docs -e '
+            using Documenter: doctest
+            using CFMMRouter
+            doctest(CFMMRouter)'
+      - run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/CompatHelper.yml

@@ -0,0 +1,16 @@
+name: CompatHelper
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pkg.add("CompatHelper")
+        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
+      - name: CompatHelper.main()
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia -e 'using CompatHelper; CompatHelper.main()'

.github/workflows/TagBot.yml

@@ -0,0 +1,15 @@
+name: TagBot
+on:
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+jobs:
+  TagBot:
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -0,0 +1,10 @@
+*.jl.*.cov
+*.jl.cov
+*.jl.mem
+.DS_Store
+Manifest.toml
+dev/
+devtest/Project.toml
+/docs/build/
+/docs/src/examples/
+.vscode/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Guillermo Angeris, Theo Diamandis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Project.toml

@@ -0,0 +1,30 @@
+name = "CFMMRouter"
+uuid = "591468fd-1d79-403f-bb2b-3ef7f4d90130"
+authors = ["Guillermo Angeris", "Theo Diamandis"]
+version = "0.1.0"
+
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+LBFGSB = "5be7bae1-8223-5378-bac3-9e7378a2f6e6"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+Optim = "429524aa-4258-5aef-a3af-852621145aeb"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+
+[compat]
+Documenter = "0.27"
+LBFGSB = "0.4"
+Literate = "2"
+Optim = "1"
+StaticArrays = "1"
+julia = "1.7"
+
+[extras]
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test", "Random", "StatsBase"]

README.md

@@ -0,0 +1,54 @@
+# CFMMRouter
+
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://bcc-research.github.io/CFMMRouter.jl/dev/)
+[![Build Status](https://github.com/bcc-research/CFMMRouter.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/bcc-research/CFMMRouter.jl/actions/workflows/CI.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/bcc-research/CFMMRouter.jl/branch/main/graph/badge.svg?token=TYizMgRYNE)](https://codecov.io/gh/bcc-research/CFMMRouter.jl)
+
+## Overview
+This package contains a fast solver for the CFMM Routing problem, as defined
+by Angeris et al. in [Optimal Routing for Constant Function Market Makers](https://web.stanford.edu/~guillean/papers/cfmm-routing.pdf). 
+We partially decompose the problem to enable fast solutions when the number
+of CFMMs is large relative to the number of tokens.
+
+For more information, check out the [documentation](https://tjdiamandis.github.io/CFMMRouter.jl/dev).
+
+## Quick Start
+First, add the package locally.
+```julia 
+using Pkg; Pkg.add("https://github.com/bcc-research/CFMMRouter.jl.git")
+```
+
+Make some swap pools.
+```julia
+using LinearAlgebra
+using CFMMRouter
+
+equal_pool = ProductTwoCoin([1e6, 1e6], 1, [1, 2])
+unequal_small_pool = ProductTwoCoin([1e3, 2e3], 1, [1, 2])
+```
+
+Build a Router & route.
+```julia
+router = Router(
+    LinearNonnegative(ones(2)),
+    [equal_pool, unequal_small_pool],
+    2,
+)
+route!(router)
+```
+
+Check out the results.
+```julia
+Ψ = round.(Int, netflows(router))
+println("Profit: $(dot(prices, Ψ))")
+```
+
+## Performance
+This routing algorithm scales approximately linearly in the number of swap pools
+for the [arbitrage problem](https://bcc-research.github.io/CFMMRouter.jl/dev/examples/arbitrage/).
+These tests were run on a MacBook Pro with a 2.3GHz 8-Core Intel i9 processor.
+Several performance improvements are possible.
+![alt text](https://github.com/bcc-research/CFMMRouter.jl/blob/main/benchmark/router_scaling.png)
+
+## References
+G Angeris, T Chitra, A Evans, and S Boyd. [Optimal Routing for Constant Function Market Makers](https://web.stanford.edu/~guillean/papers/cfmm-routing.pdf)

benchmark/scaling.jl

@@ -0,0 +1,70 @@
+using Pkg
+Pkg.activate(joinpath(@__DIR__, ".."))
+using LinearAlgebra, Random, StatsBase, BenchmarkTools
+using Plots, LaTeXStrings
+using CFMMRouter
+
+## Setup experiment
+ns_pools = round.(Int, 10 .^ range(2, 4, 10))
+factors = [1, 2, 4]
+times = zeros(length(ns_pools), length(factors))
+σs = zeros(length(ns_pools), length(factors))
+
+function run_trial(n_pools, factor; rseed=1234)
+    Random.seed!(rseed)
+    n_tokens = round(Int, factor * sqrt(n_pools))
+    v0 = ones(n_tokens)
+
+    pools = Vector{CFMM{Float64}}(undef, n_pools)
+    coins = collect(1:n_tokens)
+
+    for i in 1:length(pools)
+        Ai = sample(coins, 2, replace=false)
+        pools[i] = ProductTwoCoin(
+            1000*rand(2),
+            rand((0.997, 1.0)),
+            Ai
+        )
+    end
+
+    router = Router(
+        LinearNonnegative(rand(n_tokens)),
+        pools,
+        n_tokens
+    )
+
+    trial = @benchmark route!($router; v=$v0)
+    return trial
+end
+
+## Run experiment
+for (i, n_pools) in enumerate(ns_pools)
+    for (j, factor) in enumerate(factors)
+        trial = run_trial(n_pools, factor)
+
+        times[i, j] = median(trial).time
+        σs[i, j] = std(trial).time
+    end
+    @info "Done with $n_pools"
+end
+
+## Plot results
+plt = plot(
+    ns_pools,
+    times ./ 1e9,
+    lw=3,
+    ribbon=σs ./ 1e9,
+    yaxis=:log,
+    xaxis=:log,
+    fillalpha=0.5,
+    title="Routing Solve Time",
+    ylabel="Time (seconds)",
+    xlabel="Number of Swap Pools (m)",
+    legend=:bottomright,
+    label=[L"$\sqrt{m}$ tokens" L"$2\sqrt{m}$ tokens" L"$4\sqrt{m}$ tokens"],
+    dpi=300,
+    xlims=(100, 10_000),
+    minorgrid=true,
+    margin=3Plots.PlotMeasures.mm,
+)
+savefig(plt, joinpath(@__DIR__, "router_scaling.png"))

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

docs/make.jl

@@ -0,0 +1,60 @@
+using CFMMRouter
+using Documenter
+using Literate
+
+# For Plots.jl
+# https://discourse.julialang.org/t/plotting-errors-when-building-documentation-using-plots-jl-and-documenter-jl/67849
+# ENV["GKSwstype"]="100"
+
+EXCLUDED_EXAMPLES = []
+
+# utility function from https://github.com/JuliaOpt/Convex.jl/blob/master/docs/make.jl
+fix_math_md(content) = replace(content, r"\$\$(.*?)\$\$"s => s"```math\1```")
+
+# utility functions from https://github.com/oxfordcontrol/COSMO.jl/blob/master/docs/make.jl
+fix_suffix(filename) = replace(filename, ".jl" => ".md")
+function postprocess(content)
+      """
+      The source files for all examples can be found in [/examples](https://github.com/bcc-research/CFMMRouter.jl/tree/main/examples).
+      """ * content
+end
+
+examples_path = joinpath(@__DIR__, "../examples/")
+examples = filter(x -> endswith(x, ".jl") && !in(x, EXCLUDED_EXAMPLES), readdir(examples_path))
+build_path =  joinpath(@__DIR__, "src", "examples/")
+
+for example in examples
+      Literate.markdown(
+        examples_path * example, build_path;
+        preprocess = fix_math_md,
+        postprocess = postprocess,
+        flavor = Literate.DocumenterFlavor(),
+        credit = true
+    )
+end
+
+examples_nav = fix_suffix.(joinpath.("examples", examples))
+
+makedocs(;
+    modules=[CFMMRouter],
+    authors="Guillermo Angeris, Theo Diamandis",
+    repo="https://github.com/bcc-research/CFMMRouter.jl/blob/{commit}{path}#L{line}",
+    sitename="CFMMRouter.jl",
+    format=Documenter.HTML(;
+        prettyurls=get(ENV, "CI", "false") == "true",
+        canonical="https://bcc-research.github.io/CFMMRouter.jl",
+        assets=String[],
+    ),
+    pages=[
+        "Home" => "index.md",
+        "Solution method" => "method.md",
+        "Specifying objectives" => "objective.md",
+        "Examples" => examples_nav,
+        "API reference" => "api.md"
+    ],
+)
+
+deploydocs(;
+    repo="github.com/bcc-research/CFMMRouter.jl",
+    devbranch = "main"
+)

docs/src/api.md

@@ -0,0 +1,8 @@
+# API Reference
+
+```@index
+```
+
+```@autodocs
+Modules = [CFMMRouter]
+```