Module builder 

Convenience builders for constructing shielded state transitions.

These functions encapsulate the full Orchard bundle construction pipeline: builder configuration, proof generation, signature application, and serialization into platform state transitions.

Requires the shielded-client feature, which pulls in grovedb-commitment-tree (and transitively the orchard crate).

Example

use dpp::shielded::builder::*;
use grovedb_commitment_tree::{SpendingKey, FullViewingKey, Scope, ProvingKey};

// Derive recipient address
let sk = SpendingKey::from_bytes(seed)?;
let fvk = FullViewingKey::from(&sk);
let recipient = OrchardAddress::from_raw_bytes(
    &fvk.address_at(0, Scope::External).to_raw_address_bytes(),
);

// Build a shield transition; pass the sender's OVK so the wallet can
// later recover its own send from chain data (None = unrecoverable)
let pk = ProvingKey::build();
let st = build_shield_transition(
    &recipient, shield_amount, inputs, fee_strategy,
    &signer, 0, &pk, [0u8; 36], Some(fvk.to_ovk(Scope::External)), platform_version,
)?;

Structs

IdentityCreateFromShieldedPoolBuildResult

Output of build_identity_create_from_shielded_pool_transition: everything the SDK’s IdentityCreateFromShieldedPool::identity_create_from_shielded_pool broadcast helper needs.

SerializedBundle

The serialized fields extracted from an authorized Orchard bundle, ready for use by state transition constructors.

ShieldedFeePayer

The credit pool side of an identity-less token pool transition: the wallet’s credit pool notes to spend, where the change goes, and the keys that authorize the spend.

SpendableNote

A note that can be spent in a shielded transaction, paired with its Merkle inclusion path in the commitment tree.

TokenPoolSpender

The wallet’s notes in a token’s shielded pool and the keys that spend them.

Traits

OrchardProver

Trait abstracting over Orchard proof generation.

Functions

build_document_shielded_token_payment

Builds the shielded payment of a document action whose token cost is amount: spends spends from the token’s shielded pool, returns the remainder to change_address as a new note and binds the token id, the batch owner, the document’s contract and id and the amount into the Orchard sighash. Put the result into a TokenPaymentInfo::V1 on the document transition’s base; the identity signing the batch still pays the credit fee.

build_identity_create_from_shielded_pool_transition

Builds an IdentityCreateFromShieldedPool (Type 20) state transition: spend shielded-pool notes to fund a brand-new Platform identity.

build_identity_top_up_from_shielded_pool_transition

Build an IdentityTopUpFromShieldedPool transition: spend spends so that exactly top_up_amount + fee leaves the pool, sending change back to change_address. The identity receives top_up_amount; the flat fee is carved from the value balance exactly as Unshield does. Returns the transition and the fee used.

build_shield_from_asset_lock_transition

Builds a ShieldFromAssetLock state transition (core asset lock -> shielded pool).

build_shield_from_asset_lock_transition_with_signer

Builds a ShieldFromAssetLock state transition where the asset-lock-proof signature is produced by an external [key_wallet::signer::Signer] (Swift / hardware-wallet / HSM flow). The raw private key never crosses the FFI boundary; derive + sign + zeroise happen inside the signer.

build_shield_from_identity_transition

Build a ShieldFromIdentity transition: prove an outputs-only Orchard bundle paying shield_amount to recipient, then identity-sign it with a TRANSFER key.

build_shield_transition

Builds a Shield state transition (transparent platform addresses -> shielded pool).

build_shielded_transfer_transition

Builds a ShieldedTransfer state transition (shielded pool -> shielded pool).

build_shielded_withdrawal_transition

Builds a ShieldedWithdrawal state transition (shielded pool -> core L1 address).

build_token_burn_from_pool_transition

Builds a TokenBurnFromPool batch transition: spends spends inside the token’s shielded pool, destroys amount and returns the remainder to change_address, then wraps the bundle in a batch transition signed by owner_id, who must be authorized to burn and pays the fee in credits. The token id, owner id and amount are bound into the Orchard sighash.

build_token_claim_to_pool_transition

Builds a TokenClaimToPool batch transition: proves an outputs-only Orchard bundle creating amount of the token as a note for recipient inside the token’s shielded pool, then wraps it in a batch transition signed by owner_id, the claimant, who pays the fee in credits.

build_token_direct_purchase_to_pool_transition

Builds a TokenDirectPurchaseToPool batch transition: proves an outputs-only Orchard bundle creating token_count of the token as a note for recipient inside the token’s shielded pool, then wraps it in a batch transition signed by owner_id, the buyer, who pays at most total_agreed_price credits to the contract owner plus the fee.

build_token_mint_to_pool_transition

Builds a TokenMintToPool batch transition: proves an outputs-only Orchard bundle creating amount of the token as a note for recipient inside the token’s shielded pool, then wraps it in a batch transition signed by owner_id, who must be authorized to mint and pays the fee in credits. using_group_info sets up a group action exactly like a transparent mint.

build_token_purchase_from_shielded_pool_transition

Builds a TokenPurchaseFromShieldedPool: token_count tokens are bought at total_agreed_price credits (which must match the token’s direct purchase price) paid out of the credit shielded pool together with the fee, and minted into a note for recipient in the token’s shielded pool. Returns the transition and the fee paid.

build_token_shield_transition

Builds a TokenShield batch transition: proves an outputs-only Orchard bundle paying amount of the token to recipient inside the token’s own shielded pool, then wraps it in a batch transition signed by owner_id, the identity whose token balance funds the shield.

build_token_shielded_transfer_transition

Builds a TokenShieldedTransfer batch transition: spends spends inside the token’s shielded pool, pays transfer_amount to recipient and any remainder to change_address, and wraps the bundle in a batch transition signed by owner_id, which pays the fee in credits.

build_token_shielded_transfer_with_shielded_fee_transition

Builds a TokenShieldedTransferWithShieldedFee: pays transfer_amount of the token to recipient inside the token’s shielded pool (value balance zero) and the fee out of the credit shielded pool. No identity is involved. Returns the transition and the fee paid.

build_token_unshield_transition

Builds a TokenUnshield batch transition: spends spends from the token’s shielded pool, credits amount tokens to recipient_id, returns the remainder to change_address as a new note, and wraps the bundle in a batch transition signed by owner_id.

build_token_unshield_with_shielded_fee_transition

Builds a TokenUnshieldWithShieldedFee: amount of the token leaves the token’s shielded pool into recipient_id’s balance, the fee is paid out of the credit shielded pool. Returns the transition and the fee paid.

build_unshield_transition

Builds an Unshield state transition (shielded pool -> platform address).

serialize_authorized_bundle

Serializes an authorized Orchard bundle into the raw fields used by state transition constructors.