Kernel: Add functions for working with outpoints

This introduces the transaction outpoint, input and id types. This now
allows a user to retrieve a transaction output from a prior transaction
that a transaction outpoint is pointing to by either scanning through
all available transactions, or maintaining a data structure for lookups.

This is exercised in the tests by verifying the script of every
transaction in the test chain.

Author: TheCharlatan

src/kernel/bitcoinkernel.cpp

@@ -491,6 +491,9 @@ struct btck_BlockSpentOutputs : Handle<btck_BlockSpentOutputs, std::shared_ptr<C
 struct btck_TransactionSpentOutputs : Handle<btck_TransactionSpentOutputs, CTxUndo> {};
 struct btck_Coin : Handle<btck_Coin, Coin> {};
 struct btck_BlockHash : Handle<btck_BlockHash, uint256> {};
+struct btck_TransactionInput : Handle<btck_TransactionInput, CTxIn> {};
+struct btck_TransactionOutPoint: Handle<btck_TransactionOutPoint, COutPoint> {};
+struct btck_Txid: Handle<btck_Txid, Txid> {};
 
 btck_Transaction* btck_transaction_create(const void* raw_transaction, size_t raw_transaction_len)
 {
@@ -519,6 +522,17 @@ size_t btck_transaction_count_inputs(const btck_Transaction* transaction)
     return btck_Transaction::get(transaction)->vin.size();
 }
 
