feat: dual-path architecture with order manifest support [tracking]

[mfw78]

Summary

• Introduces dual-path architecture separating gas-sensitive settlement from rich polling
• Typed error surface: bytes4 reasonCode selectors end to end, no stringly errors
• Adds IOrderManifest interface for order enumeration across all order types
• Emits ConditionalOrderRemoved event on order deauthorization
• Updates documentation for ERC-1271 wallet support and upstream breaking changes

This PR stays open as the delivery tracker and review record. The work lands as a stack of slices into develop; review threads here remain the canonical design discussion. This branch is frozen and will not be merged.

Slices

Stacked in dependency order; each merges into develop via squash after review.

• chore: stop tracking build artifacts #18 chore: stop tracking build artifacts
• chore: upgrade to Solidity 0.8.30 and pin toolchain #19 chore: upgrade to Solidity 0.8.30 and pin toolchain
• refactor: resolve divide-before-multiply lint in ConditionalOrdersUtilsLib #20 refactor: resolve divide-before-multiply lint in ConditionalOrdersUtilsLib
• feat!: rename getTradeableOrder to generateOrder #21 feat!: rename getTradeableOrder to generateOrder
• feat!: replace string error reasons with typed error selectors #22 feat!: replace string error reasons with typed error selectors
• feat!: add structured poll interface for watch-towers #23 feat!: add structured poll interface for watch-towers
• feat!: compose fill state into the registry poll path #24 feat!: compose fill state into the registry poll path
• feat: add poll scheduling hints to order types #25 feat: add poll scheduling hints to order types
• fix: reject degenerate zero-amount orders at handler validation #26 fix: reject degenerate zero-amount orders at handler validation
• feat: add IOrderManifest interface with base defaults #27 feat: add IOrderManifest interface with base defaults
• feat: implement order manifest for TWAP and PerpetualStableSwap #28 feat: implement order manifest for TWAP and PerpetualStableSwap
• docs: add architecture documentation for the dual-path design #29 docs: add architecture documentation for the dual-path design
• refactor: adopt require-with-custom-error style #30 refactor: adopt require-with-custom-error style

