diff --git a/concepts/hyle-vs-vintage-blockchains/index.html b/concepts/hyle-vs-vintage-blockchains/index.html index 00af750..794b6a0 100644 --- a/concepts/hyle-vs-vintage-blockchains/index.html +++ b/concepts/hyle-vs-vintage-blockchains/index.html @@ -1191,7 +1191,7 @@

Minimal onchain state

Transactions on Hylé verify and settle transitions without storing full intermediary states onchain.

This architecture reduces storage overhead and promotes scalability while maintaining trustlessness.

No wallets

-

Stop asking yourself, «Which wallet do I use? How do I bridge? ». With Hylé, there are no wallets and no bridges − any identity source that can be attested with a zero-knowledge proof is a valid identity.

+

Stop asking yourself, "Which wallet do I use? How do I bridge?". With Hylé, there are no wallets and no bridges − any identity source that can be attested with a zero-knowledge proof is a valid identity.

Every app is a rollup

On Hylé, there is one general-purpose blockchain, and every app is its own based ZK-rollup, removing the problems associated with fragmentation.

An app’s transactions are sequenced directly on the Hylé base layer. They are split into a blob transaction, which allows for pipelined proving, and a proof transaction to store the state commitment onchain.

diff --git a/concepts/proof-composability/index.html b/concepts/proof-composability/index.html index fcf48bb..10f0fca 100644 --- a/concepts/proof-composability/index.html +++ b/concepts/proof-composability/index.html @@ -1243,7 +1243,7 @@

The problem: clunky interactions

The solution: proof composition

Cross-contract calls with proof composition

Proof composability means that Hylé enables these interactions while keeping each proof independent; proof composition is the action enabled by composability.

-

Hylé gets rid of recursion by allowing Program A to specify: «This only applies if all blobs in this operation are valid ». At settlement, both proofs are included in the same proof transaction. Hylé verifies them together, and the entire operation fails if any proof fails.

+

Hylé gets rid of recursion by allowing Program A to specify: "This only applies if all blobs in this operation are valid". At settlement, both proofs are included in the same proof transaction. Hylé verifies them together, and the entire operation fails if any proof fails.

This solution improves developer experience, lowers gas costs, and shortens proving time.

Proofs using different schemes

Since proofs in Hylé remain independent, you can batch multiple proofs within a single transaction, each using its optimal proving scheme.

diff --git a/quickstart/example/proof-composition/index.html b/quickstart/example/proof-composition/index.html index b1cb12b..2f02704 100644 --- a/quickstart/example/proof-composition/index.html +++ b/quickstart/example/proof-composition/index.html @@ -1564,7 +1564,7 @@

Simple-identity preparation

Let's verify it quickly with:

cargo run -- --contract-name id verify bob.id pass 0
-

0 is a nonce: every time we verify successfully bob's identity, it increments. Now if we want to verify it again, we should use 1 as nonce. (We also use « pass » as our default password.)

+

0 is a nonce: every time we verify successfully bob's identity, it increments. Now if we want to verify it again, we should use 1 as nonce. (We also use "pass" as our default password.)

We now do the same for alice:

cargo run -- --contract-name id verify alice.id pass 0
diff --git a/search/search_index.json b/search/search_index.json index fbc30b2..8b2ec9d 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":""},{"location":"#home","title":"Home","text":"

Hyl\u00e9 is the new-generation base layer for the era of unchained applications.

"},{"location":"#navigation","title":"Navigation","text":"

Reach out on Telegram or open an issue if you need assistance or wish to provide feedback on the documentation: we're always looking to improve.

"},{"location":"#useful-links","title":"Useful links","text":""},{"location":"#lets-talk","title":"Let's talk!","text":"

Reach out to the team for more information:

Github Twitter Farcaster LinkedIn Youtube Telegram Hyl\u00e9 @hyle_org @hyle-org Hyl\u00e9 @Hyl\u00e9 @hyle_org"},{"location":"introduction/","title":"Introduction to Hyl\u00e9","text":""},{"location":"introduction/#introduction-to-hyle","title":"Introduction to Hyl\u00e9","text":"

Hyl\u00e9 is the new-generation base layer for the era of unchained applications.

An unchained application runs offchain and settles onchain. It benefits from the Web2 user experience and the security of Web3.

"},{"location":"introduction/#why-choose-hyle","title":"Why choose Hyl\u00e9","text":"

Hyl\u00e9 is built for speed, flexibility, and seamless blockchain integration:

"},{"location":"introduction/#how-hyle-works","title":"How Hyl\u00e9 works","text":"

Here\u2019s what happens when you use Hyl\u00e9\u2019s next-generation base layer:

  1. Sequencing: Send a provable blob of information to Hyl\u00e9: say what information you expect to prove later. We'll sequence the transaction immediately and give you time to prove it. Read more about pipelined proving.
  2. Proof submission: when the proofs for your transaction are ready, send them to Hyl\u00e9.
  3. Verification: Hyl\u00e9 validators receive the transaction. They verify the proofs natively, without the limitations of a bulky virtual machine.
  4. Consensus: if the proofs are valid, Hyl\u00e9 settles your transaction's state onchain. You're good to go!

With this system, execution and storage happen anywhere you like. You only need a fast and trustworthy verifier: that\u2019s Hyl\u00e9.

"},{"location":"concepts/","title":"\ud83d\udca1 Concepts","text":""},{"location":"concepts/#concepts","title":"Concepts","text":"

Welcome to the developer documentation for Hyl\u00e9.

This section includes general documentation topics. You can also refer to our Getting Started step-by-step guide.

"},{"location":"concepts/#hyle-specific-docs-on-industry-concepts","title":"Hyl\u00e9-specific docs on industry concepts","text":""},{"location":"concepts/#hyle-specific-concepts","title":"Hyl\u00e9-specific concepts","text":""},{"location":"concepts/#more","title":"More","text":""},{"location":"concepts/hyle-vs-vintage-blockchains/","title":"Hyl\u00e9 vs. vintage blockchains","text":""},{"location":"concepts/hyle-vs-vintage-blockchains/#hyle-vs-vintage-blockchains","title":"Hyl\u00e9 vs. vintage blockchains","text":"

If you're used to traditional blockchains such as Ethereum or Solana, keep these Hyl\u00e9 characteristics in mind.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#no-evm-or-execution-layer","title":"No EVM or execution layer","text":"

Hyl\u00e9 does not include a Virtual Machine.

There is no dedicated execution engine or specific programming language (like Solidity) you should use.

Our approach is simple: onchain, we verify zero-knowledge proofs natively. Offchain, you do everything else the way you prefer. This gives you higher throughput, faster finality, and lower gas fees.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#minimal-onchain-state","title":"Minimal onchain state","text":"

The network maintains proofs of state transitions rather than the entire onchain state.

Transactions on Hyl\u00e9 verify and settle transitions without storing full intermediary states onchain.

This architecture reduces storage overhead and promotes scalability while maintaining trustlessness.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#no-wallets","title":"No wallets","text":"

Stop asking yourself, \u00abWhich wallet do I use? How do I bridge? \u00bb. With Hyl\u00e9, there are no wallets and no bridges \u2212 any identity source that can be attested with a zero-knowledge proof is a valid identity.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#every-app-is-a-rollup","title":"Every app is a rollup","text":"

On Hyl\u00e9, there is one general-purpose blockchain, and every app is its own based ZK-rollup, removing the problems associated with fragmentation.

An app\u2019s transactions are sequenced directly on the Hyl\u00e9 base layer. They are split into a blob transaction, which allows for pipelined proving, and a proof transaction to store the state commitment onchain.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#privacy-is-built-in","title":"Privacy is built-in","text":"

Unlike Ethereum, where privacy solutions must be implemented on top of the platform, Hyl\u00e9 integrates privacy features natively.

The proof is public, but your inputs don't need to be, as execution happens offchain.

"},{"location":"concepts/identity/","title":"Identity management","text":""},{"location":"concepts/identity/#identity-management","title":"Identity management","text":"

Identity in traditional blockchains is often tied to a single wallet address, which limits flexibility and privacy.

Hyl\u00e9 introduces a proof-based identity model. Instead of relying on fixed addresses or centralized registries, your application can use cryptographic proofs of identity.

This approach allows users to authenticate with any identity source: meet users where they are and don't worry about onboarding and clunky wallets!

"},{"location":"concepts/identity/#choosing-an-identity-source","title":"Choosing an identity source","text":"

On Hyl\u00e9, any smart contract can be used as a proof of identity. This flexibility enables you to register your preferred identity source as a smart contract for account authentication.

Here are some important aspects of identity contracts:

A safe Identity provider should sign the whole blob transaction to ensure that the blobs have been approved by the user. One way of doing it is to let the user sign the blobs they agree to execute. The identity contract will then check that all the transaction's blobs are signed.

If you don't want to create a custom identity source for early development, Hyl\u00e9 provides a native hydentity contract. This contract is not secure and must not be used in production.

"},{"location":"concepts/identity/#how-hyle-processes-identity-proofs","title":"How Hyl\u00e9 processes identity proofs","text":"

As explained in our transactions concept page, a BlobTransaction on Hyl\u00e9 can include multiple blobs. One of these blobs must be an identity claim.

"},{"location":"concepts/identity/#custom-identity-contracts","title":"Custom identity contracts","text":"

Applications on Hyl\u00e9 can implement custom identity verification rules through smart contracts. A typical identity contract includes two core functions, as shown in our identity quickstart:

Applications can use this structure or define their own identity workflows as needed.

"},{"location":"concepts/pipelined-proving/","title":"Pipelined proving","text":""},{"location":"concepts/pipelined-proving/#pipelined-proving","title":"Pipelined proving","text":""},{"location":"concepts/pipelined-proving/#the-problem-base-state-conflicts","title":"The problem: base state conflicts","text":"

The Hyl\u00e9 base layer ensures both privacy and scalability by verifying only the state transitions of smart contracts, rather than re-executing them. This approach reduces computational overhead but introduces a critical issue for provable applications: base state conflicts.

An app with a lot of usage will see conflicting operations, where multiple transactions reference the same base state, waiting for the previous state change to be settled.

The time spent generating proofs delays transaction finality. Proofs require accurate timestamps, but users can't predict when their transaction will be sequenced.

This causes parallelization limits: multiple transactions may reference the same base state, creating invalid proofs when one is settled before the other.

We solve these issues by splitting sequencing from settlement; an operation includes two transactions.

"},{"location":"concepts/pipelined-proving/#blob-and-proof-transactions","title":"Blob- and proof-transactions","text":"

Read more on the content of blob and proof transactions on our transaction page.

To address base state conflicts, Hyl\u00e9 splits operations into two transactions:

  1. Blob-transaction: outlines a state change for sequencing.
  2. Proof-transaction: provides a proof of the state change for settlement.

From Hyl\u00e9\u2019s perspective, the blob-transaction's content does not matter: it simply represents incoming information that your contract will process. For a developer, sequencing provides you with a fixed order and timestamp before proving begins. Once the transactions are sequenced, the provers can easily know upon which state they should base their proof. As a developer, you can also decide on how much information is disclosed in your blob-transaction: this is app-specific.

Settlement happens when the corresponding proof transaction is verified and added to a block. During settlement, unproven blob transactions linked to the contract are executed in their sequencing order.

This separation solves all three issues shown above. The blob transaction immediately reserves a place in execution order, allowing proof generation to run without blocking other transactions. The sequencing provides an immutable timestamp, so provers know which base state to use when generating proofs and can parallelize actions.

"},{"location":"concepts/pipelined-proving/#unprovable-transactions","title":"Unprovable transactions","text":"

Even with pipelined proving, sequenced transactions that never settle can slow down the network.

To remove this risk, Hyl\u00e9 enforces timeouts for blob transactions.

Each blob transaction is assigned a specific time limit for the associated proof to be submitted and verified. Subsequent transactions can proceed without waiting indefinitely.

"},{"location":"concepts/pipelined-proving/#failed-transactions","title":"Failed transactions","text":"

If the proof isn't submitted before timeout, or if the submitted proof is invalid, the transaction is included in the block, marked as Rejected, and is ignored for state updates.

The inclusion of the unproven transaction in the block ensures transparency, as the transaction data remains accessible.

"},{"location":"concepts/proof-composability/","title":"Proof composition","text":""},{"location":"concepts/proof-composability/#proof-composition","title":"Proof composition","text":"

Note

To understand proof composition in practice, check out our quickstart example.

"},{"location":"concepts/proof-composability/#the-problem-clunky-interactions","title":"The problem: clunky interactions","text":"

In zero-knowledge systems, interactions between different proofs introduce complexity.

Cross-contract interactions require recursive proof verification, where Program A verifies proof of the correct execution of Program B. This is inefficient and creates overhead at the proof generation and verification stages.

The challenge becomes even greater when you start involving proofs that use different schemes.

Most zero-knowledge systems force you to write your proofs in a unified scheme. By doing that, you lose all the advantages of specialization.

Different proving schemes meet different needs. Some proof systems are best for client-side proving; others allow developers to use general-purpose programming languages.

We solve this issue by allowing for native proof composition between contracts and proving schemes. Now, proofs interact seamlessly, and each one can be written in the language that works best.

"},{"location":"concepts/proof-composability/#the-solution-proof-composition","title":"The solution: proof composition","text":""},{"location":"concepts/proof-composability/#cross-contract-calls-with-proof-composition","title":"Cross-contract calls with proof composition","text":"

Proof composability means that Hyl\u00e9 enables these interactions while keeping each proof independent; proof composition is the action enabled by composability.

Hyl\u00e9 gets rid of recursion by allowing Program A to specify: \u00abThis only applies if all blobs in this operation are valid \u00bb. At settlement, both proofs are included in the same proof transaction. Hyl\u00e9 verifies them together, and the entire operation fails if any proof fails.

This solution improves developer experience, lowers gas costs, and shortens proving time.

"},{"location":"concepts/proof-composability/#proofs-using-different-schemes","title":"Proofs using different schemes","text":"

Since proofs in Hyl\u00e9 remain independent, you can batch multiple proofs within a single transaction, each using its optimal proving scheme.

Proofs are verified separately, eliminating the need to compromise for compatibility. This also enables cross-contract calls between applications using different proof systems.

"},{"location":"concepts/proof-composability/#when-to-use-proof-composition","title":"When to use proof composition","text":"

Proof composition is useful if:

It has no effect if your operation's entire logic is in one single proof.

"},{"location":"concepts/proof-composability/#writing-a-cross-contract-call","title":"Writing a cross-contract call","text":"

