From 59b42e75120ca83473bf39623bcb92b52f3c5ea7 Mon Sep 17 00:00:00 2001
From: deleterium <rui.santana@protonmail.com>
Date: Fri, 9 Feb 2024 15:55:49 -0300
Subject: [PATCH] Improving documentation Get_Account_Balance

---
 docs/1.5-Built-in-functions.md | 17 +++++++++++++----
 docs/2-API-Pseudo-Code.md      | 30 ++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/docs/1.5-Built-in-functions.md b/docs/1.5-Built-in-functions.md
index 66b9b90..a1c4f0f 100644
--- a/docs/1.5-Built-in-functions.md
+++ b/docs/1.5-Built-in-functions.md
@@ -92,6 +92,9 @@ void distributeToHoldersFx(
 );
 long getAssetHoldersCount(long minimumQuantity, long assetId);
 long getAssetCirculating(long assetId);
+long getAccountBalance(long accountId);
+fixed getAccountBalanceFx(long accountId);
+long getAccountQuantity(long accountId, long assetId);
 
 // Special instructions
 long mdv(long m1, long m2, long div);
@@ -498,21 +501,27 @@ Returns the quantity of 'assetId' currently in circulation.
   2) In sell orders;
   3) In accountId zero (burn address).
 
-### getAccountBalance
+### getAccountBalance, getAccountBalanceFx
 * Prototype:
 `long getAccountBalance(long accountId);`
+* Fixed version prototype:
+`fixed getAccountBalanceFx(long accountId);`
 * Description:
 Returns the SIGNA balance owned by 'accountId'.
+If there is no accountId, returns zero.
+When used to get the balances from smart contracts, it will return the balance on last block, not the one after the execution on current block.
+Same applies to get the own contract balance, which is the same as signum API Get_Previous_Balance and most of times not useful.
 * Note that some parts of the balance are also considered:
-  1) Commitment;
+  1) Commitment.
 
 ### getAccountAssetQuantity
 * Prototype:
-`long getAccountAssetQuantity(long accountId, long assetId);`
+`long getAccountQuantity(long accountId, long assetId);`
 * Description:
 Returns the quantity of 'assetId' owned by 'accountId'.
+When used to get the balances from smart contracts, it will return the balance on last block, not the one after the execution on current block.
 * Note that some quantities are also considered:
-  1) In sell orders;
+  1) In sell orders.
 </details>
 <details>
 <summary>
diff --git a/docs/2-API-Pseudo-Code.md b/docs/2-API-Pseudo-Code.md
index 5a3f6cd..17b7f5d 100644
--- a/docs/2-API-Pseudo-Code.md
+++ b/docs/2-API-Pseudo-Code.md
@@ -657,6 +657,21 @@ long Get_Asset_Circulating(void) {
        treasury account.
     */
 }
+
+long Get_Account_Balance(void) {
+    // Assembly name: Get_Account_Balance
+    accountId = B1;
+    assetId = B2;
+
+    if(assetId == 0L){
+        balance = Blockchain.getAccountBalance(accountId);
+        // if there is no account, then return zero
+        return balance
+    }
+    quantity = Blockchain.getAccountQuatity(accountId, assetId);
+    // If there is no account, or if account does not have the given asset, returns 0
+    return quantity
+}
 ```
 </details>
 <details>
@@ -821,6 +836,21 @@ fixed F_Get_Activation_Fee(void) {
     }
     return 0;
 }
+
+fixed F_Get_Account_Balance(void) {
+    // Assembly name: Get_Account_Balance
+    accountId = B1;
+    assetId = B2;
+
+    if(assetId == 0L){
+        balance = Blockchain.getAccountBalance(accountId);
+        // if there is no account, then return zero
+        return balance
+    }
+    quantity = Blockchain.getAccountQuatity(accountId, assetId);
+    // If there is no account, or if account does not have the given asset, returns 0
+    return quantity
+}
 ```
 </details>