Documentation update

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Haddock annotations
+
+### Changed
+
+- Upgrade to Haskell LTS 21.6
+
 ## [0.1.0] - 2023-06-14 
 
 ### Added

package.yaml

@@ -1,5 +1,5 @@
 name:                zcash-haskell
-version:             0.1.0
+version:             0.2.0
 git:                 "https://git.vergara.tech/Vergara_Tech/zcash-haskell"
 license:             BOSL
 author:              "Rene Vergara"
@@ -18,7 +18,7 @@ category:            Blockchain
 # To avoid duplicated efforts in documentation and dealing with the
 # complications of embedding Haddock markup inside cabal files, it is
 # common to point users to the README.md file.
-description:         Please see the README on the repo at <https://git.vergara.tech/Vergara_Tech/haskell-wrapper#readme>
+description:         Please see the README on the repo at <https://git.vergara.tech/Vergara_Tech/zcash-haskell#readme>
 
 dependencies:
 - base >= 4.7 && < 5

src/ZcashHaskell/Orchard.hs

@@ -1,3 +1,14 @@
+-- |
+-- Module      :  ZcashHaskell.Orchard
+-- Copyright   :  Vergara Technologies 2023
+-- License     :  BOSL
+--
+-- Maintainer  :  rene@vergara.network
+-- Stability   :  experimental
+-- Portability :  unknown
+--
+-- Functions to interact with the Orchard shielded pool of the Zcash blockchain.
+--
 module ZcashHaskell.Orchard where
 
 import C.Zcash
@@ -9,11 +20,11 @@ import qualified Data.ByteString as BS
 import Foreign.Rust.Marshall.Variable
 import ZcashHaskell.Types
 
--- | Check if given bytestring is a valid encoded unified address
+-- | Checks if given bytestring is a valid encoded unified address
 isValidUnifiedAddress :: BS.ByteString -> Bool
 isValidUnifiedAddress = rustWrapperIsUA
 
--- | Attempt to decode the given bytestring into a Unified Full Viewing Key
+-- | Attempts to decode the given bytestring into a Unified Full Viewing Key
 decodeUfvk :: BS.ByteString -> Maybe UnifiedFullViewingKey
 decodeUfvk str =
   case net decodedKey of
@@ -22,6 +33,7 @@ decodeUfvk str =
   where
     decodedKey = (withPureBorshVarBuffer . rustWrapperUfvkDecode) str
 
+-- | Attempts to decode the given @OrchardAction@ using the given @UnifiedFullViewingKey@.
 decryptOrchardAction ::
      OrchardAction -> UnifiedFullViewingKey -> Maybe OrchardDecodedAction
 decryptOrchardAction encAction key =

src/ZcashHaskell/Types.hs

