Merge pull request #58 from Rigidity/documentation

Documentation and some structural changes

Author: Rigidity

Cargo.toml

@@ -21,12 +21,12 @@ keywords = ["chia", "wallet", "blockchain", "crypto"]
 categories = ["cryptography::cryptocurrencies", "development-tools"]
 
 [workspace.lints.rust]
+rust_2018_idioms = { level = "deny", priority = -1 }
+rust_2021_compatibility = { level = "deny", priority = -1 }
+future_incompatible = { level = "deny", priority = -1 }
+nonstandard_style = { level = "deny", priority = -1 }
 unsafe_code = "deny"
-rust_2018_idioms = "deny"
-rust_2021_compatibility = "deny"
-future_incompatible = "deny"
 non_ascii_idents = "deny"
-nonstandard_style = "deny"
 unused_extern_crates = "deny"
 trivial_casts = "deny"
 trivial_numeric_casts = "deny"
@@ -44,7 +44,7 @@ all = { level = "deny", priority = -1 }
 missing_crate_level_docs = "allow"
 
 [workspace.lints.clippy]
-all = "deny"
+all = { level = "deny", priority = -1 }
 cargo = { level = "warn", priority = -1 }
 pedantic = { level = "warn", priority = -1 }
 too_many_lines = "allow"

crates/chia-sdk-driver/docs.md

@@ -0,0 +1,42 @@
+## Puzzles
+
+Chia coins have a puzzle, which controls how it can be spent.
+The solution is used as the arguments to the puzzle, and the
+output is a list of [`Conditions`].
+
+A puzzle consists of multiple layers composed together.
+
+## Layers
+
+A [`Layer`] is a subset of the logic that makes up a smart coin in Chia.
+They are also referred to as "inner puzzles", and the solution can be broken
+up into "inner solutions" as well.
+
+Generally, you can parse and construct the individual layers separately.
+This allows them to be composed together freely. However, there are sometimes
+additional restraints which limit the ways they can be mixed. For example,
+the [`CatLayer`] cannot have another [`CatLayer`] as its inner puzzle, due to the
+way it's written. This would create an error when validating the announcements.
+
+### P2 Puzzles
+
+A p2 puzzle (meaning "pay to") controls the ownership of the coin.
+The simplest example of this is [`p2_conditions.clsp`], which requires a signature
+from a single public key and outputs a list of conditions from the solution.
+
+The "standard transaction" (which is [`p2_delegated_puzzle_or_hidden_puzzle.clsp`])
+is a kind of p2 puzzle that adds additional flexibility. Specifically, support
+for an inner puzzle, and usage of a delegated puzzle instead of directly conditions.
+
+Generally, the p2 puzzle is the base layer in a coin's puzzle, and everything
+else builds on top of it to restrict the way it can be spent or attach state.
+
+## Primitives
+
+A [`Primitive`] uses one or more [`Layer`] to parse info from a parent's coin spend.
+Generally, [`Layer`] has the ability to parse and construct individual puzzles and solutions,
+and the composed [`Primitive`] struct can parse all of the information required to spend a coin.
+The [`Primitive`] should also provide a way to spend the coin, and other utilities necessary.
+
+[`p2_conditions.clsp`]: https://github.com/Chia-Network/chia-blockchain/blob/bd022b0c9b0d3e0bc13a0efebba9f22417ca64b5/chia/wallet/puzzles/p2_conditions.clsp
+[`p2_delegated_puzzle_or_hidden_puzzle.clsp`]: https://github.com/Chia-Network/chia-blockchain/blob/bd022b0c9b0d3e0bc13a0efebba9f22417ca64b5/chia/wallet/puzzles/p2_delegated_puzzle_or_hidden_puzzle.clsp

crates/chia-sdk-driver/src/layers/cat_layer.rs

@@ -6,9 +6,13 @@ use clvmr::{Allocator, NodePtr};
 
 use crate::{DriverError, Layer, Puzzle, SpendContext};
 
-#[derive(Debug)]
+/// The CAT [`Layer`] enforces restrictions on the supply of a token.
+/// Specifically, unless the TAIL program is run, the supply cannot change.
+#[derive(Debug, Clone, Copy)]
 pub struct CatLayer<I> {
+    /// The asset id of the CAT token. This is the tree hash of the TAIL program.
     pub asset_id: Bytes32,
+    /// The inner puzzle layer, commonly used for determining ownership.
     pub inner_puzzle: I,
 }
 

crates/chia-sdk-driver/src/layers/did_layer.rs

