From 30ad1d41449d056f57713d1d80eb3e8ce6fa53c5 Mon Sep 17 00:00:00 2001
From: Burak Bilge Yalcinkaya <bbyalcinkaya@gmail.com>
Date: Mon, 29 Jul 2024 18:05:57 +0300
Subject: [PATCH] add comments

---
 src/ksoroban/kdist/soroban-semantics/cheatcodes.md      | 4 +++-
 src/ksoroban/kdist/soroban-semantics/configuration.md   | 7 +++++++
 src/tests/integration/data/ledger_sequence_get_set.wast | 6 +++++-
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/ksoroban/kdist/soroban-semantics/cheatcodes.md b/src/ksoroban/kdist/soroban-semantics/cheatcodes.md
index 6efcea8..9e80ee1 100644
--- a/src/ksoroban/kdist/soroban-semantics/cheatcodes.md
+++ b/src/ksoroban/kdist/soroban-semantics/cheatcodes.md
@@ -7,6 +7,8 @@ requires "host/hostfuns.md"
 module CHEATCODES
     imports HOSTFUNS
 
+    // TODO: Add a check to ensure these host functions are only called from a Kasmer test contract.
+
     // extern "C" {
     //     fn kasmer_set_ledger_sequence(x : u64);
     // }
@@ -16,7 +18,7 @@ module CHEATCODES
                  ...
         </instrs>
         <locals>
-          0 |-> < i64 > NEW_SEQ_NUM
+          0 |-> < i64 > NEW_SEQ_NUM // U32 HostVal
         </locals>
         <ledgerSequenceNumber> _ => getMajor(HostVal(NEW_SEQ_NUM)) </ledgerSequenceNumber>
       requires getTag(HostVal(NEW_SEQ_NUM)) ==Int getTag(U32(0)) // check `NEW_SEQ_NUM` is a U32
diff --git a/src/ksoroban/kdist/soroban-semantics/configuration.md b/src/ksoroban/kdist/soroban-semantics/configuration.md
index 42b511a..be4d9e6 100644
--- a/src/ksoroban/kdist/soroban-semantics/configuration.md
+++ b/src/ksoroban/kdist/soroban-semantics/configuration.md
@@ -42,6 +42,13 @@ module CONFIG
           </account>
         </accounts>
         <contractCodes> .Map </contractCodes>
+```
+
+- `ledgerSequenceNumber`: The current block (or "ledger" in Stellar) number.
+    Accessible to contracts via the `get_ledger_sequence` host function.
+    Set externally using `kasmer_set_ledger_sequence`.
+
+```k
         <ledgerSequenceNumber> 0 </ledgerSequenceNumber>
         <logging> .List </logging>
       </soroban>
diff --git a/src/tests/integration/data/ledger_sequence_get_set.wast b/src/tests/integration/data/ledger_sequence_get_set.wast
index 6a42d52..0e6989d 100644
--- a/src/tests/integration/data/ledger_sequence_get_set.wast
+++ b/src/tests/integration/data/ledger_sequence_get_set.wast
@@ -8,8 +8,12 @@ uploadWasm( b"test-wasm",
 ;; #[contract]
 ;; pub struct IncrementContract;
 
+;; // To enable the `kasmer_set_ledger_sequence` cheatcode, we first need to declare it as an extern function
+;; // The function will appear as an import from the "env" module
+;; //
+;; //   (import "env" "kasmer_set_ledger_sequence" (func $kasmer_set_ledger_sequence (param i64)))
+;; //
 ;; extern "C" {
-;;     // (import "env" "kasmer_set_ledger_sequence" (func $kasmer_set_ledger_sequence (param i64)))
 ;;     fn kasmer_set_ledger_sequence(x : u64);
 ;; }