Skip to content

Grease Payment Channels -- production implementation and SDK

CJ requested to merge CjS77/ccs-proposals:cjs77/grease into master

Project overview

          ++++++++++++                      *   .   *           .       *       .       *          .        *
      +++++++++++++++++++                                 .    *     .    *  *      .       *           *
    +++++++++++++++++++++++                   ;;;;;;;;                                              .
   ++++++++++++++++++++++++++              ;&&&&&&&&&&;  ;&&&&&;   ;&&&&&&&&; ;&&&&&&;    ;&&&&&; ;;;;;;;;;
  +++++++++++++++++++++++ ++++            ;&&&&&&&&&&&; ;&&&&&&&&; ;&&&&&&&+  ;&&&&&&;  ;&&&&&&&&;&&&&&&&&;
 +++++  +++++++++++++++   +++++          ;&&&&x;  ;&&&; ;&&&;;;&&&;;&&&;      ;&&&&&&&  ;&&&&;;;; &&&&;;;;;
++++++    ++++++++++++    +++++         ;&&&&&;    ;;;;  &&&; ;&&&;;&&&;;;;   ;&&; &&&; ;&&&&;    &&&&;
++++++      ++++++++      ++++++        ;&&&&;           &&&;;&&&&;;&&&&&&;   x&&; ;&&;  ;&&&&;   &&&&&&&;
++++++   #    ++++    #   ++++++        ;&&&&;  ;&&&&&&&;&&&&&&&;; ;&&&;;.   ;&&&&&&&&;   ;X&&&&; &&&&&&&;
++++++   ##    +    ###   +++++         ;&&&&;  ;&&&&&&&;&&&&&&&;  ;&&&;     ;&&&&&&&&;     ;&&&&;&&&&;     &
++++++   ####     #####   +++++         ;&&&&&: ;;;;&&&; +&&&;&&&; ;&&&&&&&&;&&&&  ;&&&.;&   ;&&&&;&&&;     .
         ###### #######                  ;&&&&;    &&&&; ;&&& ;&&&&;&&&&&&&&;&&&;  ;&&&;&&&+;&&&&&;&&&&&&&&;
         ##############                   ;&&&&&&&&&&&&; ;&&&; ;&&&&&;;     &&&&;  ;&&&;&&&&&&&&&;;&&&&&&&&
   ##########################              ;&&&&&&&&&&;  ;;;;;   ;&&&&&&&;         ;&&&&;;&&&&&&;        .
    #######################                  ;;&&&&;;              ;;X&;;        &  ;;;;;   ;     *   .
       ##################                 .               *     .    .   .      .     *      .  *      *
          ###########                         *  .   *       .    *        *  .         *          .      .

What is Grease?

Grease is a bidirectional, two-party payment channel implementation for Monero.

Grease allows an unlimited number of near-instant, free, trustless transactions to take place between two parties -- typically a customer and a merchant -- without waiting for blockchain confirmations or having to manage UTXOs. The parties can close the channel at any time to settle the final balance on the Monero blockchain. A key escrow service (KES) exists to handle the cases of uncooperative channel closures and disputes, but in the vast majority of cases, channels will be opened and closed
cooperatively without the KES needing to intervene.

Key use cases

Grease demonstrates its value anywhere that multiple, fast, low-value transactions are needed.

The obvious examples include:

  • Rapid point-of-sale transactions - Conferences, festivals, arcades, bars. Load up a channel at the start of the event, make instant purchases throughout, and close the channel at the end to settle. The estimated addressable market for this use case is $1.5T annually (Monerokon 2025).
  • Online games - Casino games, in-game microtransactions, etc. The estimated addressable market for this use case is $500B annually (Monerokon 2025).
  • Fine-grained on-demand content - The market for this use case does not even exist yet, since microtransactions are too costly to facilitate -- even in the fiat world. However, this is where the biggest opportunity lies, particularly in the context of privacy. Grease payment channels would allow, anonymous on-demand consumption of music, video, news and, perhaps most importantly, AI inference.
  • Agentic AI payments - This emerging use-case may become the most important. As AI agents become more capable and autonomous, they will need to make a huge number of on-demand payments for various services, such as API calls, data access, compute resources, and more. Grease channels can be thought of as disposable wallets for these agents. Users can fund a channel with a predetermined budget for a specific purpose, and the agent can only use it for that purpose and nothing else until the budget runs out. This provides a secure and private way for agents to make payments without their owners risking overspending or having to share seed phrases.

The state of the project

Overall, the project is around 60% of the way towards a production-ready beta. Total development time for a production-ready beta is estimated at 3,500 hours, of which around 1,975 hours have been completed, thanks to generous donations from PowerUp Privacy who have funded the PoC development and beyond.

The proof-of-concept was demonstrated at Monerokon 2025 which covered the "happy path" of the channel flow, but did not implement the Key Escrow Service (KES), force-close or dispute phases.

