Grant Application: Programmatic Orders API

CoW Grants Program
1

Grant Application: Programmatic Orders API

Grant Title:

Programmatic Orders API

Author:

@bleu @yvesfracari @ribeirojose @mendesfabio

About You:

bleu collaborates with companies and DAOs as a web3 technology and user experience partner. We’re passionate about bridging the experience gap we see in blockchain and web3. We have completed 10+ grants for CoW Protocol, including Hook dApps, Framework-agnostic SDK, Python SDK, and various Safe apps.

Additional Links:

Our work for CoW Protocol includes:

  • [CoW] Framework-agnostic SDK: Refactored the CoW SDK to support multiple EVM adapters (ethers v5/v6, viem, wagmi), enabling framework-agnostic integration.
  • [CoW] Hook dApps: Developed a suite of hook dApps integrated on the CoW Swap frontend, including liquidity pool hooks, claim airdrop, and vesting hooks.
  • [CoW] Python SDK: Created a Python version of the CoW SDK for developers to query on-chain data, manage orders, and integrate with CoW Protocol’s smart contracts.
  • [CoW] AMM Deployer: Safe app to deploy new CoW AMM pools from a Safe Wallet.
  • [CoW] Stop Loss: Safe App to create stop loss orders, during this grant we develop an API that tracks the creation of composable cow and decode the stop loss ones: https://composable-cow-api.up.railway.app/

Grant Category:

Core Infrastructure & Developer Tooling

Grant Description:

CoW Protocol supports various types of programmatic orders that enable advanced trading strategies:

  • Composable CoW orders: Conditional orders like TWAP, Stop Loss, Perpetual Swap, Good After Time, and Trade Above Threshold
  • Flash loan orders: AAVE integration that use helper contracts deployed via pre-hooks

As programmatic orders become available to EOAs through CoWShedForComposableCow and other mechanisms, there is a need for unified indexing infrastructure to support the CoW Swap frontend and ecosystem applications.

Currently, there is no unified infrastructure to efficiently track and query programmatic orders across all types. This creates a few problems:

  • Lack of order visibility before OrderBook: Programmatic orders only become visible in the CoW Protocol OrderBook when they are actually placed and are executable. Before that, there’s no centralized way to track pending orders, monitor their status, or display them to users.

  • Difficult to map CoWShedForComposableCow contracts with EOAs: Each user interacts with Composable CoW through their own CoWShed proxy contract, making it challenging to establish the relationship between the proxy address and the actual EOA owner.

  • Flash loan order ownership tracking: AAVE integration rely on a pattern where an EOA places an order whose owner is an undeployed helper contract, which is then deployed in a pre-hook. This enables powerful constructs but creates poor UX because it becomes harder to track the original owner of the order and show trading history.

We propose to build a Programmatic Orders API that will provide queryable access to all programmatic order data. The API, built with Ponder as the indexing framework, will:

  • Index all Composable CoW orders created on supported chains with real-time monitoring
  • Decode all Composable CoW order types:
    • TWAP (Time-Weighted Average Price) orders
    • Stop Loss orders
    • Perpetual Swap orders
    • Good After Time orders
    • Trade Above Threshold orders
  • Track flash loan orders (AAVE integration) by linking deployed helper contracts to their rightful EOA owners
  • Resolve ownership by integrating with CoW Shed to map contract addresses to EOA owners
  • Provide API access via GraphQL endpoints with comprehensive querying capabilities

Flash Loan Order Indexing Approach:

For flash loan orders (AAVE integration), we need to establish a link between the deployed helper contract and the original EOA owner. Currently, there is no event that links these two addresses, so we recommend that this be added to make the indexer more efficient. However, we propose a two-workaround approach to the already executed orders:

Solution 1: Factory Event Monitoring

  • Monitor AaveV3AdapterFactory.deployAndTransferFlashLoan calls where the receiver is the helper contract and the owner is the EOA who created the order
  • Challenge: Requires call traces which are not supported on all chains and depends on expensive RPC calls

Solution 2: Trade Event Pattern Detection

  • Listen to trade events and verify if the owner follows the helper contract pattern by calling specific ABI methods
  • Challenge: Requires many RPC calls but works on all chains

Grant Goals and Impact:

This grant will provide critical infrastructure for CoW Protocol’s programmatic order ecosystem by enabling:

  • Support CoW Swap Frontend Integration: Enable the frontend to display all programmatic orders (Composable CoW and flash loan orders) to users, providing full visibility into their active, completed, and cancelled orders.
  • EOA Support: As programmatic orders become available to regular wallets through CoWShedForComposableCow and helper contracts, users will need a unified way to manage and monitor their orders
  • Unified Order Tracking: Support all programmatic order types:
    • Composable CoW orders (TWAP, Stop Loss, Perpetual Swap, Good After Time, Trade Above Threshold)
    • Flash loan orders (AAVE integration, generalized wrappers)
  • Third-party Integration: Developers can use the same API to debug and track their own programmatic orders
  • Extensible Infrastructure: Extensible architecture ready to support new programmatic order types as they are developed

