From 2f8d9a0c11011b9f0575af130ba95f390e15f322 Mon Sep 17 00:00:00 2001 From: Rene Vergara Date: Thu, 17 Aug 2023 10:02:32 -0500 Subject: [PATCH] Documentation update --- CHANGELOG.md | 10 +++ package.yaml | 4 +- src/ZcashHaskell/Orchard.hs | 16 ++++- src/ZcashHaskell/Types.hs | 126 +++++++++++++++++++----------------- src/ZcashHaskell/Utils.hs | 13 +++- stack.yaml | 7 +- zcash-haskell.cabal | 4 +- 7 files changed, 112 insertions(+), 68 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a19bc0..ed02bc6 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/package.yaml b/package.yaml index e4bb94b..5c4a606 100644 --- a/package.yaml +++ b/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 +description: Please see the README on the repo at dependencies: - base >= 4.7 && < 5 diff --git a/src/ZcashHaskell/Orchard.hs b/src/ZcashHaskell/Orchard.hs index 4c759b2..d6bbb56 100644 --- a/src/ZcashHaskell/Orchard.hs +++ b/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 = diff --git a/src/ZcashHaskell/Types.hs b/src/ZcashHaskell/Types.hs index b4deba0..8006e01 100644 --- a/src/ZcashHaskell/Types.hs +++ b/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} - deriving stock (Prelude.Show, GHC.Generic) - deriving anyclass (SOP.Generic, SOP.HasDatatypeInfo) - deriving anyclass (Data.Structured.Show) - deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct RawData +-- | Type to represent data after Bech32 decoding +data RawData = RawData + { hrp :: BS.ByteString -- ^ Human-readable part of the Bech32 encoding + , bytes :: BS.ByteString -- ^ Decoded bytes + } 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 = - UnifiedFullViewingKey - { net :: Word8 - , o_key :: BS.ByteString - , s_key :: BS.ByteString - , t_key :: 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 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 +-- | Type to represent a Unified Full Viewing Key +data UnifiedFullViewingKey = UnifiedFullViewingKey + { net :: Word8 -- ^ Number representing the network the key belongs to. @1@ for @mainnet@, @2@ for @testnet@ and @3@ for @regtestnet@. + , 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 -- ^ Raw bytes of the Sapling Full Viewing Key as specified in [ZIP-316](https://zips.z.cash/zip-0316) + , 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 anyclass (SOP.Generic, SOP.HasDatatypeInfo) + deriving anyclass (Data.Structured.Show) + deriving (BorshSize, ToBorsh, FromBorsh) via AsStruct UnifiedFullViewingKey -data OrchardAction = - OrchardAction - { nf :: BS.ByteString - , rk :: BS.ByteString - , cmx :: BS.ByteString - , eph_key :: BS.ByteString - , enc_ciphertext :: BS.ByteString - , out_ciphertext :: BS.ByteString - , cv :: BS.ByteString - , auth :: 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 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 a Sapling Shielded Output as provided by the @getrawtransaction@ RPC method of @zcashd@. +data ShieldedOutput = ShieldedOutput + { s_cv :: BS.ByteString -- ^ Value commitment to the input note + , s_cmu :: BS.ByteString -- ^ The u-coordinate of the note commitment for the output note + , s_ephKey :: BS.ByteString -- ^ Ephemeral Jubjub public key + , s_encCipherText :: BS.ByteString -- ^ The output note encrypted to the recipient + , s_outCipherText :: BS.ByteString -- ^ A ciphertext enabling the sender to recover the output note + , s_proof :: BS.ByteString -- ^ Zero-knowledge proof using the Sapling Output circuit + } 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 +-- | 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 diff --git a/src/ZcashHaskell/Utils.hs b/src/ZcashHaskell/Utils.hs index 8c28cc9..c56a368 100644 --- a/src/ZcashHaskell/Utils.hs +++ b/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 diff --git a/stack.yaml b/stack.yaml index ce32d8f..84f9e22 100644 --- a/stack.yaml +++ b/stack.yaml @@ -17,8 +17,7 @@ # # resolver: ./custom-snapshot.yaml # resolver: https://example.com/snapshots/2018-01-01.yaml -resolver: - url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/20/17.yaml +resolver: lts-21.6 # 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: [] diff --git a/zcash-haskell.cabal b/zcash-haskell.cabal index 433f5ae..821d867 100644 --- a/zcash-haskell.cabal +++ b/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 +description: Please see the README on the repo at category: Blockchain author: Rene Vergara maintainer: rene@vergara.network