From 2f2706218fb6b0d0bd1b20d21925a1a15d1799fe Mon Sep 17 00:00:00 2001
From: CedarMist <134699267+CedarMist@users.noreply.github.com>
Date: Sun, 17 Sep 2023 12:10:26 +0200
Subject: [PATCH] contracts: added more documentation to subcall & consensus
 utils

---
 contracts/contracts/ConsensusUtils.sol | 24 ++++++++++++++++++++++++
 contracts/contracts/Subcall.sol        |  5 +++++
 2 files changed, 29 insertions(+)

diff --git a/contracts/contracts/ConsensusUtils.sol b/contracts/contracts/ConsensusUtils.sol
index e863561e8..058a3e2cb 100644
--- a/contracts/contracts/ConsensusUtils.sol
+++ b/contracts/contracts/ConsensusUtils.sol
@@ -4,15 +4,29 @@ pragma solidity ^0.8.0;
 
 import {sha512_256, Sapphire} from "./Sapphire.sol";
 
+// 21 byte version-prefixed address (1 byte version, 20 bytes truncated digest )
 type StakingAddress is bytes21;
 
+/// 32 byte secret key
 type StakingSecretKey is bytes32;
 
+/**
+ * @title Consensus-level utilities
+ * @dev Generate Oasis wallets for use with staking at the consensus level
+ */
 library ConsensusUtils {
+    /// The unique context for v0 staking account addresses.
+    /// https://github.com/oasisprotocol/oasis-core/blob/master/go/staking/api/address.go#L16
     string private constant ADDRESS_V0_CONTEXT_IDENTIFIER =
         "oasis-core/address: staking";
     uint8 private constant ADDRESS_V0_CONTEXT_VERSION = 0;
 
+    /**
+     * @dev Generate a random Ed25519 wallet for Oasis consensus-layer staking
+     * @param personalization Optional user-specified entropy
+     * @return publicAddress Public address of the keypair
+     * @return secretKey Secret key for the keypair
+     */
     function generateStakingAddress(bytes memory personalization)
         internal
         view
@@ -32,6 +46,10 @@ library ConsensusUtils {
         secretKey = StakingSecretKey.wrap(bytes32(sk));
     }
 
+    /**
+     * @dev Derive the staking address from the public key
+     * @param ed25519publicKey Ed25519 public key
+     */
     function _stakingAddressFromPublicKey(bytes32 ed25519publicKey)
         internal
         view
@@ -45,6 +63,12 @@ library ConsensusUtils {
             );
     }
 
+    /**
+     * @dev Derive an Oasis-style address
+     * @param contextIdentifier Domain separator
+     * @param contextVersion Domain version
+     * @param data Public point of the keypair
+     */
     function _addressFromData(
         string memory contextIdentifier,
         uint8 contextVersion,
diff --git a/contracts/contracts/Subcall.sol b/contracts/contracts/Subcall.sol
index 49db4353e..f3b6ac497 100644
--- a/contracts/contracts/Subcall.sol
+++ b/contracts/contracts/Subcall.sol
@@ -4,6 +4,10 @@ pragma solidity ^0.8.0;
 
 import {StakingAddress, StakingSecretKey} from "./ConsensusUtils.sol";
 
+/**
+ * @title SDK Subcall wrappers
+ * @dev Interact with Oasis Runtime SDK modules from Sapphire
+ */
 library Subcall {
     string private constant CONSENSUS_DELEGATE = "consensus.Delegate";
     string private constant CONSENSUS_UNDELEGATE = "consensus.Undelegate";
@@ -13,6 +17,7 @@ library Subcall {
     address internal constant SUBCALL =
         0x0100000000000000000000000000000000000103;
 
+    /// Only raised if the underlying subcall precompile does not succeed
     error Subcall_Error();
 
     /**