GraphQL Schema (Draft):

The indexer will expose the following schema through a GraphQL API: dbdiagram.io - Database Relationship Diagrams Design Tool

Schema Design Rationale:

  • Transaction: Tracks all transaction details for order creation and cancellation
  • User: Can be EOAs or proxy contracts (AAVE flash loan helper or CoW Sheds). If is a proxy, it references the real owner.
  • ComposableCoW: Central entity for Composable CoW orders with ownership.
  • Order Type Entities: Each Composable CoW order type has dedicated fields for its specific parameters
  • Token: Normalized entity to avoid data duplication and enable aggregated statistics
  • Order: Links to CoW Protocol Orders (posted on the orderbook) with the entity that created that order. This is more complex on orders where the UID is not defined on the composable cow creation (like the PerpetualSwap but it could be achieved by comparing with the getTradableOrderWithSignature). This would require pooling the OrderBook historically and in realtime, which requires adaptations of the indexing framework since it is an off-chain data. Also, to minimize delay on real time indexing, we will need to perform complex optimizations on the order matching algorithm.

Milestones:

Milestone Duration Payment
Composable CoW tracking 3 weeks 9k xDAI
Flash loan order tracking 1 week 3k xDAI
CoWShed ownership mapping 1 week 3k xDAI
Orderbook integration 4 weeks 12k xDAI
Review and Documentation 2 week 6k xDAI

Composable CoW tracking and decoding (3 weeks)

  • Ponder indexer setup with PostgreSQL database
  • Event listening for Composable CoW order creation and cancellation
  • Historical backfilling and real-time monitoring
  • Implement decoders for all five order types (TWAP, Stop Loss, Perpetual Swap, Good After Time, Trade Above Threshold)
  • Integrate missing conditional orders (all except TWAP) into cow-sdk.

Flash loan order tracking (AAVE) (1 week)

  • Flash loan order to EOA owner mapping (AAVE integration)
    • Implement factory event monitoring AaveV3AdapterFactory.deployAndTransferFlashLoan
    • Implement trade event pattern detection as fallback
    • Support for contract event enhancement when available

CoWShed ownership mapping (1 week)

  • CoWShedForComposableCow proxy to EOA owner mapping
  • Tracking CoWShed proxy deployments
  • Linking proxy contracts to their controlling EOAs

Orderbook integration (4 weeks)

  • Pooling of historical and realtime order book data.
  • Matching of order book orders with generators.
  • Linking orders to their originating programmatic orders generator
  • Tracking execution status for Composable CoW orders

Review & Documentation (2 weeks)

  • Review of CoW team and bug fixing
  • Complete API documentation (GraphQL schema, examples)
  • Integration guides for frontend and third-party developers
  • README documentations on how to run and deploy the application

Funding Request:

We propose that milestone payments be released upon each milestone’s approval.

Budget Breakdown:

We suggest a payment structure similar to our previous grants:

  • xDAI payments for each milestone completion
  • COW tokens vested over 12 months for ongoing maintenance and support
  • RPC costs should be covered by the CoW Protocol by providing private RPC connection links. Ideally one RPC of each chain should be provided, however develop in just one chain is also possible.

Gnosis Chain Address (to receive the grant):

0x554866e3654E8485928334e7F91B5AfC37D18e04

Other Information:

  • All code will be open-source from day 0
  • We’re open to feedback during PRs and happy to collaborate closely with CoW Protocol team
  • Frontend Collaboration: We plan to work closely with the CoW Swap frontend team to ensure the API meets their requirements for displaying all programmatic orders to users
  • For the OrderBook integration, we’ll need access to the current auction endpoints of the API.
  • During development we’ll deploy the indexer for testing reasons, but this should be handed off to the CoW team operations after the grant conclusion.
  • We have extensive experience with blockchain indexing infrastructure, having worked on multiple data layer projects for DeFi protocols (Silo Finance, other CoW grants, etc)
  • We’re happy to answer any questions and iterate on this proposal based on feedback

Terms and Conditions:

By submitting this grant application, I acknowledge and agree to be bound by the CoW DAO Participation Agreement and the CoW Grant Terms and Conditions.

4 Likes
2

Update: Revised Scope Based on Feedback

Based on feedback on the initial proposal, we’re adjusting the proposal to focus on core deliverables while reducing optional features and buffers.

Updated Milestones:

