KIP Draft: Threshold Address Format for KIP-10 Mutual Transactions

Introduction

This proposal introduces a new address type for Kaspa that leverages a compact floating-point representation for threshold values. The Float24 format enables efficient encoding of threshold values within P2SH scripts, borrowing functionality while maintaining compatibility with existing address infrastructure.

Motivation

Current address formats don’t efficiently support threshold-based spending conditions as described in KIP-10. By encoding threshold values directly in addresses, we can:

  • Support borrowing functionality where UTXOs can only be spent by increasing their value
  • Provide a compact representation for a wide range of threshold values
  • Maintain compatibility with existing P2SH infrastructure

Specification

Address Version

We propose a new address version for threshold-based scripts:

Version::ThresholdScript = 9

Address Structure

A threshold address consists of:

  • Network prefix (e.g., “kaspa”, “kaspatest”)
  • Version byte (9 for ThresholdScript)
  • Address payload (35 bytes for ECDSA, 35 bytes for Schnorr)

Address Payload Format

The address payload consists of:

  • Public key X coordinate (32 bytes)
  • Float24 threshold value (3 bytes)

The Float24 format uses 3 bytes (24 bits) with the following structure:

[1 bit: signature type] [1 bit: Y coordinate parity (ECDSA) or reserved (Schnorr)] [17 bits: mantissa] [5 bits: exponent]

Where:

  • Signature type bit: 0 for ECDSA, 1 for Schnorr
  • Y coordinate parity bit:
    • For ECDSA: 0 for even Y, 1 for odd Y
    • For Schnorr: Always 0 (reserved for future use)
  • Mantissa: 17-bit unsigned integer (0-131,071)
  • Exponent: 5-bit unsigned integer (0-31)

The threshold value is calculated as:

threshold = mantissa * (2^exponent)

Range of Representable Values

With this format, we can represent:

  • Minimum value: 0 * 2^0 = 0 sompi (allowing zero-threshold conditions)
  • Maximum value: 131,071 * 2^31 ≈ 281.4 trillion sompi

This range easily covers most practical threshold values, though it falls short of the maximum possible Kaspa supply of 29 billion KAS (2.9 * 10^18 sompi).

Script Template

The address automatically generates a P2SH script with the following pattern:

For non-zero thresholds:

OP_IF
   <pubkey> OP_CHECKSIG[_ECDSA]
OP_ELSE
   OP_TXINPUTINDEX OP_TXINPUTSPK OP_TXINPUTINDEX OP_TXOUTPUTSPK OP_EQUALVERIFY
   OP_TXINPUTINDEX OP_TXOUTPUTAMOUNT
   <threshold_value> OP_SUB
   OP_TXINPUTINDEX OP_TXINPUTAMOUNT
   OP_GREATERTHANOREQUAL
OP_ENDIF

Examples

Example 1: Zero Threshold with Schnorr

Public key X coordinate: 5fff3c4da18f45adcdd499e44611e9fff148ba69db3c4ea2ddd955fc46a59522 (32 bytes)
Signature type: Schnorr (1)
Y coordinate bit: 0 (reserved for Schnorr)
Threshold: 0 sompi
Float24: [1][0][00000000000000000][00000] (mantissa=0, exponent=0)

Example 2: Small Threshold (1,024 sompi) with Schnorr

Public key X coordinate: 5fff3c4da18f45adcdd499e44611e9fff148ba69db3c4ea2ddd955fc46a59522 (32 bytes)
Signature type: Schnorr (1)
Y coordinate bit: 0 (reserved for Schnorr)
Threshold: 1,024 sompi
Float24: [1][0][00000000000000001][00010] (mantissa=1, exponent=10)

Example 3: Medium Threshold (100,000 sompi) with ECDSA (Even Y)

Public key X coordinate: ba01fc5f4e9d9879599c69a3dafdb835a7255e5f2e934e9322ecd3af190ab0f6 (32 bytes)
Signature type: ECDSA (0)
Y coordinate bit: 0 (even Y)
Threshold: 100,000 sompi
Float24: [0][0][00000000001100100][00000] (mantissa=100000, exponent=0)