@@ -3,73 +3,81 @@
 {-# LANGUAGE DerivingVia #-}
 {-# LANGUAGE UndecidableInstances #-}
 
+-- |
+-- Module      :  ZcashHaskell.Types
+-- Copyright   :  Vergara Technologies 2023
+-- License     :  BOSL
+--
+-- Maintainer  :  rene@vergara.network
+-- Stability   :  experimental
+-- Portability :  unknown
+--
+-- The types used by the ZcashHaskell library to interact with the Zcash blockchain
+--
 module ZcashHaskell.Types where
 
-import qualified Data.ByteString as BS
 import Codec.Borsh
-import Data.Word
+import qualified Data.ByteString as BS
 import Data.Int
 import Data.Structured
-import qualified Generics.SOP as SOP
+import Data.Word
 import qualified GHC.Generics as GHC
+import qualified Generics.SOP as SOP
 
-data RawData = RawData { hrp :: BS.ByteString, bytes :: BS.ByteString}
+-- | Type to represent data after Bech32 decoding
-  deriving stock (Prelude.Show, GHC.Generic)
+data RawData = RawData
-  deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
+  { hrp :: BS.ByteString -- ^ Human-readable part of the Bech32 encoding
-  deriving anyclass (Data.Structured.Show)
+  , bytes :: BS.ByteString -- ^ Decoded bytes
-  deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct RawData
+  } deriving stock (Prelude.Show, GHC.Generic)
+    deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
+    deriving anyclass (Data.Structured.Show)
+    deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct RawData
 
-data UnifiedFullViewingKey =
+-- | Type to represent a Unified Full Viewing Key
-  UnifiedFullViewingKey 
+data UnifiedFullViewingKey = UnifiedFullViewingKey
-    { net :: Word8
+  { net :: Word8 -- ^ Number representing the network the key belongs to. @1@ for @mainnet@, @2@ for @testnet@ and @3@ for @regtestnet@.
-    , o_key :: BS.ByteString
+  , o_key :: BS.ByteString -- ^ Raw bytes of the Orchard Full Viewing Key as specified in [ZIP-316](https://zips.z.cash/zip-0316)
-    , s_key :: BS.ByteString
+  , s_key :: BS.ByteString -- ^ Raw bytes of the Sapling Full Viewing Key as specified in [ZIP-316](https://zips.z.cash/zip-0316)
-    , t_key :: BS.ByteString
+  , t_key :: BS.ByteString -- ^ Raw bytes of the P2PKH chain code and public key as specified in [ZIP-316](https://zips.z.cash/zip-0316)
-    }
+  } deriving stock (Eq, Prelude.Show, GHC.Generic)
-  deriving stock (Eq, Prelude.Show, GHC.Generic)
+    deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
-  deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
+    deriving anyclass (Data.Structured.Show)
-  deriving anyclass (Data.Structured.Show)
+    deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct UnifiedFullViewingKey
-  deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct UnifiedFullViewingKey
-    
-data ShieldedOutput =
-  ShieldedOutput
-    { s_cv :: BS.ByteString
-    , s_cmu :: BS.ByteString
-    , s_ephKey :: BS.ByteString
-    , s_encCipherText :: BS.ByteString
-    , s_outCipherText :: BS.ByteString
-    , s_proof :: BS.ByteString
-    }
-  deriving stock (Eq, Prelude.Show, GHC.Generic)
-  deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
-  deriving anyclass (Data.Structured.Show)
-  deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct ShieldedOutput
 
-data OrchardAction =
+-- | Type to represent a Sapling Shielded Output as provided by the @getrawtransaction@ RPC method of @zcashd@.
-  OrchardAction
+data ShieldedOutput = ShieldedOutput
-    { nf :: BS.ByteString
+  { s_cv :: BS.ByteString -- ^ Value commitment to the input note
-    , rk :: BS.ByteString
+  , s_cmu :: BS.ByteString -- ^ The u-coordinate of the note commitment for the output note
-    , cmx :: BS.ByteString
+  , s_ephKey :: BS.ByteString -- ^ Ephemeral Jubjub public key
-    , eph_key :: BS.ByteString
+  , s_encCipherText :: BS.ByteString -- ^ The output note encrypted to the recipient
-    , enc_ciphertext :: BS.ByteString
+  , s_outCipherText :: BS.ByteString -- ^ A ciphertext enabling the sender to recover the output note
-    , out_ciphertext :: BS.ByteString
+  , s_proof :: BS.ByteString -- ^ Zero-knowledge proof using the Sapling Output circuit
-    , cv :: BS.ByteString
+  } deriving stock (Eq, Prelude.Show, GHC.Generic)
-    , auth :: BS.ByteString
+    deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
-    }
+    deriving anyclass (Data.Structured.Show)
-  deriving stock (Eq, Prelude.Show, GHC.Generic)
+    deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct ShieldedOutput
-  deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
-  deriving anyclass (Data.Structured.Show)
-  deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct OrchardAction
-
-data OrchardDecodedAction =
-  OrchardDecodedAction
-    { a_value :: Int64
-    , a_recipient :: BS.ByteString
-    , a_memo :: BS.ByteString
-    }
-  deriving stock (Eq, Prelude.Show, GHC.Generic)
-  deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
-  deriving anyclass (Data.Structured.Show)
-  deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct OrchardDecodedAction
 
+-- | Type to represent an Orchard Action as provided by the @getrawtransaction@ RPC method of @zcashd@, and defined in the [Zcash Protocol](https://zips.z.cash/protocol/protocol.pdf)
+data OrchardAction = OrchardAction
+  { nf :: BS.ByteString -- ^ The nullifier of the input note
+  , rk :: BS.ByteString -- ^ The randomized validating key for @auth@
+  , cmx :: BS.ByteString -- ^ The x-coordinate of the note commitment for the output note
+  , eph_key :: BS.ByteString -- ^ An encoding of an ephemeral Pallas public key
+  , enc_ciphertext :: BS.ByteString -- ^ The output note encrypted to the recipient
+  , out_ciphertext :: BS.ByteString -- ^ A ciphertext enabling the sender to recover the output note
+  , cv :: BS.ByteString -- ^ A value commitment to the net value of the input note minus the output note
+  , auth :: BS.ByteString -- ^ A signature authorizing the spend in this Action
+  } deriving stock (Eq, Prelude.Show, GHC.Generic)
+    deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
+    deriving anyclass (Data.Structured.Show)
+    deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct OrchardAction
 
+-- | Type to represent a decoded Orchard Action
+data OrchardDecodedAction = OrchardDecodedAction
+  { a_value :: Int64 -- ^ The amount of the transaction in _zatoshis_.
+  , a_recipient :: BS.ByteString -- ^ The recipient Orchard receiver.
+  , a_memo :: BS.ByteString -- ^ The decoded shielded memo field.
+  } deriving stock (Eq, Prelude.Show, GHC.Generic)
+    deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo)
+    deriving anyclass (Data.Structured.Show)
+    deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct OrchardDecodedAction

src/ZcashHaskell/Utils.hs

@@ -1,3 +1,14 @@
+-- |
+-- Module      :  ZcashHaskell.Utils
+-- Copyright   :  Vergara Technologies (c)2023
+-- License     :  BOSL
+--
+-- Maintainer  :  rene@vergara.network
+-- Stability   :  experimental
+-- Portability :  unknown
+--
+-- A set of functions to assist in the handling of elements of the Zcash protocol, allowing for decoding of memos, addresses and viewing keys.
+--
 module ZcashHaskell.Utils where
 
 import C.Zcash
@@ -10,7 +21,7 @@ import qualified Data.ByteString as BS
 import Foreign.Rust.Marshall.Variable
 import ZcashHaskell.Types
 
--- | Helper function to turn a hex-encoded strings to bytestring
+-- | Helper function to turn a hex-encoded string to bytestring
 decodeHexText :: String -> BS.ByteString
 decodeHexText h = BS.pack $ hexRead h
   where

stack.yaml

@@ -17,8 +17,7 @@
 #
 # resolver: ./custom-snapshot.yaml
 # resolver: https://example.com/snapshots/2018-01-01.yaml
-resolver:
+resolver: lts-21.6
-  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/20/17.yaml
 
 # User packages to be built.
 # Various formats can be used as shown in the example below.
@@ -44,6 +43,10 @@ extra-deps:
  - vector-0.13.0.0@sha256:fa5cac81a17a5af388716792e8b99c24b3b66770086756d0d8b23f8272a0244c,9112
  - aeson-2.1.2.1@sha256:f10f3c661bd5cf57aee46b94420e47736240b8e209ac15f4bfc1a4e4d55831fa,6344
  - generically-0.1.1
+ - semialign-1.2.0.1@sha256:ee3468e349e72ec0a604ae05573a4de7181d97d10366254244a0cca8a76d6c35,2852
+ - strict-0.4.0.1@sha256:d6205a748eb8db4cd17a7179be970c94598809709294ccfa43159c7f3cc4bf5d,4187
+ - these-1.1.1.1@sha256:2991c13e264b0c35c696c8f5f85c428c53bc42e93b1dfbd19a582052112d948a,2748
+ - assoc-1.0.2@sha256:9decd0933cb6b903a40a8ace02d634bf90048ee2e5b0a514dccad7056c041881,1253
 #
 # extra-deps: []
 

zcash-haskell.cabal

@@ -5,9 +5,9 @@ cabal-version: 1.12
 -- see: https://github.com/sol/hpack
 
 name:           zcash-haskell
-version:        0.1.0
+version:        0.2.0
 synopsis:       Utilities to interact with the Zcash blockchain
-description:    Please see the README on the repo at <https://git.vergara.tech/Vergara_Tech/haskell-wrapper#readme>
+description:    Please see the README on the repo at <https://git.vergara.tech/Vergara_Tech/zcash-haskell#readme>
 category:       Blockchain
 author:         Rene Vergara
 maintainer:     rene@vergara.network