Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs]: Update Transaction #1114

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

[Docs]: Update Transaction #1114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
45ebeff
Initiate structure for transaction
phklive Jan 21, 2025
79f11b5
Merge branch 'main' into phklive-docs-update-transaction
phklive Jan 29, 2025
c9cf249
Updated transaction section
phklive Jan 29, 2025
9108c96
rename from plural to singular
phklive Jan 29, 2025
0380230
Removed conclusions + Removed header for 'What is X' and replaced in …
phklive Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 1 addition & 9 deletions docs/architecture/accounts.md → docs/architecture/account.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,11 @@
# Account

> The primary entity of the Miden protocol
An `Account` represents the primary entity of the protocol. Capable of holding assets, storing data, and executing custom code. Each `Account` is a specialized smart contract providing a programmable interface for interacting with its state and assets.

## What is the purpose of an account?

In Miden's hybrid UTXO and account-based model `Account`s enable the creation of expressive smart contracts via a Turing-complete language.

## What is an account?

In Miden, an `Account` represents an entity capable of holding assets, storing data, and executing custom code. Each `Account` is a specialized smart contract providing a programmable interface for interacting with its state and managed assets.

## Account core components

An `Account` is composed of several core components, illustrated below:
Expand Down Expand Up @@ -117,7 +113,3 @@ Users can choose whether their `Account`s are stored publicly or privately. The
Only a commitment (hash) to the `Account`’s state is stored on-chain. This mode is suitable for users who prioritize privacy or plan to store a large amount of data in their `Account`. To interact with a private `Account`, a user must have knowledge of its interface.

The storage mode is chosen during `Account` creation, it cannot be changed later.

## Conclusion

You are now better equipped to understand how a Miden `Account` operates, how it manages data and assets, and how its programmable interface enables secure and flexible interactions within the Miden protocol.
10 changes: 1 addition & 9 deletions docs/architecture/assets.md → docs/architecture/asset.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Asset

> Fungible and Non-fungible assets in the Miden protocol.
An `Asset` is a unit of value that can be transferred from one [account](accounts.md) to another using [notes](notes.md).

## What is the purpose of an asset?

Expand All @@ -18,10 +18,6 @@ In Miden, `Asset`s serve as the primary means of expressing and transferring val
4. **Flexible fee payment:**
Unlike protocols that require a specific base `Asset` for fees, Miden allows users to pay fees in any supported `Asset`. This flexibility simplifies the user experience.

## What is an asset?

An `Asset` in Miden is a unit of value that can be transferred from one [account](accounts.md) to another using [notes](notes.md).

## Native asset

> All data structures following the Miden asset model that can be exchanged.
Expand Down Expand Up @@ -62,7 +58,3 @@ Non-fungible `Asset`s are encoded by hashing the `Asset` data into 32 bytes and
> All data structures not following the Miden asset model that can be exchanged.

Miden is flexible enough to support other `Asset` models. For example, developers can replicate Ethereum’s ERC20 pattern, where fungible `Asset` ownership is recorded in a single account. To transact, users send a note to that account, triggering updates in the global hashmap state.

## Conclusion

Miden’s `Asset` model provides a secure, flexible, scalable, and privacy-preserving framework for representing and transferring value. By embedding `Asset` information directly into accounts and supporting multiple `Asset` types, Miden fosters a decentralized ecosystem where users maintain their privacy, control, transactions can scale efficiently, and censorship is minimized.
10 changes: 1 addition & 9 deletions docs/architecture/notes.md → docs/architecture/note.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,11 @@
# Note

> The medium through which [Accounts](accounts.md) communicate in the Miden protocol.
A `Note` is the medium through which [Accounts](accounts.md) communicate. A `Note` holds assets and defines how they can be consumed.

## What is the purpose of a note?

In Miden's hybrid UTXO and account-based model `Note`s represent UTXO's which enable parallel transaction execution and privacy through asynchronous local `Note` production and consumption.

## What is a note?

A `Note` in Miden holds assets and defines how these assets can be consumed.

## Note core components

A `Note` is composed of several core components, illustrated below:
Expand Down Expand Up @@ -135,7 +131,3 @@ This achieves the following properties:
That means if a `Note` is private and the operator stores only the `Note`'s hash, only those with the `Note` details know if this `Note` has been consumed already. Zcash first [introduced](https://zcash.github.io/orchard/design/nullifiers.html#nullifiers) this approach.

![Architecture core concepts](../img/architecture/note/nullifier.png)

## Conclusion

Miden’s `Note` introduce a powerful mechanism for secure, flexible, and private state management. By enabling asynchronous asset transfers, parallel execution, and privacy at scale, `Note`s transcend the limitations of strictly account-based models. As a result, developers and users alike enjoy enhanced scalability, confidentiality, and control. With these capabilities, Miden is paving the way for true **programmable money** where assets, logic, and trust converge seamlessly.
10 changes: 1 addition & 9 deletions docs/architecture/state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# State

