{"id":13766873,"url":"https://github.com/graphprotocol/allocation-optimizer","last_synced_at":"2025-09-13T19:27:56.089Z","repository":{"id":39762832,"uuid":"473042377","full_name":"graphprotocol/allocation-optimizer","owner":"graphprotocol","description":"Agents and algorithms for optimizing Indexer decision problems.","archived":false,"fork":false,"pushed_at":"2024-10-17T19:14:46.000Z","size":1031,"stargazers_count":15,"open_issues_count":10,"forks_count":14,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-12-25T16:09:36.034Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/graphprotocol.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-23T04:58:50.000Z","updated_at":"2024-11-07T07:12:37.000Z","dependencies_parsed_at":"2023-01-25T13:46:07.965Z","dependency_job_id":"deee6d4b-197b-4e20-b567-62825078e257","html_url":"https://github.com/graphprotocol/allocation-optimizer","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphprotocol%2Fallocation-optimizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphprotocol%2Fallocation-optimizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphprotocol%2Fallocation-optimizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphprotocol%2Fallocation-optimizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphprotocol","download_url":"https://codeload.github.com/graphprotocol/allocation-optimizer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239207415,"owners_count":19599966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T16:01:01.997Z","updated_at":"2025-02-16T23:13:12.111Z","avatar_url":"https://github.com/graphprotocol.png","language":"Julia","funding_links":[],"categories":["Participating on The Graph's decentralized network"],"sub_categories":["Indexers"],"readme":"# AllocationOpt\n\n[![Latest](https://img.shields.io/badge/docs-latest-purple.svg)](https://graphprotocol.github.io/allocation-optimizer/latest/)\n[![Build Status](https://github.com/graphprotocol/allocation-optimizer/actions/workflows/CI.yml/badge.svg?branch=)](https://github.com/graphprotocol/allocation-optimizer/actions/workflows/CI.yml?query=branch%3A)\n[![Coverage](https://codecov.io/gh/graphprotocol/allocation-optimizer/branch/main/graph/badge.svg)](https://codecov.io/gh/graphprotocol/allocation-optimizer)\n[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)\n\n\nAllocationOpt is a library for optimising the stake distribution for The Graph indexers for indexing rewards [The Graph Protocol](https://thegraph.com/en/).\n\nFor details on installation and usage, visit our [documentation](https://graphprotocol.github.io/allocation-optimizer/latest).\nFor the underlying optimisation method, visit our [blog post](https://semiotic.ai/articles/indexer-allocation-optimisation/).\n\n## Usage\n\nRun the provided binary pointing at the configuration TOML that you would like to use.\n\n``` sh\n./app/bin/AllocationOpt /path/to/your_config.toml\n```\n\n**NOTE:** This binary only works for x86 Linux.\nIf you are you a different operating system or architecture, please see the documentation for other options.\n\n**IMPORTANT:** By default, `opt_mode=\"optimal\"`.\nBecause of our algorithm, `optimal` mode may take a long time to converge.\nIf this is the case for you, you have two options.\nYou can use `opt_mode=fastgas`, which runs a different algorithm.\nThis algorithm is not guaranteed to find the optimal value, and may fail to ever converge (it could hang).\nHowever, it still considers gas unlike the third option `opt_mode=fastnogas`.\nThis is your fastest option, but it won't take into account gas costs or your preferences for max allocations.\nThis mode is appropriate when you have negligible gas fees and are okay with allocating to a large number of subgraphs.\n\n## Configuration\n\nAn example configuration TOML file might look as below.\n\n``` toml\nid = \"0x6f8a032b4b1ee622ef2f0fc091bdbb98cfae81a3\"\nwritedir = \"data\"\nmax_allocations = 10\nwhitelist = []\nblacklist = []\nfrozenlist = []\npinnedlist = []\nallocation_lifetime = 28\ngas = 100\nmin_signal = 100\nverbose = true\nnum_reported_options = 2\nexecution_mode = \"none\"\nopt_mode = \"optimal\"\nnetwork_subgraph_endpoint = \"https://api.thegraph.com/subgraphs/name/graphprotocol/graph-network-arbitrum\"\nprotocol_network = \"arbitrum\"\nsyncing_networks = [\"mainnet\", \"gnosis\", \"arbitrum-one\", \"arbitrum\"]\n```\n\n### Detailed Field Descriptions\n\n- `id::String`: The ID of the indexer for whom we're optimising. No default value.\n- `network_subgraph_endpoint::String`: The network subgraph endpoint to query. The optimizer\n    support any network (such as mainnet, goerli, arbitrum-one, arbitrum-goerli) as long as the\n    provided API serves the query requests. If unspecified,\n    `\"https://api.thegraph.com/subgraphs/name/graphprotocol/graph-network-mainnet\"`\n- `writedir::String`: The directory to which to write the results of optimisation.\n    If don't specify `readdir`, `writedir` also specifies the path to which to save\n    the input data tables. If unspecified, `\".\"`\n- `readdir::Union{String, Nothing}`: The directory from which to read saved data tables.\n    This speeds up the process as we won't have to query the network subgraph for the\n    relevant data. If you don't specify `readdir`, we will query your specified\n    `network_subgraph_endpoint` for the data and write it to CSV files in `writedir`.\n    This way, you can use your previous `writedir` as your `readdir` in future runs.\n    If unspecified, `nothing`\n- `whitelist::Vector{String}`: A list of subgraph IPFS hashes that you want to consider\n    as candidates to which to allocate. If you leave this empty, we'll assume all subgraphs\n    are in the whitelist. If unspecified, `String[]`\n- `blacklist::Vector{String}`: A list of subgraph IPFS hashes that you do not want to\n    consider allocating to. For example, this list could include broken subgraphs or\n    subgraphs that you don't want to index. If unspecified, `String[]`\n- `frozenlist::Vector{String}`: If you have open allocations that you don't want to change,\n    add the corresponding subgraph IPFS hashes to this list. If unspecified, `String[]`\n- `pinnedlist::Vector{String}`: If you have subgraphs that you absolutely want to be\n    allocated to, even if only with a negligible amount of GRT, add it to this list.\n    If unspecified, `String[]`\n- `allocation_lifetime::Integer`: The number of epochs for which you expect the allocations\n    the optimiser finds to be open. If unspecified, `28`\n- `gas::Real`: The estimated gas cost in GRT to open/close allocations. If unspecified, `100`\n- `min_signal::Real`: The minimum amount of signal in GRT that must be on a subgraph\n    in order for you to consider allocating to it. If unspecified, `100`\n- `max_allocations::Integer`: The maximum number of new allocations you'd like the optimiser\n    to consider opening. If unspecified, `10`\n- `num_reported_options::Integer`: The number of proposed allocation strategies to report.\n    For example, if you select `10` we'd report best 10 allocation strategies ranked by\n    profit. Options are reported to a *report.json* in your `writedir`. If unspecified, `1`\n- `verbose::Bool`: If true, the optimiser will print details about what it is doing to\n    stdout. If unspecified, `false`\n- `execution_mode::String`: How the optimiser should execute the allocation strategies it\n    finds. Options are `\"none\"`, which won't do anything, `\"actionqueue\"`, which will\n    push actions to the action queue, and `\"rules\"`, which will generate indexing rules.\n    If unspecified, `\"none\"`\n- `indexer_url::Union{String, Nothing}`: The URL of the indexer management server you want\n    to execute the allocation strategies on. If you specify `\"actionqueue\"`, you must also\n    specify `indexer_url`. If unspecified, `nothing`\n- `opt_mode::String`: We support three optimisation modes. One is `\"fastnogas\"`. This mode does\n    not consider gas costs and optimises allocation amount over all subgraph deployments.\n    Second one is `\"fastgas\"`. This mode is fast, but may not find the optimal strategy and\n    could potentially fail to converge. This mode is also used to the top\n    `num_reported_options` allocation strategies. The final mode is `\"optimal\"`.\n    This mode is slower, but it satisfies stronger optimality conditions.\n    It will find strategies at least as good as `\"fast\"`, but not guaranteed to be better.\n    By default, `\"optimal\"`\n- `protocol_network::String`: Defines the protocol network that allocation transactions\n    should be sent to. The current protocol network options are \"mainnet\", \"goerli\",\n    \"arbitrum\", and \"arbitrum-goerli\". By default, `\"mainnet\"`\n- `syncing_networks::Vector{String}`: The list of syncing networks to support when selecting\n    the set of possible subgraphs. This list should match the networks available to your\n    graph-node. By default, the list is a singleton of your protocol network\n\n### Example Configurations\n\n#### ActionQueue\n\nSet `execution_mode` to `\"actionqueue\"` and provide an `indexer_url`.\n\n``` toml\nid = \"0xd75c4dbcb215a6cf9097cfbcc70aab2596b96a9c\"\nwritedir = \"data\"\nreaddir = \"data\"\nmax_allocations = 10\nwhitelist = []\nblacklist = []\nfrozenlist = []\npinnedlist = []\nallocation_lifetime = 28\ngas = 100\nmin_signal = 100\nverbose = true\nnum_reported_options = 2\nexecution_mode = \"actionqueue\"\nindexer_url = \"https://localhost:8000\"\n```\n\n#### Indexer Rules\n\nChange `execution_mode` to `\"rules\"`.\n\n``` toml\nid = \"0xd75c4dbcb215a6cf9097cfbcc70aab2596b96a9c\"\nwritedir = \"data\"\nreaddir = \"data\"\nmax_allocations = 10\nwhitelist = []\nblacklist = []\nfrozenlist = []\npinnedlist = []\nallocation_lifetime = 28\ngas = 100\nmin_signal = 100\nverbose = true\nnum_reported_options = 2\nexecution_mode = \"rules\"\n```\n\n#### Query Data Instead of Reading Local CSVs\n\nJust don't specify the `readdir`.\n\n``` toml\nid = \"0xd75c4dbcb215a6cf9097cfbcc70aab2596b96a9c\"\nwritedir = \"data\"\nmax_allocations = 10\nwhitelist = []\nblacklist = []\nfrozenlist = []\npinnedlist = []\nallocation_lifetime = 28\ngas = 100\nmin_signal = 100\nverbose = true\nnum_reported_options = 2\nexecution_mode = \"none\"\nnetwork_subgraph_endpoint = \"https://api.thegraph.com/subgraphs/name/graphprotocol/graph-network-arbitrum\"\nprotocol_network = \"arbitrum\"\nsyncing_networks = [\"mainnet\", \"gnosis\", \"arbitrum-one\", \"arbitrum\"]\n```\n\n#### Quiet Mode\n\nWe set `verbose` to `false` here to surpress info messages.\n\n``` toml\nid = \"0xd75c4dbcb215a6cf9097cfbcc70aab2596b96a9c\"\nwritedir = \"data\"\nreaddir = \"data\"\nmax_allocations = 10\nwhitelist = []\nblacklist = []\nfrozenlist = []\npinnedlist = []\nallocation_lifetime = 28\ngas = 100\nmin_signal = 100\nverbose = false\nnum_reported_options = 2\nexecution_mode = \"none\"\n```\n\n#### Whitelisting Subgraphs\n\nAdd some subgraph deployment IDs to the `whitelist`.\nIf, in addition or instead you want to use `blacklist`, `frozenlist`, or `pinnedlist`, you can\nsimilarly add subgraph deployment IDs to those lists.\nNotice that we did not change `max_allocations` here.\nIf `max_allocations` exceeds the number of available subgraphs (2 in this case), the code will\ntreat the number of available subgraphs as `max_allocations`.\n\n``` toml\nid = \"0xd75c4dbcb215a6cf9097cfbcc70aab2596b96a9c\"\nwritedir = \"data\"\nreaddir = \"data\"\nmax_allocations = 10\nwhitelist = [\n    \"QmUVskWrz1ZiQZ76AtyhcfFDEH1ELnRpoyEhVL8p6NFTbR\",\n    \"QmcBSr5R3K2M5tk8qeHFaX8pxAhdViYhcKD8ZegYuTcUhC\"\n]\nblacklist = []\nfrozenlist = []\npinnedlist = []\nallocation_lifetime = 28\ngas = 100\nmin_signal = 100\nverbose = false\nnum_reported_options = 2\nexecution_mode = \"none\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphprotocol%2Fallocation-optimizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphprotocol%2Fallocation-optimizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphprotocol%2Fallocation-optimizer/lists"}