Deferred Redeemers¶

typedef cardano_error_t (*cardano_deferred_redeemer_fn_t)(void *user_context, cardano_transaction_t *draft_tx, cardano_utxo_list_t *resolved_inputs, cardano_plutus_data_t **redeemer)¶

Produces the redeemer payload for a script purpose from the balanced draft transaction.

Deferred redeemer callbacks are the mechanism for building redeemers that depend on the final canonical layout of the transaction (input indices, change outputs, the fee), which only exists after balancing. See cardano_tx_builder_add_input_with_deferred_redeemer.

The callback receives the balanced draft transaction (canonical input order, outputs including change, fee) and the final selected inputs as fully resolved UTXOs in canonical order. The cardano_transaction_find_input_index family of functions can be used to look up canonical positions.

Warning

Callbacks are invoked on EVERY balancing iteration and MUST be pure, deterministic functions of their arguments: no captured mutable state, no side effects, no randomness. A callback that violates this contract can prevent the balancing loop from converging.

Param user_context:¶

[in] The opaque pointer given at registration time.

Param draft_tx:¶

[in] The balanced draft transaction. Borrowed; must not be modified.

Param resolved_inputs:¶

[in] The final selected inputs as resolved UTXOs. Borrowed.

Param redeemer:¶

[out] The produced redeemer payload. The caller takes ownership.

Return:¶

CARDANO_SUCCESS on success, or an appropriate error code (which aborts balancing).

cardano_error_t cardano_deferred_redeemer_list_new(cardano_deferred_redeemer_list_t **list)¶

Creates a new empty deferred redeemer list.

Parameters:¶

cardano_deferred_redeemer_list_t **list¶

[out] A pointer to store the address of the newly created list.

Returns:¶

CARDANO_SUCCESS on success, or an appropriate error code.

cardano_error_t cardano_deferred_redeemer_list_add(cardano_deferred_redeemer_list_t *list, cardano_redeemer_t *redeemer, cardano_deferred_redeemer_fn_t callback, void *user_context)¶

Registers a deferred redeemer.

The list takes a reference on the redeemer object. Because the transaction builder shares the same redeemer object between the witness set and its bookkeeping maps, resolving the deferred payload updates the witness set in place.

Parameters:¶

cardano_deferred_redeemer_list_t *list¶

[in] The list to add to.

cardano_redeemer_t *redeemer¶

[in] The witness-set redeemer object whose payload is produced by the callback.

cardano_deferred_redeemer_fn_t callback¶

[in] The callback producing the payload. See cardano_deferred_redeemer_fn_t.

void *user_context¶

[in] An opaque pointer forwarded to the callback. Can be NULL. The caller must keep it valid until the transaction is built.

Returns:¶

CARDANO_SUCCESS on success, or an appropriate error code.

size_t cardano_deferred_redeemer_list_get_length(const cardano_deferred_redeemer_list_t *list)¶

Returns the number of registered deferred redeemers.

Parameters:¶

const cardano_deferred_redeemer_list_t *list¶

[in] The list to inspect.

Returns:¶

The number of entries, or zero if the list is NULL.

cardano_error_t cardano_deferred_redeemer_list_resolve(cardano_deferred_redeemer_list_t *list, cardano_transaction_t *draft_tx, cardano_utxo_list_t *resolved_inputs)¶

Resolves every deferred redeemer against a balanced draft transaction.

Invokes each registered callback with the draft transaction and the resolved inputs, and replaces the corresponding redeemer’s payload with the produced plutus data. This is called by cardano_balance_transaction on every balancing iteration, after the canonical input order and the change outputs are final and before evaluation and fee computation.

Parameters:¶

cardano_deferred_redeemer_list_t *list¶

[in] The list of deferred redeemers. Can be NULL (no-op).

cardano_transaction_t *draft_tx¶

[in] The balanced draft transaction.

cardano_utxo_list_t *resolved_inputs¶

[in] The final selected inputs as resolved UTXOs.

Returns:¶

CARDANO_SUCCESS on success, or the first error returned by a callback.

void cardano_deferred_redeemer_list_ref(cardano_deferred_redeemer_list_t *list)¶

Increments the reference count of the deferred redeemer list.

Parameters:¶

cardano_deferred_redeemer_list_t *list¶

[in] The list whose reference count to increment.

void cardano_deferred_redeemer_list_unref(cardano_deferred_redeemer_list_t **list)¶

Decrements the reference count of the deferred redeemer list; frees it when it reaches zero.

Parameters:¶

cardano_deferred_redeemer_list_t **list¶

[inout] A pointer to the list pointer. Set to NULL.

size_t cardano_deferred_redeemer_list_refcount(const cardano_deferred_redeemer_list_t *list)¶

Returns the current reference count of the deferred redeemer list.

Parameters:¶

const cardano_deferred_redeemer_list_t *list¶

[in] The list to inspect.

Returns:¶

The reference count, or zero if the list is NULL.