Marlowe 2025: Oracle Protocol, Design and Implementation

[GENERAL] Name and surname of main applicant

Tomasz Rybarczyk (aka paluh)

[GENERAL] Are you delivering this project as an individual or as an entity (whether formally incorporated or not)

Entity (Incorporated)

[GENERAL] Please specify how many months you expect your project to last (from 2-12 months)

12

[GENERAL] Please indicate if your proposal has been auto-translated into English from another language

No

[GENERAL] Summarize your solution to the problem (200-character limit including spaces)

The Marlowe Oracle Protocol and easy-to-use toolkit will enable flexible, transparent data provision, and deliver improved oracles to developers and users of all Cardano smart contract languages.

[GENERAL] Does your project have any dependencies on other organizations, technical or otherwise?

Yes

[GENERAL] If YES, please describe what the dependency is and why you believe it is essential for your project’s delivery. If NO, please write “No dependencies.”

No dependencies

[GENERAL] Will your project’s output/s be fully open source?

Yes

[GENERAL] Please provide here more information on the open source status of your project outputs

All the code is and will be licensed under permissive “Apache License Version 2.0”. 

[METADATA] Horizons

DeFi

[SOLUTION] Please describe your proposed solution

Marlowe 2025

This is one of a set of proposals that together consolidate the Marlowe infrastructure and improve the developer experience, enhance Marlowe with an innovative oracle protocol, developed in collaboration with leading Cardano oracle providers, and design the successor core language, Marlowe V2, working with the Marlowe developer ecosystem.

Increasing Oracle’s Accessibility on Cardano

The current oracle systems on Cardano operate predominantly on a fixed, push-based model, which limits the ability to meet diverse and less commonly used data needs for smart contracts. Our solution, the Marlowe Oracle Protocol, aims to solve this by shifting towards a pull-based model, where oracles respond dynamically to on-chain data requests, ensuring better adaptability and data coverage for a wider array of contracts.

Our approach is centered around enhancing flexibility, transparency, and simplicity. We want to make the process of using oracles in smart contracts much more accessible to developers, whether they are experienced with Cardano tools or are just getting started with Marlowe, Aiken, or PlutusTx. The protocol will also include user-friendly tools, developed in TypeScript, Rust, and Haskell, to facilitate oracle accessibility for the end users and simplify integrations for developers as well as data providers.

Marlowe Oracle Specification

We want to formalize the “Marlowe Oracle Protocol” and submit it as a detailed Cardano Improvement Proposal (CIP). There are no guarantees that the proposal will be accepted but the process itself will allow us to approach the problem in a systematic manner and to create concise specifications.

Collaborations with Oracle Providers

To ensure the success and adoption of the Marlowe Oracle Protocol we are collaborating with key partners in the Cardano ecosystem:

• Wolfram Blockchain Labs: We are working pretty closely with the Team already and they are in the process of deploying their oracle solution on the mainnet and are really open to integrate the new approach into their future product release.
• Charli3 Oracles: We already initiated discussions with Charli3, and they expressed interest in our proposal and future integrations.
• Other oracle providers: We have spoken to other providers, including Orcfax and we hope to work closely with them on this project.

Marlowe Runtime and TS-SDK Adaptations

We will enhance the Marlowe Runtime to better support the Marlowe Oracle Protocol. This adaptation will include more precise “merkleization splitting” so developers are able to specify division points which preserve semantically meaningful subcontracts from the oracle perspective. This capability will be also exposed in our TypeScript SDK and examples.

Data Providers Toolkit

Ready To Use Oracle Service

We will expand on our oracle CLI application, which is currently a basic request harvester and data provider, transforming it into a fully operational, standalone system service. This minimal but complete implementation will serve as an MVP for the Marlowe Oracle Protocol. The goal is to deliver an out-of-the-box solution that requires minimal configuration, enabling oracle operators to start providing data points using the new emerging standard.

Customizable TypeScript Example and SDK

Additionally we will create standalone TypeScript examples which will demonstrate to the oracle builders how to discover and respond to the data point requests on the chain. These examples should be easy to customize and integrate with existing systems and complementary to the stand alone system service delivered separately.

[IMPACT] Please define the positive impact your project will have on the wider Cardano community

The Marlowe Oracle Protocol is a key enabler that will significantly lower barriers for both developers and data providers within the Cardano ecosystem. Marlowe already simplifies blockchain technology adoption for new users by providing an intuitive domain-specific language for financial contracts. With the addition of Oracle Protocols, we are expanding this accessibility to a wider range of real-world applications.

