Add C header

rustdoc

op-service/rethdb-reader/README.md

 # `rethdb-reader`
 
-Exported Rust code to be used via FFI in `op-service`'s `sources` package for reading information
+A dylib to be accessed via FFI in `op-service`'s `sources` package for reading information
 directly from the `reth` database.
+
+### C Header
+
+```c
+#include <cstdarg>
+#include <cstdint>
+#include <cstdlib>
+#include <ostream>
+#include <new>
+
+struct ReceiptsResult {
+  uint32_t *data;
+  uintptr_t data_len;
+  bool error;
+};
+
+extern "C" {
+
+/// Read the receipts for a blockhash from the RETH database directly.
+///
+/// # Safety
+/// - All possible nil pointer dereferences are checked, and the function will return a
+///   failing [ReceiptsResult] if any are found.
+ReceiptsResult read_receipts(const uint8_t *block_hash,
+                             uintptr_t block_hash_len,
+                             const char *db_path);
+
+/// Free a string that was allocated in Rust and passed to C.
+///
+/// # Safety
+/// - All possible nil pointer dereferences are checked.
+void free_string(char *string);
+
+}
+```

op-service/rethdb-reader/src/lib.rs

+#![doc = include_str!("../README.md")]
+
 use reth::{
     blockchain_tree::noop::NoopBlockchainTree,
     primitives::{
@@ -10,6 +12,12 @@ use reth::{
 };
 use std::{os::raw::c_char, path::Path};
 
+/// A [ReceiptsResult] is a wrapper around a JSON string containing serialized [TransactionReceipt]s
+/// as well as an error status that is compatible with FFI.
+///
+/// # Safety
+/// - When the `error` field is false, the `data` pointer is guaranteed to be valid.
+/// - When the `error` field is true, the `data` pointer is guaranteed to be null.
 #[repr(C)]
 pub struct ReceiptsResult {
     data: *mut char,
@@ -18,6 +26,7 @@ pub struct ReceiptsResult {
 }
 
 impl ReceiptsResult {
+    /// Constructs a successful [ReceiptsResult] from a JSON string.
     pub fn success(data: *mut char, data_len: usize) -> Self {
         Self {
             data,
@@ -26,6 +35,7 @@ impl ReceiptsResult {
         }
     }
 
+    /// Constructs a failing [ReceiptsResult] with a null pointer to the data.
     pub fn fail() -> Self {
         Self {
             data: std::ptr::null_mut(),
@@ -143,6 +153,10 @@ pub unsafe extern "C" fn free_string(string: *mut c_char) {
     }
 }
 
+/// Builds a hydrated [TransactionReceipt] from information in the passed transaction,
+/// receipt, and block receipts.
+///
+/// Returns [None] if the transaction's sender could not be recovered from the signature.
 #[inline(always)]
 fn build_transaction_receipt_with_block_receipts(
     tx: TransactionSigned,

op-service/sources/reth_db_test.go

+package sources
+
+import (
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+)
+
+func TestRethDBRead(t *testing.T) {
+	t.Parallel()
+
+	_, err := FetchRethReceipts("/test", &common.Hash{})
+	if err != nil {
+		panic("test")
+	}
+}