Your program doesn't need to verify another program\u2019s execution directly. Instead, it references the external contract using a structured claim, such as:

MoneyApp::transfer(10, A, B) == true\nTicketApp::get(A) == ticket\n

Each claim consists of:

In our quickstart example, the source code looks like this.

"},{"location":"concepts/proof-composability/#how-hyle-settles-multiple-proofs","title":"How Hyl\u00e9 settles multiple proofs","text":"

When you submit multiple proofs to Hyl\u00e9, proof generation can be parallelized.

Thanks to pipelined proving, proof verification is asynchronous. Proving times do not compound since proofs do not depend on each other, allowing proof generation to be parallelized.

As soon as one proof is ready, it can be verified on Hyl\u00e9, even if the other proofs aren't ready yet.

Once all proofs related to the transaction are verified, the transaction is settled on Hyl\u00e9. If one proof verification fails, then the entire transaction fails. If a proof times out, the transaction fails when the timeout occurs.

"},{"location":"concepts/proof-generation/","title":"Proof generation and submission","text":""},{"location":"concepts/proof-generation/#proof-generation-and-submission","title":"Proof generation and submission","text":"

Hyl\u00e9 allows you to build unchained applications by leveraging zero-knowledge proofs. They allow you to avoid onchain execution, guarantee privacy, and customize your application while maintaining composability with other smart contracts.

With Hyl\u00e9, generate your proof wherever you prefer, then send it for native onchain verification and settlement. This process enables scalable, modular applications with customizable proving schemes.

If you're a complete beginner with zero-knowledge proofs, our no-code introduction might help.

"},{"location":"concepts/proof-generation/#generating-zero-knowledge-proofs-for-hyle","title":"Generating zero-knowledge proofs for Hyl\u00e9","text":""},{"location":"concepts/proof-generation/#choose-what-you-prove","title":"Choose what you prove","text":"

Each application defines its proof logic. This means that each application developer can decide what information gets proven: for Hyl\u00e9, proof settlement is a Success or a Failure. You define what that means for your app.

Each app developer also defines what the public and private inputs of their app will be: what information should remain private and what should go onchain?

"},{"location":"concepts/proof-generation/#how-to-generate-a-zero-knowledge-proof","title":"How to generate a zero-knowledge proof","text":"

There are many ZK languages. Hyl\u00e9 aims to verify as many as possible.

DSLs, like Circom, are specific languages that usually compile down to a specific circuit. They're good, but they're complex and may have a high learning curve.

zkVMs prove the correct execution of arbitrary code. They allow you to build ZK applications in a certain language without having to build a circuit around it. There are two main types of zkVMs: Cairo and RISC-V. You can benchmark your Rust code and find the best zkVM for your needs with the any-zkvm template.

Each application can generate its proof in whichever place fits best.

Pros Cons When to use Client-side (browser, mobile app) Maximum privacyData ownership Requires robust client-side hardware Personal data that should remain private External prover or proving market No client-side costs or constraintsOffload proof generation to the experts Requires trusting the external prover with your inputs Resource-intensive and not privacy-sensitive proofs By the application itself Simple UXNo dependenciesCode can be private Higher infrastructure needsPotential liveness issue Confidential or centralized applications"},{"location":"concepts/proof-generation/#our-supported-proving-schemes","title":"Our supported proving schemes","text":"

Proving schemes are the cryptographic protocols that make zero-knowledge proofs usable. We support as many as we can, giving you the flexibility to choose the most suitable protocol for your specific use case.

We've written templates for some of our supported programs. Clone them to get started with smart contract writing.

| Proving scheme | Template | |----------------||---| | Noir | - | | Risc0 | Template | | SP1 | Template |

We also verify these natively, without the need for a ZK proof.

We will support more types, including Cairo-based zkVMs and DSLs, in the future, and plan to support all major proving schemes eventually. The next proving schemes we're aiming to support are Cairo via Stwo and Groth16.

"},{"location":"concepts/proof-generation/#our-proof-generation-partners","title":"Our proof generation partners","text":"

If you choose to work with an external prover or proving market, you can choose from one of our partners in that area and benefit from a better Hyl\u00e9 integration.

We recommend checking out Electron, Fermah, Kakarot, Marlin, Nexus, Nodekit, ZEROBASE, or zkCloud.

"},{"location":"concepts/proof-generation/#submitting-a-proof-to-hyle","title":"Submitting a proof to Hyl\u00e9","text":"

Read more about the transaction lifecycle on our transactions overview.

First, your application sends a blob transaction to Hyl\u00e9.

Thanks to pipelined proving, once a transaction is submitted, it is sequenced.

You can then start generating your proof using the sequenced virtual base state as the base state for your operation. Read our quickstart for a concrete example of how to prove a transaction.

Once sent, the proof goes through Hyl\u00e9\u2019s native verification, removing the need for verifier contracts.

Once verified, the proof is settled onchain. Use this settled state to update your app accordingly outside of Hyl\u00e9.

"},{"location":"concepts/proof-generation/#external-resources","title":"External resources","text":""},{"location":"concepts/smart-contracts/","title":"Smart contracts","text":""},{"location":"concepts/smart-contracts/#smart-contracts","title":"Smart contracts","text":"

Hyl\u00e9 is a fully programmable blockchain designed for efficient data storage. Hyl\u00e9 only keeps the essential information needed to validate smart contract proofs, ensuring that smart contracts are lightweight and performant.

Unlike traditional blockchains, which store all smart contract data onchain, Hyl\u00e9 separates execution data (managed offchain by each application) from onchain data, which can be retrieved via our ABI.

"},{"location":"concepts/smart-contracts/#onchain-smart-contract-data","title":"Onchain smart contract data","text":"

Hyl\u00e9 smart contracts store the following data onchain:

"},{"location":"concepts/smart-contracts/#explanation-of-the-contract-fields","title":"Explanation of the contract fields","text":""},{"location":"concepts/smart-contracts/#name","title":"Name","text":"

The contract name must be unique.

"},{"location":"concepts/smart-contracts/#verifier-and-program-id","title":"Verifier and program ID","text":"

Smart contracts on Hyl\u00e9 rely on a pairing of a zero-knowledge proof scheme (verifier) and a program identifier. Together, these components validate contract proofs.

We've written templates for some of our supported programs. Clone them to get started with smart contract writing.

Proving scheme Verifier Program ID Noir noir Verification key. Risc0 risc0 Image ID without a prefix. ex. 0x123 becomes 123. SP1 sp1 Verification key."},{"location":"concepts/smart-contracts/#state-digest","title":"State digest","text":"

The state digest represents the contract's current state commitment. It allows Hyl\u00e9 to guarantee its integrity. It can take any form as long as it fulfills this purpose.

The state digest can be expressed as a hash or even a serialization of the state if it's small enough.

"},{"location":"concepts/smart-contracts/#smart-contract-abi","title":"Smart contract ABI","text":"

All inputs in Hyl\u00e9 smart contracts must be known at proof generation time. This includes elements like the tx_hash which are typically available only at execution time on other blockchains.

Here is the Rust structure specifying the output of a Hyl\u00e9 smart contract:

pub struct HyleOutput {\n    pub version: u32,\n    pub initial_state: StateDigest,\n    pub next_state: StateDigest,\n    pub identity: Identity,\n    pub index: BlobIndex,\n    pub blobs: Vec<u8>,\n    pub tx_hash: TxHash,\n    pub success: bool,\n    pub tx_ctx: Option<TxContext>,\n    pub registered_contracts: Vec<RegisterContractEffect>,\n    pub program_outputs: Vec<u8>, \n}\n
"},{"location":"concepts/smart-contracts/#version","title":"Version","text":"

For now, version should always be set to 1.

"},{"location":"concepts/smart-contracts/#initial-state-and-next-state","title":"Initial state and next state","text":"

These fields define state transitions.