> The snapshot of all accounts, notes, nullifiers and their statuses in Miden, reflecting the “current reality” of the protocol at any given time.
The `State` describes the current condition of all accounts, notes, nullifiers and their statuses. Reflecting the “current reality” of the protocol at any given time.

## What is the purpose of the Miden state model?

Expand All @@ -17,10 +17,6 @@ Miden’s `State` model focuses on:
- **Privacy:**
By using notes and nullifiers, Miden ensures that value transfers remain confidential. Zero-knowledge proofs allow users to prove correctness without revealing sensitive information.

## What is state?

The `State` of the Miden rollup describes the current condition of all accounts and notes in the protocol; i.e., the current reality.

## State model components

The Miden node maintains three databases to describe `State`:
Expand Down Expand Up @@ -117,7 +113,3 @@ In this diagram, multiple participants interact with a common, publicly accessib
Miden nodes do not need to know the entire `State` to verify or produce new blocks. Rather than storing the full `State` data with the nodes, users keep their data locally, and the rollup stores only commitments to that data. While some contracts must remain publicly visible, this approach minimizes `State` bloat. Furthermore the Miden rollup can discard non-required data after certain conditions have been met.

This ensures that the account and note databases remain manageable, even under sustained high usage.

## Conclusion

Miden’s `State` model lays the foundation for a scalable, privacy-preserving, and user-centric environment. By combining parallelizable execution, flexible data storage, and Zero-knowledge proofs that ensure integrity and confidentiality, Miden addresses many of the challenges of traditional blockchains. As a result, the network can handle high throughput, maintain manageable `State` sizes, and support a wide range of applications.
56 changes: 56 additions & 0 deletions docs/architecture/transaction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Transaction

`Transaction`s are a mechanism by which the state of the chain is updated. That is, all changes in account and note states result from executing `Transaction`s. In Miden, `Transaction`s can originate either from the users or from the network itself.

Miden aims for the following characteristics in `Transaction`s:

- **Parallel transaction execution**: Because a transaction is always performed against a single account, Miden obtains asynchronicity.
- **Private transaction execution**: Local execution of transactions enables preservation of sensitive data.

## What is the purpose of a transaction?

In Miden, a `Transaction` represents the state transition of a single account. A `Transaction` takes a single [account](accounts.md) and zero or more [notes](notes.md), and none or one script (piece of code executed after all notes have been executed) as input, and outputs the same account with a potentially updated state, together with some potential newly created notes.

![Transaction diagram](../img/architecture/transaction/transaction-diagram.png)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me this digram is somewhat confusing. I would use something simpler (which have a simpler version in the deck). The proportions of the graphic are also off (it is too big).


## Transaction core components

WIP
Comment on lines +16 to +18
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we are missing quite a bit of information about what transactions are and what they can do and maybe this is the section this info is supposed to go to? The things we should cover (at the high level):

  • How transaction execution flows - e.g., note scripts are executed one by one, this sequence is defined by whoever crates the transaction, note scripts can call procedures exposed by the account interface - but they cannot do arbitrary things etc.
    • We could give a bit of info about things like note inputs and note args and how they affect note execution - but maybe that's too much and should go somewhere else.
  • I would explain a bit more about the transaction script and why it is needed. maybe give a couple of examples of what it is used for (same goes for notes).
  • We should also mention other interesting things about transactions - e.g., that it is possible set transaction expiration height (both accounts and notes can do this), that we can read states of other accounts in a transaction (via foreign procedure invocation).

We don't need to go into all of the above topics in depth, but we should make sure a somewhat technical person can come away with good understanding of how transactions work and what they provide.

I would also add a "real-world" example of how transactions accomplish some task - e.g., transferring funds from one account to another.


## Transaction types

There are two types of transactions in Miden: **local transactions** and **network transactions**.

![Local vs network transactions](../img/architecture/transaction/local-vs-network-transaction.png)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this comes from our deck, but this diagram is actually not correct. All steps happen in both cases - just who does them differs.


### Local transactions

This is where clients executing the transactions also generate the proofs of their correct execution. So, no additional work needs to be performed by the network.

Local transactions are useful for several reasons:

1. They are cheaper (i.e., lower fees) as zk-proofs are already generated by the clients.
2. They allow fairly complex computations because the proof size doesn't grow linearly with the complexity of the computation.
3. They enable privacy as neither the account state nor account code are needed to verify the zk-proof.
Comment on lines +28 to +34
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can improve this section to make sure it really stands out. Local transactions is something that most other chains cannot do. They basically enabled theoretically unbounded computation complexity (e.g., no more gas limits). I would also make sure that this is not just for users - apps can benefit from this too. e.g., we can have apps running their logic off-chain (either in a centralized or decentralized mode) to minimize fees, not be subject to network congestion etc.


