Skip to content

Rates and interest

concrete_fhe_toolkit.finance.core

Bounded finance helpers for encrypted integer amounts.

Money convention: encrypted amounts are plain integers in the smallest unit you choose (for example cents/kurus). Rates are public floats with at most two decimal digits and are applied through the fixed RATE_SCALE factor, so every rate-scaled result returned by this module is RATE_SCALE times larger than the real value. Use :func:return_actual_value after decryption to recover the real value.

apply_rate 

apply_rate(amount: Any, rate: float) -> Any

Multiply an encrypted amount by a public rate.

The result is scaled by RATE_SCALE; decode with :func:return_actual_value after decryption.

Parameters:

Name Type Description Default
amount Any

The encrypted integer amount to be processed.

 required
rate float

A public floating point rate (e.g., 0.05 for 5%).

 required

Returns:

Name Type Description
Any Any

The encrypted result scaled by RATE_SCALE.
Example 
from concrete_fhe_toolkit.finance.core import apply_rate

# Inside an FHE circuit (e.g. applying a 5% rate)
# result = apply_rate(enc_amount, rate=0.05)
Source code in src/concrete_fhe_toolkit/finance/core.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def apply_rate(amount: Any, rate: float) -> Any:
    """Multiply an encrypted amount by a public rate.

    The result is scaled by ``RATE_SCALE``; decode with
    :func:`return_actual_value` after decryption.

    Args:
        amount (Any): The encrypted integer amount to be processed.
        rate (float): A public floating point rate (e.g., 0.05 for 5%).

    Returns:
        Any: The encrypted result scaled by RATE_SCALE.

    Example:
        ```python
        from concrete_fhe_toolkit.finance.core import apply_rate

        # Inside an FHE circuit (e.g. applying a 5% rate)
        # result = apply_rate(enc_amount, rate=0.05)
        ```
    """
    return amount * _scaled_rate(rate)

return_actual_value 

return_actual_value(value: Any) -> float

Decode a RATE_SCALE-scaled cleartext result back to its real value.

Parameters:

Name Type Description Default
value Any

The encrypted value to process or validate.

 required

Returns:

Name Type Description
float float

The actual real value.
Example 
from concrete_fhe_toolkit.finance.core import return_actual_value

# After decryption
real_value = return_actual_value(decrypted_result)
Source code in src/concrete_fhe_toolkit/finance/core.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@client_side_helper
def return_actual_value(value: Any) -> float:
    """Decode a RATE_SCALE-scaled cleartext result back to its real value.

    Args:
        value (Any): The encrypted value to process or validate.

    Returns:
        float: The actual real value.

    Example:
        ```python
        from concrete_fhe_toolkit.finance.core import return_actual_value

        # After decryption
        real_value = return_actual_value(decrypted_result)
        ```
    """
    return value / RATE_SCALE

calculate_tax 

calculate_tax(amount: Any, rate: float) -> Any

Calculate the tax amount at RATE_SCALE scaling.

Parameters:

Name Type Description Default
amount Any

The encrypted integer amount to be processed.

 required
rate float

A public floating point rate (e.g., 0.05 for 5%).

 required

Returns:

Name Type Description
Any Any

The encrypted tax amount scaled by RATE_SCALE.
Example 
from concrete_fhe_toolkit.finance.core import calculate_tax

# Inside an FHE circuit (18% tax)
# tax_amount = calculate_tax(enc_amount, rate=0.18)
Source code in src/concrete_fhe_toolkit/finance/core.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def calculate_tax(amount: Any, rate: float) -> Any:
    """Calculate the tax amount at RATE_SCALE scaling.

    Args:
        amount (Any): The encrypted integer amount to be processed.
        rate (float): A public floating point rate (e.g., 0.05 for 5%).

    Returns:
        Any: The encrypted tax amount scaled by RATE_SCALE.

    Example:
        ```python
        from concrete_fhe_toolkit.finance.core import calculate_tax

        # Inside an FHE circuit (18% tax)
        # tax_amount = calculate_tax(enc_amount, rate=0.18)
        ```
    """
    return apply_rate(amount, rate)

discount 

discount(amount: Any, rate: float) -> Any

Calculate the discounted amount at RATE_SCALE scaling.

Parameters:

Name Type Description Default
amount Any

The encrypted integer amount to be processed.

 required
rate float

A public floating point rate (e.g., 0.05 for 5%).

 required

Returns:

Name Type Description
Any Any

The encrypted discounted amount scaled by RATE_SCALE.
Example 
from concrete_fhe_toolkit.finance.core import discount

# Inside an FHE circuit (20% discount)
# final_price = discount(enc_amount, rate=0.20)
Source code in src/concrete_fhe_toolkit/finance/core.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def discount(amount: Any, rate: float) -> Any:
    """Calculate the discounted amount at RATE_SCALE scaling.

    Args:
        amount (Any): The encrypted integer amount to be processed.
        rate (float): A public floating point rate (e.g., 0.05 for 5%).

    Returns:
        Any: The encrypted discounted amount scaled by RATE_SCALE.

    Example:
        ```python
        from concrete_fhe_toolkit.finance.core import discount

        # Inside an FHE circuit (20% discount)
        # final_price = discount(enc_amount, rate=0.20)
        ```
    """
    return (amount * RATE_SCALE) - apply_rate(amount, rate)

simple_interest 

simple_interest(amount: Any, rate: float, time_period: Any) -> Any

Calculate simple interest (amount * rate * time) at RATE_SCALE scaling.

Parameters:

Name Type Description Default
amount Any

The encrypted integer amount to be processed.

 required
rate float

A public floating point rate (e.g., 0.05 for 5%).

 required
time_period Any

The encrypted or plaintext time period.

 required

Returns:

Name Type Description
Any Any

The encrypted simple interest scaled by RATE_SCALE.
Example 
from concrete_fhe_toolkit.finance.core import simple_interest

# Inside an FHE circuit (e.g. 5% interest over 3 years)
# interest = simple_interest(enc_amount, rate=0.05, time_period=3)
Source code in src/concrete_fhe_toolkit/finance/core.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
def simple_interest(amount: Any, rate: float, time_period: Any) -> Any:
    """Calculate simple interest (amount * rate * time) at RATE_SCALE scaling.

    Args:
        amount (Any): The encrypted integer amount to be processed.
        rate (float): A public floating point rate (e.g., 0.05 for 5%).
        time_period (Any): The encrypted or plaintext time period.

    Returns:
        Any: The encrypted simple interest scaled by RATE_SCALE.

    Example:
        ```python
        from concrete_fhe_toolkit.finance.core import simple_interest

        # Inside an FHE circuit (e.g. 5% interest over 3 years)
        # interest = simple_interest(enc_amount, rate=0.05, time_period=3)
        ```
    """
    return apply_rate(amount, rate) * time_period