feat(ymax-planner): Calculate steps by linear programming over a model of the blockchain network #11932

dtribble · 2025-09-14T22:32:46Z

The approach:

withdraw and deposit are special cases of rebalance
simple hack: rebalance by determining required transfers and the generating the steps for them
robust: rebalance using a Fixed-Charge Network Flow (FCNF) algorithm
start with a graph: nodes are Places and bridges are links
links have cost, time, and capacity limits
use a Mixed-Integer Linear Programming to determine the routing for minimum cost or speed
uses javascript-lp-solver linear programming solver
graph definition is JS constant with types

Description

packages/portfolio-contract/src/network/network.prod.ts represents the blockchain network as a collection of interlinked hubs with attached pools and local "places", including time and fee metadata about the inter- and intra-hub links, which is then integrated with current and target allocations to produce an LP model in which variables represent use of the links and constraints apply to the flow over them (in particular, a net flow constraint for each node whose allocation should change). Once a solution has been identified, the flows are normalized to group activity by hub and apply deterministic ordering within that overall pattern.

Security Considerations

The chosen library is inherently floating-point, and there's a risk that no solution is identified merely because a value that should be integral is off by a small amount (as indeed manifests in the test cases if jsLPSolver.Solve is called with the default precision of 1e-9 rather than 1e-6). To mitigate this, the error messages of such failures include the returned negative result.

Scaling Considerations

Performance is an explicit concern of our chosen library, and expected to be on the order of 20 ms for the scale of our inputs (given a small-world network of 10–20 [tree-like] hubs with a small number of child pools each: one binary + one integer variable per edge, two or three constraints per edge, and one constraint per node).

Documentation Considerations

Includes some Markdown files that probably ought to be subject to further cleanup.

Testing Considerations

Includes new unit tests.

Upgrade Considerations

n/a

cloudflare-workers-and-pages · 2025-09-14T22:32:52Z

Deploying agoric-sdk with Cloudflare Pages

Latest commit:	`3732799`
Status:	✅ Deploy successful!
Preview URL:	https://53a8ba01.agoric-sdk.pages.dev
Branch Preview URL:	https://dt-solver-graph.agoric-sdk.pages.dev

View logs

amessbee · 2025-09-15T15:59:38Z

packages/portfolio-contract/solver-approach-design.md

+
+Node (vertex) types (all implement `AssetPlaceRef`):
+- Chain hubs: `@ChainName` (e.g. `@Arbitrum`, `@Avalanche`, `@Ethereum`, `@noble`, `@agoric`). A single hub per chain collects and redistributes flow for that chain.
+- Protocol / pool leaves: `Protocol_Chain` identifiers (e.g. `Aave_Arbitrum`, `Beefy_re7_Avalanche`, `Compound_Ethereum`). Each is attached to exactly one hub (its chain).


Since there is, presumably, a single edge for each pool, we can do away with them altogether and solve the flow on a network on only the hubs.

There may be more than one. Those edges may have fees or time impacts. There also may in the future not be just a single edge (we could have USDN to USDNVault as well as @noble to USDNVault, or direct transfers between Beefy vaults without coming out to the base account).

packages/portfolio-contract/solver-approach-design.md

amessbee · 2025-09-15T16:03:06Z

packages/portfolio-contract/solver-approach-design.md

+We build an LP/MIP object with:
+- `variables`: one per flow variable `f_edgeId`, each holding coefficients into every node constraint and capacity constraint; plus binary usage vars `y_edgeId` when required.
+- `constraints`:
+  - Node equality constraints (one per node with any incident edges).


No sure if you have already tried but solving this could be, at times, really hard (this being an NP-Hard problem) even on reasonable small graphs. Not sure if it is advised to do it live. I would at least store the solutions to matched and fetched for future possibly by an LLM.

From ChatGPT analysis, based on our usage of Mixed Integer Linear Program solving.

Practical Complexity for Our Usage:
Expected case: O(k × n^3) where k is typically much smaller than 2^25

Performance Characteristics:

Variables: ~50 (25 integer + 25 binary)

Constraints: ~63

Expected solve time: Milliseconds to low seconds for typical rebalancing scenarios

Memory usage: Linear in problem size (~O(m×n))

Why it performs better than worst-case:

Network flow structure: Our problem has special structure (min-cost flow with binary activation) that branch-and-bound handles efficiently

Small scale: 25 binary variables is manageable for modern MIP solvers

Good LP relaxation bounds: The continuous relaxation likely provides tight bounds, reducing the branch-and-bound tree size

Practical branching: Most edges will have clear economic preferences, leading to early pruning

Practical scaling: Should handle networks with 50-100 edges reasonably well

