# Balance Guard

## Overview

This policy makes sure that a the balance of some address in some token *(Native or ERC20)* doesn't change over an allowed threshold with any given transaction.

## Protected Attack Vector

If an attacker gains privileged access to an account *(wallet or smart contract)* - either by stealing the private keys or by exploiting some vulnerability - and the account has some balance in some token *(Native or ERC20) -* this policy will block a malicious transaction from going through if the change in balance is above a configured threshold for the token.

## How It Works

1. When a transaction reaches this policy in the [Pre Execution](/firewall/glossary.md#pre-execution) hook, it first looks up the balances of the account in it's configured tokens.<br>
2. Then, in the [Post Execution](/firewall/glossary.md#post-execution) hook, the policy compares the difference in balance *(per token)* against it's configured change-threshold.<br>
3. If the transaction changed the balance more than is allowed by the threshold, it will be reverted.

## Setup Instructions

1. Deploy your own version of this policy *(see* [*Source Code*](#source-code)*)*.<br>
2. Call the [setConsumerMaxBalanceChange()](#setconsumermaxbalancechange) method to configure the balance change thresholds.<br>
3. Add the newly deployed policy to the [Firewall](/firewall/glossary.md#firewall) *(you can do this* [*Globally*](/firewall/configuration/firewall-configuration.md#global-policies) *or* [*Per-Method*](/firewall/configuration/firewall-configuration.md#per-method-policies)*, see* [*Policy Administration*](/firewall/configuration/policy-administration.md)*)*.<br>
4. That's it!

## Properties

<table><thead><tr><th width="293">Name</th><th width="256.3333333333333">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>consumerMaxBalanceChange</code></td><td><p><code>mapping</code></p><p><code>(address =></code></p><p>   <code>mapping</code></p><p>   <code>(address => uint)</code></p><p><code>)</code></p></td><td><p>a mapping between accounts, tokens, and their balance balance change threshold</p><p><br>for example:<br><code>[someAccount][someToken] = 50000</code></p></td></tr><tr><td><code>consumerLastBalance</code></td><td><p><code>mapping</code></p><p><code>(address =></code></p><p>   <code>mapping</code></p><p>   <code>(address => uint[])</code></p><p><code>)</code></p></td><td>a mapping between accounts, tokens, and their balances before executing the transaction</td></tr></tbody></table>

## Methods

### setConsumerMaxBalanceChange()

#### `function setConsumerMaxBalanceChange(address consumer, address token, uint maxBalanceChange)`

Callable only by the policy owner. Sets the maximum balance change that can take place on the given token in a transaction.

| Parameter Name     | Type      | Description                              |
| ------------------ | --------- | ---------------------------------------- |
| `consumer`         | `address` | the account holding the balance          |
| `token`            | `address` | the token to track balance changes for   |
| `maxBalanceChange` | `uint`    | the maximum balance change for the token |

### removeToken()

#### `function removeToken(address consumer, address token)`

Callable only by the policy owner. Removes the token from the consumer, so that the policy will  no longer track balance changes on that token.

| Parameter Name | Type      | Description                            |
| -------------- | --------- | -------------------------------------- |
| `consumer`     | `address` | the account holding the balance        |
| `token`        | `address` | the token to track balance changes for |

## View Functions

### getConsumerTokens()

#### `function getConsumerTokens(address consumer)`

Gets the tokens and their configured balance change threshold for `consumer`.

| Parameter Name | Type      | Description                     |
| -------------- | --------- | ------------------------------- |
| `consumer`     | `address` | the account holding the balance |

## **Security Lifecycle**

This policy runs during both the Firewall's [Pre Execution](/firewall/glossary.md#pre-execution) and the [Post Execution](/firewall/glossary.md#post-execution) hooks.

## Source Code

On our GitHub repository: [BalanceChangePolicy.sol](https://github.com/ironblocks/onchain-firewall/blob/main/packages/onchain-firewall/contracts/policies/BalanceChangePolicy.sol)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ironblocks.com/firewall/policies/balance-guard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.