Example 4: Medium Threshold (5,242,880 sompi) with ECDSA (Odd Y)

Public key X coordinate: ba01fc5f4e9d9879599c69a3dafdb835a7255e5f2e934e9322ecd3af190ab0f6 (32 bytes)
Signature type: ECDSA (0)
Y coordinate bit: 1 (odd Y)
Threshold: 5,242,880 sompi
Float24: [0][1][00000000000000101][00020] (mantissa=5, exponent=20)

Example 5: Large Threshold (~1 million KAS) with Schnorr

Public key X coordinate: Public key X coordinate: 5fff3c4da18f45adcdd499e44611e9fff148ba69db3c4ea2ddd955fc46a59522 (32 bytes)
Signature type: Schnorr (1)
Y coordinate bit: 0 (reserved for Schnorr)
Threshold: 99,999,547,392 sompi (~999,995 KAS)
Float24: [1][0][10111010010000111][10100] (mantissa=95367, exponent=20)

Alternative Approaches

Alternative 1: Adjusting Bit Allocation for Full Range Coverage

One alternative approach would be to adjust the bit allocation to provide coverage for the full range of possible Kaspa values. By moving 1 bit from the mantissa to the exponent, we could use:

[1 bit: signature type] [1 bit: Y coordinate parity] [16 bits: mantissa] [6 bits: exponent]

With this adjustment:

  • Mantissa: 16-bit unsigned integer (0-65,535)
  • Exponent: 6-bit unsigned integer (0-63)

The maximum representable value would be:
65,535 * 2^63 ≈ 6.04 * 10^23 sompi

This would easily cover the maximum Kaspa supply of 2.9 * 10^18 sompi with significant headroom. The tradeoff would be slightly less precision in the mantissa (16 bits instead of 17 bits), but 65,535 distinct mantissa values should still provide sufficient granularity for practical threshold purposes.

Alternative 2: Non-Power-of-2 Exponent Base

Another alternative would be to use a non-power-of-2 base for the exponent, such as 10:

threshold = mantissa * (10^exponent)

This would make the values more human-readable and potentially allow for more intuitive threshold settings. However, this approach has significant drawbacks:

  • Performance Penalties: Computing powers of 10 is more computationally expensive than powers of 2, which can be implemented as simple bit shifts.
  • Precision Issues: Powers of 10 cannot be represented exactly in binary, potentially leading to rounding errors.

For these reasons, the power-of-2 approach is preferred for the Float24 format.

Benefits

  • Practical Range: Float24 can represent values from 0 sompi to well beyond most practical threshold needs
  • Zero Threshold Support: Enables simple same-address spending without value constraints
  • Signature Type Choice: Allows selection between ECDSA and Schnorr signatures
  • Complete Public Key Information: Preserves Y coordinate parity for ECDSA keys

Implementation Considerations

  • Bech32 Encoding: The complete 35-byte payload would be encoded using bech32
  • Script Generation: Wallet software would need to generate the appropriate script based on the Float24 value and signature type
  • Validation: Address validation would need to check the Float24 format is valid
  • Compatibility: Existing software would need updates to recognize and handle the new address type

Summary

The Float24 Threshold Address format provides an efficient way to encode threshold values directly in Kaspa addresses, enabling powerful compounding and borrowing functionality without requiring consensus changes. This proposal builds on the transaction introspection capabilities introduced in KIP-10 while maintaining compatibility with existing P2SH infrastructure.

By standardizing this address format, we can enable a new class of applications that leverage threshold-based spending conditions, particularly for mining pools and other services that benefit from auto-compounding UTXOs. The support for both ECDSA and Schnorr signatures, along with a wide range of threshold values, provides flexibility for various financial applications.

It’s important to note that the conversion from an address to a script public key (SPK) is a one-way process. Once an address is converted to an SPK, the original script cannot be recovered from the SPK hash alone unless all placeholder values are known.