Lowering Entry Barriers for Developers

By developing and integrating the Marlowe Oracle Protocol into the Marlowe Runtime, we empower developers to not only create financial contracts but also seamlessly include oracle-based functionalities, which are critical for DeFi and other blockchain-powered use cases. Developers can now:

• Easily access real-world data in a secure, transparent, and trustless manner.
• Utilize easy-to-integrate tools and examples within our TypeScript SDK (TS-SDK), allowing them to quickly build dApps that harness external data.
• Implement Oracle requests in their contracts through straightforward integration, opening new possibilities for data-driven dApps.

Lowering Entry Barriers for Data Providers

The Marlowe Oracle Protocol also provides a clear pathway for data providers, such as stake pool operators (SPOs) or other trusted entities, to start contributing to the Cardano ecosystem with minimal overhead. We will deliver a lightweight but fully functional Oracle software component that implements the new protocol. This system is designed for:

• Ease of Deployment: Data providers can quickly set up and deploy this Oracle software integrating it with their knowledge backends.
• Reach and Incentives: With Marlowe's expanding ecosystem, Oracle data providers will gain direct access to a growing pool of developers and dApps that need data for their contracts. This creates a strong incentive model, where providers can monetize data sharing in a transparent and standardized manner.

DeFi Expansion

The ability to incorporate real-world data into contracts expands Marlowe’s potential use cases in the DeFi space, allowing for more sophisticated financial products and growth of the whole Cardano DeFi ecosystem.

Infrastructure Growth

Oracle services built with our protocol will help establish a foundational layer of real-world data access, which is crucial for many applications. The integration and standardization of Oracles will lead to an increase in robust and reliable infrastructure that dApp developers can depend on.

[CAPABILITY & FEASIBILITY] What is your capability to deliver your project with high levels of trust and accountability? How do you intend to validate if your approach is feasible?

Experience in Developing Marlowe Technology 

We are the core maintainers of Marlowe Lang and Core Team members of the Marlowe Project under IOG. 

We believe in the value it provides to the community and to the issues it can solve regarding mainstream adoption.

Development process will be public and open-source 

Both the output and the development process will be public and open-source. This approach provides an easy way for the Catalyst team and the Cardano community to evaluate the progress at each step of the process.

[PROJECT MILESTONES] What are the key milestones you need to achieve in order to complete your project successfully?

Specification and CIP Submission

• Rationale: To formally define the Marlowe Oracle Protocol and ensure its acceptance and understanding within the Cardano community, a detailed Cardano Improvement Proposal (CIP) must be submitted.
• Outputs:
• Prepare the full specification of the Marlowe Oracle Protocol.
• Submit the CIP proposal to the Cardano Improvement Proposal repository.
• Initial engagement with Oracle service providers (e.g., Wolfram Blockchain Labs, Charlie3, Orcfax) for feedback and integration.
• Acceptance Criteria:
• The CIP for the Marlowe Oracle Protocol is successfully submitted.
• Stakeholder feedback is documented, and adjustments to the specification (if any) are addressed.
• Evidence of Milestone Completion:
• Link to the publicly accessible CIP document.
• Meeting notes and documented feedback from Oracle providers.

Validator and Runtime Changes

• Rationale: To fully support Oracle functionality, we need to adapt the existing Marlowe validator and runtime backend to handle Oracle data interactions efficiently and securely.
• Outputs:
• Implement validator changes to guard the Marlowe state output after contract finalization, ensuring Oracle data integrity.
• Introduce changes to allow Marlowe to output relevant contract state (choices) as a UTxO, facilitating Oracle data integration.
• Adapt the Marlowe Runtime to support these new capabilities, including handling "merkleization splitting" to enable optimized Oracle interaction.
• Acceptance Criteria:
• Successful deployment of validator and runtime changes on both testnets.
• Functional integration of new Oracle data handling in test contracts.
• Evidence of Milestone Completion:
• Validator and runtime updates pushed to the public repository.
• Tests demonstrating correct handling of Oracle data on testnets.

Oracle Service App Enhancement and TypeScript SDK Example

• Rationale: Provide Oracle operators and developers with easy-to-use software components that fully implement the Marlowe Oracle Protocol, enabling both data provisioning and integration with contracts.
• Outputs:
• Enhance the current Oracle service app to transform it into a minimal but operational standalone system, ready for deployment.
• Develop example code and integration modules in the TypeScript SDK, demonstrating Oracle data requests and interactions with Marlowe contracts.
• Acceptance Criteria:
• Oracle service app is ready for use by data providers, including an example deployment.
• TypeScript SDK includes documented examples showcasing Oracle integration with Marlowe contracts.
• Evidence of Milestone Completion:
• Link to the Oracle service app in the public repository, along with deployment instructions.
• TypeScript SDK modules and example projects published and accessible for developers.

