Add some high level notes about rust-miniscript design #603
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
apoelstra
reviewed
Sep 27, 2023
doc/high_level_design.md
Outdated
| All the users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you know what you are doing. | ||
| * **Policy**(<span style="color:red">Red box</span>): This is the policy language for miniscript. | ||
| - It is a simple language which allows users to specify the policy for a descriptor. This simple user provided policy is referred as concrete policy. The miniscript compiler compiles this concrete policy into a descriptor. | ||
| - The policy also provides a semantic policy for analysis of descriptors and miniscript. Users can use the APIs in the module to analyze the descriptors and miniscript for various properties. |
There was a problem hiding this comment.
In 78c9df6:
I think we should say
- The policy module also provides a "semantic policy" for analysis of descriptors and miniscript. Unlike the concrete policy, which is implemented and used by other projects, the semantic policy is purely part of rust-miniscript. The APIs on this object can be used to analyze descriptors and miniscripts for various properties.
The main thing is to emphasize that there are actually two policy languages here; one is "the miniscript policy language" and the other is an analysis tool.
Arguably we should move the semantic policy out of the policy module ... and maybe rename it to Abstract which is what I originally wanted to do, but avoided because abstract (lowercase) is a reserved Rust keyword ... and maybe drop the FromStr and serde impls for it because you shouldn't ever be serializing a semantic policy.
There was a problem hiding this comment.
Agreed, we move things so that semantic policy and concrete policy are not confused.
apoelstra
approved these changes
Sep 27, 2023
tcharding
approved these changes
Sep 27, 2023
|
|
||
| As of 10.0.0 rust-miniscript is roughly divided into following components: | ||
|
|
||
| * **Miniscript Core**(<span style="color:green">Green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors. |
There was a problem hiding this comment.
Suggested change
| * **Miniscript Core**(<span style="color:green">Green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors. | |
| * **Miniscript Core** (<span style="color:green">green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors. |
| As of 10.0.0 rust-miniscript is roughly divided into following components: | ||
|
|
||
| * **Miniscript Core**(<span style="color:green">Green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors. | ||
| All the users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you know what you are doing. |
There was a problem hiding this comment.
Suggested change
| All the users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you know what you are doing. | |
| All users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you really know what you are doing. |
|
|
||
| * **Miniscript Core**(<span style="color:green">Green box</span>): This is the core of the library. It contains the core data structures and algorithms for miniscript and output descriptors. | ||
| All the users are expected to interact with the library using the descriptor APIs. Raw miniscript should be used only if you know what you are doing. | ||
| * **Policy**(<span style="color:red">Red box</span>): This module consists of _two_ separate policy languages with different purposes: |
There was a problem hiding this comment.
Suggested change
| * **Policy**(<span style="color:red">Red box</span>): This module consists of _two_ separate policy languages with different purposes: | |
| * **Policy** (<span style="color:red">red box</span>): This module consists of _two_ separate policy languages with different purposes: |
| - _Concrete Policy_: Concrete policy is a simple language which allows users to specify the policy for a descriptor. The miniscript compiler compiles this concrete policy into a descriptor. | ||
| - _Semantic Policy_: The policy module also provides a "semantic policy" for analysis of descriptors and miniscript. Unlike the concrete policy, which is implemented and used by other projects, the semantic policy is purely part of rust-miniscript. The APIs on this object can be used to analyze descriptors and miniscripts for various properties. | ||
|
|
||
| * **Psbt**(<span style="color:blue">Blue box</span>): Psbt support for descriptors. Provides several new extension APIs to interact for miniscript descriptors in a psbt including finalizer, planning, signing, descriptor updates, etc. |
There was a problem hiding this comment.
Suggested change
| * **Psbt**(<span style="color:blue">Blue box</span>): Psbt support for descriptors. Provides several new extension APIs to interact for miniscript descriptors in a psbt including finalizer, planning, signing, descriptor updates, etc. | |
| * **Psbt** (<span style="color:blue">blue box</span>): Psbt support for descriptors. Provides several new extension APIs to interact for miniscript descriptors in a psbt including finalizer, planning, signing, descriptor updates, etc. |
| - _Semantic Policy_: The policy module also provides a "semantic policy" for analysis of descriptors and miniscript. Unlike the concrete policy, which is implemented and used by other projects, the semantic policy is purely part of rust-miniscript. The APIs on this object can be used to analyze descriptors and miniscripts for various properties. | ||
|
|
||
| * **Psbt**(<span style="color:blue">Blue box</span>): Psbt support for descriptors. Provides several new extension APIs to interact for miniscript descriptors in a psbt including finalizer, planning, signing, descriptor updates, etc. | ||
| * **Interpreter**(<span style="color:yellow">Yellow box</span>): Script Interpreter for miniscript. It also provides APIs to figure out the satisfied constraints for a given transaction input. Useful for detecting which spend path the transaction output was spend with, as in the case of watchtowers or general monitoring, block explorers, etc. |
There was a problem hiding this comment.
Suggested change
| * **Interpreter**(<span style="color:yellow">Yellow box</span>): Script Interpreter for miniscript. It also provides APIs to figure out the satisfied constraints for a given transaction input. Useful for detecting which spend path the transaction output was spend with, as in the case of watchtowers or general monitoring, block explorers, etc. | |
| * **Interpreter** (<span style="color:yellow">yellow box</span>): Script interpreter for miniscript. It also provides APIs to figure out the satisfied constraints for a given transaction input. Useful for detecting which spend path the transaction output was spent with, as in the case of watchtowers or general monitoring, block explorers, etc. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Some notes to get people started. Still needs more details, but serves as a good start. In the long run, I believe, these can even be separate features with default on. This gives the option to people who really just want miniscript to use miniscript core without the policy/psbt/interpreter stuff.