feat: Hook up oracle_id host function

crates/xrpl-host-functions/src/lib.rs

@@ -353,6 +353,13 @@ host_functions! {
     #[wasm_name = "offer_id"]
     fn offer_keylet(&self, account: &[u8], seq: i32, out: &mut [u8]) -> HostResult<usize>;
 
+    /// The 32-byte keylet of an `Oracle`, computed from the 20-byte owner account and
+    /// its document id. `doc_id` is the guest's `u32` carried as its `i32` bit pattern.
+    /// Reads the account region and writes the keylet.
+    #[gas = 350]
+    #[wasm_name = "oracle_id"]
+    fn oracle_keylet(&self, account: &[u8], doc_id: i32, out: &mut [u8]) -> HostResult<usize>;
+
     /// The XRPL `sha512Half` of `data`: the first [`HASH_LEN`] bytes of its SHA-512.
     #[gas = 2000]
     #[wasm_name = "sha512_half"]

crates/xrpl-host-functions/tests/generated_abi.rs

@@ -324,6 +324,14 @@ impl HostFunctions for FakeHost {
         put(out, &[account[0]; HASH_LEN])
     }
 
+    /// The same account-and-scalar shape, for an `Oracle` keyed by document id.
+    fn oracle_keylet(&self, account: &[u8], _doc_id: i32, out: &mut [u8]) -> HostResult<usize> {
+        if account.is_empty() {
+            return Err(HostError::InvalidAccount);
+        }
+        put(out, &[account[0]; HASH_LEN])
+    }
+
     fn sha512_half(&self, data: &[u8], out: &mut [u8]) -> HostResult<usize> {
         let mut digest = [0; HASH_LEN];
         digest[0] = data.len() as u8;
@@ -509,6 +517,12 @@ fn the_trait_is_implementable() {
         host.offer_keylet(&[], 5, &mut out),
         Err(HostError::InvalidAccount)
     );
+    assert_eq!(host.oracle_keylet(&[7; 20], 5, &mut out), Ok(HASH_LEN));
+    assert_eq!(out[0], 7);
+    assert_eq!(
+        host.oracle_keylet(&[], 5, &mut out),
+        Err(HostError::InvalidAccount)
+    );
     assert_eq!(host.sha512_half(b"abc", &mut out), Ok(HASH_LEN));
     assert_eq!(out[0], 3);
     assert_eq!(host.trace("hello", b"xy", true), Ok(()));
@@ -608,6 +622,7 @@ fn the_spec_table_matches_the_declarations() {
             ("mptoken_id", 500),
             ("nft_offer_id", 350),
             ("offer_id", 350),
+            ("oracle_id", 350),
             ("sha512_half", 2000),
             ("trace", 500),
             ("trace_num", 500),

crates/xrpl-wasm-vm-ffi/src/lib.rs

@@ -344,6 +344,10 @@ mod ffi {
         #[cxx_name = "offerKeylet"]
         fn offer_keylet(self: &HostContext, account: &[u8], seq: i32, out: &mut [u8]) -> i32;
 
+        #[namespace = "xrpl"]
+        #[cxx_name = "oracleKeylet"]
+        fn oracle_keylet(self: &HostContext, account: &[u8], doc_id: i32, out: &mut [u8]) -> i32;
+
         #[namespace = "xrpl"]
         #[cxx_name = "sha512Half"]
         fn sha512_half(self: &HostContext, data: &[u8], out: &mut [u8]) -> i32;
@@ -576,6 +580,10 @@ impl HostFunctions for CxxHost<'_> {
         bytes_written(self.ctx.offer_keylet(account, seq, out))
     }
 
+    fn oracle_keylet(&self, account: &[u8], doc_id: i32, out: &mut [u8]) -> HostResult<usize> {
+        bytes_written(self.ctx.oracle_keylet(account, doc_id, out))
+    }
+
     fn sha512_half(&self, data: &[u8], out: &mut [u8]) -> HostResult<usize> {
         bytes_written(self.ctx.sha512_half(data, out))
     }

crates/xrpl-wasm-vm/src/abi.rs

@@ -341,6 +341,14 @@ mod tests {
         fn offer_keylet(&self, _account: &[u8], _seq: i32, _out: &mut [u8]) -> HostResult<usize> {
             unreachable!("no unit test in this module calls the host")
         }
+        fn oracle_keylet(
+            &self,
+            _account: &[u8],
+            _doc_id: i32,
+            _out: &mut [u8],
+        ) -> HostResult<usize> {
+            unreachable!("no unit test in this module calls the host")
+        }
         fn sha512_half(&self, _data: &[u8], _out: &mut [u8]) -> HostResult<usize> {
             unreachable!("no unit test in this module calls the host")
         }

crates/xrpl-wasm-vm/src/register.rs

@@ -601,6 +601,25 @@ pub(crate) fn register_host_functions(
                     })
                 },
             ),
+            HostFunctionSpec::OracleKeylet => linker.func_wrap(
+                HOST_MODULE,
+                op.wasm_name(),
+                |mut caller: Caller<'_, VmState<'_>>,
+                 acc_ptr: i32,
+                 acc_len: i32,
+                 doc_id: i32,
+                 out_ptr: i32,
+                 out_len: i32|
+                 -> Result<i32, wasmi::Error> {
+                    charged(&mut caller, HostFunctionSpec::OracleKeylet, |c| {
+                        let out = Region::new(out_ptr, out_len);
+                        let account = Region::new(acc_ptr, acc_len);
+                        write_buffered(c, out, |host, data, buf| {
+                            host.oracle_keylet(account.read(data)?, doc_id, buf)
+                        })
+                    })
+                },
+            ),
             HostFunctionSpec::Sha512Half => linker.func_wrap(
                 HOST_MODULE,
                 op.wasm_name(),

crates/xrpl-wasm-vm/tests/budgets.rs

@@ -209,6 +209,11 @@ fn call_for(op: HostFunctionSpec) -> Call {
             "(call $offer_id (i32.const 0) (i32.const 20) (i32.const 5) (i32.const 32) (i32.const 32))",
             5,
         ),
+        HostFunctionSpec::OracleKeylet => (
+            import::ORACLE_ID,
+            "(call $oracle_id (i32.const 0) (i32.const 20) (i32.const 5) (i32.const 32) (i32.const 32))",
+            5,
+        ),
         HostFunctionSpec::Sha512Half => (
             import::SHA512_HALF,
             "(call $sha512_half (i32.const 0) (i32.const 4) (i32.const 0) (i32.const 32))",

crates/xrpl-wasm-vm/tests/host_calls.rs

@@ -643,6 +643,22 @@ fn offer_id_reads_the_account_and_seq() {
     assert_eq!(*host.offer_keylets_asked.borrow(), vec![(account, 5)]);
 }
 
+/// The account-and-scalar keylet, keyed on a document id rather than a sequence; its
+/// own answer set, to keep it distinct from the other account-and-scalar getters.
+#[test]
+fn oracle_id_reads_the_account_and_doc_id() {
+    let account = vec![0u8; 20];
+    let host =
+        FakeHost::new().answering_oracle_keylet(account.clone(), 5, support::Answer::filler(32));
+
+    let wat = module(
+        &[import::ORACLE_ID, ONE_PAGE],
+        "(call $oracle_id (i32.const 0) (i32.const 20) (i32.const 5) (i32.const 64) (i32.const 64))",
+    );
+    assert_eq!(status(&wat, &host), 32, "the 32-byte keylet length");
+    assert_eq!(*host.oracle_keylets_asked.borrow(), vec![(account, 5)]);
+}
+
 /// A leading scalar parameter reaches the host as declared.
 #[test]
 fn home_le_field_passes_the_field_selector_through() {

crates/xrpl-wasm-vm/tests/preflight.rs

@@ -98,7 +98,7 @@ fn a_disabled_feature_does_not_pass() {
 
 /// Every host function the ABI declares, spelled as a guest imports it. The count
 /// is asserted against the ABI so a function added to it cannot be left out here.
-const ALL_IMPORTS: [&str; 35] = [
+const ALL_IMPORTS: [&str; 36] = [
     import::LDGR_INDEX,
     import::PARENT_LDGR_TIME,
     import::PARENT_LDGR_HASH,
@@ -131,6 +131,7 @@ const ALL_IMPORTS: [&str; 35] = [
     import::MPTOKEN_ID,
     import::NFT_OFFER_ID,
     import::OFFER_ID,
+    import::ORACLE_ID,
     import::SHA512_HALF,
     import::TRACE,
     import::TRACE_NUM,

crates/xrpl-wasm-vm/tests/support/mod.rs

@@ -244,6 +244,11 @@ pub struct FakeHost {
     pub offer_keylets: HashMap<(Vec<u8>, i32), Answer>,
     /// Every (account, seq) `offer_keylet` was asked for.
     pub offer_keylets_asked: RefCell<Vec<(Vec<u8>, i32)>>,
+    /// What `oracle_keylet` answers, by (account bytes, doc id). An unlisted key
+    /// answers `InvalidAccount`.
+    pub oracle_keylets: HashMap<(Vec<u8>, i32), Answer>,
+    /// Every (account, doc id) `oracle_keylet` was asked for.
+    pub oracle_keylets_asked: RefCell<Vec<(Vec<u8>, i32)>>,
     /// What `sha512_half` answers, whatever it is given.
     pub digest: Answer,
     /// Every field selector `get_current_ledger_obj_field` was asked for.
@@ -324,6 +329,8 @@ impl Default for FakeHost {
             nft_offer_keylets_asked: RefCell::new(Vec::new()),
             offer_keylets: HashMap::new(),
             offer_keylets_asked: RefCell::new(Vec::new()),
+            oracle_keylets: HashMap::new(),
+            oracle_keylets_asked: RefCell::new(Vec::new()),
             digest: Answer::filler(32),
             fields_asked: RefCell::new(Vec::new()),
             digested: RefCell::new(Vec::new()),
@@ -567,6 +574,16 @@ impl FakeHost {
         self
     }
 
+    pub fn answering_oracle_keylet(
+        mut self,
+        account: Vec<u8>,
+        doc_id: i32,
+        answer: Answer,
+    ) -> FakeHost {
+        self.oracle_keylets.insert((account, doc_id), answer);
+        self
+    }
+
     pub fn answering_digest(mut self, answer: Answer) -> FakeHost {
         self.digest = answer;
         self
@@ -883,6 +900,15 @@ impl HostFunctions for FakeHost {
         }
     }
 
+    fn oracle_keylet(&self, account: &[u8], doc_id: i32, out: &mut [u8]) -> HostResult<usize> {
+        let key = (account.to_vec(), doc_id);
+        self.oracle_keylets_asked.borrow_mut().push(key.clone());
+        match self.oracle_keylets.get(&key) {
+            Some(answer) => answer.fill(out),
+            None => Err(HostError::InvalidAccount),
+        }
+    }
+
     fn sha512_half(&self, data: &[u8], out: &mut [u8]) -> HostResult<usize> {
         self.digested.borrow_mut().push(data.to_vec());
         self.digest.fill(out)
@@ -956,6 +982,7 @@ pub mod import {
     pub const MPTOKEN_ID: &str = r#"(import "host_lib" "mptoken_id" (func $mptoken_id (param i32 i32 i32 i32 i32 i32) (result i32)))"#;
     pub const NFT_OFFER_ID: &str = r#"(import "host_lib" "nft_offer_id" (func $nft_offer_id (param i32 i32 i32 i32 i32) (result i32)))"#;
     pub const OFFER_ID: &str = r#"(import "host_lib" "offer_id" (func $offer_id (param i32 i32 i32 i32 i32) (result i32)))"#;
+    pub const ORACLE_ID: &str = r#"(import "host_lib" "oracle_id" (func $oracle_id (param i32 i32 i32 i32 i32) (result i32)))"#;
     pub const SHA512_HALF: &str = r#"(import "host_lib" "sha512_half" (func $sha512_half (param i32 i32 i32 i32) (result i32)))"#;
     pub const TRACE: &str =
         r#"(import "host_lib" "trace" (func $trace (param i32 i32 i32 i32 i32) (result i32)))"#;

include/xrpl/tx/wasm/HostContext.h

@@ -218,6 +218,14 @@ public:
         std::int32_t seq,
         rust::Slice<std::uint8_t> out) const noexcept;
 
+    // The account id must be 20 bytes, else `InvalidParams`. `docId` carries the
+    // guest's u32 as its i32 bit pattern. Writes the 32-byte keylet.
+    [[nodiscard]] std::int32_t
+    oracleKeylet(
+        rust::Slice<std::uint8_t const> account,
+        std::int32_t docId,
+        rust::Slice<std::uint8_t> out) const noexcept;
+
     [[nodiscard]] std::int32_t
     sha512Half(rust::Slice<std::uint8_t const> data, rust::Slice<std::uint8_t> out) const noexcept;
 

src/libxrpl/tx/wasm/HostContext.cpp

@@ -703,6 +703,26 @@ HostContext::offerKeylet(
     });
 }
 
+std::int32_t
+HostContext::oracleKeylet(
+    rust::Slice<std::uint8_t const> account,
+    std::int32_t docId,
+    rust::Slice<std::uint8_t> out) const noexcept
+{
+    return guarded(hostFunctions_.getJournal(), kHostInternal, [&] {
+        if (account.size() != AccountID::size())
+            return hfErrorToInt(HostFunctionError::InvalidParams);
+
+        // The guest's u32 docId arrives as its i32 bit pattern; recover it.
+        auto const value = hostFunctions_.oracleKeylet(
+            AccountID::fromVoid(account.data()), static_cast<std::uint32_t>(docId));
+        if (!value)
+            return hfErrorToInt(value.error());
+
+        return answer(out, value->data(), value->size());
+    });
+}
+
 std::int32_t
 HostContext::sha512Half(rust::Slice<std::uint8_t const> data, rust::Slice<std::uint8_t> out)
     const noexcept