feat(macros): Add description field on subjects

Author: pedronauck

Cargo.lock

@@ -39,6 +39,7 @@ dotenvy = "0.15"
 futures = "0.3"
 futures-util = "0.3"
 hex = "0.4"
+indexmap = { version = "2.7.1", features = ["serde"] }
 moka = { version = "0.12.9", features = ["sync"] }
 num_cpus = "1.16"
 pretty_assertions = "1.4"

Cargo.toml

@@ -12,9 +12,15 @@ use super::types::*;
 #[subject(query_all = "blocks.>")]
 #[subject(format = "blocks.{producer}.{height}")]
 pub struct BlocksSubject {
-    #[subject(sql_column = "producer_address")]
+    #[subject(
+        sql_column = "producer_address",
+        description = "The address of the producer that created the block"
+    )]
     pub producer: Option<Address>,
-    #[subject(sql_column = "block_height")]
+    #[subject(
+        sql_column = "block_height",
+        description = "The height of the block as unsigned 64 bit integer"
+    )]
     pub height: Option<BlockHeight>,
 }
 

crates/domains/src/blocks/subjects.rs

@@ -13,13 +13,27 @@ use super::InputType;
     format = "inputs.coin.{block_height}.{tx_id}.{tx_index}.{input_index}.{owner}.{asset}"
 )]
 pub struct InputsCoinSubject {
+    #[subject(
+        description = "The height of the block containing this coin input"
+    )]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this coin input (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this input within the transaction")]
     pub input_index: Option<u32>,
-    #[subject(sql_column = "owner_id")]
+    #[subject(
+        sql_column = "owner_id",
+        description = "The address of the coin owner (32 byte string prefixed by 0x)"
+    )]
     pub owner: Option<Address>,
-    #[subject(sql_column = "asset_id")]
+    #[subject(
+        sql_column = "asset_id",
+        description = "The asset ID of the coin (32 byte string prefixed by 0x)"
+    )]
     pub asset: Option<AssetId>,
 }
 
@@ -32,11 +46,22 @@ pub struct InputsCoinSubject {
     format = "inputs.contract.{block_height}.{tx_id}.{tx_index}.{input_index}.{contract}"
 )]
 pub struct InputsContractSubject {
+    #[subject(
+        description = "The height of the block containing this contract input"
+    )]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this contract input (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this input within the transaction")]
     pub input_index: Option<u32>,
-    #[subject(sql_column = "contract_id")]
+    #[subject(
+        sql_column = "contract_id",
+        description = "The ID of the contract being called (32 byte string prefixed by 0x)"
+    )]
     pub contract: Option<ContractId>,
 }
 
@@ -49,13 +74,27 @@ pub struct InputsContractSubject {
     format = "inputs.message.{block_height}.{tx_id}.{tx_index}.{input_index}.{sender}.{recipient}"
 )]
 pub struct InputsMessageSubject {
+    #[subject(
+        description = "The height of the block containing this message input"
+    )]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this message input (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this input within the transaction")]
     pub input_index: Option<u32>,
-    #[subject(sql_column = "sender_address")]
+    #[subject(
+        sql_column = "sender_address",
+        description = "The address that sent the message (32 byte string prefixed by 0x)"
+    )]
     pub sender: Option<Address>,
-    #[subject(sql_column = "recipient_address")]
+    #[subject(
+        sql_column = "recipient_address",
+        description = "The address that will receive the message (32 byte string prefixed by 0x)"
+    )]
     pub recipient: Option<Address>,
 }
 
@@ -68,9 +107,16 @@ pub struct InputsMessageSubject {
     format = "inputs.{input_type}.{block_height}.{tx_id}.{tx_index}.{input_index}"
 )]
 pub struct InputsSubject {
+    #[subject(description = "The type of input (coin, contract, or message)")]
     pub input_type: Option<InputType>,
+    #[subject(description = "The height of the block containing this input")]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this input (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this input within the transaction")]
     pub input_index: Option<u32>,
 }

crates/domains/src/inputs/subjects.rs

@@ -13,13 +13,27 @@ use super::OutputType;
     format = "outputs.coin.{block_height}.{tx_id}.{tx_index}.{output_index}.{to}.{asset}"
 )]
 pub struct OutputsCoinSubject {
+    #[subject(
+        description = "The height of the block containing this coin output"
+    )]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this coin output (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this output within the transaction")]
     pub output_index: Option<u32>,
-    #[subject(sql_column = "to_address")]
+    #[subject(
+        sql_column = "to_address",
+        description = "The recipient address of the coin output (32 byte string prefixed by 0x)"
+    )]
     pub to: Option<Address>,