@@ -1,33 +1,41 @@
 use chia_protocol::Bytes32;
 use chia_puzzles::{
     did::{DidArgs, DidSolution, DID_INNER_PUZZLE_HASH},
-    singleton::SingletonStruct,
+    singleton::{SingletonStruct, SINGLETON_LAUNCHER_PUZZLE_HASH, SINGLETON_TOP_LAYER_PUZZLE_HASH},
 };
 use clvm_traits::{FromClvm, ToClvm};
 use clvm_utils::{CurriedProgram, ToTreeHash, TreeHash};
 use clvmr::{Allocator, NodePtr};
 
 use crate::{DriverError, Layer, Puzzle, SpendContext};
 
+/// The DID [`Layer`] keeps track of metadata and handles recovery capabilities.
+/// It's typically an inner layer of the [`SingletonLayer`](crate::SingletonLayer).
 #[derive(Debug)]
 pub struct DidLayer<M, I> {
-    pub singleton_struct: SingletonStruct,
+    /// The unique launcher id for the DID. Also referred to as the DID id.
+    pub launcher_id: Bytes32,
+    /// The tree hash of a list of recovery DIDs.
+    /// Note that this is currently *not* optional, but will be in the future.
     pub recovery_list_hash: Bytes32,
+    /// The number of verifications required to recover the DID.
     pub num_verifications_required: u64,
+    /// Metadata associated with the DID. This is often just `()` for DIDs without metadata.
     pub metadata: M,
+    /// The inner puzzle layer, commonly used for determining ownership.
     pub inner_puzzle: I,
 }
 
 impl<M, I> DidLayer<M, I> {
     pub fn new(
-        singleton_struct: SingletonStruct,
+        launcher_id: Bytes32,
         recovery_list_hash: Bytes32,
         num_verifications_required: u64,
         metadata: M,
         inner_puzzle: I,
     ) -> Self {
         Self {
-            singleton_struct,
+            launcher_id,
             recovery_list_hash,
             num_verifications_required,
             metadata,
@@ -54,14 +62,20 @@ where
 
         let args = DidArgs::<NodePtr, M>::from_clvm(allocator, puzzle.args)?;
 
+        if args.singleton_struct.mod_hash != SINGLETON_TOP_LAYER_PUZZLE_HASH.into()
+            || args.singleton_struct.launcher_puzzle_hash != SINGLETON_LAUNCHER_PUZZLE_HASH.into()
+        {
+            return Err(DriverError::InvalidSingletonStruct);
+        }
+
         let Some(inner_puzzle) =
             I::parse_puzzle(allocator, Puzzle::parse(allocator, args.inner_puzzle))?
         else {
             return Ok(None);
         };
 
         Ok(Some(Self {
-            singleton_struct: args.singleton_struct,
+            launcher_id: args.singleton_struct.launcher_id,
             recovery_list_hash: args.recovery_list_hash,
             num_verifications_required: args.num_verifications_required,
             metadata: args.metadata,
@@ -89,7 +103,7 @@ where
                 self.inner_puzzle.construct_puzzle(ctx)?,
                 self.recovery_list_hash,
                 self.num_verifications_required,
-                self.singleton_struct,
+                SingletonStruct::new(self.launcher_id),
                 &self.metadata,
             ),
         };
@@ -125,7 +139,7 @@ where
             inner_puzzle_hash,
             self.recovery_list_hash,
             self.num_verifications_required,
-            self.singleton_struct,
+            SingletonStruct::new(self.launcher_id),
             metadata_hash,
         )
     }

crates/chia-sdk-driver/src/layers/nft_ownership_layer.rs

@@ -10,8 +10,11 @@ use crate::{DriverError, Layer, Puzzle, SpendContext};
 
 #[derive(Debug)]
 pub struct NftOwnershipLayer<T, I> {
+    /// The DID owner of this NFT, if it's currently assigned to one.
     pub current_owner: Option<Bytes32>,
+    /// The transfer layer, which is used to transfer ownership of the NFT.
     pub transfer_layer: T,
+    /// The inner puzzle layer, commonly used for determining ownership.
     pub inner_puzzle: I,
 }
 

crates/chia-sdk-driver/src/layers/nft_state_layer.rs

@@ -1,6 +1,5 @@
 use chia_protocol::Bytes32;
 use chia_puzzles::nft::{NftStateLayerArgs, NftStateLayerSolution, NFT_STATE_LAYER_PUZZLE_HASH};
-use chia_sdk_types::{run_puzzle, NewMetadataCondition, NewMetadataOutput};
 use clvm_traits::{FromClvm, ToClvm};
 use clvm_utils::{CurriedProgram, ToTreeHash, TreeHash};
 use clvmr::{Allocator, NodePtr};
@@ -9,8 +8,12 @@ use crate::{DriverError, Layer, Puzzle, SpendContext};
 
 #[derive(Debug)]
 pub struct NftStateLayer<M, I> {
+    /// The NFT metadata. The standard metadata type is [`NftMetadata`](chia_puzzles::nft::NftMetadata).
     pub metadata: M,
+    /// The tree hash of the metadata updater puzzle.
     pub metadata_updater_puzzle_hash: Bytes32,
+    /// The inner puzzle layer. Typically, this is the [`NftOwnershipLayer`](crate::NftOwnershipLayer).
+    /// However, for the NFT0 standard this can be the p2 layer itself.
     pub inner_puzzle: I,
 }
 
@@ -114,40 +117,3 @@ where
         .tree_hash()
     }
 }
