Docs
The mandate, in full.
Everything the contract does, in the order it does it. If a sentence here and the contract disagree, the contract is right; tell us and we will fix the sentence.
What it is
Colyseus Agent is one contract on Robinhood Chain that acts as collateral agent for loans on Morpho Blue. You keep the loan in your own name. You authorize the contract on Morpho, then give it a mandate for one market: a guard, a target and a slippage bound. When your loan-to-value reaches the guard, a defense brings it back to the target by repaying part of your debt, first from a reserve you may have left with the contract, then by selling just enough of your collateral.
It exists because of what happens otherwise. At a market's liquidation threshold, anyone may repay your debt and take collateral worth that debt plus an incentive, and may close the whole loan. In a 62.5% market the incentive is 12.7% of the debt repaid; in a 77% market, 7.4%. A defense sells earlier, at the market, and the loan stays open.
The mandate
| Term | Meaning | Rule |
|---|---|---|
| Guard | The loan-to-value at or above which the agent acts. | Under the market's liquidation threshold. |
| Target | Where a whole defense brings the loan back to. | At least 1 point under the guard, and at least 5%. |
| Slippage | The most a sale may lose against the market's own oracle price. | At most 5%, and at least 0.10% above the route's pool fee. |
Two more rules bind the slippage. A defense at its worst (repayment, tip, fee and your whole slippage) must cost less than a liquidation would in that market, or the mandate is refused: there would be no point in it. And the liquidation threshold times that worst cost must stay under 1, so that selling always lowers the loan-to-value. The app checks all of this before you sign, and termsOk on the contract answers the same question.
Your slippage is a ceiling, not a plan. The sale is sized for a fair fill (the repayment, the tip and fee, the pool's fee), so the loan lands on your target. A wider bound does not sell more; it only lets a worse fill through.
Loan-to-value is read the way Morpho reads it: debt (rounded up) over collateral valued at the market's oracle. The agent uses no price of its own.
A defense, step by step
- Anyone allowed (see below) calls
defend(borrower, marketId, portionBps). It reverts unless the loan is at or above the guard. - Interest is accrued on Morpho, so the debt is exact.
- The contract works out the gap: how far the debt sits above the target with the collateral in place.
- If there is a reserve, it repays as much of the gap as the reserve covers. No collateral moves. A caller may stop here (
portionBpsof 0), which is how a reserve still helps when the pool cannot fill inside your bound. - For what is left it calls Morpho's
repaywith a callback. Inside the callback your debt is already lower. The contract withdraws the most collateral the sale may use (the amount to raise, at the oracle price, plus your slippage), sells through the listed Uniswap route for exactly the repayment plus tip and fee, and supplies whatever the sale did not need back into your loan. - Morpho collects the repayment. The tip goes to the caller, the fee to the treasury.
- The contract checks that the loan-to-value went down, and reverts the whole transaction if it did not.
Because selling removes collateral as well as debt, the repayment is larger than the gap: repay = gap / (1 - target × k), where k is the cost of a fair sale. If the pool pays less than that, a little more collateral goes and the loan lands just above the target; it can never use more than your bound allows.
portionBps lets a caller do part of the sale (10000 is all of it) when a pool is thin. Every part must still lower the loan-to-value, and the next call continues from there. One limit comes from Morpho: collateral can only leave a loan that is healthy afterwards, so once a loan is already past the liquidation threshold a defense has to be large enough to bring it back under in one go.
Who may defend
- You, on your own loan, as soon as it is at the guard.
- Listed agents, as soon as it is at the guard. The house agent is one; its wallet is shown in the app.
- Anyone, once the loan is halfway from its guard to the liquidation threshold. With a guard of 57.5% in a 62.5% market, that line is 60%.
The half-way line exists because a caller can bend the pool price inside your slippage bound in the same transaction and keep the difference. Listed agents are accountable for not doing that; a stranger only gets the chance when the agents have failed to act and the loan is in real danger. Either way the most a sale can lose is your own bound, and the contract refuses a bound that would cost more than a liquidation. Set it as tight as the pool allows.
What it costs
Nothing until a defense happens. A defense pays, on the debt repaid: 0.10% to the caller and 0.15% to the treasury. Both are fixed in the contract for good. The Uniswap pool takes its own fee on the sale (0.01% to 0.30% depending on the pool), and the sale may move the price. All of that together is capped by your slippage bound plus the 0.25%.
The reserve
You may leave USDG with the contract for a mandate (fund). A defense repays from it first and sells collateral only for what it cannot cover. The reserve also pays the 0.25% on what it repays. It is yours: unfund returns any part of it and dismiss returns all of it, whether or not the contract is paused. Reserves are tracked per token, and the owner's sweep cannot reach them.
The coin
The ticker is $COLYSEUS, on Robinhood Chain. The contract does not know it: appointing the agent, a defense and the fees work the same with or without it.
Its address is not live yet. It will be posted on the front page, in /contracts.json and on X first; an address from anywhere else is not this coin.
Address: . It is also on the front page and in /contracts.json. It was launched on Pons. Check the address against these before you trade.
The contract
The contract is not launched yet. Its address will appear here, in /contracts.json and in the banner once it is.
ColyseusAgent on Robinhood Chain (chain id 4663): address. Machine-readable: /contracts.json.
| Function | Who | What it does |
|---|---|---|
appoint(id, guardLtv, targetLtv, slipBps) | Borrower | Creates or changes the mandate for market id. Needs your Morpho authorization first. |
dismiss(id) | Borrower | Ends the mandate and returns the reserve. |
fund(id, amount) / unfund(id, amount, to) | Borrower | Adds to or takes from the reserve. |
defend(borrower, id, portionBps) | See above | Brings the loan back toward its target. |
check(borrower, id) | View | The loan's state, whether it is due, and what a defense would do now. |
mandateOf, seatCount, seats, routeOf, termsOk | View | The mandates, the list the agents read, the routes, and the terms check. |
Loan-to-values are WAD numbers (1e18 is 100%); slippage, tip and fee are basis points. Events: Appointed, Dismissed, Funded, Unfunded, Defended. The contract is not upgradeable.
To give the contract power over your collateral you call setAuthorization(colyseus, true) on Morpho Blue. That authorization covers your whole Morpho account, not one market; the contract uses it only for loans that have a mandate. To take it away, the same call with false: that works at any time and needs nothing from this contract.
Markets and routes
A mandate can only be given for a market the owner has listed (twelve at launch, each checked with its oracle) whose pair has a sale route. That is USDG lent against these, each through its direct Uniswap v3 pool:
| Collateral | Pool fee | Liquidation thresholds in use |
|---|---|---|
| ETH (as WETH) | 0.01% | 77% |
| SPCX | 0.05% | 62.5% |
| GOOGL | 0.05% | 62.5%, 77% |
| NVDA | 0.05% | 62.5% |
| AAPL | 0.05% | 62.5% |
| SPY | 0.05% | 77% |
| TSLA | 0.30% | 62.5%, 77% |
Stock tokens are priced by feeds that rest outside market hours. While a feed rests, the loan-to-value Morpho and the agent see does not move, so neither a liquidation nor a defense is triggered. If the pool has moved away from the oracle when it resumes, a sale that cannot fill inside your slippage waits; widening the mandate lets it through.
The owner's powers
The contract has an owner (the deployer). The owner can:
- list or delist a market for new mandates;
- list, change or remove a sale route. A route cannot cost you more than your slippage bound, because the sale's input is capped by it. Removing a route stops defenses for that pair, the same as a pause does for all of them;
- list or remove agents;
- name the treasury that receives the fee;
- pause new mandates, funding and defenses;
- sweep tokens sent to the contract by mistake, never the reserves.
The owner cannot move a loan's collateral, change a mandate or reach a reserve, cannot change the tip or the fee, and cannot stop you from dismissing, taking your reserve back or revoking the authorization on Morpho.
Review findings
An independent review read the contract before launch and tested it against a fork of Robinhood Chain with the real Morpho Blue, Uniswap pools and tokens: fourteen proofs of concept and a sweep of 243 defenses. A second review then read the fixes. Neither is an audit by a firm. It found no way for anyone to move a borrower's collateral or reserve outside the limits above. It did find the following, and this is what was done.
MediumA caller can take the slippage allowance
A listed agent at the guard, or anyone past the half-way line, can sell into the pool, call defend and buy back in one transaction, so the sale fills at the edge of the borrower's bound.
Done: the bound is now capped at 5% (it was 10%), a mandate whose worst cost would exceed that market's liquidation incentive is refused, and the app starts mandates at 1% (ether) and 2% (stock tokens). Still true: inside your bound, this can happen. Keep the bound tight.
MediumThe reserve sat idle when a sale could not fill
If the pool could not pay inside the mandate, the whole defense reverted, reserve included.
Fixed: a defense with a portion of 0 repays from the reserve alone. The house agent falls back to it.
MediumParts fail once a loan is past the threshold
Morpho only lets collateral leave a loan that is healthy afterwards, so a small part of a sale reverts when the loan is already liquidatable.
Kept, and stated: past the threshold a defense must be large enough to restore the loan in one go. The agent tries the whole sale first, then three quarters, then smaller parts.
LowWide bounds oversold
The sale was sized for the worst allowed price, so a 10% bound sold a third more collateral than needed and landed under the target.
Fixed: the sale is sized for a fair fill; the bound is only the ceiling. A 0.3% and a 5% mandate now sell the same amount for the same loan.
LowThe bound is measured against the oracle
When an oracle is stale and the pool has moved, the gap between them counts against (or for) the bound.
Stated under Markets and Risks. A sale that cannot fill inside the bound waits; the reserve still works.
LowAny market of a listed pair was accepted
Anyone could create a Morpho market with their own oracle and fill the mandate list with empty entries.
Fixed: mandates are only accepted for markets the owner has listed.
LowMandates that could never fill were accepted
A bound under the route's pool fee can never be met.
Fixed: the bound must clear the route's pool fee by 0.10%.
LowThe owner can stop defenses by removing a route
Stated under The owner's powers. It is the same power as the pause.
InfoSmaller notes
If USDG ever took a cut of transfers, reserves would come up short: a defense now reverts if the contract holds less than the reserves it owes. If USDG's issuer froze this contract, dismiss would revert on the payout; revoking the authorization on Morpho still works. A treasury that cannot receive USDG would block defenses until the owner names another.
LowSecond review, of the fixes: one defense can leave a loan still at its guard
A second independent review read the changed contract and found nothing above low. Its one finding: with a wide bound, a pool paying near the edge of it and a loan far above its target, a whole defense can land a little above the guard, so the loan is due again at once.
Kept, and stated: it costs a second transaction, not more collateral; each defense must lower the loan-to-value and the agent picks the loan up on its next pass. A loan defended as it crosses its guard lands under it.
Both reviewers' test files are kept in the repository as the record of what was proved.
Risks
- Gaps. A price can jump past your guard and the liquidation threshold between two blocks. Then a liquidator can act as soon as the agent can.
- Thin pools. If the route's pool cannot pay inside your slippage, the sale does not happen until it can, or until you widen the mandate.
- Oracles. The agent trusts the market's Morpho oracle, as Morpho does. If it stops or misprices, the agent is blind in the same way.
- The agent being down. The house agent is one program. If it is offline, you and, past the half-way line, anyone can still defend.
- The contract. It is new, small and tested against the live chain's state, but it has not been audited by a firm. A bug could cost collateral or a reserve.
- Selling low. A defense sells collateral on the way down. If the price recovers, you hold less of it than you would have without a mandate, though more than after a liquidation.
Run an agent
The agent the site runs is about 250 lines of JavaScript on viem. Anyone can run the same loop: read seats, call check, simulate defend, send it. A wallet that is not listed can only act past the half-way line. The tip is paid to whoever sends the transaction.
COLYSEUS=<contract> KEEPER_PRIVATE_KEY=<key of a wallet with a little ETH> \
RPC_URL=https://rpc.mainnet.chain.robinhood.com node keeper.mjs