+const btck_TransactionInput* btck_transaction_get_input_at(const btck_Transaction* transaction, size_t input_index)
+{
+    assert(input_index < btck_Transaction::get(transaction)->vin.size());
+    return btck_TransactionInput::ref(&btck_Transaction::get(transaction)->vin[input_index]);
+}
+
+const btck_Txid* btck_transaction_get_txid(const btck_Transaction* transaction)
+{
+    return btck_Txid::ref(&btck_Transaction::get(transaction)->GetHash());
+}
+
 btck_Transaction* btck_transaction_copy(const btck_Transaction* transaction)
 {
     return btck_Transaction::copy(transaction);
@@ -637,6 +651,60 @@ int btck_script_pubkey_verify(const btck_ScriptPubkey* script_pubkey,
     return result ? 1 : 0;
 }
 
+btck_TransactionInput* btck_transaction_input_copy(const btck_TransactionInput* input)
+{
+    return btck_TransactionInput::copy(input);
+}
+
+const btck_TransactionOutPoint* btck_transaction_input_get_out_point(const btck_TransactionInput* input)
+{
+    return btck_TransactionOutPoint::ref(&btck_TransactionInput::get(input).prevout);
+}
+
+void btck_transaction_input_destroy(btck_TransactionInput* input)
+{
+    delete input;
+}
+
+btck_TransactionOutPoint* btck_transaction_out_point_copy(const btck_TransactionOutPoint* out_point)
+{
+    return btck_TransactionOutPoint::copy(out_point);
+}
+
+uint32_t btck_transaction_out_point_get_index(const btck_TransactionOutPoint* out_point)
+{
+    return btck_TransactionOutPoint::get(out_point).n;
+}
+
+const btck_Txid* btck_transaction_out_point_get_txid(const btck_TransactionOutPoint* out_point)
+{
+    return btck_Txid::ref(&btck_TransactionOutPoint::get(out_point).hash);
+}
+
+void btck_transaction_out_point_destroy(btck_TransactionOutPoint* out_point)
+{
+    delete out_point;
+}
+
+btck_Txid* btck_txid_copy(const btck_Txid* txid)
+{
+    return btck_Txid::copy(txid);
+}
+
+void btck_txid_to_bytes(const btck_Txid* txid, unsigned char output[32])
+{
+    std::memcpy(output, btck_Txid::get(txid).begin(), 32);
+}
+
+int btck_txid_equals(const btck_Txid* txid1, const btck_Txid* txid2)
+{
+    return btck_Txid::get(txid1) == btck_Txid::get(txid2);
+}
+
+void btck_txid_destroy(btck_Txid* txid)
+{
+    delete txid;
+}
 
 void btck_logging_set_options(const btck_LoggingOptions options)
 {

src/kernel/bitcoinkernel.h

@@ -249,6 +249,22 @@ typedef struct btck_Coin btck_Coin;
  */
 typedef struct btck_BlockHash btck_BlockHash;
 
+/**
+ * Opaque data structure for holding a transaction input.
+ *
+ * Holds information on the @ref btck_TransactionOutPoint held within.
+ */
+typedef struct btck_TransactionInput btck_TransactionInput;
+
+/**
+ * Opaque data structure for holding a transaction out point.
+ *
+ * Holds the txid and output index it is pointing to.
+ */
+typedef struct btck_TransactionOutPoint btck_TransactionOutPoint;
+
+typedef struct btck_Txid btck_Txid;
+
 /** Current sync state passed to tip changed callbacks. */
 typedef uint8_t btck_SynchronizationState;
 #define btck_SynchronizationState_INIT_REINDEX ((btck_SynchronizationState)(0))
@@ -498,6 +514,18 @@ BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count
 BITCOINKERNEL_API const btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_output_at(
     const btck_Transaction* transaction, size_t output_index) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Get the transaction input at the provided index. The returned
+ * transaction input is not owned and depends on the lifetime of the
+ * transaction.
+ *
+ * @param[in] transaction Non-null.
+ * @param[in] input_index The index of the transaction input to be retrieved.
+ * @return                 The transaction input
+ */
+BITCOINKERNEL_API const btck_TransactionInput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_input_at(
+    const btck_Transaction* transaction, size_t input_index) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * @brief Get the number of inputs of a transaction.
  *
@@ -507,6 +535,16 @@ BITCOINKERNEL_API const btck_TransactionOutput* BITCOINKERNEL_WARN_UNUSED_RESULT
 BITCOINKERNEL_API size_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_count_inputs(
     const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
 
+/**
+ * @brief Get the txid of a transaction. The returned txid is not owned and
+ * depends on the lifetime of the transaction.
+ *
+ * @param[in] transaction Non-null.
+ * @return                The txid.
+ */
+BITCOINKERNEL_API const btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_get_txid(
+    const btck_Transaction* transaction) BITCOINKERNEL_ARG_NONNULL(1);
+
 /**
  * Destroy the transaction.
  */
@@ -1313,6 +1351,119 @@ BITCOINKERNEL_API void btck_transaction_spent_outputs_destroy(btck_TransactionSp
 
 ///@}
 
+/** @name Transaction Input
+ * Functions for working with transaction inputs.
+ */
+///@{
+
+/**
+ * @brief Copy a transaction input.
+ *
+ * @param[in] transaction_input Non-null.
+ * @return                      The copied transaction input.
+ */
+BITCOINKERNEL_API btck_TransactionInput* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_copy(
+    const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the transaction out point. The returned transaction out point is
+ * not owned and depends on the lifetime of the transaction.
+ *
+ * @param[in] transaction_input Non-null.
+ * @return                      The transaction out point.
+ */
+BITCOINKERNEL_API const btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_input_get_out_point(
+    const btck_TransactionInput* transaction_input) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the transaction input.
+ */
+BITCOINKERNEL_API void btck_transaction_input_destroy(btck_TransactionInput* transaction_input);
+
+///@}
+
+/** @name Transaction Out Point
+ * Functions for working with transaction out points.
+ */
+///@{
+
+/**
+ * @brief Copy a transaction out point.
+ *
+ * @param[in] transaction_out_point Non-null.
+ * @return                          The copied transaction out point.
+ */
+BITCOINKERNEL_API btck_TransactionOutPoint* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_copy(
+    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the output position from the transaction out point.
+ *
+ * @param[in] transaction_out_point Non-null.
+ * @return                          The output index.
+ */
+BITCOINKERNEL_API uint32_t BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_get_index(
+    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Get the txid from the transaction out point. The returned txid is
+ * not owned and depends on the lifetime of the transaction out point.
+ *
+ * @param[in] transaction_out_point Non-null.
+ * @return                          The txid.
+ */
+BITCOINKERNEL_API const btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_transaction_out_point_get_txid(
+    const btck_TransactionOutPoint* transaction_out_point) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * Destroy the transaction out point.
+ */
+BITCOINKERNEL_API void btck_transaction_out_point_destroy(btck_TransactionOutPoint* transaction_out_point);
+
+///@}
+
+/** @name Txid
+ * Functions for working with txids.
+ */
+///@{
+
+/**
+ * @brief Copy a txid.
+ *
+ * @param[in] txid Non-null.
+ * @return         The copied txid.
+ */
+BITCOINKERNEL_API btck_Txid* BITCOINKERNEL_WARN_UNUSED_RESULT btck_txid_copy(
+    const btck_Txid* txid) BITCOINKERNEL_ARG_NONNULL(1);
+
+/**
+ * @brief Check if two txids are equal.
+ *
+ * @param[in] txid1 Non-null.
+ * @param[in] txid2 Non-null.
+ * @return          0 if the txid is not equal.
+ */
+BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_txid_equals(
+    const btck_Txid* txid1, const btck_Txid* txid2) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Serializes the txid to bytes.
+ *
+ * @param[in] txid    Non-null.
+ * @param[out] output The serialized txid.
+ */
+BITCOINKERNEL_API void btck_txid_to_bytes(
+    const btck_Txid* txid, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2);
+
+/**
+ * Destroy the txid.
+ */
+BITCOINKERNEL_API void btck_txid_destroy(btck_Txid* txid);
+
+///@}
+
+///@}
+
 /** @name Coin
  * Functions for working with coins.
  */
@@ -1328,7 +1479,8 @@ BITCOINKERNEL_API btck_Coin* BITCOINKERNEL_WARN_UNUSED_RESULT btck_coin_copy(
     const btck_Coin* coin) BITCOINKERNEL_ARG_NONNULL(1);
 
 /**
- * @brief Returns the height of the block that contains the coin's prevout.
+ * @brief Returns the block height where the transaction that
+ * created this coin was included in.
  *
  * @param[in] coin Non-null.
  * @return         The block height of the coin.