Being a PoC, the code is also not production-ready in many ways, but was sufficient to demonstrate the core concept and get feedback from the community, which has been encouraging. Therefore, I am asking the community to help fund the remainder of the development to take Grease from PoC to production-ready beta. I estimate that 1525 hours are required to complete the Production Beta at a blended rate of €100/hr. At an XMR price of $345 (€295) this amounts to 517 XMR, split over 8 milestones.

Development history and roadmap

Developing the PoC took around 1,350 man-hours. This was primarily focused on research as well as the initial happy path implementation for the proof-of-concept.

Post-PoC, an additional 640 hours has been spent on writing detailed technical documentation, designing the architecture for the production implementation, and improving the performance of the zero-knowledge proofs by some 30x.

Although Grease was inspired by the Monet paper, it is clear that Monet is a good academic concept for the core payment channel construction, but is missing many components that are required for practical, safe, production payment channels.

The remaining work to be done (estimated 1,525 hours) includes:

  • Rewriting the entire payment channel flow from the PoC code into safe, secure, production patterns including
    • disaster recovery,
    • safe secret handling,
    • forward secrecy,
    • multi-channel support and a myriad other things that are irrelevant to a PoC but critical for financial software living in the wild.
  • Implementing the force-close, dispute, and channel claim phases.
  • Writing an SDK to make it easy to develop Grease-based applications
  • Implementing FCMP++ support.
  • Completing a real-world app demonstrating Grease: Real-time editing of a shared, canvas with a per-pixel payment API (akin to the original /r/place).

Milestones

# Milestone Man-hours XMR
1 Production-ready happy path (Channel init → payments → co-operative close) 100 33.9
2 Production-ready Consensus close 225 76.3
3 Production-ready Dispute & channel-claim 310 105.1
4 Kes server + Grease server implementation 445 150.8
5 FCMP++ integration 200 67.8
6 Grease SDK 85 28.8
7 Deployment tools, updated docs & e2e testing coverage 95 32.2
8 Pixel Place App 65 22.0
Total 1,525 516.9

Deliverables

To help determine whether a milestone is complete, I propose the following deliverables for each milestone.

Milestone 1: Production-ready happy path

No UI or APi exists yet, so this milestone will be judged on the completion of a set of E2E integration tests over the underlying protocols:

  • collaboratively open a channel, fund the channel form a testnet wallet, and receive proofs from the KES that the keys have been escrowed properly.
  • perform a series of payments,
  • co-operatively close the channel.
  • Receive the balance in the nominated Monero exit wallet.
  • The KES destroys the escrowed keys and cleans up their records for the channel.

Milestone 2: Production-ready Consensus close

The Grease white paper mentions two alternatives for force-close resolution. This CCS only implements Option 1. No UI or APi exists yet, so this milestone will be judged on the completion of a set of E2E integration tests over the underlying protocols:

  • The merchant force-closes the channel with the latest state. The client can prevent the merchant taking all the funds by performing a consensus close request via the KES.
  • The client force-closes the channel with the latest state. The merchant can prevent the client taking all the funds by performing a consensus close request via the KES.
  • After the channel close, both parties receive their expected channel balance back in their designated wallets.
  • After the channel close, the KES cleans up their records for the channel, and destroys the escrowed keys.

Milestone 3: Production-ready dispute and channel-claim

The Grease white paper mentions two alternatives for force-close resolution. This CCS only implements Option 1. No UI or APi exists yet, so this milestone will be judged on the completion of a set of E2E integration tests over the underlying protocols.

Scenario: The claimant attempts to close the channel with an outdated state.

  • The defendant can register a dispute with the KES.
  • Prior to the dispute window closing, the claimant cannot claim the channel.
  • The defendant can submit a new state proof to the KES and claim the channel funds.
  • After the dispute window is closed, but before the claimant has claimed the channel, the defendant can submit a dispute resolution proof to the KES and claim the channel funds.
  • Either claimant or defendant can claim an abandoned channel.
  • After a channel has been claimed, the KES cleans up their records for the channel, and destroys the escrowed keys.

Milestone 4: KES server + Grease server implementation

This milestone includes the development of API servers for the merchant, client and KES. The deliverables include:

  • Running API servers for the merchant, client and KES, with proper logging, persistence, disaster recovery and reliability consistent with a production-ready beta release.
  • CLI interfaces to the APIs.
  • A demonstration of the servers working together over a networked environment, using live (testnet) Monero wallets to demonstrate the happy path:
    • collaboratively open a channel, fund the channel form a testnet wallet, and receive proofs from the KES that the keys have been escrowed properly.
    • perform a series of payments,
    • publish a set of benchmarks for payment channel performance (pre FCMP++),
    • co-operatively close the channel.
    • Receive the balance in the nominated Monero exit wallet.
    • Merchant notifies the KES of the channel closure,
    • and the KES destroys the escrowed keys and cleans up their records for the channel.
  • Demonstration of the force-close and dispute flows, over a networked environment:
    • The merchant becomes unresponsive. The client can force-close the channel, and claim the channel funds after the dispute window closes.
    • The client becomes unresponsive. The merchant can force-close the channel, and claim the channel funds after the dispute window closes.
    • The merchant force-closes the channel with the latest state. The client can perform a consensus close request via the KES.
    • The client force-closes the channel with the latest state. The merchant can perform a consensus close request via the KES.
    • The merchant attempts to close the channel with an outdated state. The client can dispute the closure, and claim the channel funds after a successful dispute.
    • The client attempts to close the channel with an outdated state. The merchant can dispute the closure, and claim the channel funds after a successful dispute.
    • The channel is abandoned after a force-close request. Either party can claim the channel funds.
    • In all cases, the KES destroys the escrowed keys and cleans up their records for the channel after it has been claimed.

