Merge pull request #922 from onflow/nialexsan/add-available-balance

Nialexsan/add available balance

docs/build/basics/accounts.md

@@ -24,27 +24,54 @@ A simple representation of an account:
 
 ![Screenshot 2023-08-16 at 16.43.07.png](_accounts_images/Screenshot_2023-08-16_at_16.43.07.png)
 
-**Address**
+## Address
 
 A Flow address is represented as 16 hex-encoded characters (usually prefixed with `0x` to indicate hex encoding). Unlike Bitcoin and Ethereum, Flow addresses are not derived from cryptographic public keys. Instead, each Flow address is assigned by the Flow protocol using an on-chain deterministic sequence. The sequence uses an error detection code to guarantee that all addresses differ with at least 2 hex characters. This makes typos resulting in accidental loss of assets not possible.
 
 This decoupling is a unique advantage of Flow, allowing for multiple public keys to be associated with one account, or for a single public key to be used across several accounts.
 
-**Balance**
+## Balance
 
 Each Flow account created on Mainnet will by default [hold a Flow vault that holds a balance and is part of the FungibleToken standard](./flow-token.md). This balance is used to pay for [transaction fees and storage fees](./fees.md). More on that in the fees document.
 
-<Callout type="warning">
+:::warning
+
 The minimum amount of FLOW an account can have is **0.001**.
-</Callout>
+
+:::
 
 This minimum storage fee is provided by the account creator and covers the cost of storing up to 100kB of data in perpetuity. This fee is applied only once and can be "topped up" to add additional storage to an account. The minimum account reservation ensures that most accounts won't run out of storage capacity if anyone deposits anything (like an NFT) to the account. 
 
