Merge pull request #28 from hyperledger/example-fixes

Fixes for issues found while documenting

Author: SupernaviX

Cargo.lock

@@ -1,14 +1,14 @@
 [package]
 name = "firefly-balius"
-version = "0.3.1"
+version = "0.4.0"
 description = "Helpers to write contracts for the FireFly Cardano connector"
 license-file.workspace = true
 publish = false
 edition = "2021"
 repository = "https://github.com/hyperledger/firefly-cardano"
 
 [dependencies]
-balius-sdk = { git = "https://github.com/txpipe/balius.git", rev = "2a66c8c" }
+balius-sdk = "0.3.4"
 hex = "0.4"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

firefly-balius/Cargo.toml

@@ -5,19 +5,50 @@ use serde::{Deserialize, Serialize};
 
 use crate::kv;
 
+/// A helper trait, which makes it easy to define custom events.
 pub trait EventData: Serialize {
+    /// The signature of this event.
+    /// FireFly expects this to follow a certain format based on the schema of the event. For an event with the following schema:
+    /// ```json
+    /// {
+    ///   "name": "Created",
+    ///   "params": [
+    ///     {
+    ///       "name": "from",
+    ///       "schema": {
+    ///         "type": "string"
+    ///       }
+    ///     },
+    ///     {
+    ///       "name": "value",
+    ///       "schema": {
+    ///         "type": "number"
+    ///       }
+    ///     }
+    ///   ]
+    /// }
+    /// ```
+    /// The signature should be `Created(string, number)`.
     fn signature(&self) -> String;
 }
 
