Propose Transaction

The propose_transaction function creates a PCZT by combining the Creator, Constructor, and IO Finalizer roles from ZIP 374.

Function Signature

TypeScript
Go
Kotlin

function propose_transaction(
  inputs: WasmTransparentInput[],
  payments: WasmPayment[],
  change_address: string | null,
  network: 'mainnet' | 'testnet',
  expiry_height: number
): WasmPczt

func ProposeTransaction(
  inputs []TransparentInput,
  payments []Payment,
  changeAddress *string,
  network string,
  expiryHeight uint32,
) (*Pczt, error)

fun proposeTransaction(
  inputs: List<TransparentInput>,
  payments: List<Payment>,
  changeAddress: String?,
  network: String,
  expiryHeight: UInt
): Pczt

Parameters

inputs

TransparentInput[]

required

Array of transparent UTXOs to spend. Each input requires:

Field	Type	Description
`pubkey`	string	33-byte compressed public key (hex)
`prevoutTxid`	string	32-byte transaction ID (little-endian hex)
`prevoutIndex`	number	Output index in previous transaction
`value`	bigint	Value in zatoshis
`scriptPubkey`	string	P2PKH scriptPubkey (hex)
`sequence`	number?	Sequence number (default: 0xffffffff)

payments

Payment[]

required

Array of outputs to create. Each payment requires:

Field	Type	Description
`address`	string	Unified address (Orchard) or transparent address
`amount`	bigint	Amount in zatoshis
`memo`	string?	Hex-encoded memo for shielded outputs (max 512 bytes)
`label`	string?	Optional display label

change_address

string | null

Address to receive change. Can be:

Unified address with Orchard receiver (recommended for privacy)
Transparent P2PKH address (t1... or tm...)
null if no change expected

If total_input > total_payments + fee, a change address is required.

network

string

required

Network to use: 'mainnet' or 'testnet'

expiry_height

number

required

Block height at which the transaction expires. Must be:

After Nu5 activation (mainnet: 1,687,104 / testnet: 1,842,420)
At least current_height + 40 to avoid “tx-expiring-soon” errors

Example

TypeScript
Go

import * as t2z from '@d4mr/t2z-wasm';

// Prepare inputs
const inputs = [
  new t2z.WasmTransparentInput(
    '03abc123...',                    // Compressed pubkey (33 bytes hex)
    'ce15f716...1338',                // Txid (little-endian)
    0,                                 // Output index
    1_000_000n,                        // 0.01 ZEC
    '76a914...88ac',                  // P2PKH scriptPubkey
    null                               // Default sequence
  )
];

// Prepare payments
const payments = [
  new t2z.WasmPayment(
    'u1abc...',                        // Unified address with Orchard
    800_000n,                          // 0.008 ZEC
    Buffer.from('Hello!').toString('hex'),  // Memo
    'Payment for services'             // Label
  )
];

// Get current block height (in production, fetch from lightwalletd)
const currentHeight = 3_720_000;
const expiryHeight = currentHeight + 100;

// Create the PCZT
const pczt = t2z.propose_transaction(
  inputs,
  payments,
  'u1change...',   // Change goes to Orchard (shielded)
  'testnet',
  expiryHeight
);

// Inspect what was created
const info = t2z.inspect_pczt(pczt.to_hex());
console.log('Fee:', info.implied_fee, 'zatoshis');

inputs := []t2z.TransparentInput{{
    Pubkey:       "03abc123...",
    PrevoutTxid:  "ce15f716...1338",
    PrevoutIndex: 0,
    Value:        1_000_000,
    ScriptPubkey: "76a914...88ac",
}}

payments := []t2z.Payment{{
    Address: "u1abc...",
    Amount:  800_000,
    Memo:    hex.EncodeToString([]byte("Hello!")),
}}

changeAddr := "u1change..."
pczt, err := t2z.ProposeTransaction(
    inputs,
    payments,
    &changeAddr,
    "testnet",
    3_720_100,
)
if err != nil {
    log.Fatal(err)
}

What Happens Internally

Validation — Inputs and payment addresses are validated
Fee Calculation — ZIP 317 fee is computed based on transaction structure
Change Calculation — change = total_input - total_payments - fee
Builder Construction — Zcash transaction builder creates the structure
PCZT Creation — Builder output is converted to PCZT format
IO Finalization — Input/output metadata is finalized

Fee Calculation

Fees are calculated automatically according to ZIP 317:

fee = 5000 × max(2, logical_actions)
logical_actions = max(transparent_inputs, transparent_outputs) + orchard_actions

Scenario	Fee
1 input → 1 Orchard output	10,000 zats
1 input → 1 Orchard output + Orchard change	10,000 zats
2 inputs → 1 Orchard output	10,000 zats
3 inputs → 2 Orchard outputs	15,000 zats

Common Errors

OrchardBuilderNotAvailable

The expiry height is before Nu5 activation. Use a height after:

Mainnet: 1,687,104
Testnet: 1,842,420

InsufficientFunds

Total input value is less than payments + fee. Either:

Add more inputs
Reduce payment amounts

ChangeRequired

There’s leftover value but no change address provided. Pass a change address.

InvalidAddress

The address couldn’t be parsed. Ensure it’s a valid:

Unified address (u1... or utest1...)
Transparent address (t1... or tm...)

Next Step

After creating the PCZT, you can optionally verify it before signing, or proceed directly to signing.

Getting Started

Transaction Flow

Platform Guides

Advanced

Propose Transaction

Function Signature

Parameters

Example

What Happens Internally

Fee Calculation

Common Errors

Next Step

​Function Signature

​Parameters

​Example

​What Happens Internally

​Fee Calculation

​Common Errors

​Next Step

Function Signature

Parameters

Example

What Happens Internally

Fee Calculation

Common Errors

Next Step