# Shielding Coinbase UTXOs

**Summary**

Use the `z_shieldcoinbase` RPC call to move mining coinbase UTXOs into the shielded pool.

**Who should read this document**

Miners, mining pools, online wallets.

## Background

DragonX is a fully private chain from genesis (`ac_private=1`, Sapling active at
height 1). All ordinary payments are shielded (`z2z`) and transparent addresses can
never be transaction recipients — they only ever receive mining coinbase.

There is **no** consensus rule that coinbase must be shielded: mature coinbase is
directly spendable. `z_shieldcoinbase` is therefore an optional convenience for
miners who want to move coinbase into the shielded pool for privacy, and to sweep
up many small coinbase UTXOs in a single operation. See
[hd-transparent-keys.md](hd-transparent-keys.md) for how transparent coinbase keys
work on a private chain.

## User Experience Challenges

A user can use the `z_sendmany` RPC call to shield coinbase funds, but that call was
not designed for sweeping up many UTXOs and offers a suboptimal experience.

If customers send mining pool payouts to their online wallet, the service provider
must sort through UTXOs to correctly determine the non-coinbase UTXO funds that can be
withdrawn or transferred by customers.

## Solution

The `z_shieldcoinbase` call makes it easy to sweep up coinbase rewards from multiple
coinbase UTXOs across multiple coinbase reward addresses.

    z_shieldcoinbase fromaddress toaddress (fee) (limit)

The default fee is 0.0001 DRAGONX and the default limit on the maximum number of UTXOs
to shield is 50.

## Examples

Sweep up coinbase UTXOs from a transparent address you use for mining:

    dragonx-cli z_shieldcoinbase RMyMiningAddress zsMyPrivateAddress

Sweep up coinbase UTXOs from multiple transparent addresses to a shielded address:

    dragonx-cli z_shieldcoinbase "*" zsMyPrivateAddress

Sweep up with a fee of 1.23 DRAGONX:

    dragonx-cli z_shieldcoinbase RMyMiningAddress zsMyPrivateAddress 1.23

Sweep up with a fee of 0.1 DRAGONX and set limit on the maximum number of UTXOs to shield at 25:

    dragonx-cli z_shieldcoinbase "*" zsMyPrivateAddress 0.1 25

### Asynchronous Call

The `z_shieldcoinbase` RPC call is an asynchronous call, so you can queue up multiple operations.

When you invoke

    dragonx-cli z_shieldcoinbase RMyMiningAddress zsMyPrivateAddress

JSON will be returned immediately, with the following data fields populated:

- operationid: a temporary id to use with `z_getoperationstatus` and `z_getoperationresult` to get the status and result of the operation.
- shieldedUTXOs: number of coinbase UTXOs being shielded
- shieldedValue: value of coinbase UTXOs being shielded.
- remainingUTXOs: number of coinbase UTXOs still available for shielding.
- remainingValue: value of coinbase UTXOs still available for shielding

### Locking UTXOs

The `z_shieldcoinbase` call will lock any selected UTXOs. This prevents the selected UTXOs which are already queued up from being selected for any other send operation.  If the `z_shieldcoinbase` call fails, any locked UTXOs are unlocked.

You can use the RPC call `lockunspent` to see which UTXOs have been locked.  You can also use this call to unlock any UTXOs in the event of an unexpected system failure which leaves UTXOs in a locked state.

### Limits, Performance and Transaction Confirmation

The number of coinbase UTXOs selected for shielding can be adjusted by setting the limit parameter. The default value is 50.

If the limit parameter is set to zero, the `mempooltxinputlimit` option will be used instead, where the default value for `mempooltxinputlimit` is zero, which means no limit.

Any limit is constrained by a hard limit due to the consensus rule defining a maximum transaction size.

In general, the more UTXOs that are selected, the longer it takes for the transaction to be verified.  Due to the quadratic hashing problem, some miners use the `mempooltxinputlimit` option to reject transactions with a large number of UTXO inputs.

As a rule of thumb (a form of emergent consensus) if a transaction has less than 100 UTXO inputs, the transaction will be mined promptly by the majority of mining pools, but if it has many more UTXO inputs, such as 500, it might take longer to be mined by a miner who has higher or no limits.

### Anatomy of a z_shieldcoinbase transaction

The transaction created is a shielded transaction.  It consists of a single ShieldedSpend, which consumes coinbase UTXOs as input, and deposits value at a shielded address, minus any fee.

The number of coinbase UTXOs is determined by a user configured limit.

If no limit is set (in the case when limit parameter and `mempooltxinputlimit` options are set to zero) the behaviour of z_shieldcoinbase is to consume as many UTXOs as possible, with `z_shieldcoinbase` constructing a transaction up to the maximum size.
