From fe9239dd0fee9d1639b8c6ceb74104a078492010 Mon Sep 17 00:00:00 2001 From: Marco Granelli Date: Fri, 24 Oct 2025 15:22:59 +0200 Subject: [PATCH 1/2] Documents masp frontend sustainability fees --- .../sdk/shielded-transfers.mdx | 46 ++++++++++++++++--- 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/shielded-transfers.mdx b/packages/docs/pages/integrating-with-namada/sdk/shielded-transfers.mdx index 93f8e28b..bb7841ca 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/shielded-transfers.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/shielded-transfers.mdx @@ -1,14 +1,19 @@ +import { Callout } from 'nextra-theme-docs' + # Shielded Transfers -You can construct shielded transfers similarly to transparent transfers, except that rather than providing implicit addresses as the `source` and `target`, -you will need to provide a spending key and payment address, respectively. +You can construct shielded transfers similarly to transparent transfers, except +that rather than providing implicit addresses as the `source` and `target`, you +will need to provide a spending key and payment address, respectively. -Before building your transaction, you will want to make sure the [shielded wallet is synced](./shielded-sync.mdx). +Before building your transaction, you will want to make sure the +[shielded wallet is synced](./shielded-sync.mdx). ### Constructing the Transfer -This example assumes you have a spending key with sufficient shielded balance, a recipient payment address, and the -public key of an implicit account with gas funds. +This example assumes you have a spending key with sufficient shielded balance, a +recipient payment address, and the public key of an implicit account with gas +funds. ```rust use namada_sdk::Namada; @@ -56,4 +61,33 @@ async fn construct_transfer(sdk: impl Namada) { Err(e) => println!("Tx error: {:?}", e) } } -``` \ No newline at end of file +``` + +### Frontend sustainability fee + +For transactions that move assets into or out of the shielded pool, the namada +SDK provides the possibility to charge an optional fee to support the operations +of the frontend provider. The specific transactions are: + +- `TxShieldingTransfer` +- `TxUnshieldingTransfer` +- `TxOsmosisSwap` +- `TxIbcTransfer` +- `GenIbcShieldingTransfer` + + + For fully shielded osmosis swaps (from shieleded address to shielded address), + the operator should refrain from charging a fee. + + +These structures provide an optional field in one of two forms: + +```rust + pub frontend_sus_fee: Option<(C::TransferTarget, Dec)>, + pub frontend_sus_fee: Option<(C::PaymentAddress, Dec)>, +``` + +where the first element of the tuple is the receiver of the fee (an address +controlled by the operator) and the second one is the fee expressed as a +percentage of the shielded/unshielded amount. This percentage will be charged on +top of the amount specified by the user. From 542849f0686696c7ca97186db05e283ced967f8c Mon Sep 17 00:00:00 2001 From: Marco Granelli Date: Mon, 27 Oct 2025 16:00:05 +0100 Subject: [PATCH 2/2] Improves frontend shielded fee docs --- .../sdk/shielded-transfers.mdx | 25 ++++++++++++++++--- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/shielded-transfers.mdx b/packages/docs/pages/integrating-with-namada/sdk/shielded-transfers.mdx index bb7841ca..bd7ea6c9 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/shielded-transfers.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/shielded-transfers.mdx @@ -1,4 +1,4 @@ -import { Callout } from 'nextra-theme-docs' +import { Callout } from "nextra-theme-docs"; # Shielded Transfers @@ -77,7 +77,9 @@ of the frontend provider. The specific transactions are: For fully shielded osmosis swaps (from shieleded address to shielded address), - the operator should refrain from charging a fee. + the operator should refrain from charging a fee as the unshielding and + reshielding operations are only needed to perform the swap but the value + inside the shielded pool remains unchanged. These structures provide an optional field in one of two forms: @@ -89,5 +91,20 @@ These structures provide an optional field in one of two forms: where the first element of the tuple is the receiver of the fee (an address controlled by the operator) and the second one is the fee expressed as a -percentage of the shielded/unshielded amount. This percentage will be charged on -top of the amount specified by the user. +percentage of the shielded/unshielded amount. By providing a value for this +field, the SDK builder for the desired transaction will inject extra inputs (one +for every source address) and an extra output to the transfer data (no batching +required): more specifically, the provided percentage will be taken from every +transfer's source on top of the amount specified by the user and sent to the +provided target address. Whether these extra inputs/output are shielded or +transparent depends on the specific transaction and its sources: when the +transaction's source is transparent an extra trasparent input will be added to +the `Transfer` data, whereas if the input is shielded another shieleded input +will be added to the MASP `Transaction` section. The output can either be +shielded or transparent when the above `frontend_sus_fee` specifies it via the +`C::TransferTarget` type. For the `TxOsmosisSwap` and `GenIbcShieldingTransfer` +transactions instead, the fee target can be specified only as a shielded payment +address. + +The user will accept this fee when signing the transaction since this +information will be available to them for review and acceptance at that time.