Discovery train (spec-first; implements #15):

• docs: add order discovery specification #36 docs: add order discovery specification
• feat!: signal offchainInput requirement at the verdict layer #37 feat!: signal offchainInput requirement at the verdict layer
• feat!: separate swap-guard restriction from the generator verdict #38 feat!: separate swap-guard restriction from the generator verdict
• feat!: URI-based proof payload locations with blob publication verification #39 feat!: URI-based proof payload locations with blob publication verification
• feat: handler discovery interfaces IOrderDescriptor and IOrderModule #40 feat: handler discovery interfaces IOrderDescriptor and IOrderModule
• docs: monitoring-service terminology, verdict permanence, deployments manifest #41 docs: monitoring-service terminology, verdict permanence, deployments manifest

Design gates

• interfaces: split PollResultCode into generator verdict and orthogonal fill overlay #16 — PollResultCode verdict/fill split (settled; lands in feat!: add structured poll interface for watch-towers #23/feat!: compose fill state into the registry poll path #24)
• interfaces: multi-order generation per poll — pattern, not signature change #17 — multi-order per poll (docs pattern; lands in docs: add architecture documentation for the dual-path design #29)
• interfaces: add handler discovery (typeId/descriptorURI/version) for off-chain SDK and runtime #15 — handler discovery (spec docs: add order discovery specification #36, implementation feat!: signal offchainInput requirement at the verdict layer #37–docs: monitoring-service terminology, verdict permanence, deployments manifest #41)

Breaking Changes

See docs/architecture.md (#29) for the full migration guide from upstream.

Test Plan

• 155 tests green at the stack tip, including the TWAP simulation fuzz
• Each slice builds and tests green standalone
• Gas: −7.8% vs string-reason baseline

[anxolin]

Nice to see you are taking further the learnings from building the indexers to give the composable cow handlers more semantics.

Do you think we can come up with a simpler way to automatically decode the static input? (so UIs and the indexer have an easier time explaining the order)

We have this thing that uses the SDK, but requires you to register the handler.
https://sdk-tools.cow.fi

[anxolin]

I like the general idea, but It feels we mix some concepts inside PollResultCode

I assume the code is about some human readable message that is nice for debugging.
But for example, what if its PARTIALLY_FILLED our order from last poll but we want to also return WAIT_TIMESTAMP for example?

I understand poll result about the generation of a discrete order from the programmatic order. So I don't get too much SUCCESS , PARTIALLY_FILLED, FILLED, and instead should just be POST_NEW_ORDER or similar.

This way, you either get INVALID or it signals to wait for block/timestamp or it tells you to post an order.

[anxolin]

Maybe I get FILLED too, as a kind of equivalent to INVALID('already filled'), but I don't get PARTIALLY_FILLED

[mfw78]

PollResultCode does contain additional information, and nominally there is a discrete order that is authorised if the PollResult struct contains a PullResultCode of SUCCESS, PARTIALLY_FILLED, or FILLED.

In these cases, the nextPollTimestamp would then contain the timestamp as to when to next poll the contract for a discrete order. Semantically, type(uint256).max aligns with similar semantics in that setting type(uint32).max is the settlement contract's preferred method of invalidation (nothing can happen past this time as its the end type bounds).

Given this, there may be some duplication between waitUntil and nextPollTimestamp and we could most probably compress these down into the same part of the struct, though having waitUntil sounds nicer, though no strong opinions there.

[anxolin]

Sorry, I still don't get it.

Watch tower will poll, potentially every block.
Each poll will return a PollResultCode. Its possible, that is not time to trade (WAIT_TIMESTAMP/WAIT_BLOCK/TRY_NEXT_BLOCK/INVALID) or its time to trade.

If its time to trade, you are saying you want to return some order data from the handler, but also make that handler responsible of deriving the orderUid and checking in the settlement the traded amounts, so you can decided if its

• SUCCESS: Untouched order, potentially needs to be created
• PARTIALLY_FILLED: We can assume it was created. Potentially watch tower doesn't need to do anything
• FILLED: We can assume it was created. Watch tower needs to stop caring about the order

Is this your idea behind the enum?

[mfw78]

It is to make allowance and present to a possible UI that if the ConditionalOrderParams are indexed, a dapp could subsequently do the poll itself and determine the state of the order, potentially reducing load on indexers and shifting load to RPC endpoints.

And yes, the breakdown in all cases is similar to what you mention with some nuances:

• SUCCESS: Order has been yielded and should be submitted by the off-chain indexer to the API.
• PARTIALLY_FILLED: Discrete is already in the order book, as evidenced by being partially filled. No need for the off-chain indexer to do anything for this specific discrete order. Off-chain indexer is to respect nextPollTimestamp which has semantics to indicate if it should do anything, or cease monitoring the ConditionalOrder.
• FILLED: Same semantics as PARTIALLY_FILLED, just with the difference that the order has been completed filled.

[mfw78]

Settled in #16 (verdict/fill split); lands with the poll-interface and registry slices.

[anxolin]

Probably not worth it, but do you think there's any value on letting a handler generate more than one order per block?
generateOrder could take a index param , and return the order and a boolean indicating if there's more orders to be generated.

This way you call it once, count=0 and if there's more orders (moreOrders=true), you call again with count=1 and so forth

[mfw78]

A simple salt can be used so that multiple orders can be done in the same block. This is supported already at the ComposableCoW level, above the handler.

[anxolin]

Not sure I get this, these are the params

 struct ConditionalOrderParams {
        IConditionalOrder handler;
        bytes32 salt;
        bytes staticInput;
    }

When we create a single order, we create composableCow.create(..) and give this info. So SALT is given.

What I'm asking here, is, imagine we want to make a contract that in each polling creates 2 orders.
For the same handler/salt/staticinput poll, it will return

1. Call 1: [order1, hasMoreOrders=true]
2. Call 2: [order2, hasMoreOrders=false]

This way conditional order has a way to yield more than one order

[mfw78]

Fair in that the salt is a given. What is a concrete example of a conditional order type that would yield multiple discrete orders such as this?

[anxolin]

Not saying we should do it, but assuming each block generates only one order is arbitrary

• Multi-currency-DCA: Buys you each month automatically a bunch of tokens
• Simplified AMM? Creates multiple buy and sell orders
• Go long and take profit: Sell something , and creates a limit order to take profit once the bought token appreciates

[mfw78]

Good examples — opened #17. Short version: offchainInput-keyed orders + manifest enumeration already cover these; proposing we document the pattern rather than change the signature.

[anxolin]

not strong preference, but wouldn't be slightly more natural to make

• 0 --> stop polling
• 1 --> validTo+1

[mfw78]

I do prefer the semantics of having "stop" being indicated by the "maximum" timestamp (nothing can happen beyond that point of time if that's the time's bounds), ie. with the purpose / point as outlined in the previous comment.

[anxolin]

My thinking was, watch-tower will probably stop watching if the time is in the past. So 0 was saying, don't poll any more. But im fine with yours

[anxolin]

Can we make a simpler alternative way for these orders?

It has been once of the biggest criticism of composable cow.
It would be a scape hatch, for example

• A method in composable cow contract createSingleShotOrder(order)
• The method emits an event that is picked by composable cow
• The owner of the order is a random contract which implements 1271
• This contract doesn't need to do the delegation to composable cow at all
• Composable cow post the order to the API (if ready), if not, tries on every block

What this allow is to make a contract that creates the order by calling this simple method with the order you want to place. It allows a trivial way to integrate.

I see that someone could spam with this (if we keep trying forever), however the indexer can have some policies to pause polling for some orders after a while. Even if we decide to drop it after 30min is already super useful for quick integrations.

[mfw78]

ComposableCoW was never designed inherently to support single-shot, and these were somewhat "wedged" into the design in retrospect. It was designed to support primarily generational conditional orders that generate multiple discrete orders.

I don't think that we should be opening some escape hatch mechanism like this, and perhaps should drive more of a defining line that separates multi-discrete order generators and single-shot. The concern with single-shot has always been with trying to define a nullifier that ensures the single-shot property. For example, StopLoss will continue to generate discrete orders so long as the conditions are met, even if the position has already been sold, and so to handle this, it was often done that there would be some intermediate contract whose job was specifically just to hold the funds for that purpose (this is really a mess, and IMO having specific contracts spun up for specific orders such as this is more indicative of an architectural smell as opposed to a sound system).

I would think that there may be scope available for the single-shot conditional order mechanism to be refined / clarified with a combination of indexing work + generalised wrappers, so as to be able to then ensure that some requisite post-hook has run, adjusting state to nullify the single-shot conditional order, though I would determine generalised wrapper implementation for such to be out-of-scope on the current grant (but indexing / architectural design to be within scope).

[anxolin]

Not sure I got all this.

The point is, currently is super complex for a smart contract to create an order.

They need to use ComposableCoW, which has a lot of indirection built in and people struggle to understand.

So for the simpler cases, of a SC creating an order, and a watch tower picking it, would be nice to have a contract that receives the params, emits the event, and someone creates the order for them.

It doesn't need to be in Composable CoW it can be an independent contract, I just thought watch-tower could index and post order for both flows.

If this is out of scope, fine, I just bring it up as it has been a feedback, and if you are modifying the contract, which will require re-audit and has breaking changes, might be worth it to add this alternative simpler flow.

[anxolin]

i love moving the polling logic to the handler. Not sure people will put the effort into optimising for this in the contract, but it really makes the indexers simpler.

[anxolin]

I didn't get exactly what you mean? can you give one example

[mfw78]

Cardinality defines the number in a set. Let's consider some hypothetical "range trading" conditional order that trades for side-ways pairs. It may attempt to do so every n period, but only if certain conditions are established (price at certain range), for some time t. In which case, the upper bound (cardinality) for this conditional order may be t / n, but the price case may not always be met, so it may be less than t / n.

[anxolin]

Maybe what confuses me is that BOUNDED is by defiition FINITE.

[mfw78]

Do you think we can come up with a simpler way to automatically decode the static input? (so UIs and the indexer have an easier time explaining the order)

We have this thing that uses the SDK, but requires you to register the handler. https://sdk-tools.cow.fi

So, I suppose we could add a 'Metadata' abstract contract interface, but this would present only a string-based representation of the conditional order. Nonetheless, this is the nature of ABI and IMO SDK interfaces coupled with dynamic discovery method to retrieve some application specific module that is capable of decoding (this would then allow, for example, a handler to register via ENS the location of their decoder) is the way to go. Such design is non-trivial, but could be included from an architectural perspective so that some discovery mechanism was able to be implemented at a later date.

[anxolin]

Do you think we can come up with a simpler way to automatically decode the static input? (so UIs and the indexer have an easier time explaining the order)
We have this thing that uses the SDK, but requires you to register the handler. https://sdk-tools.cow.fi

So, I suppose we could add a 'Metadata' abstract contract interface, but this would present only a string-based representation of the conditional order. Nonetheless, this is the nature of ABI and IMO SDK interfaces coupled with dynamic discovery method to retrieve some application specific module that is capable of decoding (this would then allow, for example, a handler to register via ENS the location of their decoder) is the way to go. Such design is non-trivial, but could be included from an architectural perspective so that some discovery mechanism was able to be implemented at a later date.

What about we force handlers to implememt:

function staticInputAbi() external pure returns (string memory);

This way TWAP can return the string:

TWAPOrder(address sellToken,address buyToken,address receiver,uint256 partSellAmount, ...)

Any web3 lib could use this and the static input and make sense of it

[mfw78]

function staticInputAbi() external pure returns (string memory);

This would have to take a bytes parameter as well yes? ie.:

function staticInputAbi(bytes calldata) external pure returns (string memory);

The interface would make no enforcement at a smart contract level as to what the string itself would return, other than that the developer should "convey a human readable understanding of the static input".

[yvesfracari]

Can you confirm if the single shot order enforcement is more flexible or if the same pattern will be used -- handler must return a constant order?

In my opinion single-shot orders handlers should be more easier / more flexible to create. Stop loss is a good example that you must hard-code the entire order to make it work (so you can't calculate the amounts based on current price + slippage for example). The current interface limits the flexibility of single shot orders a lot in my understanding.

I don't have full context on how hard would be possible to create an easier way to do it with this new interface. Since the pooling and verifier interfaces changed, my understand is that this could be solved by invalidating the composable cow after its verification. This would only work for fill or kill orders but it still looks like a good feature from my point of view.

[mfw78]

I don't have full context on how hard would be possible to create an easier way to do it with this new interface. Since the pooling and verifier interfaces changed, my understand is that this could be solved by invalidating the composable cow after its verification. This would only work for fill or kill orders but it still looks like a good feature from my point of view.

As isValidSignature is view only, it is not possible to modify any state after its verification. The only method to modify any state is by reference to a post-hook, which then runs into authorisation / griefing attack problems (anyone can execute the post-hook that does the voiding action from the HooksTrampoline).

Essentially I think that with the difficulty associated with this, it's more than likely that this kind of design is an anti-pattern when it comes to CoW Protocol in its current incarnation. A much simpler solution, albeit one that requires the use of gas, is to have a conditional order that is triggered via account abstraction or similar, which does setPreSignature and then subsequently voids the conditional order atomically.

[anxolin]

As isValidSignature is view only, it is not possible to modify any state after its verification. The only method to modify any state is by reference to a post-hook, which then runs into authorisation / griefing attack problems (anyone can execute the post-hook that does the voiding action from the HooksTrampoline).

This could be convined with Generalise Wrappers to make it work.

We add a wrapper hint to a contract that, marks the order as traded after the settlement. The composable cow handler, only allows to trade if we haven't traded a similar order.

[anxolin]

Would this make sense?

[anxolin]

If there's a second sister order generated by the handler:

• If the settlement calls the wrapper (as instructed) --> Reverts
• If it skips the wrapper, the order will be unsigned

[mfw78]

Given the advent of the wrappers, does this create any technical debt on the indexing methods that have been proposed in this PR?

[anxolin]

I don't think so. The indexer would pick order1 post it to the API, while in-flight, will pick a second order order2, because the 1st one is not executed, it will post it to the API too.

The API accept both, they both are accepted by the contract.

The first one executing, will automatically invalidate the other. The order will remain in the orderbook until expiration.