Milestone 5: FCMP++ integration

Grease has been updated to support Monero FCMP++ transactions. This is demonstrated by:

  • Faster channel initialization through the use of chained transactions.
  • Postponing state update signatures until channel closure. We expect an improvement in channel benchmarks, and more importantly, Grease channels can stay open indefinitely without being updated. Pre-FCMP++ channel decoys become stale and so periodic channel updates are required to maintain the validity of the commitment transactions.

This milestone also requires the upgrade of Grease to make use of the latest version of Serai and Monero Oxide, which is a significant effort in itself. This deliverable will be demonstrated via the dependency graph of the Grease codebase, showing the updated dependencies, and migration to the latest Serai wallet APIs.

Milestone 6: Grease SDK

The Grease SDK will be a library that abstracts away the underlying protocol and provides a simple interface for developers to build
applications on top of Grease. It is anticipated that this milestone will be developed in concert with Milestone 8 in order to iterate towards the most ergonomic API for developers building on top of Grease.

Milestone 7: Deployment tools, updated docs & e2e testing coverage

  • To facilitate the deployment of Grease, a set of deployment tools will be developed. This includes, documentation and scripts for deploying the KES, the client application, and the merchant server.

  • Completion of end-to-end testing coverage to all major flow paths and edge cases.

  • Completion of unit testing coverage to 80% of the codebase.

  • Updated documentation to reflect the production-ready beta release, including API documentation for the Grease SDK

Milestone 8: Pixel Place App

Deliverables of this milestones include:

  • A live, public instance of a Pixel Place-type app, demonstrating real-time editing of a shared canvas with a per-pixel payment API built on top of the Grease SDK.
  • Users will need to run a client application to interact with the Pixel Place app. Only Linux support is included in the deliverables. The client application may be CLI only, but will support these features:
    • Channel management (open, close, view balance, etc.)
    • Read the state of the canvas.
    • Manually change a single pixel.
    • Batch change pixels using a file-based image.

Out of scope

  • Security audits
  • Mobile client applications. It makes more sense to engage existing wallets to integrate Grease rather than develop standalone mobile clients.
  • Smart-contract-based KES. Grease is designed to accommodate multiple KES solutions. The ultimate goal is to deploy KES implementations to one or more trustless private blockchains. Candidates include Aleo, Aztec, DarkFi & Tari. However, these projects (with the exception of Aleo) are still in testnet phase. Therefore, rather than delay Grease, the first KES implementation will be a centralized escrow service. The trade-offs of this decision are discussed in the technical documentation.

Who

CjS77 is an engineer that has been developing in the blockchain space since 2016. He has been actively advancing privacy technologies since 2018. Highlights from this period include:

Use of funds and progress tracking

The funds will be used exclusively for the furtherment of the Grease beta release. The vast majority of the funds will be spent on engineering time. However, CjS77 reserves the discretionary right to use a portion of the funds to pay for related services if he deems that such expenses would benefit the development from an efficiency, security or quality point of view. Non-exclusive examples include cryptography expertise and input, front-end development, development tools and software licenses. All code and research delivered by third parties will be thoroughly reviewed by CjS77, and he takes ultimate responsibility for all code delivered as part of this CCS. Unless they request otherwise, third party work will be acknowledged and credited.

Software engineering estimates are notoriously unreliable. Only the median estimate for this CCS proposal is presented and there is a significant chance that the effort required is under-estimated, particularly for milestones 5-8, for which there are several "unknown unknowns". CjS77 will shoulder the risk of under-estimation and will commit to completing the milestones for the stated budget, irrespective of the actual hours required or third-party expertise that he employs. I also accept the price volatility risk of XMR over what is likely to be a 10-14 month development effort.

On the other hand, if milestones are completed under budget, CjS77 requests that excess funds be rolled over to the next milestone, given the lower confidence in the estimates of milestones 5-8. If the entire project is completed under budget, then excess funds will be subject to the standard CCS policy and be transferred to the general fund.

Over and above the requirements of the CCS rules, progress towards the milestones will be tracked via a Project board on the Grease Github repository (including actual time taken).

References

Edited by CJ

Merge request reports