-**Contracts**
+
+### Maximum available balance
+
+Due to the storage restrictions, there is a maximum available balance that user can withdraw from the wallet. The core contract [`FlowStorageFees`](../core-contracts/05-flow-fees.md#flowstoragefees) provides a function to retrieve that value:  
+
+```cadence
+import "FlowStorageFees"
+
+access(all) fun main(accountAddress: Address): UFix64 {
+  return FlowStorageFees.defaultTokenAvailableBalance(accountAddress)
+}
+```
+
+Alternatively developers can use `availableBalance` property of the `Account`
+
+```cadence
+access(all) fun main(address: Address): UFix64 {
+  let acc = getAccount(address)
+  let balance = acc.availableBalance
+
+  return balance
+}
+
+```
+
+## Contracts
 
 An account can optionally store multiple [Cadence contracts](https://cadence-lang.org/docs/language/contracts). The code is stored as a human-readable UTF-8 encoded string which makes it easy for anyone to inspect the contents.
 
-**Storage**
+## Storage
 
 Each Flow account has an associated storage and capacity. The account's storage used is the byte size of all the data stored in the account's storage. An account's [storage capacity is directly tied to the balance of Flow tokens](./fees.md#storage) an account has. An account can, without any additional cost, use any amount of storage up to its storage capacity. If a transaction puts an account over storage capacity or drops an account's balance below the minimum 0.001 Flow tokens, that transaction fails and is reverted.
 
@@ -56,9 +83,11 @@ During account creation, public keys can be provided which will be used when int
 
 Each account key has a weight that determines the signing power it holds.
 
-<Callout type="warning">
+:::warning
+
 A transaction is not authorized to access an account unless it has a total signature weight greater than or equal to **1000**, the weight threshold.
-</Callout>
+
+:::
 
 For example, an account might contain 3 keys, each with 500 weight:
 
@@ -104,10 +133,11 @@ An account on Flow doesn’t require keys in order to exist, but this makes the
 
 You can achieve keyless accounts by either removing an existing public key from an account signing with that same key and repeating that action until an account has no keys left, or you can create a new account that has no keys assigned. With account linking you can also have a child account that has no keys but is controlled by the parent.
 
-<Callout type="danger">
+:::danger
+
 Be careful when removing keys from an existing account, because once an account’s total key weights sum to less than 1000, it can no longer be modified.
 
-</Callout>
+:::
 
 ### **Multi-Sig Accounts**
 
@@ -143,10 +173,11 @@ For development purposes, [you can use Flow CLI to easily create emulator, testn
 
 Keys should be generated in a secure manner. Depending on the purpose of the keys different levels of caution need to be taken.
 
-<Callout type="warning">
+:::warning
+
 Anyone obtaining access to a private key can modify the account the key is associated with (assuming it has enough weight). Be very careful how you store the keys.
 
-</Callout>
+:::
 
 For secure production keys, we suggest using key management services such as [Google key management](https://cloud.google.com/security-key-management) or [Amazon KMS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.Keys.html), which are also supported by our CLI and SDKs. Those services are mostly great when integrated into your application. However, for personal use, you can securely use any [existing wallets](../../ecosystem/wallets.md) as well as a [hardware Ledger wallet](../../ecosystem/wallets.md).
 

docs/build/basics/fees.md

@@ -77,19 +77,21 @@ Flow's approach to storage capacity is a bit similar to some banks' pricing mode
 
 Each Flow account has associated storage used. The account's storage used is the byte size of all the data stored in the account's storage. Accounts also have a storage capacity, which is directly tied to the amount of Flow tokens an account has. The account can, without any additional cost, use any amount of storage up to its storage capacity. 
 
-<Callout type="warning">
+:::warning
+
 If a transaction puts an account over storage capacity, that transaction fails and is reverted. Likewise, if a transaction would drop an account's balance below 0.001 Flow tokens, which is the minimum an account can have, the transaction would also fail.
 
-</Callout>
+:::
 
 **Storage Capacity**
 
 The storage capacity of an account is dictated by the amount of FLOW it has. 
 
-<Callout type="danger">
+:::danger
+
 The **minimum amount of FLOW an account can have is 0.001**. This minimum is provided by the account creator at account creation.
 
-</Callout>
+:::
 
 The minimum account reservation ensures that most accounts won't run out of storage capacity if anyone deposits anything (like an NFT) to the account.
 
@@ -119,6 +121,29 @@ Adding additional keys, smart contracts, capabilities, resources, etc. to the ac
 
 Data stored on the Flow blockchain is stored in a key-value ledger. Each item’s key contains the address that owns the item and the path to the item. An account can have many keys, therefore flow considers the account key items are stored with. This means that the storage used by each item is the byte length of the item plus the byte length of the item’s key.
 
+### Maximum available balance
+
+Due to the storage restrictions, there is a maximum available balance that user can withdraw from the wallet. The core contract [`FlowStorageFees`](../core-contracts/05-flow-fees.md#flowstoragefees) provides a function to retrieve that value:  
+
+```cadence
+import "FlowStorageFees"
+
+access(all) fun main(accountAddress: Address): UFix64 {
+  return FlowStorageFees.defaultTokenAvailableBalance(accountAddress)
+}
+```
+
+Alternatively developers can use `availableBalance` property of the `Account`
+
+```cadence
+access(all) fun main(address: Address): UFix64 {
+  let acc = getAccount(address)
+  let balance = acc.availableBalance
+
+  return balance
+}
+
+```
 
 ## Practical Understanding of Fees
 

docs/build/core-contracts/05-flow-fees.md

@@ -4,7 +4,7 @@ sidebar_position: 5
 sidebar_label: Flow Fees
 ---
 
-# FlowFees
+## FlowFees
 
 The `FlowFees` contract is where all the collected flow fees are gathered.
 
@@ -17,7 +17,7 @@ Source: [FlowFees.cdc](https://github.com/onflow/flow-core-contracts/blob/master
 | Testnet                   | `0x912d5440f7e3769e` |
 | Mainnet                   | `0xf919ee77447b7497` |
 
-## Events
+### Events
 
 Important events for `FlowFees` are:
 
@@ -35,7 +35,7 @@ access(all) event FeesDeducted(amount: UFix64, inclusionEffort: UFix64, executio
 access(all) event FeeParametersChanged(surgeFactor: UFix64, inclusionEffortCost: UFix64, executionEffortCost: UFix64)
 ```
 
-# FlowStorageFees
+## FlowStorageFees
 
 The `FlowStorageFees` contract defines the parameters and utility methods for storage fees.
 
@@ -48,7 +48,7 @@ Source: [FlowStorageFees.cdc](https://github.com/onflow/flow-core-contracts/blob
 | Testnet                   | `0x8c5303eaa26202d6` |
 | Mainnet                   | `0xe467b9dd11fa00df` |
 
-## Events
+### Events
 
 Important events for `FlowStorageFees` are:
 

docs/tools/clients/flow-go-sdk/error-codes.mdx → docs/tools/error-codes.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 2
+---
+
 # Error Codes
 
 List of error codes returned from failing transactions and scripts. The error code has an accompanied error message that usually gives more clarification. This list is meant to give more information and helpful hints.
@@ -135,6 +139,9 @@ Example:
 `
 
 
+For more information refer to [Fees](../build/basics/fees.md)
+
+
 
 ### 1105
 **ErrCodeEventLimitExceededError**
@@ -380,5 +387,3 @@ Example:
 `
 ...
 `
-
-

vercel.json

@@ -1228,6 +1228,11 @@
     {
       "source": "/networks/flow-networks/accessing-previewnet",
       "destination": "/evm/using"
+    },
+    {
+      "source": "/tools/clients/flow-go-sdk/error-codes",
+      "destination": "/tools/error-codes",
+      "permanent": true
     }
   ]
 }