### Network transactions

This is where the operator executes the transaction and generates the proofs.

Network transactions are useful for two reasons:

1. Clients may not have sufficient resources to generate zk-proofs.
2. Executing many transactions against the same public account by different clients is challenging, as the account state changes after every transaction. Due to this, the Miden node/operator acts as a "synchronizer" to execute transactions sequentially by feeding the output of the previous transaction into the input of the next.
Comment on lines +42 to +43
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first point is not correct - I would get rid of it. Network transactions are there basically for 2 reasons:

  1. Handling of public shared state. This is an important thing to cover somewhat in depth because after reading about local transactions, savvy developers will immediately have questions about how how public shared state works.
  2. Ensuring liveness for public accounts. This is something we haven't really covered previously, but is a pretty cool thing which would basically let the network update some accounts only during some blocks. For example, let's say for 59 minutes of every hour only some permissioned set of entities can update a given account, but every last minute of the hour, the network can do it. This way, as long as the permissioned set does what it is supposed to, the computational burden on the network is minimal. But if the permissioned set stops working, the network could still update the account (though at a much slower pace).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you clarify why the first point is not true?

I have the feeling that the second point is a very specific use case of networked tx's and does not really have it's place there. But it could be argued.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you clarify why the first point is not true?

Network transactions do not help resource-constrained clients. That is, for the network transaction to happen, the client still needs to put a note intended for this transaction on-chain. So, they still need to generate a proof for this transaction. What helps resource-constrained clients is delegated proving - but that's different from network transactions.

I have the feeling that the second point is a very specific use case of networked tx's and does not really have it's place there. But it could be argued.

Yeah, we probably don't need to describe it in such detail but maybe there is a good way to mention it in 1 - 2 sentences as an example of what network transactions could be used for.

Copy link
Contributor Author

@phklive phklive Jan 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Network transactions do not help resource-constrained clients. That is, for the network transaction to happen, the client still needs to put a note intended for this transaction on-chain. So, they still need to generate a proof for this transaction. What helps resource-constrained clients is delegated proving - but that's different from network transactions.

Does that mean that in Miden there is no way for a user to make a transaction without executing the VM and Prover?

Would a user have the ability to make a transaction like in Ethereum by simply signing a message? ( I guess this would work for public accounts but not for local / private accounts )

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does that mean that in Miden there is no way for a user to make a transaction without executing the VM and Prover?

Without executing - no, without proving, yes. That is, the user could execute a transaction but delegate proving to someone else (at the expense of giving up privacy to this someone).

Would a user have the ability to make a transaction like in Ethereum by simply signing a message? ( I guess this would work for public accounts but not for local / private accounts )

Doing something like this today would be pretty difficult. The biggest question is, what message would the user sign? For example, if we want someone else to execute a transaction on our behalf, we need to give them enough info to complete the transaction. Currently, the means a signature over a message that is derived from: initial account state, final account state, all input notes of the transaction, all output notes of a transaction. If someone can produce such a message (and a corresponding signature), then someone else can create a transaction for them.

However, building such a messages for a general transaction would mean executing the VM (to get the final state of the account and output notes). For a specialized transaction, we can probably compute these without running the VM (e.g., if we consume a P2ID note, we know how the account will be updated - so, no need to run the VM to get the account's final state).

Another option could be to re-define what is being signed (and this can be specified on per-account basis). Maybe it is enough to sign over initial account state + input notes, but this needs to be analyzed more carefully to make sure we don't open up any attack vectors.


## Transaction lifecycle

In Miden, every `Transaction` is executed within the Miden VM. Throughout its lifetime, a `Transaction` progresses through various phases:

1. **Compilation:** All `Transaction` inputs (account, notes, script) are compiled into an executable Miden program.
2. **Execution:** The `Transaction` program is executed within the Miden VM, which produces outputs (updated account, notes).
3. **Proving:** The executed `Transaction` is proven by the Miden prover.

![Transaction execution process](../img/architecture/transaction/transaction-execution-process.png)

> **Info**
> - One of the main reasons for separating out the execution and proving steps is to allow _stateless provers_; i.e., the executed transaction has all the data it needs to re-execute and prove a transaction without database access. This supports easier proof-generation distribution.
Comment on lines +45 to +56
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we need to mention compilation/execution/proving in this section - it feels like lower-level details that can be explained somewhere else. I would talk about proving costs and delegated proving though - but maybe as a part of some other section above.

84 changes: 0 additions & 84 deletions docs/architecture/transactions/contexts.md
View file
Open in desktop

This file was deleted.

45 changes: 0 additions & 45 deletions docs/architecture/transactions/execution.md
View file
Open in desktop

This file was deleted.

Loading
Loading