-    #[subject(sql_column = "asset_id")]
+    #[subject(
+        sql_column = "asset_id",
+        description = "The asset ID of the coin (32 byte string prefixed by 0x)"
+    )]
     pub asset: Option<AssetId>,
 }
 
@@ -32,11 +46,22 @@ pub struct OutputsCoinSubject {
     format = "outputs.contract.{block_height}.{tx_id}.{tx_index}.{output_index}.{contract}"
 )]
 pub struct OutputsContractSubject {
+    #[subject(
+        description = "The height of the block containing this contract output"
+    )]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this contract output (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this output within the transaction")]
     pub output_index: Option<u32>,
-    #[subject(sql_column = "contract_id")]
+    #[subject(
+        sql_column = "contract_id",
+        description = "The ID of the contract (32 byte string prefixed by 0x)"
+    )]
     pub contract: Option<ContractId>,
 }
 
@@ -49,13 +74,27 @@ pub struct OutputsContractSubject {
     format = "outputs.change.{block_height}.{tx_id}.{tx_index}.{output_index}.{to}.{asset}"
 )]
 pub struct OutputsChangeSubject {
+    #[subject(
+        description = "The height of the block containing this change output"
+    )]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this change output (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this output within the transaction")]
     pub output_index: Option<u32>,
-    #[subject(sql_column = "to_address")]
+    #[subject(
+        sql_column = "to_address",
+        description = "The recipient address of the change output (32 byte string prefixed by 0x)"
+    )]
     pub to: Option<Address>,
-    #[subject(sql_column = "asset_id")]
+    #[subject(
+        sql_column = "asset_id",
+        description = "The asset ID of the change output (32 byte string prefixed by 0x)"
+    )]
     pub asset: Option<AssetId>,
 }
 
@@ -68,13 +107,27 @@ pub struct OutputsChangeSubject {
     format = "outputs.variable.{block_height}.{tx_id}.{tx_index}.{output_index}.{to}.{asset}"
 )]
 pub struct OutputsVariableSubject {
+    #[subject(
+        description = "The height of the block containing this variable output"
+    )]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this variable output (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this output within the transaction")]
     pub output_index: Option<u32>,
-    #[subject(sql_column = "to_address")]
+    #[subject(
+        sql_column = "to_address",
+        description = "The recipient address of the variable output (32 byte string prefixed by 0x)"
+    )]
     pub to: Option<Address>,
-    #[subject(sql_column = "asset_id")]
+    #[subject(
+        sql_column = "asset_id",
+        description = "The asset ID of the variable output (32 byte string prefixed by 0x)"
+    )]
     pub asset: Option<AssetId>,
 }
 
@@ -87,11 +140,22 @@ pub struct OutputsVariableSubject {
     format = "outputs.contract_created.{block_height}.{tx_id}.{tx_index}.{output_index}.{contract}"
 )]
 pub struct OutputsContractCreatedSubject {
+    #[subject(
+        description = "The height of the block containing this contract creation output"
+    )]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this contract creation output (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this output within the transaction")]
     pub output_index: Option<u32>,
-    #[subject(sql_column = "contract_id")]
+    #[subject(
+        sql_column = "contract_id",
+        description = "The ID of the created contract (32 byte string prefixed by 0x)"
+    )]
     pub contract: Option<ContractId>,
 }
 
@@ -104,9 +168,18 @@ pub struct OutputsContractCreatedSubject {
     format = "outputs.{output_type}.{block_height}.{tx_id}.{tx_index}.{output_index}"
 )]
 pub struct OutputsSubject {
+    #[subject(
+        description = "The type of output (coin, contract, change, variable, or contract_created)"
+    )]
     pub output_type: Option<OutputType>,
+    #[subject(description = "The height of the block containing this output")]
     pub block_height: Option<BlockHeight>,
+    #[subject(
+        description = "The ID of the transaction containing this output (32 byte string prefixed by 0x)"
+    )]
     pub tx_id: Option<TxId>,
+    #[subject(description = "The index of the transaction within the block")]
     pub tx_index: Option<u32>,
+    #[subject(description = "The index of this output within the transaction")]
     pub output_index: Option<u32>,
 }