Documentation update

This commit is contained in:
Rene Vergara 2023-08-17 10:02:32 -05:00
parent ee19bc3e36
commit 2f8d9a0c11
Signed by: pitmutt
GPG key ID: 65122AD495A7F5B2
7 changed files with 112 additions and 68 deletions

View file

@ -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

View file

@ -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

View file

@ -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 =

View file

@ -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
-- | 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 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 =
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

View file

@ -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

View file

@ -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: []

View file

@ -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