-
-impl<M, IP> NftStateLayer<M, IP>
-where
-    M: FromClvm<Allocator>,
-{
-    pub fn new_metadata_and_updater_from_conditions(
-        allocator: &mut Allocator,
-        inner_layer_puzzle: NodePtr,
-        inner_layer_solution: NodePtr,
-    ) -> Result<Option<(M, Bytes32)>, DriverError> {
-        let output = run_puzzle(allocator, inner_layer_puzzle, inner_layer_solution)?;
-
-        let conditions = Vec::<NodePtr>::from_clvm(allocator, output)?;
-
-        for condition in conditions {
-            let condition =
-                NewMetadataCondition::<NodePtr, NodePtr>::from_clvm(allocator, condition);
-
-            if let Ok(condition) = condition {
-                let output = run_puzzle(
-                    allocator,
-                    condition.metadata_updater_reveal,
-                    condition.metadata_updater_solution,
-                )?;
-
-                let output = NewMetadataOutput::<M, NodePtr>::from_clvm(allocator, output)?;
-
-                return Ok(Some((
-                    output.metadata_part.new_metadata,
-                    output.metadata_part.new_metadata_updater_puzhash,
-                )));
-            }
-        }
-
-        Ok(None)
-    }
-}

crates/chia-sdk-driver/src/layers/royalty_transfer_layer.rs

@@ -3,7 +3,7 @@ use std::convert::Infallible;
 use chia_protocol::Bytes32;
 use chia_puzzles::{
     nft::{NftRoyaltyTransferPuzzleArgs, NFT_ROYALTY_TRANSFER_PUZZLE_HASH},
-    singleton::SingletonStruct,
+    singleton::{SingletonStruct, SINGLETON_LAUNCHER_PUZZLE_HASH, SINGLETON_TOP_LAYER_PUZZLE_HASH},
 };
 use clvm_traits::FromClvm;
 use clvm_utils::CurriedProgram;