In the future, state_digest size will be limited and fees will depend on proof size (which is affected by the digest's size). Keep them small!

"},{"location":"concepts/smart-contracts/#identity","title":"Identity","text":"

Info

Read our identity documentation for details.

Identity consists of:

  1. An identifier;
  2. The name of the contract that the proof was generated for.

Example

A contract verifying Ethereum EOAs might have an identity like 0x1234...5678.eth_eoa where the first part matches a regular Ethereum address and eth_eoa is the name of the contract.

"},{"location":"concepts/smart-contracts/#blob-index-and-blobs","title":"Blob index and blobs","text":"

Each blob transaction includes multiple blobs:

"},{"location":"concepts/smart-contracts/#tx-hash","title":"TX Hash","text":"

tx_hash is the blob Transaction's hash.

The protocol does not validate this field and tx_hash may be deprecated in later versions.

"},{"location":"concepts/smart-contracts/#success","title":"Success","text":"

This boolean field indicates whether the proof is for a successful or failed transactions. It can be used to prove that a transaction is invalid.

If a proof returns success = false, the whole blob transaction will fail. In that case, there is no need to generate proofs for other blobs.

"},{"location":"concepts/smart-contracts/#transaction-context","title":"Transaction context","text":"

Transaction context allows the contract to know in which block (hash, height, timestamp) the blob transaction has been sequenced.

This field is optional. If left empty, it will not be validated by Hyl\u00e9 or usable by the program.

"},{"location":"concepts/smart-contracts/#registered-contracts","title":"Registered contracts","text":"

A list of new contracts to register, which can be used to self-upgrade a contract.

"},{"location":"concepts/smart-contracts/#other-program-specific-outputs","title":"Other program-specific outputs","text":"

Smart contracts can generate additional outputs as proof data. These outputs ensure data availability.

"},{"location":"concepts/smart-contracts/#events","title":"Events","text":"

Hyl\u00e9 does not use traditional events. Instead, it relies on blobs, which serve as containers for offchain data.

"},{"location":"concepts/transaction/","title":"Transactions on Hyl\u00e9","text":""},{"location":"concepts/transaction/#transactions-on-hyle","title":"Transactions on Hyl\u00e9","text":"

Hyl\u00e9 introduces a novel transaction model that separates intent from proof, optimizing for scalability and privacy.

Unlike traditional blockchains, where transactions are executed and proven in a single step, Hyl\u00e9 employs a two-step process called pipelined proving:

  1. Blob-transaction: outlines a state change for sequencing.
  2. Proof-transaction: provides a proof of the state change for settlement.

Each proof transaction verifies a single blob, unless you use recursion. If a blob transaction contains multiple blobs, each requires a separate proof.

Once all blobs are proven, the blob transaction is settled, and the referenced contract states are updated.

"},{"location":"concepts/transaction/#blob-transaction-structure","title":"Blob transaction structure","text":"

A blob transaction consists of:

"},{"location":"concepts/transaction/#proof-transaction-structure","title":"Proof transaction structure","text":"

A proof transaction includes:

For Risc0 and SP1, the proof data's smart contract output follows HyleOutput as defined in the smart contract ABI.

"},{"location":"concepts/transaction/#example-token-transfer","title":"Example: token transfer","text":"

A token transfer involves two blobs in a blob transaction:

Each blob requires a corresponding proof transaction.

"},{"location":"concepts/transaction/#blob-transaction","title":"Blob transaction","text":"
{\n    \"identity\": \"bob.hydentity\",\n    \"blobs\": [\n        {\n            \"contract_name\": \"hydentity\",\n             // Binary data for the operation of hydentity contract\n             // VerifyIdentity { account: \"bob.hydentity\", nonce: \"2\" }\n            \"data\": \"[...]\" \n        },\n        {\n            \"contract_name\": \"hyllar\",\n             // Binary data for the operation of hyllar contract\n             // Transfer { recipient: \"alice.hydentity\", ammount: \"20\" }\n            \"data\": \"[...]\"\n        }\n    ]\n}\n
"},{"location":"concepts/transaction/#proof-transactions","title":"Proof transactions","text":""},{"location":"concepts/transaction/#identity-proof","title":"Identity proof","text":"
{\n    \"contract_name\": \"hydentity\",\n    \"proof\": \"[...]\"\n}\n

The binary proof's output includes:

and

{\n    \"contract_name\": \"hyllar\",\n    \"proof\": \"[...]\"\n}\n

The binary proof's output includes:

"},{"location":"quickstart/","title":"\ud83c\udfc1 Quickstart","text":""},{"location":"quickstart/#quickstart","title":"Quickstart","text":"

Welcome to the Quickstart guide for Hyl\u00e9.

It uses several examples to help you start building as soon as possible.

Run your local devnet

Where it all begins.

Create your first smart contract

In just a couple of lines, create and register your first smart contract.

Walk through a full example

Check out a ticket app based on a token and simple identity contract.

"},{"location":"quickstart/devnet/","title":"Run your local devnet","text":""},{"location":"quickstart/devnet/#run-your-local-devnet","title":"Run your local devnet","text":""},{"location":"quickstart/devnet/#recommended-run-from-source","title":"Recommended: Run from source","text":"

For a single-node devnet (consensus disabled) with an indexer, clone the hyle repository and run:

cargo run -- --pg\n

This command starts a temporary PostGreSQL server and erases its data when you stop the node. For persistent storage, start a standalone PostgreSQL instance:

# Start PostgreSQL with default configuration:\ndocker run -d --rm --name pg_hyle -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres\n

Then, navigate to the Hyl\u00e9 root and run:

cargo run\n
"},{"location":"quickstart/devnet/#alternative-start-with-docker","title":"Alternative: Start with Docker","text":"

Use Docker to run a local node. Note that the devnet is unstable and may break with future updates.

"},{"location":"quickstart/devnet/#pull-the-docker-image","title":"Pull the Docker image","text":"
docker pull ghcr.io/hyle-org/hyle:v0.12.1\n
"},{"location":"quickstart/devnet/#run-the-docker-container","title":"Run the Docker container","text":"
docker run -v ./data:/hyle/data -p 4321:4321 ghcr.io/hyle-org/hyle:v0.12.1\n

If you run into an error, try adding the --privileged flag:

docker run --privileged -v ./data:/hyle/data -p 4321:4321 ghcr.io/hyle-org/hyle:v0.12.1\n

To run with an indexer, add the parameter -e HYLE_RUN_INDEXER=true and set up a running PostGreSQL server with Docker:

docker run -d --rm --name pg_hyle -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres\n

And the node linked to it:

docker run -v ./data:/hyle/data \\\n    -e HYLE_RUN_INDEXER=true \\\n    -e HYLE_DATABASE_URL=postgres://postgres:postgres@pg_hyle:5432/postgres \\\n    --link pg_hyle \\\n    -p 4321:4321 \\\n    ghcr.io/hyle-org/hyle:v0.7.2\n

You can now create your first smart contract.

Tip

To reset your devnet, delete the ./data folder and restart from Step 1. Otherwise, you risk re-registering a contract that still exists.

"},{"location":"quickstart/devnet/#alternative-build-the-docker-image-locally","title":"Alternative: Build the Docker image locally","text":"

If you prefer to build the image from source, run:

docker build -t Hyle-org/hyle . && docker run -dit Hyle-org/hyle\n
"},{"location":"quickstart/devnet/#configuration","title":"Configuration","text":"

You can configure your setup using environment variables or by editing a configuration file.

"},{"location":"quickstart/devnet/#using-environment-variables","title":"Using environment variables","text":"

All variables can be customized on your single-node instance.

Variable Default value Description HYLE_ID node Node identifier in the consensus. Usage subject to change in future releases. HYLE_SINGLE_NODE true Whether the network runs as a single node or with a multi-node consensus. HYLE_P2P_LISTEN true Mandatory (true) if multi-node consensus. The node should listen to new peers. HYLE_HOST 127.0.0.1:1231 Host & port to listen for the P2P protocol. HYLE_PEERS [] List of peers to connect to at startup to follow a running consensus. HYLE_STORAGE__INTERVAL 10 unused HYLE_LOG_FORMAT full \u201cfull\u201d or \u201cjson\u201d HYLE_REST 127.0.0.1:4321 Host & port for the REST API endpoint. HYLE_DATA_DIRECTORY data_node Directory name to store node state. HYLE_DATABASE_URL postgres://postgres:postgres @localhost:5432/postgres PostgreSQL server address (necessary if you want to use an indexer). HYLE_CONSENSUS__SLOT_DURATION 1000 Duration between blocks. HYLE_CONSENSUS__GENESIS_STAKERS {} Keys are all nodes \u201cid\u201d, and values are the stake amount for each one of them. Map of stakers for the genesis block. HYLE_P2P__PING_INTERVAL 10 Interval the p2p layer does a ping to check aliveness of other peers. HYLE_RUN_INDEXER true Whether there should be an indexer. HYLE_DA_ADDRESS 127.0.0.1:4141 Host & port of the data availability module, which streams historical & new blocks. It might be used by indexers."},{"location":"quickstart/devnet/#using-a-configuration-file","title":"Using a configuration file","text":"

To load settings from a file, place config.ron in your node's working directory. It will be detected automatically at startup.

For Docker users, mount the config file when running the container:

docker run -v ./data:/hyle/data -v ./config.run:/hyle/config.ron -e HYLE_RUN_INDEXER=false -p 4321:4321 -p 1234:1234 ghcr.io/hyle-org/hyle:v0.12.1\ncp ./src/utils/conf_defaults.ron config.ron\n

For source users, copy the default config template:

cp ./src/utils/conf_defaults.ron config.ron\n
"},{"location":"quickstart/your-first-smart-contract/","title":"Your first smart contract","text":""},{"location":"quickstart/your-first-smart-contract/#your-first-smart-contract","title":"Your first smart contract","text":"

Tip

Check our example walkthrough for more!

"},{"location":"quickstart/your-first-smart-contract/#step-1-clone-a-template","title":"Step 1: Clone a template","text":"

We support several proving schemes and provide templates for the following:

Clone the template or, for proving schemes without templates, use the templates as inspiration for writing your contract. You can also check our smart contract concept page for more information!

"},{"location":"quickstart/your-first-smart-contract/#step-2-edit-your-contract","title":"Step 2: Edit your contract","text":"

Navigate to the contract/ folder and edit your contract as necessary.

"},{"location":"quickstart/your-first-smart-contract/#step-3-register-your-contract","title":"Step 3: Register your contract","text":"

On the devnet, register your contract by running:

cargo run -- register-contract\n
"},{"location":"quickstart/example/","title":"Example walkthrough","text":""},{"location":"quickstart/example/#example-walkthrough","title":"Example walkthrough","text":"

Here's a step-by-step walkthrough of an example.

Run your local devnet

Where it all begins.

Create your first smart contract

Understand how smart contracts work on Hyl\u00e9 with our simple-token example.

Use an identity contract

Every contract can be an identity on Hyl\u00e9. Try it out with our simple-identity example.

Call several contracts in one transaction

Use cross-contract proof composition to buy a simple-ticket with a simple-token.

"},{"location":"quickstart/example/custom-identity-contract/","title":"Using a custom identity contract","text":""},{"location":"quickstart/example/custom-identity-contract/#using-a-custom-identity-contract","title":"Using a custom identity contract","text":""},{"location":"quickstart/example/custom-identity-contract/#when-to-use-identity-contracts-on-hyle","title":"When to use identity contracts on Hyl\u00e9","text":"

On Hyl\u00e9, any smart contract can be a proof of identity. This flexibility enables you to register your preferred identity source as a smart contract for account identification. If you don't want to use a custom identity source, Hyl\u00e9 ships a native hydentity contract.

This guide walks you through creating and deploying your first simple identity contract using Hyl\u00e9 and RISC Zero. We'll use our simple identity example, which mirrors our simple token transfer example.

If you\u2019re new to identity management on Hyl\u00e9, read the identity management concept page.

"},{"location":"quickstart/example/custom-identity-contract/#run-the-example","title":"Run the example","text":"

Warning

Our examples work on Hyl\u00e9 v0.12.1. Later versions may introduce breaking changes which have not yet been reflected in our examples.

Info

Jump to Code Snippets for an in-depth look at the contract.

"},{"location":"quickstart/example/custom-identity-contract/#prerequisites","title":"Prerequisites","text":""},{"location":"quickstart/example/custom-identity-contract/#build-and-register-the-identity-contract","title":"Build and register the identity contract","text":"

To build all methods and register the smart contract on the local node from the source, navigate to your cloned Examples folder and run:

cargo run -- register-contract\n

The expected output is \ud83d\udcdd Registering new contract simple_identity.

"},{"location":"quickstart/example/custom-identity-contract/#register-an-account-sign-up","title":"Register an account (sign up)","text":"

To register an account with a username (alice) and password (abc123), execute:

cargo run -- register-identity alice.simple_identity abc123\n

Expected log output:

INFO hyle::data_availability::node_state::verifiers: \u2705 Risc0 proof verified.\nINFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Successfully registered identity for account: alice.simple_identity\n
"},{"location":"quickstart/example/custom-identity-contract/#verify-identity-login","title":"Verify identity / Login","text":"

To verify alice's identity:

cargo run -- verify-identity alice.simple_identity abc123 0\n

This command:

  1. Sends a blob transaction to verify alice's identity.
  2. Generates a ZK proof of that identity. It will only be valid once, thus the inclusion of a nonce.
  3. Sends the proof to the devnet.

Upon reception of the proof, the node will:

  1. Verify the proof.
  2. Settle the blob transaction.
  3. Update the contract's state.

Expected log output:

INFO hyle::data_availability::node_state::verifiers: \u2705 Risc0 proof verified.\nINFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Identity verified for account: alice.simple_identity\n
"},{"location":"quickstart/example/custom-identity-contract/#development-mode","title":"Development mode","text":"

We recommend activating dev-mode during your early development phase for faster iteration upon code changes with -e RISC0_DEV_MODE=1.

You may also want to get insights into the execution statistics of your project: add the environment variable RUST_LOG=\"[executor]=info\" before running your project.

The full command to run your project in development mode while getting execution statistics is:

RUST_LOG=\"[executor]=info\" RISC0_DEV_MODE=1 cargo run\n
"},{"location":"quickstart/example/custom-identity-contract/#code-snippets","title":"Code snippets","text":"

Find the full annotated code in our examples repository.

"},{"location":"quickstart/example/custom-identity-contract/#registering-the-contract","title":"Registering the contract","text":"

This part is the same as for Your first smart contract.

"},{"location":"quickstart/example/custom-identity-contract/#register-an-identity","title":"Register an identity","text":""},{"location":"quickstart/example/custom-identity-contract/#build-the-blob-transaction","title":"Build the blob transaction","text":"

This is a simplified code snippet:

let action = RegisterIdentity {\n    account: identity,\n};\nlet blob = sdk::Blob {\n    contract_name: contract_name,\n    data: action.as_blob_data(), // Note: This function does not exist. Used here for clarity\n};\nlet blob_tx = BlobTransaction {\n    identity: identity,\n    blobs: vec![blob],\n};\n

You can compare these to the fields described in the Transactions on Hyl\u00e9 page.

"},{"location":"quickstart/example/custom-identity-contract/#prove-the-registration","title":"Prove the registration","text":""},{"location":"quickstart/example/custom-identity-contract/#on-the-backend-host-side","title":"On the backend (host) side","text":"

Hyl\u00e9 transactions follow a two-step settlement process based on pipelined proving principles:

  1. Sending the blob transaction: The transaction is sequenced but not yet settled.
  2. Proving the transaction: The transaction is settled after a proof is generated.

To generate the proof, we build the contract input, specifying:

// Build the contract input\nlet inputs = ContractInput {\n    initial_state: initial_state.as_digest(),\n    identity: blob_tx.identity,\n    tx_hash: blob_tx_hash,\n    private_blob: sdk::BlobData(password),\n    blobs: blobs,\n    index: sdk::BlobIndex(0),\n};\n
"},{"location":"quickstart/example/custom-identity-contract/#on-the-contract-guest-side","title":"On the contract (guest) side","text":"

These inputs are then processed by the SDK to initialize the contract :

    // Parse contract inputs\n    let (input, action) = sdk::guest::init_raw::<IdentityAction>();\n

The password is extracted as a private input:

    // Extract private information\n    let password = from_utf8(&input.private_blob.0).unwrap();\n

The contract processes the identity registration:

    // We clone the initial state to be updated\n    let mut next_state: Identity = input.initial_state.clone();\n\n    // Execute the given action\n    let res = sdk::identity_provider::execute_action(&mut next_state, action, password);\n

Finally, the contract commits the updated state:

    sdk::guest::commit(input, next_state, res);\n

The guest::commit function includes the HyleOutput, as explained in Transactions on Hyl\u00e9.

"},{"location":"quickstart/example/custom-identity-contract/#verify-an-identity","title":"Verify an identity","text":"

The identity verification process is identical to identity registration, with a different action:

let action = VerifyIdentity {\n    account: identity,\n    nonce,\n};\n

Check the full annotated code in our GitHub example.

"},{"location":"quickstart/example/first-token-contract/","title":"Your first token contract","text":""},{"location":"quickstart/example/first-token-contract/#your-first-token-contract","title":"Your first token contract","text":"

This guide will walk you through creating and deploying your first token transfer contract using Hyl\u00e9's tools and infrastructure. We'll use our simple-token transfer example as the basis for this tutorial.

For an alternative implementation, check out the same example built with SP1.

If you\u2019re new to smart contracts on Hyl\u00e9, read the anatomy of a smart contract.

"},{"location":"quickstart/example/first-token-contract/#example","title":"Example","text":"

Warning

Our examples work on Hyl\u00e9 v0.12.1. Later versions may introduce breaking changes that are not yet reflected in our examples.

"},{"location":"quickstart/example/first-token-contract/#prerequisites","title":"Prerequisites","text":""},{"location":"quickstart/example/first-token-contract/#quickstart","title":"Quickstart","text":""},{"location":"quickstart/example/first-token-contract/#build-and-register-the-contract","title":"Build and register the contract","text":"

To build all methods and register the smart contract from the source, navigate to your cloned Examples folder and run:

cargo run -- register 1000\n

The expected output is \ud83d\udcdd Registering new contract simple_token.

"},{"location":"quickstart/example/first-token-contract/#transfer-tokens","title":"Transfer tokens","text":"

Transfer 2 tokens from the Hyl\u00e9 faucet to Bob:

cargo run -- transfer faucet.simple_token bob.simple_token 2\n

This command:

  1. Sends a blob transaction to transfer 2 tokens from faucet to bob. To better understand what a blob transaction is, read more about transactions on Hyl\u00e9.
  2. Generates a ZK proof for the transfer.
  3. Sends the proof to the devnet for verification. (Scroll down to see what that looks like in code.)
"},{"location":"quickstart/example/first-token-contract/#verify-settled-state","title":"Verify settled state","text":"

Upon reception of the proof, the node will:

  1. Verify the proof
  2. Settle the blob transaction
  3. Update the contract's state

Expected log output:

INFO hyle::data_availability::node_state::verifiers: \u2705 Risc0 proof verified.\nINFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Transferred 2 to bob.simple_token\n

On the following slot:

INFO hyle::data_availability::node_state: Settle tx TxHash(\"[..]\")\n
"},{"location":"quickstart/example/first-token-contract/#check-onchain-balance","title":"Check onchain balance","text":"

Verify onchain balances:

cargo run -- balance faucet.simple_token\ncargo run -- balance bob.simple_token\n

Note

In this example, we do not verify the identity of the person who initiates the transaction. We use .simple_token as a suffix for the \"from\" and \"to\" transfer fields, but the correct identity scheme should be used in production.

See your contract's state digest at: https://hyleou.hyle.eu/contract/$CONTRACT_NAME.

See your transaction on Hyl\u00e9's explorer: https://hyleou.hyle.eu/tx/$TX_HASH.

"},{"location":"quickstart/example/first-token-contract/#development-mode","title":"Development mode","text":"

For faster iteration during development, enable dev-mode: -e RISC0_DEV_MODE=1.

To get execution statistics, set: RUST_LOG=\"[executor]=info\" as an environment variable.

To run your project in development mode with logs:

RUST_LOG=\"[executor]=info\" RISC0_DEV_MODE=1 cargo run\n
"},{"location":"quickstart/example/first-token-contract/#annotated-code-snippets","title":"Annotated code snippets","text":"

Find the full annotated code in our examples repository.

Below are key snippets explaining contract registration, blob transactions, and proofs.

"},{"location":"quickstart/example/first-token-contract/#registering-the-contract","title":"Registering the contract","text":"

Set up information about your contract. To register the contract, you'll need:

// Build initial state of contract\nlet initial_state = Token::new(supply, format!(\"faucet.{}\", contract_name).into());\nprintln!(\"Initial state: {:?}\", initial_state);\n\n// Send the transaction to register the contract\nlet register_tx = RegisterContractTransaction {\n    owner: \"examples\".to_string(),\n    verifier: \"risc0\".into(),\n    program_id: sdk::ProgramId(sdk::to_u8_array(&GUEST_ID).to_vec()),\n    state_digest: initial_state.as_digest(),\n    contract_name: contract_name.clone().into(),\n};\nlet res = client\n    .send_tx_register_contract(&register_tx)\n    .await\n    .unwrap()\n    .text()\n    .await\n    .unwrap();\n\nprintln!(\"\u2705 Register contract tx sent. Tx hash: {}\", res);\n

In the explorer, this will look like this:

{\n    \"tx_hash\": \"321b7a4b2228904fc92979117e7c2aa6740648e339c97986141e53d967e08097\",\n    \"owner\": \"examples\",\n    \"verifier\": \"risc0\",\n    \"program_id\":\"e085fa46f2e62d69897fc77f379c0ba1d252d7285f84dbcc017957567d1e812f\",\n    \"state_digest\": \"fd00e876481700000001106661756365742e687964656e74697479fd00e876481700000000\",\n    \"contract_name\": \"simple_token\"\n}\n
"},{"location":"quickstart/example/first-token-contract/#create-blob-transaction","title":"Create blob transaction","text":"
// The action to execute, that will be proved later\nlet action = sdk::erc20::ERC20Action::Transfer {\n    recipient: to.clone(),\n    amount,\n};\n// Into a BlobTransaction to be sent on chain\nlet blobs = vec![sdk::Blob {\n    contract_name: contract_name.clone().into(),\n    data: sdk::BlobData(\n        bincode::encode_to_vec(action, bincode::config::standard())\n            .expect(\"failed to encode BlobData\"),\n    ),\n}];\nlet blob_tx = BlobTransaction {\n    identity: from.into(),\n    blobs,\n};\n\n// Send the blob transaction\nlet blob_tx_hash = client.send_tx_blob(&blob_tx).await.unwrap();\nprintln!(\"\u2705 Blob tx sent. Tx hash: {}\", blob_tx_hash);\n
"},{"location":"quickstart/example/first-token-contract/#prove-the-transaction","title":"Prove the transaction","text":"

Hyl\u00e9 transactions are settled in two steps, following pipelined proving principles. After this step, your transaction is sequenced, but not settled.

For the transaction to be settled, it needs to be proven. You'll start with building the contract input, specifying:

// Build the contract input\nlet inputs = ContractInput::<Token> {\n    initial_state,\n    identity: from.clone().into(),\n    tx_hash: \"\".into(),\n    private_blob: sdk::BlobData(vec![]),\n    blobs: blobs.clone(),\n    index: sdk::BlobIndex(0),\n};\n\n// Generate the zk proof\nlet receipt = prove(cli.reproducible, inputs).unwrap();\n\nlet proof_tx = ProofTransaction {\n    blob_tx_hash,\n    proof: ProofData::Bytes(borsh::to_vec(&receipt).expect(\"Unable to encode receipt\")),\n    contract_name: contract_name.clone().into(),\n};\n\n// Send the proof transaction\nlet proof_tx_hash = client\n    .send_tx_proof(&proof_tx)\n    .await\n    .unwrap()\n    .text()\n    .await\n    .unwrap();\nprintln!(\"\u2705 Proof tx sent. Tx hash: {}\", proof_tx_hash);\n

Check the full annotated code in our GitHub example.

"},{"location":"quickstart/example/proof-composition/","title":"Proof composition with Ticket App","text":""},{"location":"quickstart/example/proof-composition/#proof-composition-with-ticket-app","title":"Proof composition with Ticket App","text":"

Hyl\u00e9 enables proof composition, allowing different proving systems to work within a single operation. This removes constraints on provers and significantly improves interoperability and efficiency.

In this guide, we\u2019ll build a Ticket App that demonstrates proof composition. Users can buy a ticket using simple-token, and Hyl\u00e9 will verify multiple proofs in a single transaction.

Find the source code for all contracts here:

Traditional verification systems often require all proofs to be generated using the same proving system. Hyl\u00e9 removes this limitation, allowing:

"},{"location":"quickstart/example/proof-composition/#how-this-example-works","title":"How this example works","text":"

In this example, Alice and Bob both want to buy a ticket from Ticket App for 15 simple-tokens. Bob has enough tokens to complete the transaction, while Alice does not.

"},{"location":"quickstart/example/proof-composition/#step-1-create-the-blob-transaction","title":"Step 1: Create the blob transaction","text":"

The Ticket App backend creates and sends a blob transaction to Hyl\u00e9, including three blobs:

At this stage, Hyl\u00e9 sequences the transaction, but it\u2019s not yet settled. Read more about pipelined proving.

"},{"location":"quickstart/example/proof-composition/#step-2-prove-the-blobs","title":"Step 2: Prove the blobs","text":"

The Ticket App backend generates ZK proofs of each blob.

The ticket-app contract is executed, checking whether:

At this step, the contract does not verify whether Bob actually has enough tokens: if the token transfer fails in Step 3, the entire transaction fails.

Check out the source code.

"},{"location":"quickstart/example/proof-composition/#step-3-settlement","title":"Step 3: Settlement","text":"

Once TicketApp has sent the proofs for the previously sequenced blobs, Hyl\u00e9 verifies:

If all proofs are valid, the simple-token balance and ticket-app ticket balance are updated simultaneously at transaction settlement: bob.id sends 15 simple-tokens and gains one ticket.

If any proof fails, the entire transaction fails. Neither state is updated: Bob's token balance does not change and he doesn't get a ticket.

"},{"location":"quickstart/example/proof-composition/#run-the-example","title":"Run the example","text":"

Warning

Our examples work on Hyl\u00e9 v0.12.1. Later versions introduce breaking changes which have not yet been reflected in our examples.

"},{"location":"quickstart/example/proof-composition/#prerequisites","title":"Prerequisites","text":"

This quickstart guide will take you through the following steps:

"},{"location":"quickstart/example/proof-composition/#simple-identity-preparation","title":"Simple-identity preparation","text":"

Let's start with registering an identity contract and two identities.

Go to the ./simple-identity folder and run:

cargo run -- --contract-name id register-contract\n

Now we have an identity contract called id. We can use it to declare our users:

cargo run -- --contract-name id register-identity bob.id pass\ncargo run -- --contract-name id register-identity alice.id pass\n

Let's verify it quickly with:

cargo run -- --contract-name id verify bob.id pass 0\n

0 is a nonce: every time we verify successfully bob's identity, it increments. Now if we want to verify it again, we should use 1 as nonce. (We also use \u00ab pass \u00bb as our default password.)

We now do the same for alice:

cargo run -- --contract-name id verify alice.id pass 0\n

bob.id is bob's identity on the simple-identity contract. Check out our Identity management and custom identity contract pages to know more.

"},{"location":"quickstart/example/proof-composition/#simple-token-preparation","title":"Simple-token preparation","text":""},{"location":"quickstart/example/proof-composition/#register-simple-token","title":"Register simple-token","text":"

Go to ./simple-token folder and run:

cargo run -- --contract-name simple-token register 1000\n

On the node's logs, you will see:

\ud83d\udcdd Registering new contract simple_token

You just registered a token contract named simple-token with an initial supply of 1000.

"},{"location":"quickstart/example/proof-composition/#transfer-tokens","title":"Transfer tokens","text":"

Now let's transfer some tokens to our user bob.

To send 50 tokens to bob and 10 tokens to alice, run:

cargo run -- -contract-name simple-token transfer faucet.simple-token bob.id 50\ncargo run -- -contract-name simple-token transfer faucet.simple-token alice.id 10\n

The node's log will show:

INFO hyle::data_availability::node_state::verifiers: \u2705 Risc0 proof verified.

INFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Transferred 50 to bob.ticket_app INFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Transferred 10 to alice.ticket_app

"},{"location":"quickstart/example/proof-composition/#check-onchain-balance","title":"Check onchain balance","text":"

Check onchain balance:

cargo run -- --contract-name simple-token balance faucet.simple-token\n\ncargo run -- --contract-name simple-token balance bob.id\ncargo run -- --contract-name simple-token balance alice.id\n

You should see that bob has a balance of 50 and alice has a balance of 10.

"},{"location":"quickstart/example/proof-composition/#using-ticket-app","title":"Using ticket-app","text":"

Now that bob has some tokens, let's buy him a ticket.

"},{"location":"quickstart/example/proof-composition/#register-ticket-app","title":"Register ticket-app","text":"

Register the ticket app by going to ./ticket-app folder and running:

cargo run -- --contract-name ticket-app register simple-token 15\n

ticket-app sells bob a ticket for 15 simple-token.

"},{"location":"quickstart/example/proof-composition/#buy-a-ticket","title":"Buy a ticket","text":"

Let's buy a ticket for bob:

cargo run -- --contract-name ticket-app --user bob.id buy-ticket\n

Let's try with alice:

cargo run -- --contract-name ticket-app --user alice.id buy-ticket\n

You will get an error while executing the TicketApp program: Execution failed ! Program output: Insufficient balance. This is because Alice has a balance of 10 and the ticket costs 15.

"},{"location":"quickstart/example/proof-composition/#check-ticket-and-token-balance","title":"Check ticket and token balance","text":"

Check that bob has a ticket:

cargo run -- --contract-name ticket-app --user bob.id has-ticket\n

You can also check bob's balance and see he now has 35 tokens.

With proof composition, Hyl\u00e9 empowers you to leverage multiple proving systems in a single transaction, making advanced functionality like the Ticket App easier than ever.

"},{"location":"resources/","title":"\ud83d\udcda Resources","text":""},{"location":"resources/#resources","title":"\ud83d\udcda Resources","text":""},{"location":"resources/find-us/","title":"Find us","text":""},{"location":"resources/find-us/#useful-links","title":"Useful links","text":""},{"location":"resources/find-us/#contact-us","title":"Contact us","text":"

Reach out to the team for more information:

Github Twitter Farcaster LinkedIn Youtube Telegram Hyl\u00e9 @hyle_org @hyle-org Hyl\u00e9 @Hyl\u00e9 @hyle_org"},{"location":"resources/glossary/","title":"Glossary","text":""},{"location":"resources/glossary/#glossary","title":"Glossary","text":"Term Definition Related concept page blob A piece of provable information that is sent to Hyl\u00e9. Smart contracts blob transaction A transaction including a provable blob, used for sequencing. Pipelined proving cross-contract composition The ability to use and verify a contract's proofs in other contracts. Proof composition operation Something that happens on an unchained app. An operation includes two transactions: a blob transaction and a proof transaction. Transactions proof composition The process of combining multiple zero-knowledge proofs into a single proof, enabling efficient verification and interoperability across different proving systems. Proof composition proof transaction A transaction including a proof of a previously-submitted blob, used for verification and settlement. Transactions proof verification The act by which Hyl\u00e9 verifies submitted proofs before settling them onchain. Transactions timeout A time window after which, if no proof transaction has been submitted, an operation fails. Pipelined proving transaction A part of an operation that gets sent to Hyl\u00e9. There are two types of transactions: blob transactions and proof transactions. Transactions unchained app An app that runs offchain and settles onchain, giving it both the Web2 user experience and the security of Web3."},{"location":"resources/grants/","title":"Contribute to Hyl\u00e9","text":""},{"location":"resources/grants/#contribute-to-hyle","title":"Contribute to Hyl\u00e9","text":""},{"location":"resources/grants/#contribution-opportunities","title":"Contribution opportunities","text":"

You can contribute to Hyl\u00e9 in several ways. We are active participants in OnlyDust projects and welcome maintainers.

You can also check out our Careers page for longer-term opportunities.

"},{"location":"resources/grants/#grant-program","title":"Grant program","text":"

We have a grant program supporting developers who want to work on trust infrastructure and programmable cryptography on Hyl\u00e9.

"},{"location":"resources/grants/#what-are-our-grants-like","title":"What are our grants like?","text":"

To read more, see our grant ideas, and apply, please go to our Grants page on the main Hyl\u00e9 repository. If you represent an organization, we'd love to discuss co-grants ideas.

For questions that aren't answered on the Grants page, reach out in our Telegram group.

"},{"location":"resources/grants/#current-and-past-grants","title":"Current and past grants","text":"

Here are two past grants:

Find the full list on our Grants page on the main Hyl\u00e9 repository.

"},{"location":"resources/release-notes/","title":"Release notes","text":""},{"location":"resources/release-notes/#release-notes","title":"Release notes","text":"

Read our full changelogs on GitHub or the short versions in our Telegram group.

"},{"location":"resources/release-notes/#2025-02-24-v0120","title":"2025-02-24 \u2212 v0.12.0","text":"

\ud83d\uddde\ufe0f Our news:

\ud83d\udca5 Breaking changes:

We heard your feedback on our frequent breaking changes. Going forward, we\u2019ll be making fewer releases, relying instead on rc versions, so that breaking changes are batched.

\u2728 New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

"},{"location":"resources/release-notes/#2025-02-14-v0110","title":"2025-02-14 \u2212 v0.11.0","text":"

\u2728 New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

"},{"location":"resources/release-notes/#2025-02-07-v0100","title":"2025-02-07 \u2212 v0.10.0","text":"

\ud83d\udca5 Breaking change: we\u2019ve replaced our serialization standard, bincode, with borsh. Encoding BlobData from JS didn\u2019t work properly with bincode: borsh offers better support and opens new possibilities!

\u2728 New features:

\ud83d\udee0\ufe0f No longer broken:

"},{"location":"resources/release-notes/#2025-02-03-v090","title":"2025-02-03 \u2212 v0.9.0","text":"

\ud83d\udca5 Breaking changes:

\u2728 New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

Quick note: release notes will be published on Fridays instead of Mondays from now on. See you in just a few days!

"},{"location":"resources/release-notes/#2025-01-27-v080","title":"2025-01-27 \u2212 v0.8.0","text":"

\ud83d\udca5 Breaking changes:

\u2728New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

Read the full changelog on GitHub.

"},{"location":"resources/release-notes/#2025-01-21-v071-v072","title":"2025-01-21 \u2212 v0.7.1 & v0.7.2","text":"

Small patches for our SDK.

Read release notes for v0.7.1 and v0.7.2; see new SDK readme for more info.

"},{"location":"resources/release-notes/#2025-01-20-v070","title":"2025-01-20 \u2212 v0.7.0","text":"

\ud83d\udca5 Breaking changes:

\u2728 New features;

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

Read the full changelog on GitHub and receive future release notes in our Telegram group.

"},{"location":"resources/release-notes/#2025-01-13-v060","title":"2025-01-13 \u2212 v0.6.0","text":"

\u2728 New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

Read the full changelog on GitHub and receive future release notes in our Telegram group.

"},{"location":"resources/roadmap/","title":"Roadmap","text":""},{"location":"resources/roadmap/#testnet","title":"Testnet","text":"

We are on our way to launch a private testnet in Q2 2025, which will be followed by a public testnet.

Stay tuned for updates or ask specific questions in our Telegram group.

While we\u2019re working, you can get hands-on right now:

"},{"location":"resources/roadmap/#proving-schemes","title":"Proving schemes","text":"

Check the list of the proving schemes we currently support and the ones we'll work on next.

"},{"location":"tooling/","title":"\ud83e\uddf0 Tooling","text":""},{"location":"tooling/#tooling","title":"Tooling","text":"

Here, you'll find our resources about Hyl\u00e9's tooling.

"},{"location":"tooling/explorer/","title":"Explorer","text":"

Hyl\u00e9ou (a French pun for \"Il est o\u00f9\" or \"Where is it?\") is the blockchain explorer for the Hyl\u00e9 ecosystem.

The explorer is live at hyleou.hyle.eu.

The source code is available on GitHub. We welcome PRs and issues!

"},{"location":"tooling/explorer/#features","title":"Features","text":"

All features are in active development.

"},{"location":"tooling/explorer/#live-features","title":"Live features","text":"

Currently, you can:

"},{"location":"tooling/explorer/#upcoming-features","title":"Upcoming features","text":"

Planned features include:

"},{"location":"tooling/sdk/","title":"SDK","text":""},{"location":"tooling/sdk/#sdk","title":"SDK","text":"

Our contract SDK includes helper functions for building a smart contract on Hyl\u00e9.

Read more: SDK README.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":""},{"location":"#home","title":"Home","text":"

Hyl\u00e9 is the new-generation base layer for the era of unchained applications.

"},{"location":"#navigation","title":"Navigation","text":"

Reach out on Telegram or open an issue if you need assistance or wish to provide feedback on the documentation: we're always looking to improve.

"},{"location":"#useful-links","title":"Useful links","text":""},{"location":"#lets-talk","title":"Let's talk!","text":"

Reach out to the team for more information:

Github Twitter Farcaster LinkedIn Youtube Telegram Hyl\u00e9 @hyle_org @hyle-org Hyl\u00e9 @Hyl\u00e9 @hyle_org"},{"location":"introduction/","title":"Introduction to Hyl\u00e9","text":""},{"location":"introduction/#introduction-to-hyle","title":"Introduction to Hyl\u00e9","text":"

Hyl\u00e9 is the new-generation base layer for the era of unchained applications.

An unchained application runs offchain and settles onchain. It benefits from the Web2 user experience and the security of Web3.

"},{"location":"introduction/#why-choose-hyle","title":"Why choose Hyl\u00e9","text":"

Hyl\u00e9 is built for speed, flexibility, and seamless blockchain integration:

"},{"location":"introduction/#how-hyle-works","title":"How Hyl\u00e9 works","text":"

Here\u2019s what happens when you use Hyl\u00e9\u2019s next-generation base layer:

  1. Sequencing: Send a provable blob of information to Hyl\u00e9: say what information you expect to prove later. We'll sequence the transaction immediately and give you time to prove it. Read more about pipelined proving.
  2. Proof submission: when the proofs for your transaction are ready, send them to Hyl\u00e9.
  3. Verification: Hyl\u00e9 validators receive the transaction. They verify the proofs natively, without the limitations of a bulky virtual machine.
  4. Consensus: if the proofs are valid, Hyl\u00e9 settles your transaction's state onchain. You're good to go!

With this system, execution and storage happen anywhere you like. You only need a fast and trustworthy verifier: that\u2019s Hyl\u00e9.

"},{"location":"concepts/","title":"\ud83d\udca1 Concepts","text":""},{"location":"concepts/#concepts","title":"Concepts","text":"

Welcome to the developer documentation for Hyl\u00e9.

This section includes general documentation topics. You can also refer to our Getting Started step-by-step guide.

"},{"location":"concepts/#hyle-specific-docs-on-industry-concepts","title":"Hyl\u00e9-specific docs on industry concepts","text":""},{"location":"concepts/#hyle-specific-concepts","title":"Hyl\u00e9-specific concepts","text":""},{"location":"concepts/#more","title":"More","text":""},{"location":"concepts/hyle-vs-vintage-blockchains/","title":"Hyl\u00e9 vs. vintage blockchains","text":""},{"location":"concepts/hyle-vs-vintage-blockchains/#hyle-vs-vintage-blockchains","title":"Hyl\u00e9 vs. vintage blockchains","text":"

If you're used to traditional blockchains such as Ethereum or Solana, keep these Hyl\u00e9 characteristics in mind.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#no-evm-or-execution-layer","title":"No EVM or execution layer","text":"

Hyl\u00e9 does not include a Virtual Machine.

There is no dedicated execution engine or specific programming language (like Solidity) you should use.

Our approach is simple: onchain, we verify zero-knowledge proofs natively. Offchain, you do everything else the way you prefer. This gives you higher throughput, faster finality, and lower gas fees.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#minimal-onchain-state","title":"Minimal onchain state","text":"

The network maintains proofs of state transitions rather than the entire onchain state.

Transactions on Hyl\u00e9 verify and settle transitions without storing full intermediary states onchain.

This architecture reduces storage overhead and promotes scalability while maintaining trustlessness.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#no-wallets","title":"No wallets","text":"

Stop asking yourself, \"Which wallet do I use? How do I bridge?\". With Hyl\u00e9, there are no wallets and no bridges \u2212 any identity source that can be attested with a zero-knowledge proof is a valid identity.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#every-app-is-a-rollup","title":"Every app is a rollup","text":"

On Hyl\u00e9, there is one general-purpose blockchain, and every app is its own based ZK-rollup, removing the problems associated with fragmentation.

An app\u2019s transactions are sequenced directly on the Hyl\u00e9 base layer. They are split into a blob transaction, which allows for pipelined proving, and a proof transaction to store the state commitment onchain.

"},{"location":"concepts/hyle-vs-vintage-blockchains/#privacy-is-built-in","title":"Privacy is built-in","text":"

Unlike Ethereum, where privacy solutions must be implemented on top of the platform, Hyl\u00e9 integrates privacy features natively.

The proof is public, but your inputs don't need to be, as execution happens offchain.

"},{"location":"concepts/identity/","title":"Identity management","text":""},{"location":"concepts/identity/#identity-management","title":"Identity management","text":"

Identity in traditional blockchains is often tied to a single wallet address, which limits flexibility and privacy.

Hyl\u00e9 introduces a proof-based identity model. Instead of relying on fixed addresses or centralized registries, your application can use cryptographic proofs of identity.

This approach allows users to authenticate with any identity source: meet users where they are and don't worry about onboarding and clunky wallets!

"},{"location":"concepts/identity/#choosing-an-identity-source","title":"Choosing an identity source","text":"

On Hyl\u00e9, any smart contract can be used as a proof of identity. This flexibility enables you to register your preferred identity source as a smart contract for account authentication.

Here are some important aspects of identity contracts:

A safe Identity provider should sign the whole blob transaction to ensure that the blobs have been approved by the user. One way of doing it is to let the user sign the blobs they agree to execute. The identity contract will then check that all the transaction's blobs are signed.

If you don't want to create a custom identity source for early development, Hyl\u00e9 provides a native hydentity contract. This contract is not secure and must not be used in production.

"},{"location":"concepts/identity/#how-hyle-processes-identity-proofs","title":"How Hyl\u00e9 processes identity proofs","text":"

As explained in our transactions concept page, a BlobTransaction on Hyl\u00e9 can include multiple blobs. One of these blobs must be an identity claim.

"},{"location":"concepts/identity/#custom-identity-contracts","title":"Custom identity contracts","text":"

Applications on Hyl\u00e9 can implement custom identity verification rules through smart contracts. A typical identity contract includes two core functions, as shown in our identity quickstart:

Applications can use this structure or define their own identity workflows as needed.

"},{"location":"concepts/pipelined-proving/","title":"Pipelined proving","text":""},{"location":"concepts/pipelined-proving/#pipelined-proving","title":"Pipelined proving","text":""},{"location":"concepts/pipelined-proving/#the-problem-base-state-conflicts","title":"The problem: base state conflicts","text":"

The Hyl\u00e9 base layer ensures both privacy and scalability by verifying only the state transitions of smart contracts, rather than re-executing them. This approach reduces computational overhead but introduces a critical issue for provable applications: base state conflicts.

An app with a lot of usage will see conflicting operations, where multiple transactions reference the same base state, waiting for the previous state change to be settled.

The time spent generating proofs delays transaction finality. Proofs require accurate timestamps, but users can't predict when their transaction will be sequenced.

This causes parallelization limits: multiple transactions may reference the same base state, creating invalid proofs when one is settled before the other.

We solve these issues by splitting sequencing from settlement; an operation includes two transactions.

"},{"location":"concepts/pipelined-proving/#blob-and-proof-transactions","title":"Blob- and proof-transactions","text":"

Read more on the content of blob and proof transactions on our transaction page.

To address base state conflicts, Hyl\u00e9 splits operations into two transactions:

  1. Blob-transaction: outlines a state change for sequencing.
  2. Proof-transaction: provides a proof of the state change for settlement.

From Hyl\u00e9\u2019s perspective, the blob-transaction's content does not matter: it simply represents incoming information that your contract will process. For a developer, sequencing provides you with a fixed order and timestamp before proving begins. Once the transactions are sequenced, the provers can easily know upon which state they should base their proof. As a developer, you can also decide on how much information is disclosed in your blob-transaction: this is app-specific.

Settlement happens when the corresponding proof transaction is verified and added to a block. During settlement, unproven blob transactions linked to the contract are executed in their sequencing order.

This separation solves all three issues shown above. The blob transaction immediately reserves a place in execution order, allowing proof generation to run without blocking other transactions. The sequencing provides an immutable timestamp, so provers know which base state to use when generating proofs and can parallelize actions.

"},{"location":"concepts/pipelined-proving/#unprovable-transactions","title":"Unprovable transactions","text":"

Even with pipelined proving, sequenced transactions that never settle can slow down the network.

To remove this risk, Hyl\u00e9 enforces timeouts for blob transactions.

Each blob transaction is assigned a specific time limit for the associated proof to be submitted and verified. Subsequent transactions can proceed without waiting indefinitely.

"},{"location":"concepts/pipelined-proving/#failed-transactions","title":"Failed transactions","text":"

If the proof isn't submitted before timeout, or if the submitted proof is invalid, the transaction is included in the block, marked as Rejected, and is ignored for state updates.

The inclusion of the unproven transaction in the block ensures transparency, as the transaction data remains accessible.

"},{"location":"concepts/proof-composability/","title":"Proof composition","text":""},{"location":"concepts/proof-composability/#proof-composition","title":"Proof composition","text":"

Note

To understand proof composition in practice, check out our quickstart example.

"},{"location":"concepts/proof-composability/#the-problem-clunky-interactions","title":"The problem: clunky interactions","text":"

In zero-knowledge systems, interactions between different proofs introduce complexity.

Cross-contract interactions require recursive proof verification, where Program A verifies proof of the correct execution of Program B. This is inefficient and creates overhead at the proof generation and verification stages.

The challenge becomes even greater when you start involving proofs that use different schemes.

Most zero-knowledge systems force you to write your proofs in a unified scheme. By doing that, you lose all the advantages of specialization.

Different proving schemes meet different needs. Some proof systems are best for client-side proving; others allow developers to use general-purpose programming languages.

We solve this issue by allowing for native proof composition between contracts and proving schemes. Now, proofs interact seamlessly, and each one can be written in the language that works best.

"},{"location":"concepts/proof-composability/#the-solution-proof-composition","title":"The solution: proof composition","text":""},{"location":"concepts/proof-composability/#cross-contract-calls-with-proof-composition","title":"Cross-contract calls with proof composition","text":"

Proof composability means that Hyl\u00e9 enables these interactions while keeping each proof independent; proof composition is the action enabled by composability.

Hyl\u00e9 gets rid of recursion by allowing Program A to specify: \"This only applies if all blobs in this operation are valid\". At settlement, both proofs are included in the same proof transaction. Hyl\u00e9 verifies them together, and the entire operation fails if any proof fails.

This solution improves developer experience, lowers gas costs, and shortens proving time.

"},{"location":"concepts/proof-composability/#proofs-using-different-schemes","title":"Proofs using different schemes","text":"

Since proofs in Hyl\u00e9 remain independent, you can batch multiple proofs within a single transaction, each using its optimal proving scheme.

Proofs are verified separately, eliminating the need to compromise for compatibility. This also enables cross-contract calls between applications using different proof systems.

"},{"location":"concepts/proof-composability/#when-to-use-proof-composition","title":"When to use proof composition","text":"

Proof composition is useful if:

It has no effect if your operation's entire logic is in one single proof.

"},{"location":"concepts/proof-composability/#writing-a-cross-contract-call","title":"Writing a cross-contract call","text":"

Your program doesn't need to verify another program\u2019s execution directly. Instead, it references the external contract using a structured claim, such as:

MoneyApp::transfer(10, A, B) == true\nTicketApp::get(A) == ticket\n

Each claim consists of:

In our quickstart example, the source code looks like this.

"},{"location":"concepts/proof-composability/#how-hyle-settles-multiple-proofs","title":"How Hyl\u00e9 settles multiple proofs","text":"

When you submit multiple proofs to Hyl\u00e9, proof generation can be parallelized.

Thanks to pipelined proving, proof verification is asynchronous. Proving times do not compound since proofs do not depend on each other, allowing proof generation to be parallelized.

As soon as one proof is ready, it can be verified on Hyl\u00e9, even if the other proofs aren't ready yet.

Once all proofs related to the transaction are verified, the transaction is settled on Hyl\u00e9. If one proof verification fails, then the entire transaction fails. If a proof times out, the transaction fails when the timeout occurs.

"},{"location":"concepts/proof-generation/","title":"Proof generation and submission","text":""},{"location":"concepts/proof-generation/#proof-generation-and-submission","title":"Proof generation and submission","text":"

Hyl\u00e9 allows you to build unchained applications by leveraging zero-knowledge proofs. They allow you to avoid onchain execution, guarantee privacy, and customize your application while maintaining composability with other smart contracts.

With Hyl\u00e9, generate your proof wherever you prefer, then send it for native onchain verification and settlement. This process enables scalable, modular applications with customizable proving schemes.

If you're a complete beginner with zero-knowledge proofs, our no-code introduction might help.

"},{"location":"concepts/proof-generation/#generating-zero-knowledge-proofs-for-hyle","title":"Generating zero-knowledge proofs for Hyl\u00e9","text":""},{"location":"concepts/proof-generation/#choose-what-you-prove","title":"Choose what you prove","text":"

Each application defines its proof logic. This means that each application developer can decide what information gets proven: for Hyl\u00e9, proof settlement is a Success or a Failure. You define what that means for your app.

Each app developer also defines what the public and private inputs of their app will be: what information should remain private and what should go onchain?

"},{"location":"concepts/proof-generation/#how-to-generate-a-zero-knowledge-proof","title":"How to generate a zero-knowledge proof","text":"

There are many ZK languages. Hyl\u00e9 aims to verify as many as possible.

DSLs, like Circom, are specific languages that usually compile down to a specific circuit. They're good, but they're complex and may have a high learning curve.

zkVMs prove the correct execution of arbitrary code. They allow you to build ZK applications in a certain language without having to build a circuit around it. There are two main types of zkVMs: Cairo and RISC-V. You can benchmark your Rust code and find the best zkVM for your needs with the any-zkvm template.

Each application can generate its proof in whichever place fits best.

Pros Cons When to use Client-side (browser, mobile app) Maximum privacyData ownership Requires robust client-side hardware Personal data that should remain private External prover or proving market No client-side costs or constraintsOffload proof generation to the experts Requires trusting the external prover with your inputs Resource-intensive and not privacy-sensitive proofs By the application itself Simple UXNo dependenciesCode can be private Higher infrastructure needsPotential liveness issue Confidential or centralized applications"},{"location":"concepts/proof-generation/#our-supported-proving-schemes","title":"Our supported proving schemes","text":"

Proving schemes are the cryptographic protocols that make zero-knowledge proofs usable. We support as many as we can, giving you the flexibility to choose the most suitable protocol for your specific use case.

We've written templates for some of our supported programs. Clone them to get started with smart contract writing.

| Proving scheme | Template | |----------------||---| | Noir | - | | Risc0 | Template | | SP1 | Template |

We also verify these natively, without the need for a ZK proof.

We will support more types, including Cairo-based zkVMs and DSLs, in the future, and plan to support all major proving schemes eventually. The next proving schemes we're aiming to support are Cairo via Stwo and Groth16.

"},{"location":"concepts/proof-generation/#our-proof-generation-partners","title":"Our proof generation partners","text":"

If you choose to work with an external prover or proving market, you can choose from one of our partners in that area and benefit from a better Hyl\u00e9 integration.

We recommend checking out Electron, Fermah, Kakarot, Marlin, Nexus, Nodekit, ZEROBASE, or zkCloud.

"},{"location":"concepts/proof-generation/#submitting-a-proof-to-hyle","title":"Submitting a proof to Hyl\u00e9","text":"

Read more about the transaction lifecycle on our transactions overview.

First, your application sends a blob transaction to Hyl\u00e9.

Thanks to pipelined proving, once a transaction is submitted, it is sequenced.

You can then start generating your proof using the sequenced virtual base state as the base state for your operation. Read our quickstart for a concrete example of how to prove a transaction.

Once sent, the proof goes through Hyl\u00e9\u2019s native verification, removing the need for verifier contracts.

Once verified, the proof is settled onchain. Use this settled state to update your app accordingly outside of Hyl\u00e9.

"},{"location":"concepts/proof-generation/#external-resources","title":"External resources","text":""},{"location":"concepts/smart-contracts/","title":"Smart contracts","text":""},{"location":"concepts/smart-contracts/#smart-contracts","title":"Smart contracts","text":"

Hyl\u00e9 is a fully programmable blockchain designed for efficient data storage. Hyl\u00e9 only keeps the essential information needed to validate smart contract proofs, ensuring that smart contracts are lightweight and performant.

Unlike traditional blockchains, which store all smart contract data onchain, Hyl\u00e9 separates execution data (managed offchain by each application) from onchain data, which can be retrieved via our ABI.

"},{"location":"concepts/smart-contracts/#onchain-smart-contract-data","title":"Onchain smart contract data","text":"

Hyl\u00e9 smart contracts store the following data onchain:

"},{"location":"concepts/smart-contracts/#explanation-of-the-contract-fields","title":"Explanation of the contract fields","text":""},{"location":"concepts/smart-contracts/#name","title":"Name","text":"

The contract name must be unique.

"},{"location":"concepts/smart-contracts/#verifier-and-program-id","title":"Verifier and program ID","text":"

Smart contracts on Hyl\u00e9 rely on a pairing of a zero-knowledge proof scheme (verifier) and a program identifier. Together, these components validate contract proofs.

We've written templates for some of our supported programs. Clone them to get started with smart contract writing.

Proving scheme Verifier Program ID Noir noir Verification key. Risc0 risc0 Image ID without a prefix. ex. 0x123 becomes 123. SP1 sp1 Verification key."},{"location":"concepts/smart-contracts/#state-digest","title":"State digest","text":"

The state digest represents the contract's current state commitment. It allows Hyl\u00e9 to guarantee its integrity. It can take any form as long as it fulfills this purpose.

The state digest can be expressed as a hash or even a serialization of the state if it's small enough.

"},{"location":"concepts/smart-contracts/#smart-contract-abi","title":"Smart contract ABI","text":"

All inputs in Hyl\u00e9 smart contracts must be known at proof generation time. This includes elements like the tx_hash which are typically available only at execution time on other blockchains.

Here is the Rust structure specifying the output of a Hyl\u00e9 smart contract:

pub struct HyleOutput {\n    pub version: u32,\n    pub initial_state: StateDigest,\n    pub next_state: StateDigest,\n    pub identity: Identity,\n    pub index: BlobIndex,\n    pub blobs: Vec<u8>,\n    pub tx_hash: TxHash,\n    pub success: bool,\n    pub tx_ctx: Option<TxContext>,\n    pub registered_contracts: Vec<RegisterContractEffect>,\n    pub program_outputs: Vec<u8>, \n}\n
"},{"location":"concepts/smart-contracts/#version","title":"Version","text":"

For now, version should always be set to 1.

"},{"location":"concepts/smart-contracts/#initial-state-and-next-state","title":"Initial state and next state","text":"

These fields define state transitions.

In the future, state_digest size will be limited and fees will depend on proof size (which is affected by the digest's size). Keep them small!

"},{"location":"concepts/smart-contracts/#identity","title":"Identity","text":"

Info

Read our identity documentation for details.

Identity consists of:

  1. An identifier;
  2. The name of the contract that the proof was generated for.

Example

A contract verifying Ethereum EOAs might have an identity like 0x1234...5678.eth_eoa where the first part matches a regular Ethereum address and eth_eoa is the name of the contract.

"},{"location":"concepts/smart-contracts/#blob-index-and-blobs","title":"Blob index and blobs","text":"

Each blob transaction includes multiple blobs:

"},{"location":"concepts/smart-contracts/#tx-hash","title":"TX Hash","text":"

tx_hash is the blob Transaction's hash.

The protocol does not validate this field and tx_hash may be deprecated in later versions.

"},{"location":"concepts/smart-contracts/#success","title":"Success","text":"

This boolean field indicates whether the proof is for a successful or failed transactions. It can be used to prove that a transaction is invalid.

If a proof returns success = false, the whole blob transaction will fail. In that case, there is no need to generate proofs for other blobs.

"},{"location":"concepts/smart-contracts/#transaction-context","title":"Transaction context","text":"

Transaction context allows the contract to know in which block (hash, height, timestamp) the blob transaction has been sequenced.

This field is optional. If left empty, it will not be validated by Hyl\u00e9 or usable by the program.

"},{"location":"concepts/smart-contracts/#registered-contracts","title":"Registered contracts","text":"

A list of new contracts to register, which can be used to self-upgrade a contract.

"},{"location":"concepts/smart-contracts/#other-program-specific-outputs","title":"Other program-specific outputs","text":"

Smart contracts can generate additional outputs as proof data. These outputs ensure data availability.

"},{"location":"concepts/smart-contracts/#events","title":"Events","text":"

Hyl\u00e9 does not use traditional events. Instead, it relies on blobs, which serve as containers for offchain data.

"},{"location":"concepts/transaction/","title":"Transactions on Hyl\u00e9","text":""},{"location":"concepts/transaction/#transactions-on-hyle","title":"Transactions on Hyl\u00e9","text":"

Hyl\u00e9 introduces a novel transaction model that separates intent from proof, optimizing for scalability and privacy.

Unlike traditional blockchains, where transactions are executed and proven in a single step, Hyl\u00e9 employs a two-step process called pipelined proving:

  1. Blob-transaction: outlines a state change for sequencing.
  2. Proof-transaction: provides a proof of the state change for settlement.

Each proof transaction verifies a single blob, unless you use recursion. If a blob transaction contains multiple blobs, each requires a separate proof.

Once all blobs are proven, the blob transaction is settled, and the referenced contract states are updated.

"},{"location":"concepts/transaction/#blob-transaction-structure","title":"Blob transaction structure","text":"

A blob transaction consists of:

"},{"location":"concepts/transaction/#proof-transaction-structure","title":"Proof transaction structure","text":"

A proof transaction includes:

For Risc0 and SP1, the proof data's smart contract output follows HyleOutput as defined in the smart contract ABI.

"},{"location":"concepts/transaction/#example-token-transfer","title":"Example: token transfer","text":"

A token transfer involves two blobs in a blob transaction:

Each blob requires a corresponding proof transaction.

"},{"location":"concepts/transaction/#blob-transaction","title":"Blob transaction","text":"
{\n    \"identity\": \"bob.hydentity\",\n    \"blobs\": [\n        {\n            \"contract_name\": \"hydentity\",\n             // Binary data for the operation of hydentity contract\n             // VerifyIdentity { account: \"bob.hydentity\", nonce: \"2\" }\n            \"data\": \"[...]\" \n        },\n        {\n            \"contract_name\": \"hyllar\",\n             // Binary data for the operation of hyllar contract\n             // Transfer { recipient: \"alice.hydentity\", ammount: \"20\" }\n            \"data\": \"[...]\"\n        }\n    ]\n}\n
"},{"location":"concepts/transaction/#proof-transactions","title":"Proof transactions","text":""},{"location":"concepts/transaction/#identity-proof","title":"Identity proof","text":"
{\n    \"contract_name\": \"hydentity\",\n    \"proof\": \"[...]\"\n}\n

The binary proof's output includes:

and

{\n    \"contract_name\": \"hyllar\",\n    \"proof\": \"[...]\"\n}\n

The binary proof's output includes:

"},{"location":"quickstart/","title":"\ud83c\udfc1 Quickstart","text":""},{"location":"quickstart/#quickstart","title":"Quickstart","text":"

Welcome to the Quickstart guide for Hyl\u00e9.

It uses several examples to help you start building as soon as possible.

Run your local devnet

Where it all begins.

Create your first smart contract

In just a couple of lines, create and register your first smart contract.

Walk through a full example

Check out a ticket app based on a token and simple identity contract.

"},{"location":"quickstart/devnet/","title":"Run your local devnet","text":""},{"location":"quickstart/devnet/#run-your-local-devnet","title":"Run your local devnet","text":""},{"location":"quickstart/devnet/#recommended-run-from-source","title":"Recommended: Run from source","text":"

For a single-node devnet (consensus disabled) with an indexer, clone the hyle repository and run:

cargo run -- --pg\n

This command starts a temporary PostGreSQL server and erases its data when you stop the node. For persistent storage, start a standalone PostgreSQL instance:

# Start PostgreSQL with default configuration:\ndocker run -d --rm --name pg_hyle -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres\n

Then, navigate to the Hyl\u00e9 root and run:

cargo run\n
"},{"location":"quickstart/devnet/#alternative-start-with-docker","title":"Alternative: Start with Docker","text":"

Use Docker to run a local node. Note that the devnet is unstable and may break with future updates.

"},{"location":"quickstart/devnet/#pull-the-docker-image","title":"Pull the Docker image","text":"
docker pull ghcr.io/hyle-org/hyle:v0.12.1\n
"},{"location":"quickstart/devnet/#run-the-docker-container","title":"Run the Docker container","text":"
docker run -v ./data:/hyle/data -p 4321:4321 ghcr.io/hyle-org/hyle:v0.12.1\n

If you run into an error, try adding the --privileged flag:

docker run --privileged -v ./data:/hyle/data -p 4321:4321 ghcr.io/hyle-org/hyle:v0.12.1\n

To run with an indexer, add the parameter -e HYLE_RUN_INDEXER=true and set up a running PostGreSQL server with Docker:

docker run -d --rm --name pg_hyle -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres\n

And the node linked to it:

docker run -v ./data:/hyle/data \\\n    -e HYLE_RUN_INDEXER=true \\\n    -e HYLE_DATABASE_URL=postgres://postgres:postgres@pg_hyle:5432/postgres \\\n    --link pg_hyle \\\n    -p 4321:4321 \\\n    ghcr.io/hyle-org/hyle:v0.7.2\n

You can now create your first smart contract.

Tip

To reset your devnet, delete the ./data folder and restart from Step 1. Otherwise, you risk re-registering a contract that still exists.

"},{"location":"quickstart/devnet/#alternative-build-the-docker-image-locally","title":"Alternative: Build the Docker image locally","text":"

If you prefer to build the image from source, run:

docker build -t Hyle-org/hyle . && docker run -dit Hyle-org/hyle\n
"},{"location":"quickstart/devnet/#configuration","title":"Configuration","text":"

You can configure your setup using environment variables or by editing a configuration file.

"},{"location":"quickstart/devnet/#using-environment-variables","title":"Using environment variables","text":"

All variables can be customized on your single-node instance.

Variable Default value Description HYLE_ID node Node identifier in the consensus. Usage subject to change in future releases. HYLE_SINGLE_NODE true Whether the network runs as a single node or with a multi-node consensus. HYLE_P2P_LISTEN true Mandatory (true) if multi-node consensus. The node should listen to new peers. HYLE_HOST 127.0.0.1:1231 Host & port to listen for the P2P protocol. HYLE_PEERS [] List of peers to connect to at startup to follow a running consensus. HYLE_STORAGE__INTERVAL 10 unused HYLE_LOG_FORMAT full \u201cfull\u201d or \u201cjson\u201d HYLE_REST 127.0.0.1:4321 Host & port for the REST API endpoint. HYLE_DATA_DIRECTORY data_node Directory name to store node state. HYLE_DATABASE_URL postgres://postgres:postgres @localhost:5432/postgres PostgreSQL server address (necessary if you want to use an indexer). HYLE_CONSENSUS__SLOT_DURATION 1000 Duration between blocks. HYLE_CONSENSUS__GENESIS_STAKERS {} Keys are all nodes \u201cid\u201d, and values are the stake amount for each one of them. Map of stakers for the genesis block. HYLE_P2P__PING_INTERVAL 10 Interval the p2p layer does a ping to check aliveness of other peers. HYLE_RUN_INDEXER true Whether there should be an indexer. HYLE_DA_ADDRESS 127.0.0.1:4141 Host & port of the data availability module, which streams historical & new blocks. It might be used by indexers."},{"location":"quickstart/devnet/#using-a-configuration-file","title":"Using a configuration file","text":"

To load settings from a file, place config.ron in your node's working directory. It will be detected automatically at startup.

For Docker users, mount the config file when running the container:

docker run -v ./data:/hyle/data -v ./config.run:/hyle/config.ron -e HYLE_RUN_INDEXER=false -p 4321:4321 -p 1234:1234 ghcr.io/hyle-org/hyle:v0.12.1\ncp ./src/utils/conf_defaults.ron config.ron\n

For source users, copy the default config template:

cp ./src/utils/conf_defaults.ron config.ron\n
"},{"location":"quickstart/your-first-smart-contract/","title":"Your first smart contract","text":""},{"location":"quickstart/your-first-smart-contract/#your-first-smart-contract","title":"Your first smart contract","text":"

Tip

Check our example walkthrough for more!

"},{"location":"quickstart/your-first-smart-contract/#step-1-clone-a-template","title":"Step 1: Clone a template","text":"

We support several proving schemes and provide templates for the following:

Clone the template or, for proving schemes without templates, use the templates as inspiration for writing your contract. You can also check our smart contract concept page for more information!

"},{"location":"quickstart/your-first-smart-contract/#step-2-edit-your-contract","title":"Step 2: Edit your contract","text":"

Navigate to the contract/ folder and edit your contract as necessary.

"},{"location":"quickstart/your-first-smart-contract/#step-3-register-your-contract","title":"Step 3: Register your contract","text":"

On the devnet, register your contract by running:

cargo run -- register-contract\n
"},{"location":"quickstart/example/","title":"Example walkthrough","text":""},{"location":"quickstart/example/#example-walkthrough","title":"Example walkthrough","text":"

Here's a step-by-step walkthrough of an example.

Run your local devnet

Where it all begins.

Create your first smart contract

Understand how smart contracts work on Hyl\u00e9 with our simple-token example.

Use an identity contract

Every contract can be an identity on Hyl\u00e9. Try it out with our simple-identity example.

Call several contracts in one transaction

Use cross-contract proof composition to buy a simple-ticket with a simple-token.

"},{"location":"quickstart/example/custom-identity-contract/","title":"Using a custom identity contract","text":""},{"location":"quickstart/example/custom-identity-contract/#using-a-custom-identity-contract","title":"Using a custom identity contract","text":""},{"location":"quickstart/example/custom-identity-contract/#when-to-use-identity-contracts-on-hyle","title":"When to use identity contracts on Hyl\u00e9","text":"

On Hyl\u00e9, any smart contract can be a proof of identity. This flexibility enables you to register your preferred identity source as a smart contract for account identification. If you don't want to use a custom identity source, Hyl\u00e9 ships a native hydentity contract.

This guide walks you through creating and deploying your first simple identity contract using Hyl\u00e9 and RISC Zero. We'll use our simple identity example, which mirrors our simple token transfer example.

If you\u2019re new to identity management on Hyl\u00e9, read the identity management concept page.

"},{"location":"quickstart/example/custom-identity-contract/#run-the-example","title":"Run the example","text":"

Warning

Our examples work on Hyl\u00e9 v0.12.1. Later versions may introduce breaking changes which have not yet been reflected in our examples.

Info

Jump to Code Snippets for an in-depth look at the contract.

"},{"location":"quickstart/example/custom-identity-contract/#prerequisites","title":"Prerequisites","text":""},{"location":"quickstart/example/custom-identity-contract/#build-and-register-the-identity-contract","title":"Build and register the identity contract","text":"

To build all methods and register the smart contract on the local node from the source, navigate to your cloned Examples folder and run:

cargo run -- register-contract\n

The expected output is \ud83d\udcdd Registering new contract simple_identity.

"},{"location":"quickstart/example/custom-identity-contract/#register-an-account-sign-up","title":"Register an account (sign up)","text":"

To register an account with a username (alice) and password (abc123), execute:

cargo run -- register-identity alice.simple_identity abc123\n

Expected log output:

INFO hyle::data_availability::node_state::verifiers: \u2705 Risc0 proof verified.\nINFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Successfully registered identity for account: alice.simple_identity\n
"},{"location":"quickstart/example/custom-identity-contract/#verify-identity-login","title":"Verify identity / Login","text":"

To verify alice's identity:

cargo run -- verify-identity alice.simple_identity abc123 0\n

This command:

  1. Sends a blob transaction to verify alice's identity.
  2. Generates a ZK proof of that identity. It will only be valid once, thus the inclusion of a nonce.
  3. Sends the proof to the devnet.

Upon reception of the proof, the node will:

  1. Verify the proof.
  2. Settle the blob transaction.
  3. Update the contract's state.

Expected log output:

INFO hyle::data_availability::node_state::verifiers: \u2705 Risc0 proof verified.\nINFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Identity verified for account: alice.simple_identity\n
"},{"location":"quickstart/example/custom-identity-contract/#development-mode","title":"Development mode","text":"

We recommend activating dev-mode during your early development phase for faster iteration upon code changes with -e RISC0_DEV_MODE=1.

You may also want to get insights into the execution statistics of your project: add the environment variable RUST_LOG=\"[executor]=info\" before running your project.

The full command to run your project in development mode while getting execution statistics is:

RUST_LOG=\"[executor]=info\" RISC0_DEV_MODE=1 cargo run\n
"},{"location":"quickstart/example/custom-identity-contract/#code-snippets","title":"Code snippets","text":"

Find the full annotated code in our examples repository.

"},{"location":"quickstart/example/custom-identity-contract/#registering-the-contract","title":"Registering the contract","text":"

This part is the same as for Your first smart contract.

"},{"location":"quickstart/example/custom-identity-contract/#register-an-identity","title":"Register an identity","text":""},{"location":"quickstart/example/custom-identity-contract/#build-the-blob-transaction","title":"Build the blob transaction","text":"

This is a simplified code snippet:

let action = RegisterIdentity {\n    account: identity,\n};\nlet blob = sdk::Blob {\n    contract_name: contract_name,\n    data: action.as_blob_data(), // Note: This function does not exist. Used here for clarity\n};\nlet blob_tx = BlobTransaction {\n    identity: identity,\n    blobs: vec![blob],\n};\n

You can compare these to the fields described in the Transactions on Hyl\u00e9 page.

"},{"location":"quickstart/example/custom-identity-contract/#prove-the-registration","title":"Prove the registration","text":""},{"location":"quickstart/example/custom-identity-contract/#on-the-backend-host-side","title":"On the backend (host) side","text":"

Hyl\u00e9 transactions follow a two-step settlement process based on pipelined proving principles:

  1. Sending the blob transaction: The transaction is sequenced but not yet settled.
  2. Proving the transaction: The transaction is settled after a proof is generated.

To generate the proof, we build the contract input, specifying:

// Build the contract input\nlet inputs = ContractInput {\n    initial_state: initial_state.as_digest(),\n    identity: blob_tx.identity,\n    tx_hash: blob_tx_hash,\n    private_blob: sdk::BlobData(password),\n    blobs: blobs,\n    index: sdk::BlobIndex(0),\n};\n
"},{"location":"quickstart/example/custom-identity-contract/#on-the-contract-guest-side","title":"On the contract (guest) side","text":"

These inputs are then processed by the SDK to initialize the contract :

    // Parse contract inputs\n    let (input, action) = sdk::guest::init_raw::<IdentityAction>();\n

The password is extracted as a private input:

    // Extract private information\n    let password = from_utf8(&input.private_blob.0).unwrap();\n

The contract processes the identity registration:

    // We clone the initial state to be updated\n    let mut next_state: Identity = input.initial_state.clone();\n\n    // Execute the given action\n    let res = sdk::identity_provider::execute_action(&mut next_state, action, password);\n

Finally, the contract commits the updated state:

    sdk::guest::commit(input, next_state, res);\n

The guest::commit function includes the HyleOutput, as explained in Transactions on Hyl\u00e9.

"},{"location":"quickstart/example/custom-identity-contract/#verify-an-identity","title":"Verify an identity","text":"

The identity verification process is identical to identity registration, with a different action:

let action = VerifyIdentity {\n    account: identity,\n    nonce,\n};\n

Check the full annotated code in our GitHub example.

"},{"location":"quickstart/example/first-token-contract/","title":"Your first token contract","text":""},{"location":"quickstart/example/first-token-contract/#your-first-token-contract","title":"Your first token contract","text":"

This guide will walk you through creating and deploying your first token transfer contract using Hyl\u00e9's tools and infrastructure. We'll use our simple-token transfer example as the basis for this tutorial.

For an alternative implementation, check out the same example built with SP1.

If you\u2019re new to smart contracts on Hyl\u00e9, read the anatomy of a smart contract.

"},{"location":"quickstart/example/first-token-contract/#example","title":"Example","text":"

Warning

Our examples work on Hyl\u00e9 v0.12.1. Later versions may introduce breaking changes that are not yet reflected in our examples.

"},{"location":"quickstart/example/first-token-contract/#prerequisites","title":"Prerequisites","text":""},{"location":"quickstart/example/first-token-contract/#quickstart","title":"Quickstart","text":""},{"location":"quickstart/example/first-token-contract/#build-and-register-the-contract","title":"Build and register the contract","text":"

To build all methods and register the smart contract from the source, navigate to your cloned Examples folder and run:

cargo run -- register 1000\n

The expected output is \ud83d\udcdd Registering new contract simple_token.

"},{"location":"quickstart/example/first-token-contract/#transfer-tokens","title":"Transfer tokens","text":"

Transfer 2 tokens from the Hyl\u00e9 faucet to Bob:

cargo run -- transfer faucet.simple_token bob.simple_token 2\n

This command:

  1. Sends a blob transaction to transfer 2 tokens from faucet to bob. To better understand what a blob transaction is, read more about transactions on Hyl\u00e9.
  2. Generates a ZK proof for the transfer.
  3. Sends the proof to the devnet for verification. (Scroll down to see what that looks like in code.)
"},{"location":"quickstart/example/first-token-contract/#verify-settled-state","title":"Verify settled state","text":"

Upon reception of the proof, the node will:

  1. Verify the proof
  2. Settle the blob transaction
  3. Update the contract's state

Expected log output:

INFO hyle::data_availability::node_state::verifiers: \u2705 Risc0 proof verified.\nINFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Transferred 2 to bob.simple_token\n

On the following slot:

INFO hyle::data_availability::node_state: Settle tx TxHash(\"[..]\")\n
"},{"location":"quickstart/example/first-token-contract/#check-onchain-balance","title":"Check onchain balance","text":"

Verify onchain balances:

cargo run -- balance faucet.simple_token\ncargo run -- balance bob.simple_token\n

Note

In this example, we do not verify the identity of the person who initiates the transaction. We use .simple_token as a suffix for the \"from\" and \"to\" transfer fields, but the correct identity scheme should be used in production.

See your contract's state digest at: https://hyleou.hyle.eu/contract/$CONTRACT_NAME.

See your transaction on Hyl\u00e9's explorer: https://hyleou.hyle.eu/tx/$TX_HASH.

"},{"location":"quickstart/example/first-token-contract/#development-mode","title":"Development mode","text":"

For faster iteration during development, enable dev-mode: -e RISC0_DEV_MODE=1.

To get execution statistics, set: RUST_LOG=\"[executor]=info\" as an environment variable.

To run your project in development mode with logs:

RUST_LOG=\"[executor]=info\" RISC0_DEV_MODE=1 cargo run\n
"},{"location":"quickstart/example/first-token-contract/#annotated-code-snippets","title":"Annotated code snippets","text":"

Find the full annotated code in our examples repository.

Below are key snippets explaining contract registration, blob transactions, and proofs.

"},{"location":"quickstart/example/first-token-contract/#registering-the-contract","title":"Registering the contract","text":"

Set up information about your contract. To register the contract, you'll need:

// Build initial state of contract\nlet initial_state = Token::new(supply, format!(\"faucet.{}\", contract_name).into());\nprintln!(\"Initial state: {:?}\", initial_state);\n\n// Send the transaction to register the contract\nlet register_tx = RegisterContractTransaction {\n    owner: \"examples\".to_string(),\n    verifier: \"risc0\".into(),\n    program_id: sdk::ProgramId(sdk::to_u8_array(&GUEST_ID).to_vec()),\n    state_digest: initial_state.as_digest(),\n    contract_name: contract_name.clone().into(),\n};\nlet res = client\n    .send_tx_register_contract(&register_tx)\n    .await\n    .unwrap()\n    .text()\n    .await\n    .unwrap();\n\nprintln!(\"\u2705 Register contract tx sent. Tx hash: {}\", res);\n

In the explorer, this will look like this:

{\n    \"tx_hash\": \"321b7a4b2228904fc92979117e7c2aa6740648e339c97986141e53d967e08097\",\n    \"owner\": \"examples\",\n    \"verifier\": \"risc0\",\n    \"program_id\":\"e085fa46f2e62d69897fc77f379c0ba1d252d7285f84dbcc017957567d1e812f\",\n    \"state_digest\": \"fd00e876481700000001106661756365742e687964656e74697479fd00e876481700000000\",\n    \"contract_name\": \"simple_token\"\n}\n
"},{"location":"quickstart/example/first-token-contract/#create-blob-transaction","title":"Create blob transaction","text":"
// The action to execute, that will be proved later\nlet action = sdk::erc20::ERC20Action::Transfer {\n    recipient: to.clone(),\n    amount,\n};\n// Into a BlobTransaction to be sent on chain\nlet blobs = vec![sdk::Blob {\n    contract_name: contract_name.clone().into(),\n    data: sdk::BlobData(\n        bincode::encode_to_vec(action, bincode::config::standard())\n            .expect(\"failed to encode BlobData\"),\n    ),\n}];\nlet blob_tx = BlobTransaction {\n    identity: from.into(),\n    blobs,\n};\n\n// Send the blob transaction\nlet blob_tx_hash = client.send_tx_blob(&blob_tx).await.unwrap();\nprintln!(\"\u2705 Blob tx sent. Tx hash: {}\", blob_tx_hash);\n
"},{"location":"quickstart/example/first-token-contract/#prove-the-transaction","title":"Prove the transaction","text":"

Hyl\u00e9 transactions are settled in two steps, following pipelined proving principles. After this step, your transaction is sequenced, but not settled.

For the transaction to be settled, it needs to be proven. You'll start with building the contract input, specifying:

// Build the contract input\nlet inputs = ContractInput::<Token> {\n    initial_state,\n    identity: from.clone().into(),\n    tx_hash: \"\".into(),\n    private_blob: sdk::BlobData(vec![]),\n    blobs: blobs.clone(),\n    index: sdk::BlobIndex(0),\n};\n\n// Generate the zk proof\nlet receipt = prove(cli.reproducible, inputs).unwrap();\n\nlet proof_tx = ProofTransaction {\n    blob_tx_hash,\n    proof: ProofData::Bytes(borsh::to_vec(&receipt).expect(\"Unable to encode receipt\")),\n    contract_name: contract_name.clone().into(),\n};\n\n// Send the proof transaction\nlet proof_tx_hash = client\n    .send_tx_proof(&proof_tx)\n    .await\n    .unwrap()\n    .text()\n    .await\n    .unwrap();\nprintln!(\"\u2705 Proof tx sent. Tx hash: {}\", proof_tx_hash);\n

Check the full annotated code in our GitHub example.

"},{"location":"quickstart/example/proof-composition/","title":"Proof composition with Ticket App","text":""},{"location":"quickstart/example/proof-composition/#proof-composition-with-ticket-app","title":"Proof composition with Ticket App","text":"

Hyl\u00e9 enables proof composition, allowing different proving systems to work within a single operation. This removes constraints on provers and significantly improves interoperability and efficiency.

In this guide, we\u2019ll build a Ticket App that demonstrates proof composition. Users can buy a ticket using simple-token, and Hyl\u00e9 will verify multiple proofs in a single transaction.

Find the source code for all contracts here:

Traditional verification systems often require all proofs to be generated using the same proving system. Hyl\u00e9 removes this limitation, allowing:

"},{"location":"quickstart/example/proof-composition/#how-this-example-works","title":"How this example works","text":"

In this example, Alice and Bob both want to buy a ticket from Ticket App for 15 simple-tokens. Bob has enough tokens to complete the transaction, while Alice does not.

"},{"location":"quickstart/example/proof-composition/#step-1-create-the-blob-transaction","title":"Step 1: Create the blob transaction","text":"

The Ticket App backend creates and sends a blob transaction to Hyl\u00e9, including three blobs:

At this stage, Hyl\u00e9 sequences the transaction, but it\u2019s not yet settled. Read more about pipelined proving.

"},{"location":"quickstart/example/proof-composition/#step-2-prove-the-blobs","title":"Step 2: Prove the blobs","text":"

The Ticket App backend generates ZK proofs of each blob.

The ticket-app contract is executed, checking whether:

At this step, the contract does not verify whether Bob actually has enough tokens: if the token transfer fails in Step 3, the entire transaction fails.

Check out the source code.

"},{"location":"quickstart/example/proof-composition/#step-3-settlement","title":"Step 3: Settlement","text":"

Once TicketApp has sent the proofs for the previously sequenced blobs, Hyl\u00e9 verifies:

If all proofs are valid, the simple-token balance and ticket-app ticket balance are updated simultaneously at transaction settlement: bob.id sends 15 simple-tokens and gains one ticket.

If any proof fails, the entire transaction fails. Neither state is updated: Bob's token balance does not change and he doesn't get a ticket.

"},{"location":"quickstart/example/proof-composition/#run-the-example","title":"Run the example","text":"

Warning

Our examples work on Hyl\u00e9 v0.12.1. Later versions introduce breaking changes which have not yet been reflected in our examples.

"},{"location":"quickstart/example/proof-composition/#prerequisites","title":"Prerequisites","text":"

This quickstart guide will take you through the following steps:

"},{"location":"quickstart/example/proof-composition/#simple-identity-preparation","title":"Simple-identity preparation","text":"

Let's start with registering an identity contract and two identities.

Go to the ./simple-identity folder and run:

cargo run -- --contract-name id register-contract\n

Now we have an identity contract called id. We can use it to declare our users:

cargo run -- --contract-name id register-identity bob.id pass\ncargo run -- --contract-name id register-identity alice.id pass\n

Let's verify it quickly with:

cargo run -- --contract-name id verify bob.id pass 0\n

0 is a nonce: every time we verify successfully bob's identity, it increments. Now if we want to verify it again, we should use 1 as nonce. (We also use \"pass\" as our default password.)

We now do the same for alice:

cargo run -- --contract-name id verify alice.id pass 0\n

bob.id is bob's identity on the simple-identity contract. Check out our Identity management and custom identity contract pages to know more.

"},{"location":"quickstart/example/proof-composition/#simple-token-preparation","title":"Simple-token preparation","text":""},{"location":"quickstart/example/proof-composition/#register-simple-token","title":"Register simple-token","text":"

Go to ./simple-token folder and run:

cargo run -- --contract-name simple-token register 1000\n

On the node's logs, you will see:

\ud83d\udcdd Registering new contract simple_token

You just registered a token contract named simple-token with an initial supply of 1000.

"},{"location":"quickstart/example/proof-composition/#transfer-tokens","title":"Transfer tokens","text":"

Now let's transfer some tokens to our user bob.

To send 50 tokens to bob and 10 tokens to alice, run:

cargo run -- -contract-name simple-token transfer faucet.simple-token bob.id 50\ncargo run -- -contract-name simple-token transfer faucet.simple-token alice.id 10\n

The node's log will show:

INFO hyle::data_availability::node_state::verifiers: \u2705 Risc0 proof verified.

INFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Transferred 50 to bob.ticket_app INFO hyle::data_availability::node_state::verifiers: \ud83d\udd0e Program outputs: Transferred 10 to alice.ticket_app

"},{"location":"quickstart/example/proof-composition/#check-onchain-balance","title":"Check onchain balance","text":"

Check onchain balance:

cargo run -- --contract-name simple-token balance faucet.simple-token\n\ncargo run -- --contract-name simple-token balance bob.id\ncargo run -- --contract-name simple-token balance alice.id\n

You should see that bob has a balance of 50 and alice has a balance of 10.

"},{"location":"quickstart/example/proof-composition/#using-ticket-app","title":"Using ticket-app","text":"

Now that bob has some tokens, let's buy him a ticket.

"},{"location":"quickstart/example/proof-composition/#register-ticket-app","title":"Register ticket-app","text":"

Register the ticket app by going to ./ticket-app folder and running:

cargo run -- --contract-name ticket-app register simple-token 15\n

ticket-app sells bob a ticket for 15 simple-token.

"},{"location":"quickstart/example/proof-composition/#buy-a-ticket","title":"Buy a ticket","text":"

Let's buy a ticket for bob:

cargo run -- --contract-name ticket-app --user bob.id buy-ticket\n

Let's try with alice:

cargo run -- --contract-name ticket-app --user alice.id buy-ticket\n

You will get an error while executing the TicketApp program: Execution failed ! Program output: Insufficient balance. This is because Alice has a balance of 10 and the ticket costs 15.

"},{"location":"quickstart/example/proof-composition/#check-ticket-and-token-balance","title":"Check ticket and token balance","text":"

Check that bob has a ticket:

cargo run -- --contract-name ticket-app --user bob.id has-ticket\n

You can also check bob's balance and see he now has 35 tokens.

With proof composition, Hyl\u00e9 empowers you to leverage multiple proving systems in a single transaction, making advanced functionality like the Ticket App easier than ever.

"},{"location":"resources/","title":"\ud83d\udcda Resources","text":""},{"location":"resources/#resources","title":"\ud83d\udcda Resources","text":""},{"location":"resources/find-us/","title":"Find us","text":""},{"location":"resources/find-us/#useful-links","title":"Useful links","text":""},{"location":"resources/find-us/#contact-us","title":"Contact us","text":"

Reach out to the team for more information:

Github Twitter Farcaster LinkedIn Youtube Telegram Hyl\u00e9 @hyle_org @hyle-org Hyl\u00e9 @Hyl\u00e9 @hyle_org"},{"location":"resources/glossary/","title":"Glossary","text":""},{"location":"resources/glossary/#glossary","title":"Glossary","text":"Term Definition Related concept page blob A piece of provable information that is sent to Hyl\u00e9. Smart contracts blob transaction A transaction including a provable blob, used for sequencing. Pipelined proving cross-contract composition The ability to use and verify a contract's proofs in other contracts. Proof composition operation Something that happens on an unchained app. An operation includes two transactions: a blob transaction and a proof transaction. Transactions proof composition The process of combining multiple zero-knowledge proofs into a single proof, enabling efficient verification and interoperability across different proving systems. Proof composition proof transaction A transaction including a proof of a previously-submitted blob, used for verification and settlement. Transactions proof verification The act by which Hyl\u00e9 verifies submitted proofs before settling them onchain. Transactions timeout A time window after which, if no proof transaction has been submitted, an operation fails. Pipelined proving transaction A part of an operation that gets sent to Hyl\u00e9. There are two types of transactions: blob transactions and proof transactions. Transactions unchained app An app that runs offchain and settles onchain, giving it both the Web2 user experience and the security of Web3."},{"location":"resources/grants/","title":"Contribute to Hyl\u00e9","text":""},{"location":"resources/grants/#contribute-to-hyle","title":"Contribute to Hyl\u00e9","text":""},{"location":"resources/grants/#contribution-opportunities","title":"Contribution opportunities","text":"

You can contribute to Hyl\u00e9 in several ways. We are active participants in OnlyDust projects and welcome maintainers.

You can also check out our Careers page for longer-term opportunities.

"},{"location":"resources/grants/#grant-program","title":"Grant program","text":"

We have a grant program supporting developers who want to work on trust infrastructure and programmable cryptography on Hyl\u00e9.

"},{"location":"resources/grants/#what-are-our-grants-like","title":"What are our grants like?","text":"

To read more, see our grant ideas, and apply, please go to our Grants page on the main Hyl\u00e9 repository. If you represent an organization, we'd love to discuss co-grants ideas.

For questions that aren't answered on the Grants page, reach out in our Telegram group.

"},{"location":"resources/grants/#current-and-past-grants","title":"Current and past grants","text":"

Here are two past grants:

Find the full list on our Grants page on the main Hyl\u00e9 repository.

"},{"location":"resources/release-notes/","title":"Release notes","text":""},{"location":"resources/release-notes/#release-notes","title":"Release notes","text":"

Read our full changelogs on GitHub or the short versions in our Telegram group.

"},{"location":"resources/release-notes/#2025-02-24-v0120","title":"2025-02-24 \u2212 v0.12.0","text":"

\ud83d\uddde\ufe0f Our news:

\ud83d\udca5 Breaking changes:

We heard your feedback on our frequent breaking changes. Going forward, we\u2019ll be making fewer releases, relying instead on rc versions, so that breaking changes are batched.

\u2728 New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

"},{"location":"resources/release-notes/#2025-02-14-v0110","title":"2025-02-14 \u2212 v0.11.0","text":"

\u2728 New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

"},{"location":"resources/release-notes/#2025-02-07-v0100","title":"2025-02-07 \u2212 v0.10.0","text":"

\ud83d\udca5 Breaking change: we\u2019ve replaced our serialization standard, bincode, with borsh. Encoding BlobData from JS didn\u2019t work properly with bincode: borsh offers better support and opens new possibilities!

\u2728 New features:

\ud83d\udee0\ufe0f No longer broken:

"},{"location":"resources/release-notes/#2025-02-03-v090","title":"2025-02-03 \u2212 v0.9.0","text":"

\ud83d\udca5 Breaking changes:

\u2728 New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

Quick note: release notes will be published on Fridays instead of Mondays from now on. See you in just a few days!

"},{"location":"resources/release-notes/#2025-01-27-v080","title":"2025-01-27 \u2212 v0.8.0","text":"

\ud83d\udca5 Breaking changes:

\u2728New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

Read the full changelog on GitHub.

"},{"location":"resources/release-notes/#2025-01-21-v071-v072","title":"2025-01-21 \u2212 v0.7.1 & v0.7.2","text":"

Small patches for our SDK.

Read release notes for v0.7.1 and v0.7.2; see new SDK readme for more info.

"},{"location":"resources/release-notes/#2025-01-20-v070","title":"2025-01-20 \u2212 v0.7.0","text":"

\ud83d\udca5 Breaking changes:

\u2728 New features;

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

Read the full changelog on GitHub and receive future release notes in our Telegram group.

"},{"location":"resources/release-notes/#2025-01-13-v060","title":"2025-01-13 \u2212 v0.6.0","text":"

\u2728 New features:

\ud83d\ude85 Improvements:

\ud83d\udee0\ufe0f No longer broken:

\ud83d\udcda Documentation:

Read the full changelog on GitHub and receive future release notes in our Telegram group.

"},{"location":"resources/roadmap/","title":"Roadmap","text":""},{"location":"resources/roadmap/#testnet","title":"Testnet","text":"

We are on our way to launch a private testnet in Q2 2025, which will be followed by a public testnet.

Stay tuned for updates or ask specific questions in our Telegram group.

While we\u2019re working, you can get hands-on right now:

"},{"location":"resources/roadmap/#proving-schemes","title":"Proving schemes","text":"

Check the list of the proving schemes we currently support and the ones we'll work on next.

"},{"location":"tooling/","title":"\ud83e\uddf0 Tooling","text":""},{"location":"tooling/#tooling","title":"Tooling","text":"

Here, you'll find our resources about Hyl\u00e9's tooling.

"},{"location":"tooling/explorer/","title":"Explorer","text":"

Hyl\u00e9ou (a French pun for \"Il est o\u00f9\" or \"Where is it?\") is the blockchain explorer for the Hyl\u00e9 ecosystem.

The explorer is live at hyleou.hyle.eu.

The source code is available on GitHub. We welcome PRs and issues!

"},{"location":"tooling/explorer/#features","title":"Features","text":"

All features are in active development.

"},{"location":"tooling/explorer/#live-features","title":"Live features","text":"

Currently, you can:

"},{"location":"tooling/explorer/#upcoming-features","title":"Upcoming features","text":"

Planned features include:

"},{"location":"tooling/sdk/","title":"SDK","text":""},{"location":"tooling/sdk/#sdk","title":"SDK","text":"

Our contract SDK includes helper functions for building a smart contract on Hyl\u00e9.

Read more: SDK README.

"}]} \ No newline at end of file