language/diem-framework/modules/doc/DesignatedDealer.md
<a name="0x1_DesignatedDealer"></a>
0x1::DesignatedDealerModule providing functionality for designated dealers.
DealerTierInfoReceivedMintEventpublish_designated_dealer_credentialadd_currencyadd_currency_for_testtiered_mintexists_at<a name="0x1_DesignatedDealer_Dealer"></a>
DealerA <code><a href="DesignatedDealer.md#0x1_DesignatedDealer">DesignatedDealer</a></code> always holds this <code><a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a></code> resource regardless of the currencies it can hold. All <code><a href="DesignatedDealer.md#0x1_DesignatedDealer_ReceivedMintEvent">ReceivedMintEvent</a></code> events for all currencies will be emitted on <code>mint_event_handle</code>.
<pre><code><b>struct</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a> has key </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>mint_event_handle: <a href="../../../../../../move-stdlib/docs/Event.md#0x1_Event_EventHandle">Event::EventHandle</a><<a href="DesignatedDealer.md#0x1_DesignatedDealer_ReceivedMintEvent">DesignatedDealer::ReceivedMintEvent</a>></code> </dt> <dd> Handle for mint events </dd> </dl> </details><a name="0x1_DesignatedDealer_TierInfo"></a>
TierInfoThe <code><a href="DesignatedDealer.md#0x1_DesignatedDealer_TierInfo">TierInfo</a></code> resource holds the information needed to track which tier a mint to a DD needs to be in. DEPRECATED: This resource is no longer used and will be removed from the system
<pre><code><b>struct</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_TierInfo">TierInfo</a><CoinType> has key </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>window_start: u64</code> </dt> <dd> Time window start in microseconds </dd> <dt> <code>window_inflow: u64</code> </dt> <dd> The minted inflow during this time window </dd> <dt> <code>tiers: vector<u64></code> </dt> <dd> 0-indexed array of tier upperbounds </dd> </dl> </details><a name="0x1_DesignatedDealer_ReceivedMintEvent"></a>
ReceivedMintEventMessage for mint events
<pre><code><b>struct</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_ReceivedMintEvent">ReceivedMintEvent</a> has drop, store </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>currency_code: vector<u8></code> </dt> <dd> The currency minted </dd> <dt> <code>destination_address: address</code> </dt> <dd> The address that receives the mint </dd> <dt> <code>amount: u64</code> </dt> <dd> The amount minted (in base units of <code>currency_code</code>) </dd> </dl> </details><a name="@Constants_0"></a>
<a name="0x1_DesignatedDealer_EDEALER"></a>
The <code><a href="DesignatedDealer.md#0x1_DesignatedDealer">DesignatedDealer</a></code> resource is in an invalid state
<pre><code><b>const</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_EDEALER">EDEALER</a>: u64 = 0; </code></pre><a name="0x1_DesignatedDealer_EINVALID_MINT_AMOUNT"></a>
A zero mint amount was provided
<pre><code><b>const</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_EINVALID_MINT_AMOUNT">EINVALID_MINT_AMOUNT</a>: u64 = 4; </code></pre><a name="0x1_DesignatedDealer_publish_designated_dealer_credential"></a>
publish_designated_dealer_credentialPublishes a <code><a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a></code> resource under <code>dd</code> with a <code>PreburnQueue</code>. If <code>add_all_currencies = <b>true</b></code> this will add a <code>PreburnQueue</code>, for each known currency at launch.
<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_publish_designated_dealer_credential">publish_designated_dealer_credential</a><CoinType>(dd: &signer, tc_account: &signer, add_all_currencies: bool) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_publish_designated_dealer_credential">publish_designated_dealer_credential</a><CoinType>( dd: &signer, tc_account: &signer, add_all_currencies: bool, ){ <a href="Roles.md#0x1_Roles_assert_treasury_compliance">Roles::assert_treasury_compliance</a>(tc_account); <a href="Roles.md#0x1_Roles_assert_designated_dealer">Roles::assert_designated_dealer</a>(dd); <b>assert</b>(!<b>exists</b><<a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a>>(<a href="../../../../../../move-stdlib/docs/Signer.md#0x1_Signer_address_of">Signer::address_of</a>(dd)), <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_already_published">Errors::already_published</a>(<a href="DesignatedDealer.md#0x1_DesignatedDealer_EDEALER">EDEALER</a>)); move_to(dd, <a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a> { mint_event_handle: <a href="../../../../../../move-stdlib/docs/Event.md#0x1_Event_new_event_handle">Event::new_event_handle</a><<a href="DesignatedDealer.md#0x1_DesignatedDealer_ReceivedMintEvent">ReceivedMintEvent</a>>(dd) }); <b>if</b> (add_all_currencies) { <a href="DesignatedDealer.md#0x1_DesignatedDealer_add_currency">add_currency</a><<a href="XUS.md#0x1_XUS">XUS</a>>(dd, tc_account); } <b>else</b> { <a href="DesignatedDealer.md#0x1_DesignatedDealer_add_currency">add_currency</a><CoinType>(dd, tc_account); }; } </code></pre> </details> <details> <summary>Specification</summary> <pre><code><b>pragma</b> opaque; <b>let</b> dd_addr = <a href="../../../../../../move-stdlib/docs/Signer.md#0x1_Signer_spec_address_of">Signer::spec_address_of</a>(dd); <b>include</b> <a href="Roles.md#0x1_Roles_AbortsIfNotTreasuryCompliance">Roles::AbortsIfNotTreasuryCompliance</a>{account: tc_account}; <b>include</b> <a href="Roles.md#0x1_Roles_AbortsIfNotDesignatedDealer">Roles::AbortsIfNotDesignatedDealer</a>{account: dd}; <b>aborts_if</b> <b>exists</b><<a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a>>(dd_addr) <b>with</b> <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_ALREADY_PUBLISHED">Errors::ALREADY_PUBLISHED</a>; <b>include</b> <b>if</b> (add_all_currencies) <a href="DesignatedDealer.md#0x1_DesignatedDealer_AddCurrencyAbortsIf">AddCurrencyAbortsIf</a><<a href="XUS.md#0x1_XUS">XUS</a>>{dd_addr: dd_addr} <b>else</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_AddCurrencyAbortsIf">AddCurrencyAbortsIf</a><CoinType>{dd_addr: dd_addr}; <b>modifies</b> <b>global</b><<a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a>>(dd_addr); <b>ensures</b> <b>exists</b><<a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a>>(dd_addr); <b>modifies</b> <b>global</b><<a href="../../../../../../move-stdlib/docs/Event.md#0x1_Event_EventHandleGenerator">Event::EventHandleGenerator</a>>(dd_addr); <b>modifies</b> <b>global</b><<a href="Diem.md#0x1_Diem_PreburnQueue">Diem::PreburnQueue</a><CoinType>>(dd_addr); <b>modifies</b> <b>global</b><<a href="Diem.md#0x1_Diem_PreburnQueue">Diem::PreburnQueue</a><<a href="XUS.md#0x1_XUS">XUS</a>>>(dd_addr); </code></pre> </details><a name="0x1_DesignatedDealer_add_currency"></a>
add_currencyAdds the needed resources to the DD account <code>dd</code> in order to work with <code>CoinType</code>. Public so that a currency can be added to a DD later on. Will require multi-signer transactions in order to add a new currency to an existing DD.
<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_add_currency">add_currency</a><CoinType>(dd: &signer, tc_account: &signer) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_add_currency">add_currency</a><CoinType>(dd: &signer, tc_account: &signer) { <a href="Roles.md#0x1_Roles_assert_treasury_compliance">Roles::assert_treasury_compliance</a>(tc_account); <b>let</b> dd_addr = <a href="../../../../../../move-stdlib/docs/Signer.md#0x1_Signer_address_of">Signer::address_of</a>(dd); <b>assert</b>(<a href="DesignatedDealer.md#0x1_DesignatedDealer_exists_at">exists_at</a>(dd_addr), <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_not_published">Errors::not_published</a>(<a href="DesignatedDealer.md#0x1_DesignatedDealer_EDEALER">EDEALER</a>)); <a href="Diem.md#0x1_Diem_publish_preburn_queue_to_account">Diem::publish_preburn_queue_to_account</a><CoinType>(dd, tc_account); } </code></pre> </details> <details> <summary>Specification</summary> <pre><code><b>pragma</b> opaque; <b>let</b> dd_addr = <a href="../../../../../../move-stdlib/docs/Signer.md#0x1_Signer_spec_address_of">Signer::spec_address_of</a>(dd); <b>include</b> <a href="Roles.md#0x1_Roles_AbortsIfNotTreasuryCompliance">Roles::AbortsIfNotTreasuryCompliance</a>{account: tc_account}; <b>include</b> <a href="Roles.md#0x1_Roles_AbortsIfNotDesignatedDealer">Roles::AbortsIfNotDesignatedDealer</a>{account: dd}; <b>include</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_AbortsIfNoDealer">AbortsIfNoDealer</a>{dd_addr: dd_addr}; <b>include</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_AddCurrencyAbortsIf">AddCurrencyAbortsIf</a><CoinType>{dd_addr: dd_addr}; <b>modifies</b> <b>global</b><<a href="Diem.md#0x1_Diem_PreburnQueue">Diem::PreburnQueue</a><CoinType>>(dd_addr); </code></pre><a name="0x1_DesignatedDealer_AddCurrencyAbortsIf"></a>
<pre><code><b>schema</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_AddCurrencyAbortsIf">AddCurrencyAbortsIf</a><CoinType> { dd_addr: address; <b>include</b> <a href="Diem.md#0x1_Diem_AbortsIfNoCurrency">Diem::AbortsIfNoCurrency</a><CoinType>; <b>aborts_if</b> <a href="Diem.md#0x1_Diem_is_synthetic_currency">Diem::is_synthetic_currency</a><CoinType>() <b>with</b> <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_INVALID_ARGUMENT">Errors::INVALID_ARGUMENT</a>; <b>aborts_if</b> <b>exists</b><<a href="Diem.md#0x1_Diem_PreburnQueue">Diem::PreburnQueue</a><CoinType>>(dd_addr) <b>with</b> <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_ALREADY_PUBLISHED">Errors::ALREADY_PUBLISHED</a>; <b>aborts_if</b> <b>exists</b><<a href="Diem.md#0x1_Diem_Preburn">Diem::Preburn</a><CoinType>>(dd_addr) <b>with</b> <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_INVALID_STATE">Errors::INVALID_STATE</a>; } </code></pre> </details><a name="0x1_DesignatedDealer_add_currency_for_test"></a>
add_currency_for_test<a name="0x1_DesignatedDealer_tiered_mint"></a>
tiered_mint<a name="0x1_DesignatedDealer_TieredMintAbortsIf"></a>
<pre><code><b>schema</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_TieredMintAbortsIf">TieredMintAbortsIf</a><CoinType> { tc_account: signer; dd_addr: address; amount: u64; <b>include</b> <a href="Roles.md#0x1_Roles_AbortsIfNotTreasuryCompliance">Roles::AbortsIfNotTreasuryCompliance</a>{account: tc_account}; <b>aborts_if</b> amount == 0 <b>with</b> <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_INVALID_ARGUMENT">Errors::INVALID_ARGUMENT</a>; <b>include</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_AbortsIfNoDealer">AbortsIfNoDealer</a>; <b>aborts_if</b> !<b>exists</b><<a href="Diem.md#0x1_Diem_MintCapability">Diem::MintCapability</a><CoinType>>(<a href="../../../../../../move-stdlib/docs/Signer.md#0x1_Signer_spec_address_of">Signer::spec_address_of</a>(tc_account)) <b>with</b> <a href="../../../../../../move-stdlib/docs/Errors.md#0x1_Errors_REQUIRES_CAPABILITY">Errors::REQUIRES_CAPABILITY</a>; <b>include</b> <a href="Diem.md#0x1_Diem_MintAbortsIf">Diem::MintAbortsIf</a><CoinType>{value: amount}; } </code></pre><a name="0x1_DesignatedDealer_TieredMintEmits"></a>
<pre><code><b>schema</b> <a href="DesignatedDealer.md#0x1_DesignatedDealer_TieredMintEmits">TieredMintEmits</a><CoinType> { dd_addr: address; amount: u64; <b>let</b> handle = <b>global</b><<a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a>>(dd_addr).mint_event_handle; <b>let</b> msg = <a href="DesignatedDealer.md#0x1_DesignatedDealer_ReceivedMintEvent">ReceivedMintEvent</a> { currency_code: <a href="Diem.md#0x1_Diem_spec_currency_code">Diem::spec_currency_code</a><CoinType>(), destination_address: dd_addr, amount, }; emits msg <b>to</b> handle; <b>include</b> <a href="Diem.md#0x1_Diem_MintEmits">Diem::MintEmits</a><CoinType>{value: amount}; } </code></pre> </details><a name="0x1_DesignatedDealer_exists_at"></a>
exists_at<a name="@Module_Specification_1"></a>
resource struct Dealer persists after publication
<pre><code><b>invariant</b> <b>update</b> <b>forall</b> addr: address <b>where</b> <b>old</b>(<b>exists</b><<a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a>>(addr)): <b>exists</b><<a href="DesignatedDealer.md#0x1_DesignatedDealer_Dealer">Dealer</a>>(addr); </code></pre>