@@ -13,19 +13,23 @@ use crate::{DriverError, Layer, Puzzle, SpendContext};
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct RoyaltyTransferLayer {
-    pub singleton_struct: SingletonStruct,
+    /// The launcher id of the NFT this transfer program belongs to.
+    pub launcher_id: Bytes32,
+    /// The puzzle hash that receives royalties paid when transferring this NFT.
     pub royalty_puzzle_hash: Bytes32,
+    /// The percentage of the transfer amount that is paid as royalties.
+    /// This is represented in ten thousandths, so a value of 300 means 3%.
     pub royalty_ten_thousandths: u16,
 }
 
 impl RoyaltyTransferLayer {
     pub fn new(
-        singleton_struct: SingletonStruct,
+        launcher_id: Bytes32,
         royalty_puzzle_hash: Bytes32,
         royalty_ten_thousandths: u16,
     ) -> Self {
         Self {
-            singleton_struct,
+            launcher_id,
             royalty_puzzle_hash,
             royalty_ten_thousandths,
         }
@@ -39,7 +43,7 @@ impl Layer for RoyaltyTransferLayer {
         let curried = CurriedProgram {
             program: ctx.nft_royalty_transfer()?,
             args: NftRoyaltyTransferPuzzleArgs {
-                singleton_struct: self.singleton_struct,
+                singleton_struct: SingletonStruct::new(self.launcher_id),
                 royalty_puzzle_hash: self.royalty_puzzle_hash,
                 royalty_ten_thousandths: self.royalty_ten_thousandths,
             },
@@ -58,8 +62,14 @@ impl Layer for RoyaltyTransferLayer {
 
         let args = NftRoyaltyTransferPuzzleArgs::from_clvm(allocator, puzzle.args)?;
 
+        if args.singleton_struct.mod_hash != SINGLETON_TOP_LAYER_PUZZLE_HASH.into()
+            || args.singleton_struct.launcher_puzzle_hash != SINGLETON_LAUNCHER_PUZZLE_HASH.into()
+        {
+            return Err(DriverError::InvalidSingletonStruct);
+        }
+
         Ok(Some(Self {
-            singleton_struct: args.singleton_struct,
+            launcher_id: args.singleton_struct.launcher_id,
             royalty_puzzle_hash: args.royalty_puzzle_hash,
             royalty_ten_thousandths: args.royalty_ten_thousandths,
         }))

crates/chia-sdk-driver/src/layers/singleton_layer.rs

@@ -1,3 +1,4 @@
+use chia_protocol::Bytes32;
 use chia_puzzles::singleton::{
     SingletonArgs, SingletonSolution, SingletonStruct, SINGLETON_LAUNCHER_PUZZLE_HASH,
     SINGLETON_TOP_LAYER_PUZZLE_HASH,
@@ -10,14 +11,16 @@ use crate::{DriverError, Layer, Puzzle, SpendContext};
 
 #[derive(Debug)]
 pub struct SingletonLayer<I> {
-    pub singleton_struct: SingletonStruct,
+    /// The unique launcher id for the singleton. Also referred to as the singleton id.
+    pub launcher_id: Bytes32,
+    /// The inner puzzle layer. For singletons, this determines the actual behavior of the coin.
     pub inner_puzzle: I,
 }
 
 impl<I> SingletonLayer<I> {
-    pub fn new(singleton_struct: SingletonStruct, inner_puzzle: I) -> Self {
+    pub fn new(launcher_id: Bytes32, inner_puzzle: I) -> Self {
         Self {
-            singleton_struct,
+            launcher_id,
             inner_puzzle,
         }
     }
@@ -53,7 +56,7 @@ where
         };
 
         Ok(Some(Self {
-            singleton_struct: args.singleton_struct,
+            launcher_id: args.singleton_struct.launcher_id,
             inner_puzzle,
         }))
     }
@@ -75,7 +78,7 @@ where
         let curried = CurriedProgram {
             program: ctx.singleton_top_layer()?,
             args: SingletonArgs {
-                singleton_struct: self.singleton_struct,
+                singleton_struct: SingletonStruct::new(self.launcher_id),
                 inner_puzzle: self.inner_puzzle.construct_puzzle(ctx)?,
             },
         };
@@ -105,7 +108,7 @@ where
     fn tree_hash(&self) -> TreeHash {
         let inner_puzzle = self.inner_puzzle.tree_hash();
         SingletonArgs {
-            singleton_struct: self.singleton_struct,
+            singleton_struct: SingletonStruct::new(self.launcher_id),
             inner_puzzle,
         }
         .tree_hash()

crates/chia-sdk-driver/src/lib.rs

@@ -1,40 +1,4 @@
-//! ## Puzzles
-//!
-//! Chia coins have a puzzle, which controls how it can be spent.
-//! The solution is used as the arguments to the puzzle, and the
-//! output is a list of [`Conditions`].
-//!
-//! A puzzle consists of multiple layers composed together.
-//!
-//! ## Layers
-//!
-//! A [`Layer`] is a subset of the logic that makes up a smart coin in Chia.
-//! They are also referred to as "inner puzzles", and the solution can be broken
-//! up into "inner solutions" as well.
-//!
-//! Generally, you can parse and construct the individual layers separately.
-//! This allows them to be composed together freely. However, there are sometimes
-//! additional restraints which limit the ways they can be mixed. For example,
-//! the [`CatLayer`] cannot have another [`CatLayer`] as its inner puzzle, due to the
-//! way it's written. This would create an error when validating the announcements.
-//!
-//! ### P2 Layer
-//!
-//! A p2 puzzle (meaning "pay to") controls the ownership of the coin.
-//! The simplest example of this is [`p2_conditions.clsp`], which requires a signature
-//! from a single public key and outputs a list of conditions from the solution.
-//!
-//! The "standard transaction" (which is [`p2_delegated_puzzle_or_hidden_puzzle.clsp`])
-//! is a kind of p2 puzzle that adds additional flexibility. Specifically, support
-//! for an inner puzzle, and usage of a delegated puzzle instead of directly conditions.
-//!
-//! Generally, the p2 puzzle is the base layer in a coin's puzzle, and everything
-//! else builds on top of it to restrict the way it can be spent or attach state.
-//!
-//! ## Primitives
-//!
-//! [`p2_conditions.clsp`]: https://github.com/Chia-Network/chia-blockchain/blob/bd022b0c9b0d3e0bc13a0efebba9f22417ca64b5/chia/wallet/puzzles/p2_conditions.clsp
-//! [`p2_delegated_puzzle_or_hidden_puzzle.clsp`]: https://github.com/Chia-Network/chia-blockchain/blob/bd022b0c9b0d3e0bc13a0efebba9f22417ca64b5/chia/wallet/puzzles/p2_delegated_puzzle_or_hidden_puzzle.clsp
+#![doc = include_str!("../docs.md")]
 
 mod conditions;
 mod driver_error;