LuqiPan · 2025-09-22T22:09:10Z

packages/portfolio-contract/test/rebalance.test.ts

+  });
+  t.deepEqual(steps, [
+    { src: '<Deposit>', dest: '@agoric', amount: token(100n) },
+    // TODO dckc should this  go through +agoric?


I think the test case at line 142 will suffice and we don't need this test case anymore- the contract will handle moving the tokens from <Deposit> to +agoric

LuqiPan · 2025-09-22T22:10:56Z

packages/portfolio-contract/test/rebalance.test.ts

+      [A]: token(50n),
+      [B]: token(30n),
+      [C]: token(20n),
+      '@Arbitrum': ZERO,


Interface question: can we omit targets with ZEROs?

No. If there is not a target, that means "leave it the same" rather than "use those funds for the operation".

dckc

don't turn off tracing; it includes critical operational logging

dckc · 2025-09-22T22:15:41Z

packages/portfolio-contract/src/plan-rebalance.ts

+// XXX Define in AmountMath?
+const compareAmounts = (a: NatAmount, b: NatAmount): -1 | 0 | 1 => {
+  const aValue = a.value;
+  const bValue = b.value;
+  // eslint-disable-next-line no-nested-ternary
+  return aValue > bValue ? 1 : aValue < bValue ? 1 : 0;
+};


why not use AmountMath.isGTE? why ignore brands?

packages/portfolio-contract/src/plan-rebalance.ts

packages/portfolio-contract/src/portfolio.exo.ts

packages/portfolio-contract/src/portfolio.flows.ts

dtribble · 2025-09-22T22:33:44Z

packages/portfolio-contract/test/rebalance.test.ts

+  const current = balances({ [A]: 100n, [B]: 0n, [C]: 0n });
+  const targetBps = { [A]: 3400n, [B]: 3300n, [C]: 3300n };
+  const { steps } = await planRebalanceFlow({
+    mode: 'cheapest',


I think all these tests specify "cheapest", but the default mode is "fastest". I think we mostly want to run in "fastest", so we should add tests for that mode.

Added a "solver differentiates cheapest vs. fastest" test to packages/portfolio-contract/test/rebalance.test.ts, currently failing.

services/ymax-planner/test/snapshots/deposit-tools.test.ts.md

dtribble · 2025-09-23T16:37:20Z

services/ymax-planner/test/snapshots/deposit-tools.test.ts.md

+        dest: 'USDN',
        detail: {
-          usdnOut: 425n,
+          usdnOut: 430n,


NOTE These usdnOut number differences are because the code hard-coded 1% fee, whereas the actual USDN fee is 5 basis points.

packages/portfolio-contract/src/plan-solve.ts

…messages

- add feeMode to arcs in the graph - switch on feeMode when making steps to add fee info - update all networks definitions and tests - plumb feeBrand through graph building NOTE computed fee work will need to propagate from portfolio-actors to plan-solve.

…modes

(differentiated by transfer protocol)

…astest", currently failing

dtribble · 2025-09-24T04:20:11Z

packages/portfolio-contract/test/rebalance.test.ts

+  async (t, mode) => {
+    const current = balances({ [A]: 50n, [B]: 30n, '<Cash>': 0n });
+    const { steps } = await planRebalanceFlow({
+      mode: mode as RebalanceMode,


why isn't mode already correctly typed?

No idea. It's test code and I didn't want to waste more time on it.

packages/portfolio-contract/src/plan-solve.ts

…wSteps

Feedback addressed.

mergify · 2025-09-24T05:19:58Z

This pull request has been removed from the queue for the following reason: checks failed.

The merge conditions cannot be satisfied due to failing checks:

❌ integration-test-result
☑️ linear-history

You may have to fix your CI before adding the pull request to the queue again.
If you update this pull request, to fix the CI, it will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue instead, you can requeue the pull request, without updating it, by posting a @mergifyio requeue comment.

gibson042 · 2025-09-24T10:02:34Z

@Mergifyio requeue

mergify · 2025-09-24T10:02:45Z

requeue

✅ The queue state of this pull request has been cleaned. It can be re-embarked automatically

dtribble changed the title ~~Dt solver graph~~ Solver graph update Sep 14, 2025

amessbee reviewed Sep 15, 2025

View reviewed changes

packages/portfolio-contract/solver-approach-design.md Show resolved Hide resolved

amessbee reviewed Sep 15, 2025

View reviewed changes

gibson042 force-pushed the dt-solver-graph branch 4 times, most recently from 5f41cb9 to e512eae Compare September 19, 2025 11:42

gibson042 marked this pull request as ready for review September 19, 2025 11:42

gibson042 requested a review from a team as a code owner September 19, 2025 11:42

gibson042 requested review from AgoricTriage, dckc and LuqiPan September 19, 2025 11:42

dtribble mentioned this pull request Sep 19, 2025

DEPRECATED: See 11932 (solver) #11904

Closed

LuqiPan assigned gibson042 Sep 19, 2025

gibson042 changed the title ~~Solver graph update~~ feat(ymax-planner): Calculate steps by linear programming over a model of the blockchain network Sep 22, 2025

LuqiPan reviewed Sep 22, 2025

View reviewed changes

dckc previously requested changes Sep 22, 2025

View reviewed changes

dtribble commented Sep 22, 2025

View reviewed changes

services/ymax-planner/test/snapshots/deposit-tools.test.ts.md Outdated Show resolved Hide resolved

dtribble commented Sep 23, 2025

View reviewed changes

LuqiPan reviewed Sep 23, 2025

View reviewed changes

packages/portfolio-contract/src/plan-solve.ts Outdated Show resolved Hide resolved

WIP withdraw/rebalance and solver approach

6a9a25a

gibson042 force-pushed the dt-solver-graph branch 3 times, most recently from 3dc80f3 to 64320f8 Compare September 24, 2025 02:24

dtribble requested a review from dckc September 24, 2025 02:26

dtribble added 2 commits September 23, 2025 22:43

Move to a file-based definition of the network routes

ac19f08

First integration into deposit

064a590

gibson042 and others added 16 commits September 23, 2025 22:43

refactor(portfolio-contract): Improve variable names

ba2d21a

refactor(portfolio-contract): Make better use of addOrReplaceEdge

4df35c5

refactor(portfolio-contract): Avoid redundant array copies

296f970

refactor(portfolio-contract): Make intra-Agoric links unidirectional

ed21c6d

test(portfolio-contract): Simplify rebalance.test.ts

2fa2bc3

refactor(portfolio-contract): Embrace javascript-lp-solver

76a4971

feat(portfolio-contract): Include LP-solver failure results in error …

b343afb

…messages

Reactivate always-on tracing in protfolio components.

a0dddb2

doc: comment the deposit test

b2caee0

test(portfolio-contract): Cover both "cheapest" and "fastest" solver …

f977d58

…modes

refactor(portfolio-contract): Clean up plan-solve.ts

b90e3d4

feat(portfolio-contract): Allow multiple edges between the same nodes

763eb26

(differentiated by transfer protocol)

test(portfolio-contract): Add test for planRebalanceFlow with mode "f…

2c7419f

…astest", currently failing

test(ymax-planner): Update snapshot

539438c

chore: Change ymax fixed fee to 30 BLD

b321fa3

gibson042 force-pushed the dt-solver-graph branch from da9f98b to 42b0a4f Compare September 24, 2025 02:52

fix(ymax-planner): Expect policyVersion and rebalanceCount

4feda74

gibson042 force-pushed the dt-solver-graph branch from 42b0a4f to 4feda74 Compare September 24, 2025 02:54

dtribble commented Sep 24, 2025

View reviewed changes

packages/portfolio-contract/src/plan-solve.ts Outdated Show resolved Hide resolved

chore(portfolio-contract): Remove fudge factor in rebalanceMinCostFlo…

3732799

…wSteps

gibson042 approved these changes Sep 24, 2025

View reviewed changes

gibson042 added the automerge:rebase Automatically rebase updates, then merge label Sep 24, 2025

mergify bot merged commit a28ae68 into master Sep 24, 2025
123 of 124 checks passed

mergify bot deleted the dt-solver-graph branch September 24, 2025 10:26

feat(ymax-planner): Calculate steps by linear programming over a model of the blockchain network #11932

feat(ymax-planner): Calculate steps by linear programming over a model of the blockchain network #11932

Uh oh!

Conversation

dtribble commented Sep 14, 2025 • edited by gibson042 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Security Considerations

Scaling Considerations

Documentation Considerations

Testing Considerations

Upgrade Considerations

Uh oh!

cloudflare-workers-and-pages bot commented Sep 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying agoric-sdk with Cloudflare Pages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dtribble Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dtribble Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dckc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mergify bot commented Sep 24, 2025

Uh oh!

gibson042 commented Sep 24, 2025

Uh oh!

mergify bot commented Sep 24, 2025

✅ The queue state of this pull request has been cleaned. It can be re-embarked automatically

Uh oh!

Uh oh!

Uh oh!

dtribble commented Sep 14, 2025 •

edited by gibson042

Loading

cloudflare-workers-and-pages bot commented Sep 14, 2025 •

edited

Loading

dtribble Sep 24, 2025 •

edited

Loading

dtribble Sep 24, 2025 •

edited

Loading