Skip to content

Commit

Permalink
Merge pull request #1052 from iotaledger/sc-platform/issue-153
Browse files Browse the repository at this point in the history 
feat: Staking reward generation through inflation
  • Loading branch information
@lzpap
lzpap authored Jul 23, 2024
2 parents e9ee3d4 + 27bdb4a commit 639f386
Show file tree
Hide file tree
Showing 23 changed files with 1,335 additions and 515 deletions.
45 changes: 45 additions & 0 deletions crates/iota-framework/docs/iota-framework/balance.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ custom coins with <code>
- [Function `destroy_zero`](#0x2_balance_destroy_zero)
- [Function `create_staking_rewards`](#0x2_balance_create_staking_rewards)
- [Function `destroy_storage_rebates`](#0x2_balance_destroy_storage_rebates)
- [Function `destroy_genesis_supply`](#0x2_balance_destroy_genesis_supply)
- [Function `destroy_supply`](#0x2_balance_destroy_supply)


Expand Down Expand Up @@ -138,6 +139,17 @@ For when trying to withdraw more than there is.



<Link id="0x2_balance_ENotGenesisEpoch"></Link>

Epoch is not 0 (the genesis epoch).


<pre><code>
<b>const</b> <Link to="../iota-framework/balance#0x2_balance_ENotGenesisEpoch">ENotGenesisEpoch</Link>: u64 = 4;
</code></pre>



<Link id="0x2_balance_EOverflow"></Link>

For when an overflow is happening on Supply operations.
Expand Down Expand Up @@ -498,6 +510,39 @@ and nowhere else.



</details>

<Link id="0x2_balance_destroy_genesis_supply"></Link>

## Function `destroy_genesis_supply`

CAUTION: this function destroys a <code>
<Link to="../iota-framework/balance#0x2_balance_Balance">Balance</Link></code> without decreasing the supply.
It should only be called by the genesis txn to destroy parts of the IOTA supply
which was created during the migration and for no other reason.


<pre><code>
<b>fun</b> <Link to="../iota-framework/balance#0x2_balance_destroy_genesis_supply">destroy_genesis_supply</Link>&lt;T&gt;(self: <Link to="../iota-framework/balance#0x2_balance_Balance">balance::Balance</Link>&lt;T&gt;, ctx: &<Link to="../iota-framework/tx_context#0x2_tx_context_TxContext">tx_context::TxContext</Link>)
</code></pre>



<details>
<summary>Implementation</summary>


<pre><code>
<b>fun</b> <Link to="../iota-framework/balance#0x2_balance_destroy_genesis_supply">destroy_genesis_supply</Link>&lt;T&gt;(self: <Link to="../iota-framework/balance#0x2_balance_Balance">Balance</Link>&lt;T&gt;, ctx: &TxContext) \{
<b>assert</b>!(ctx.sender() == @0x0, <Link to="../iota-framework/balance#0x2_balance_ENotSystemAddress">ENotSystemAddress</Link>);
<b>assert</b>!(ctx.epoch() == 0, <Link to="../iota-framework/balance#0x2_balance_ENotGenesisEpoch">ENotGenesisEpoch</Link>);

<b>let</b> <Link to="../iota-framework/balance#0x2_balance_Balance">Balance</Link> \{ value: _ } = self;
}
</code></pre>



</details>

<Link id="0x2_balance_destroy_supply"></Link>
Expand Down
221 changes: 195 additions & 26 deletions crates/iota-framework/docs/iota-framework/iota.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,15 @@ It has 9 decimals, and the smallest unit (10^-9) is called "nano".


- [Struct `IOTA`](#0x2_iota_IOTA)
- [Struct `IotaTreasuryCap`](#0x2_iota_IotaTreasuryCap)
- [Constants](#@Constants_0)
- [Function `new`](#0x2_iota_new)
- [Function `transfer`](#0x2_iota_transfer)
- [Function `mint`](#0x2_iota_mint)
- [Function `mint_balance`](#0x2_iota_mint_balance)
- [Function `burn`](#0x2_iota_burn)
- [Function `burn_balance`](#0x2_iota_burn_balance)
- [Function `total_supply`](#0x2_iota_total_supply)


<pre><code>
Expand Down Expand Up @@ -55,51 +61,59 @@ dummy_field: bool</code>

</details>

<Link id="@Constants_0"></Link>

## Constants
<Link id="0x2_iota_IotaTreasuryCap"></Link>

## Struct `IotaTreasuryCap`

<Link id="0x2_iota_ENotSystemAddress"></Link>

Sender is not @0x0 the system address.
The IOTA token treasury capability.
Protects the token from unauthorized changes.


<pre><code>
<b>const</b> <Link to="../iota-framework/iota#0x2_iota_ENotSystemAddress">ENotSystemAddress</Link>: u64 = 1;
<b>struct</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link> <b>has</b> store
</code></pre>



<Link id="0x2_iota_EAlreadyMinted"></Link>
<details>
<summary>Fields</summary>


<dl>
<dt>
<code>
inner: <Link to="../iota-framework/coin#0x2_coin_TreasuryCap">coin::TreasuryCap</Link>&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">iota::IOTA</Link>&gt;</code>
</dt>
<dd>

<pre><code>
<b>const</b> <Link to="../iota-framework/iota#0x2_iota_EAlreadyMinted">EAlreadyMinted</Link>: u64 = 0;
</code></pre>
</dd>
</dl>


</details>

<Link id="0x2_iota_NANO_PER_IOTA"></Link>
<Link id="@Constants_0"></Link>

## Constants

The amount of Nanos per IOTA token based on the fact that nano is
10^-9 of a IOTA token

<Link id="0x2_iota_ENotSystemAddress"></Link>

Sender is not @0x0 the system address.


<pre><code>
<b>const</b> <Link to="../iota-framework/iota#0x2_iota_NANO_PER_IOTA">NANO_PER_IOTA</Link>: u64 = 1000000000;
<b>const</b> <Link to="../iota-framework/iota#0x2_iota_ENotSystemAddress">ENotSystemAddress</Link>: u64 = 1;
</code></pre>



<Link id="0x2_iota_TOTAL_SUPPLY_NANO"></Link>
<Link id="0x2_iota_EAlreadyMinted"></Link>

The total supply of IOTA denominated in Nano (4.6 Billion * 10^9)


<pre><code>
<b>const</b> <Link to="../iota-framework/iota#0x2_iota_TOTAL_SUPPLY_NANO">TOTAL_SUPPLY_NANO</Link>: u64 = 4600000000000000000;
<b>const</b> <Link to="../iota-framework/iota#0x2_iota_EAlreadyMinted">EAlreadyMinted</Link>: u64 = 0;
</code></pre>


Expand All @@ -109,13 +123,13 @@ The total supply of IOTA denominated in Nano (4.6 Billion * 10^9)
## Function `new`

Register the <code>
<Link to="../iota-framework/iota#0x2_iota_IOTA">IOTA</Link></code> Coin to acquire its <code>
Supply</code>.
<Link to="../iota-framework/iota#0x2_iota_IOTA">IOTA</Link></code> Coin to acquire <code>
<Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link></code>.
This should be called only once during genesis creation.


<pre><code>
<b>fun</b> <Link to="../iota-framework/iota#0x2_iota_new">new</Link>(ctx: &<b>mut</b> <Link to="../iota-framework/tx_context#0x2_tx_context_TxContext">tx_context::TxContext</Link>): <Link to="../iota-framework/balance#0x2_balance_Balance">balance::Balance</Link>&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">iota::IOTA</Link>&gt;
<b>fun</b> <Link to="../iota-framework/iota#0x2_iota_new">new</Link>(ctx: &<b>mut</b> <Link to="../iota-framework/tx_context#0x2_tx_context_TxContext">tx_context::TxContext</Link>): <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">iota::IotaTreasuryCap</Link>
</code></pre>


Expand All @@ -125,7 +139,7 @@ This should be called only once during genesis creation.


<pre><code>
<b>fun</b> <Link to="../iota-framework/iota#0x2_iota_new">new</Link>(ctx: &<b>mut</b> TxContext): Balance&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">IOTA</Link>&gt; \{
<b>fun</b> <Link to="../iota-framework/iota#0x2_iota_new">new</Link>(ctx: &<b>mut</b> TxContext): <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link> \{
<b>assert</b>!(ctx.sender() == @0x0, <Link to="../iota-framework/iota#0x2_iota_ENotSystemAddress">ENotSystemAddress</Link>);
<b>assert</b>!(ctx.epoch() == 0, <Link to="../iota-framework/iota#0x2_iota_EAlreadyMinted">EAlreadyMinted</Link>);

Expand All @@ -138,11 +152,12 @@ This should be called only once during genesis creation.
<Link to="../move-stdlib/option#0x1_option_some">option::some</Link>(<Link to="../iota-framework/url#0x2_url_new_unsafe_from_bytes">url::new_unsafe_from_bytes</Link>(b"https://<Link to="../iota-framework/iota#0x2_iota">iota</Link>.org/logo.png")),
ctx
);

<Link to="../iota-framework/transfer#0x2_transfer_public_freeze_object">transfer::public_freeze_object</Link>(metadata);
<b>let</b> <b>mut</b> supply = treasury.treasury_into_supply();
<b>let</b> total_iota = supply.increase_supply(<Link to="../iota-framework/iota#0x2_iota_TOTAL_SUPPLY_NANO">TOTAL_SUPPLY_NANO</Link>);
supply.destroy_supply();
total_iota

<Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link> \{
inner: treasury,
}
}
</code></pre>

Expand Down Expand Up @@ -174,4 +189,158 @@ This should be called only once during genesis creation.



</details>

<Link id="0x2_iota_mint"></Link>

## Function `mint`

Create an IOTA coin worth <code>
value</code> and increase the total supply in <code>
cap</code> accordingly.


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_mint">mint</Link>(cap: &<b>mut</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">iota::IotaTreasuryCap</Link>, value: u64, ctx: &<b>mut</b> <Link to="../iota-framework/tx_context#0x2_tx_context_TxContext">tx_context::TxContext</Link>): <Link to="../iota-framework/coin#0x2_coin_Coin">coin::Coin</Link>&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">iota::IOTA</Link>&gt;
</code></pre>



<details>
<summary>Implementation</summary>


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_mint">mint</Link>(cap: &<b>mut</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link>, value: u64, ctx: &<b>mut</b> TxContext): Coin&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">IOTA</Link>&gt; \{
<b>assert</b>!(ctx.sender() == @0x0, <Link to="../iota-framework/iota#0x2_iota_ENotSystemAddress">ENotSystemAddress</Link>);

cap.inner.<Link to="../iota-framework/iota#0x2_iota_mint">mint</Link>(value, ctx)
}
</code></pre>



</details>

<Link id="0x2_iota_mint_balance"></Link>

## Function `mint_balance`

Mint some amount of IOTA as a <code>
Balance</code> and increase the total supply in <code>
cap</code> accordingly.
Aborts if <code>
value</code> + <code>
cap.inner.total_supply</code> >= U64_MAX


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_mint_balance">mint_balance</Link>(cap: &<b>mut</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">iota::IotaTreasuryCap</Link>, value: u64, ctx: &<Link to="../iota-framework/tx_context#0x2_tx_context_TxContext">tx_context::TxContext</Link>): <Link to="../iota-framework/balance#0x2_balance_Balance">balance::Balance</Link>&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">iota::IOTA</Link>&gt;
</code></pre>



<details>
<summary>Implementation</summary>


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_mint_balance">mint_balance</Link>(cap: &<b>mut</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link>, value: u64, ctx: &TxContext): Balance&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">IOTA</Link>&gt; \{
<b>assert</b>!(ctx.sender() == @0x0, <Link to="../iota-framework/iota#0x2_iota_ENotSystemAddress">ENotSystemAddress</Link>);

cap.inner.<Link to="../iota-framework/iota#0x2_iota_mint_balance">mint_balance</Link>(value)
}
</code></pre>



</details>

<Link id="0x2_iota_burn"></Link>

## Function `burn`

Destroy the IOTA coin <code>
c</code> and decrease the total supply in <code>
cap</code> accordingly.


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_burn">burn</Link>(cap: &<b>mut</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">iota::IotaTreasuryCap</Link>, c: <Link to="../iota-framework/coin#0x2_coin_Coin">coin::Coin</Link>&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">iota::IOTA</Link>&gt;, ctx: &<Link to="../iota-framework/tx_context#0x2_tx_context_TxContext">tx_context::TxContext</Link>): u64
</code></pre>



<details>
<summary>Implementation</summary>


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_burn">burn</Link>(cap: &<b>mut</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link>, c: Coin&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">IOTA</Link>&gt;, ctx: &TxContext): u64 \{
<b>assert</b>!(ctx.sender() == @0x0, <Link to="../iota-framework/iota#0x2_iota_ENotSystemAddress">ENotSystemAddress</Link>);

cap.inner.<Link to="../iota-framework/iota#0x2_iota_burn">burn</Link>(c)
}
</code></pre>



</details>

<Link id="0x2_iota_burn_balance"></Link>

## Function `burn_balance`

Destroy the IOTA balance <code>
b</code> and decrease the total supply in <code>
cap</code> accordingly.


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_burn_balance">burn_balance</Link>(cap: &<b>mut</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">iota::IotaTreasuryCap</Link>, b: <Link to="../iota-framework/balance#0x2_balance_Balance">balance::Balance</Link>&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">iota::IOTA</Link>&gt;, ctx: &<Link to="../iota-framework/tx_context#0x2_tx_context_TxContext">tx_context::TxContext</Link>): u64
</code></pre>



<details>
<summary>Implementation</summary>


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_burn_balance">burn_balance</Link>(cap: &<b>mut</b> <Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link>, b: Balance&lt;<Link to="../iota-framework/iota#0x2_iota_IOTA">IOTA</Link>&gt;, ctx: &TxContext): u64 \{
<b>assert</b>!(ctx.sender() == @0x0, <Link to="../iota-framework/iota#0x2_iota_ENotSystemAddress">ENotSystemAddress</Link>);

cap.inner.supply_mut().decrease_supply(b)
}
</code></pre>



</details>

<Link id="0x2_iota_total_supply"></Link>

## Function `total_supply`

Return the total number of IOTA's in circulation.


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_total_supply">total_supply</Link>(cap: &<Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">iota::IotaTreasuryCap</Link>): u64
</code></pre>



<details>
<summary>Implementation</summary>


<pre><code>
<b>public</b> <b>fun</b> <Link to="../iota-framework/iota#0x2_iota_total_supply">total_supply</Link>(cap: &<Link to="../iota-framework/iota#0x2_iota_IotaTreasuryCap">IotaTreasuryCap</Link>): u64 \{
cap.inner.<Link to="../iota-framework/iota#0x2_iota_total_supply">total_supply</Link>()
}
</code></pre>



</details>
Loading

0 comments on commit 639f386

Please sign in to comment.