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 authored Jul 23, 2024
2 parents 0a8d57d + ee4f59e commit b4b1372
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
Original file line number Diff line number Diff line change
@@ -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)


@@ -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.
@@ -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>
221 changes: 195 additions & 26 deletions crates/iota-framework/docs/iota-framework/iota.mdx
Original file line number Diff line number Diff line change
@@ -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>
@@ -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>


@@ -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>


@@ -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>);

@@ -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>

@@ -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 b4b1372

Please sign in to comment.