docs(soroban): add extendInstanceTtl builtin documentation

Signed-off-by: Tarek <tareknaser360@gmail.com>
hyperledger-solang · Feb 16, 2025 · 0020820 · 0020820
1 parent 137022a
commit 0020820
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 13 deletions.
diff --git a/docs/language/builtins.rst b/docs/language/builtins.rst
@@ -667,7 +667,6 @@ Assuming `arg1` is 512 and `arg2` is 196, the output to the log will be ``foo en
     Be mindful this will increase the gas cost. Larger values will incur a higher gas cost.
     Alternatively, use a hexadecimal ``{:x}`` format specifier to reduce the cost.
 
-.. _extendPersistentTtl:
 
 extendTtl(uint32 threshold, uint32 extend_to) 
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -694,3 +693,20 @@ TTL = live_until_ledger_seq - current_ledger
 
 
 For more details on managing contract data TTLs in Soroban, refer to the docs for `TTL <https://developers.stellar.org/docs/build/smart-contracts/getting-started/storing-data#managing-contract-data-ttls-with-extend_ttl>`_.
+
+extendInstanceTtl(uint32 threshold, uint32 extend_to)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The extendInstanceTtl() function extends the time-to-live (TTL) of contract instance storage.
+
+If the TTL for the current contract instance and code (if applicable) is below threshold ledgers, this function extends ``live_until_ledger_seq`` such that TTL equals ``extend_to``.
+
+.. note:: This is a global function, not a method, and is only available on the Soroban target
+
+.. code-block:: solidity
+
+    /// Extends the TTL for the contract instance storage to 10000 ledgers
+    /// if the current TTL is smaller than 2000 ledgers
+    function extendInstanceTtl() public view returns (int64) {
+        return extendInstanceTtl(2000, 10000);
+    }
diff --git a/src/sema/builtin.rs b/src/sema/builtin.rs
@@ -42,7 +42,7 @@ pub static BUILTIN_FUNCTIONS: Lazy<[Prototype; 28]> = Lazy::new(|| {
             builtin: Builtin::ExtendInstanceTtl,
             namespace: None,
             method: vec![],
-            name: "extend_instance_ttl",  
+            name: "extendInstanceTtl",  
             params: vec![Type::Uint(32), Type::Uint(32)],
             ret: vec![Type::Int(64)],
             target: vec![Target::Soroban],

diff --git a/tests/soroban_testcases/ttl.rs b/tests/soroban_testcases/ttl.rs
@@ -131,7 +131,7 @@ fn ttl_instance_wrong() {
         r#"contract instance_counter {
             uint64 instance instanceCount = 3;
             
-            function extend_instance_ttl() public view returns (int64) {
+            function extendInstanceTtl() public view returns (int64) {
                 return instanceCount.extendTtl(700, 3000);
             }
         }"#,
@@ -152,8 +152,8 @@ fn ttl_instance_correct() {
 
             /// Extends the TTL for the instance storage to 10000 ledgers
             /// if the current TTL is smaller than 2000 ledgers
-            function extend_instance_ttl() public view returns (int64) {
-                return extend_instance_ttl(2000, 10000);
+            function extendInstanceTtl() public view returns (int64) {
+                return extendInstanceTtl(2000, 10000);
             }
         }"#,
         |env| {
@@ -185,7 +185,7 @@ fn ttl_instance_correct() {
     });
 
     // Extend instance TTL to 10000 ledgers
-    runtime.invoke_contract(addr, "extend_instance_ttl", vec![]);
+    runtime.invoke_contract(addr, "extendInstanceTtl", vec![]);
     runtime.env.as_contract(addr, || {
         assert_eq!(runtime.env.storage().instance().get_ttl(), 10000);
     });
@@ -210,8 +210,8 @@ fn ttl_combined() {
                 return tCount.extendTtl(3000, 7000);
             }
 
-            function extend_instance_ttl() public view returns (int64) {
-                return extend_instance_ttl(2000, 10000);
+            function extendInstanceTtl() public view returns (int64) {
+                return extendInstanceTtl(2000, 10000);
             }
         }"#,
         |env| {
@@ -264,7 +264,7 @@ fn ttl_combined() {
     });
 
     // Extend instance storage TTL
-    runtime.invoke_contract(addr, "extend_instance_ttl", vec![]);
+    runtime.invoke_contract(addr, "extendInstanceTtl", vec![]);
     runtime.env.as_contract(addr, || {
         assert_eq!(runtime.env.storage().instance().get_ttl(), 10000);
     });
@@ -313,7 +313,7 @@ fn ttl_combined() {
 
     // Re-extend all TTLs
     runtime.invoke_contract(addr, "extend_persistent_ttl", vec![]);
-    runtime.invoke_contract(addr, "extend_instance_ttl", vec![]);
+    runtime.invoke_contract(addr, "extendInstanceTtl", vec![]);
     runtime.invoke_contract(addr, "extend_temp_ttl", vec![]);
 
     // Final TTL verification
@@ -352,8 +352,8 @@ fn test_persistent_entry_archival() {
                 return pCount.extendTtl(1000, 10000);
             }
 
-            function extend_instance_ttl() public view returns (int64) {
-                return extend_instance_ttl(2000, 10000);
+            function extendInstanceTtl() public view returns (int64) {
+                return extendInstanceTtl(2000, 10000);
             }
         }"#,
         |env| {
@@ -369,7 +369,7 @@ fn test_persistent_entry_archival() {
     let addr = runtime.contracts.last().unwrap();
 
     // Extend instance TTL
-    runtime.invoke_contract(addr, "extend_instance_ttl", vec![]);
+    runtime.invoke_contract(addr, "extendInstanceTtl", vec![]);
 
     // Bump ledger sequence by 10001 (one past persistent TTL)
     runtime.env.ledger().with_mut(|li| {