Milestone Duration Payment
Composable CoW tracking 2 weeks 6k xDAI
Flash loan order tracking & CoWShed ownership mapping 1.5 weeks 4.5k xDAI
Orderbook integration 4 weeks 12k xDAI
Review and Documentation 1.5 weeks 4.5k xDAI

Total: 9 weeks, 27k xDAI

Key Changes:

  1. Composable CoW tracking (3w → 2w): We’re removing the cow-sdk integration for new conditional orders from the scope. The cow-sdk already includes an error decoding functionality, making our integration overhead.

  2. Flash loan & CoWShed mapping (2w → 1.5w): These two milestones are being combined as they’re closely related and more straightforward than initially estimated.

  3. Orderbook integration (4w - unchanged): This remains the most complex milestone. The core challenge is building a robust polling system to connect with the orderbook and continuously sync data. For matching orders with their originating Composable CoW generators, we’ll decode the EIP-1271 signature to identify the source (thanks @mfw78 for the guidance). The proof of concept has been adapted to demonstrate this approach.

  4. Review & Documentation (2w → 1.5w): Reduced buffer time while maintaining quality for feedback cycles, Ponder documentation, and comprehensive guides.

COW Token Payment:

We’ve also updated the funding request to include COW tokens for ongoing maintenance and support (this is standard on all of our proposals and was forgotten on the original one):

  • 40k COW tokens vested over 12 months to cover ongoing maintenance

We’re waiting for feedback from the CoW core team and grants committee on this revised proposal. Happy to discuss further adjustments based on your input.

3

I believe this initiative is very valuable and I would vouch for it. I just think the (3.) Orderbook integration, if I understand properly, should not be that complicated. 4 weeks might be too much buffer.

Just to confirm. I guess this is about reacting to trade events and mapping the order to the composable cow order.

See https://github.com/cowprotocol/composable-cow/blob/main/src/ERC1271Forwarder.sol#L30

(GPv2Order.Data memory order, ComposableCoW.PayloadStruct memory payload) =
            abi.decode(signature, (GPv2Order.Data, ComposableCoW.PayloadStruct));

struct PayloadStruct {
        bytes32[] proof;
        IConditionalOrder.ConditionalOrderParams params;
        bytes offchainInput;
}

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

This should make it easy to identify it and do the mapping.

Some other topic I didn’t fully get if this will be solved. Programmatic orders such as TWA,P might have discrete orders (parts) that don’t execute.
This means, you won’t see the trade event, therefore the orderId won’t be linked to TWAP. If this API is used in CoW Swap or Explorer, we won’t see the skipped orders. Ideally, we would so this responsibility is removed from UIs: It’s always nice for a UI to also show the parts that expired

I don’t think is a good idea to generate ahead of time all discrete orders (parts), there can be millions. But maybe we could always try to generate the next one? This way, we will have all parts, not just the filled ones.

1 Like
4

Thanks for the feedback. The complexity of the third millestone is because of the integration with the OrderBook API. While all the RPC calls will be automatically cached on Ponder, they don’t have any built in feature for cache off-chain data. On each new deploy, ponder re-run all the event handlers to rebuild the database (this is way faster the subgraph but it sill can take a while if the event / block handlers are not well optimize). In that sense, it is really important to cache (in a way that is persistent between deployment) results of the off-chain requests.

Since some composable cow can generate infinite non deterministic orders (e.g. perpetual swaps), I was assuming that will be cases that we would need to fetch all the ordebook orders from a user since the creation of the composable cow. However, since composable cow have specific revert messages to help watch tower on the indexing of the orders, we can use those as well and will probably be more efficient.

With that, we agree in change the third milestone from 4 to 3 weeks:

Updated Milestones:

Milestone Duration Payment
Composable CoW tracking 2 weeks 6k xDAI
Flash loan order tracking & CoWShed ownership mapping 1.5 weeks 4.5k xDAI
Orderbook integration 3 weeks 9k xDAI
Review and Documentation 1.5 weeks 4.5k xDAI

Total: 9 weeks, 24k xDAI

5

Sounds great! Thanks for clarifying. It looks like a good proposal

1 Like
6

Given I’m familiar with this, I volunteer to help with the reviewing process for milestone payments

2 Likes
7

Thanks @anxolin I’ll flag my support for this as well. @bleu I think you should take this to snapshot but let’s wait until early next week since we are heading into the weekend.

2 Likes
8

Okk! Thanks for the support, just moved to snapshot: Snapshot

1 Like
9

Update

Happy that the Snapshot was approved :tada:
We’re officially kicking off the project.

You can follow our progress here: cow-programmatic-orders-api

We’ll keep this thread updated as we hit each milestone. Thanks again for the support!

2 Likes
10

Thanks and congratulations. As always, just keep us updated on your progress. Looking forward to having you guys continue the great work you’ve done here for the CoW community.

2 Likes