+/**
+ * A custom event. Pass this to [emit_events] to send it to consumers.
+ */
 #[derive(Serialize, Deserialize)]
 pub struct Event {
+    /// The hash of the block which triggered this event.
     pub block_hash: Vec<u8>,
+    /// The hash of the transaction which triggered this event.
     pub tx_hash: Vec<u8>,
+    /// The signature of this event. See [EventData::signature] for details.
     pub signature: String,
+    /// The data attached to this event.
     pub data: serde_json::Value,
 }
 
 impl Event {
+    /// Builds a new event for the given uTXO.
     pub fn new<D, E: EventData>(utxo: &Utxo<D>, data: &E) -> WorkerResult<Self> {
         Ok(Self {
             block_hash: utxo.block_hash.clone(),
@@ -28,6 +59,7 @@ impl Event {
     }
 }
 
+/// Emits a group of custom events to the FireFly Cardano connector.
 pub fn emit_events(events: Vec<Event>) -> WorkerResult<()> {
     if events.is_empty() {
         return Ok(());

firefly-balius/src/events.rs

@@ -1,6 +1,7 @@
 use balius_sdk::{wit::balius::app::kv, WorkerResult};
 use serde::{Deserialize, Serialize};
 
+/// Retrieve a value from the KV store. Returns None if the value does not already exist.
 pub fn get<D: for<'a> Deserialize<'a>>(key: &str) -> WorkerResult<Option<D>> {
     match kv::get_value(key) {
         Ok(bytes) => Ok(Some(serde_json::from_slice(&bytes)?)),
@@ -9,6 +10,7 @@ pub fn get<D: for<'a> Deserialize<'a>>(key: &str) -> WorkerResult<Option<D>> {
     }
 }
 
+/// Store a value in the KV store.
 pub fn set<S: Serialize>(key: &str, value: &S) -> WorkerResult<()> {
     kv::set_value(key, &serde_json::to_vec(value)?)?;
     Ok(())

firefly-balius/src/kv.rs

@@ -4,6 +4,7 @@ mod logic;
 mod monitor;
 mod worker;
 
+pub use balius_sdk;
 pub use events::*;
 pub use logic::*;
 pub use monitor::*;

firefly-balius/src/lib.rs

@@ -1,42 +1,91 @@
+use std::collections::HashMap;
+
 use balius_sdk::txbuilder::{
-    primitives::TransactionInput, BuildContext, BuildError, InputExpr, UtxoSource,
+    primitives::TransactionInput, BuildContext, BuildError, InputExpr, UtxoSource, Value, ValueExpr,
 };
 
-pub struct CoinSelectionInput(pub UtxoSource, pub u64);
+/// When used in a transaction, adds a minimal set of UTXOs with at least the given value (plus fees).
+pub struct CoinSelectionInput<V: ValueExpr>(pub UtxoSource, pub V);
 
 // TODO: this is a naive approach to coin selection,
 // balius can probably help with a better one
-impl InputExpr for CoinSelectionInput {
+impl<V: ValueExpr> InputExpr for CoinSelectionInput<V> {
     fn eval(&self, ctx: &BuildContext) -> Result<Vec<TransactionInput>, BuildError> {
         let utxos = self.0.resolve(ctx)?;
+        let target_amount = self.1.eval(ctx)?;
+
         // If we know the fee, add it to the target amount.
         // If not, overestimate the fee so we pick at least as many TXOs as needed.
-        let target_lovelace = self.1
-            + if ctx.estimated_fee == 0 {
-                2_000_000
-            } else {
-                ctx.estimated_fee
-            };
+        let fee = if ctx.estimated_fee == 0 {
+            2_000_000
+        } else {
+            ctx.estimated_fee
+        };
+        let (target_lovelace, mut target_assets) = match target_amount {
+            Value::Coin(c) => (c + fee, HashMap::new()),
+            Value::Multiasset(c, assets) => {
+                let asset_map = assets
+                    .into_iter()
+                    .map(|(policy_id, assets)| {
+                        (
+                            policy_id,
+                            assets
+                                .into_iter()
+                                .map(|(name, coin)| (name.to_vec(), u64::from(coin)))
+                                .collect::<HashMap<_, _>>(),
+                        )
+                    })
+                    .collect();
+                (c + fee, asset_map)
+            }
+        };
 
         let mut inputs = vec![];
         let mut lovelace_so_far = 0;
         let mut pairs: Vec<_> = utxos.iter().collect();
         pairs.sort_by_key(|(ref_, _)| (ref_.hash, ref_.index));
         for (ref_, txo) in pairs {
             let coin = txo.value().coin();
-            if coin == 0 {
+            let mut useful = coin != 0 && lovelace_so_far < target_lovelace;
+            for policy_assets in txo.value().assets() {
+                let Some(target_policy_assets) = target_assets.get_mut(policy_assets.policy())
+                else {
+                    continue;
+                };
+                for asset in policy_assets.assets() {
+                    let Some(target_asset) = target_policy_assets.get_mut(asset.name()) else {
+                        continue;
+                    };
+                    let Some(amount) = asset.output_coin() else {
+                        continue;
+                    };
+                    if amount == 0 {
+                        continue;
+                    }
+                    useful = true;
+                    if amount < *target_asset {
+                        *target_asset -= amount;
+                    } else {
+                        target_policy_assets.remove(asset.name());
+                    }
+                }
+                if target_policy_assets.is_empty() {
+                    target_assets.remove(policy_assets.policy());
+                }
+            }
+            if !useful {
                 continue;
             }
             inputs.push(TransactionInput {
                 transaction_id: ref_.hash,
                 index: ref_.index,
             });
             lovelace_so_far += coin;
-            if lovelace_so_far >= target_lovelace {
+            if lovelace_so_far >= target_lovelace && target_assets.is_empty() {
                 break;
             }
         }
-        if lovelace_so_far >= target_lovelace {
+        if lovelace_so_far >= target_lovelace && target_assets.is_empty() {
             Ok(inputs)
         } else {
             Err(BuildError::OutputsTooHigh)

firefly-balius/src/logic.rs

@@ -5,9 +5,13 @@ use serde::{Deserialize, Serialize};
 
 use crate::kv;
 
+/// Interface which tells the framework to monitor specific transactions.
 pub struct FinalityMonitor;
 
 impl FinalityMonitor {
+    /// Tells the framework to monitor the given transaction.
+    /// The current contract will emit events when the transaction has been accepted or rolled back,
+    /// and also when it has been "finalized" (based on the condition passed here).
     pub fn monitor_tx(&self, hash: &str, condition: FinalizationCondition) -> WorkerResult<()> {
         let mut monitored_txs: HashMap<String, FinalizationCondition> =
             kv::get("__monitored_txs")?.unwrap_or_default();
@@ -17,7 +21,9 @@ impl FinalityMonitor {
     }
 }
 
+/// How to decide when a transaction has been finalized
 #[derive(Serialize, Deserialize)]
 pub enum FinalizationCondition {
-    AfterBlocks(usize),
+    // Treat the transaction as finalized after the given number of blocks have reached the chain.
+    AfterBlocks(u64),
 }

firefly-balius/src/monitor.rs

@@ -1,16 +1,18 @@
 use std::marker::PhantomData;
 
-pub use balius_sdk;
 use balius_sdk::{wit, Ack, Params, Worker, WorkerResult, _internal::Handler};
 use serde::Deserialize;
 
+/// Parameters to the [WorkerExt::with_tx_submitted_handler] callback.
 #[derive(Deserialize)]
 pub struct SubmittedTx {
+    /// The method which submitted this TX.
     pub method: String,
+    /// The hash of the submitted transaction.
     pub hash: String,
 }
 
-pub struct SubmittedTxHandler<F, C>
+struct SubmittedTxHandler<F, C>
 where
     F: Fn(C, SubmittedTx) -> WorkerResult<Ack> + 'static,
     C: TryFrom<wit::Config>,
@@ -49,12 +51,16 @@ where
     }
 }
 
+/// Helper methods on the Balius Worker.
 pub trait WorkerExt {
+    /// Register a callback to run when a transaction has been submitted.
+    /// The callback will be passed a [SubmittedTx] describing the transaction.
     fn with_tx_submitted_handler<C, F>(self, func: F) -> Self
     where
         C: TryFrom<wit::Config, Error = balius_sdk::Error> + Send + Sync + 'static,
         F: Fn(C, SubmittedTx) -> WorkerResult<Ack> + Send + Sync + 'static;
 
+    /// Register a callback to run whenever a new UTXO appears on-chain.
     fn with_new_txo_handler(self, handler: impl Handler) -> Self;
 }
 

firefly-balius/src/worker.rs

@@ -1,6 +1,6 @@
 [package]
 name = "firefly-cardanoconnect"
-version = "0.3.1"
+version = "0.4.0"
 description = "An implementation of the FireFly Connector API for Cardano"
 license-file.workspace = true
 publish = false
@@ -12,7 +12,7 @@ aide = { version = "0.14", features = ["axum", "axum-json", "axum-query"] }
 anyhow = "1"
 async-trait = "0.1"
 axum = { version = "0.8", features = ["macros", "ws"] }
-balius-runtime = { git = "https://github.com/txpipe/balius.git", rev = "2a66c8c" }
+balius-runtime = "0.3.4"
 blockfrost = { git = "https://github.com/SupernaviX/blockfrost-rust.git", rev = "cfa7a5e", default-features = false, features = ["rustls-tls"] }
 blockfrost-openapi = "0.1.69"
 clap = { version = "4", features = ["derive"] }