Aiken Support and Integration Example

• Rationale: To demonstrate the versatility and compatibility of the Marlowe Oracle Protocol with different smart contract languages in the Cardano ecosystem, we will add support for Aiken, along with a library and usage example.
• Outputs:
• Develop an Aiken library that supports Oracle requests and collecting responses using the Marlowe Oracle Protocol.
• Provide a complete example of an Aiken contract that integrates Oracle requests, demonstrating the protocol's interoperability.
• Acceptance Criteria:
• The Aiken library for Marlowe Oracle Protocol is implemented and accessible to developers.
• An Aiken contract example showcasing Oracle data integration is published.
• Evidence of Milestone Completion:
• The Aiken library and example contract are available in the public repository, along with documentation on integration.

Documentation, Integration with Marlowe DApp Starter Kit

• Rationale: To ensure the usability and accessibility of the Marlowe Oracle Protocol, comprehensive documentation and integration examples need to be provided.
• Outputs:
• Complete end-to-end documentation for Oracle integration, targeting data providers, developers, and users.
• Integrate Oracle examples and tutorials into the Marlowe DApp Starter Kit, including a practical dApp demonstration (such as the betting dApp using verifiable random numbers).
• Acceptance Criteria:
• Documentation is published and accessible, covering the protocol, example implementations, and integration processes.
• Marlowe DApp Starter Kit is updated with Oracle examples, including detailed tutorials.
• Evidence of Milestone Completion:
• Documentation hosted publicly, with links to access it.
• Marlowe DApp Starter Kit repository includes Oracle examples, with recorded usage tutorials.

Project Close-out Report and Video

• Rationale: To finalize the project, we will provide a summary report and a video that captures the essence of the solution, its progress, and its impact.
• Outputs:
• A project completion report detailing milestones, key achievements, and future prospects.
• A video summary showcasing the Oracle Protocol, key technical components, and how it contributes to the Cardano ecosystem.
• Acceptance Criteria:
• The project report is available via a publicly accessible link.
• The video guide is published on YouTube or X and linked for review.
• Evidence of Milestone Completion:
• Shared links to the project completion report and video.

[RESOURCES] Who is in the project team and what are their roles?

Tomasz Rybarczyk, who was an experienced member of the Marlowe team for a number of years, and who is part of the Marlowe continuity team, will be responsible for the main part of the design and Runtime/TS-SDK implementation of the protocol.

Simon Thompson, who is one of the original designers of Marlowe, will lead the project, mentoring and coordinating interactions with the community, taking part in the designing phase

Nicolas Henin (as a consultant/reviewer) was an experienced member of the Marlowe team for a number of years will help desing, evaluate and review the design and implementation.

[BUDGET & COSTS] Please provide a cost breakdown of the proposed work and resources

Milestone 1: Specification and CIP Submission

Days: 7

Milestone 2: Validator and Runtime Changes

Days: 35

Milestone 3: Oracle Service App Enhancement and TypeScript SDK Example

Days: 20

Milestone 4: Aiken Support and Integration Example

Days: 15

Milestone 5: Documentation, Integration with Marlowe DApp Starter Kit

Days: 8

Milestone 6: Project Close-out Report and Video

Days: 5

Total days: 90

Cost per day: ₳1500

Total budget: ₳135 000

[VALUE FOR MONEY] How does the cost of the project represent value for money for the Cardano ecosystem?

Investing in the Marlowe Oracle Protocol and its related tools will significantly lower the barriers for developers to integrate real-world data into smart contracts. By creating a standardized, efficient Oracle solution, we are enabling the Cardano ecosystem to build richer and more varied decentralized applications (dApps). This will not only increase the utility of the Marlowe platform but also attract new developers and data providers who can seamlessly participate in the blockchain economy. The broader use of Oracles will drive the development of sophisticated financial products and DeFi services, directly contributing to the Cardano ecosystem's growth and competitiveness.

Our costings are based on prevailing rates for researchers and developers in Europe, and we are charging the same rate for all contributors. We have a unique combination of skills in the team: one of the designers of the original Marlowe language, plus a team familiar with the systems of the Marlowe Platform, from the Marlowe validator. The team is highly experienced having previously worked as members of the core Marlowe team; there is therefore no time needed for the team to get up to speed: we hit the ground running.