X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FConfirm.java;h=9029aefb6aaa40a1b069efa07817b0ac4d69448d;hb=07d5d868dfe064aadb28a7f7ca6002c16be9723d;hp=99955fa33e2e6476da0d58916bb6194e425ab6a1;hpb=3c60e0fd0da579be9932801c1be2b32014c944a5;p=ldk-java diff --git a/src/main/java/org/ldk/structs/Confirm.java b/src/main/java/org/ldk/structs/Confirm.java index 99955fa3..9029aefb 100644 --- a/src/main/java/org/ldk/structs/Confirm.java +++ b/src/main/java/org/ldk/structs/Confirm.java @@ -8,31 +8,35 @@ import java.lang.ref.Reference; import javax.annotation.Nullable; /** - * The `Confirm` trait is used to notify when transactions have been confirmed on chain or - * unconfirmed during a chain reorganization. + * The `Confirm` trait is used to notify LDK when relevant transactions have been confirmed on + * chain or unconfirmed during a chain reorganization. * * Clients sourcing chain data using a transaction-oriented API should prefer this interface over - * [`Listen`]. For instance, an Electrum client may implement [`Filter`] by subscribing to activity - * related to registered transactions and outputs. Upon notification, it would pass along the - * matching transactions using this interface. + * [`Listen`]. For instance, an Electrum-based transaction sync implementation may implement + * [`Filter`] to subscribe to relevant transactions and unspent outputs it should monitor for + * on-chain activity. Then, it needs to notify LDK via this interface upon observing any changes + * with reference to the confirmation status of the monitored objects. * * # Use - * * The intended use is as follows: - * - Call [`transactions_confirmed`] to process any on-chain activity of interest. - * - Call [`transaction_unconfirmed`] to process any transaction returned by [`get_relevant_txids`] - * that has been reorganized out of the chain. - * - Call [`best_block_updated`] whenever a new chain tip becomes available. + * - Call [`transactions_confirmed`] to notify LDK whenever any of the registered transactions or + * outputs are, respectively, confirmed or spent on chain. + * - Call [`transaction_unconfirmed`] to notify LDK whenever any transaction returned by + * [`get_relevant_txids`] is no longer confirmed in the block with the given block hash. + * - Call [`best_block_updated`] to notify LDK whenever a new chain tip becomes available. * * # Order * * Clients must call these methods in chain order. Specifically: - * - Transactions confirmed in a block must be given before transactions confirmed in a later - * block. + * - Transactions which are confirmed in a particular block must be given before transactions + * confirmed in a later block. * - Dependent transactions within the same block must be given in topological order, possibly in * separate calls. - * - Unconfirmed transactions must be given after the original confirmations and before any - * reconfirmation. + * - All unconfirmed transactions must be given after the original confirmations and before *any* + * reconfirmations, i.e., [`transactions_confirmed`] and [`transaction_unconfirmed`] calls should + * never be interleaved, but always conduced *en bloc*. + * - Any reconfirmed transactions need to be explicitly unconfirmed before they are reconfirmed + * in regard to the new block. * * See individual method documentation for further details. * @@ -54,12 +58,24 @@ public class Confirm extends CommonBase { protected void finalize() throws Throwable { if (ptr != 0) { bindings.Confirm_free(ptr); } super.finalize(); } - + /** + * Destroys the object, freeing associated resources. After this call, any access + * to this object may result in a SEGFAULT or worse. + * + * You should generally NEVER call this method. You should let the garbage collector + * do this for you when it finalizes objects. However, it may be useful for types + * which represent locks and should be closed immediately to avoid holding locks + * until the GC runs. + */ + public void destroy() { + if (ptr != 0) { bindings.Confirm_free(ptr); } + ptr = 0; + } public static interface ConfirmInterface { /** - * Processes transactions confirmed in a block with a given header and height. + * Notifies LDK of transactions confirmed in a block with a given header and height. * - * Should be called for any transactions registered by [`Filter::register_tx`] or any + * Must be called for any transactions registered by [`Filter::register_tx`] or any * transactions spending an output registered by [`Filter::register_output`]. Such transactions * appearing in the same block do not need to be included in the same call; instead, multiple * calls with additional transactions may be made so long as they are made in [chain order]. @@ -68,44 +84,53 @@ public class Confirm extends CommonBase { * in the event of a chain reorganization, it must not be called with a `header` that is no * longer in the chain as of the last call to [`best_block_updated`]. * - * [chain order]: Confirm#Order + * [chain order]: Confirm#order * [`best_block_updated`]: Self::best_block_updated */ void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height); /** - * Processes a transaction that is no longer confirmed as result of a chain reorganization. + * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization. * - * Should be called for any transaction returned by [`get_relevant_txids`] if it has been - * reorganized out of the best chain. Once called, the given transaction should not be returned - * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`]. + * Must be called for any transaction returned by [`get_relevant_txids`] if it has been + * reorganized out of the best chain or if it is no longer confirmed in the block with the + * given block hash. Once called, the given transaction will not be returned + * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`]. * * [`get_relevant_txids`]: Self::get_relevant_txids * [`transactions_confirmed`]: Self::transactions_confirmed */ void transaction_unconfirmed(byte[] txid); /** - * Processes an update to the best header connected at the given height. + * Notifies LDK of an update to the best header connected at the given height. * - * Should be called when a new header is available but may be skipped for intermediary blocks - * if they become available at the same time. + * Must be called whenever a new chain tip becomes available. May be skipped for intermediary + * blocks. */ void best_block_updated(byte[] header, int height); /** - * Returns transactions that should be monitored for reorganization out of the chain. + * Returns transactions that must be monitored for reorganization out of the chain along + * with the hash of the block as part of which it had been previously confirmed. * - * Should include any transactions passed to [`transactions_confirmed`] that have insufficient - * confirmations to be safe from a chain reorganization. Should not include any transactions - * passed to [`transaction_unconfirmed`] unless later reconfirmed. + * Note that the returned `Option` might be `None` for channels created with LDK + * 0.0.112 and prior, in which case you need to manually track previous confirmations. * - * May be called to determine the subset of transactions that must still be monitored for + * Will include any transactions passed to [`transactions_confirmed`] that have insufficient + * confirmations to be safe from a chain reorganization. Will not include any transactions + * passed to [`transaction_unconfirmed`], unless later reconfirmed. + * + * Must be called to determine the subset of transactions that must be monitored for * reorganization. Will be idempotent between calls but may change as a result of calls to the - * other interface methods. Thus, this is useful to determine which transactions may need to be + * other interface methods. Thus, this is useful to determine which transactions must be * given to [`transaction_unconfirmed`]. * + * If any of the returned transactions are confirmed in a block other than the one with the + * given hash, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and + * [`transactions_confirmed`], respectively. + * * [`transactions_confirmed`]: Self::transactions_confirmed * [`transaction_unconfirmed`]: Self::transaction_unconfirmed */ - byte[][] get_relevant_txids(); + TwoTuple_ThirtyTwoBytesCOption_ThirtyTwoBytesZZ[] get_relevant_txids(); } private static class LDKConfirmHolder { Confirm held; } public static Confirm new_impl(ConfirmInterface arg) { @@ -131,19 +156,19 @@ public class Confirm extends CommonBase { arg.best_block_updated(header, height); Reference.reachabilityFence(arg); } - @Override public byte[][] get_relevant_txids() { - byte[][] ret = arg.get_relevant_txids(); + @Override public long[] get_relevant_txids() { + TwoTuple_ThirtyTwoBytesCOption_ThirtyTwoBytesZZ[] ret = arg.get_relevant_txids(); Reference.reachabilityFence(arg); - byte[][] result = ret != null ? Arrays.stream(ret).map(ret_conv_8 -> InternalUtils.check_arr_len(ret_conv_8, 32)).toArray(byte[][]::new) : null; + long[] result = ret != null ? Arrays.stream(ret).mapToLong(ret_conv_49 -> ret_conv_49 == null ? 0 : ret_conv_49.clone_ptr()).toArray() : null; return result; } }); return impl_holder.held; } /** - * Processes transactions confirmed in a block with a given header and height. + * Notifies LDK of transactions confirmed in a block with a given header and height. * - * Should be called for any transactions registered by [`Filter::register_tx`] or any + * Must be called for any transactions registered by [`Filter::register_tx`] or any * transactions spending an output registered by [`Filter::register_output`]. Such transactions * appearing in the same block do not need to be included in the same call; instead, multiple * calls with additional transactions may be made so long as they are made in [chain order]. @@ -152,7 +177,7 @@ public class Confirm extends CommonBase { * in the event of a chain reorganization, it must not be called with a `header` that is no * longer in the chain as of the last call to [`best_block_updated`]. * - * [chain order]: Confirm#Order + * [chain order]: Confirm#order * [`best_block_updated`]: Self::best_block_updated */ public void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height) { @@ -164,11 +189,12 @@ public class Confirm extends CommonBase { } /** - * Processes a transaction that is no longer confirmed as result of a chain reorganization. + * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization. * - * Should be called for any transaction returned by [`get_relevant_txids`] if it has been - * reorganized out of the best chain. Once called, the given transaction should not be returned - * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`]. + * Must be called for any transaction returned by [`get_relevant_txids`] if it has been + * reorganized out of the best chain or if it is no longer confirmed in the block with the + * given block hash. Once called, the given transaction will not be returned + * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`]. * * [`get_relevant_txids`]: Self::get_relevant_txids * [`transactions_confirmed`]: Self::transactions_confirmed @@ -180,10 +206,10 @@ public class Confirm extends CommonBase { } /** - * Processes an update to the best header connected at the given height. + * Notifies LDK of an update to the best header connected at the given height. * - * Should be called when a new header is available but may be skipped for intermediary blocks - * if they become available at the same time. + * Must be called whenever a new chain tip becomes available. May be skipped for intermediary + * blocks. */ public void best_block_updated(byte[] header, int height) { bindings.Confirm_best_block_updated(this.ptr, InternalUtils.check_arr_len(header, 80), height); @@ -193,24 +219,40 @@ public class Confirm extends CommonBase { } /** - * Returns transactions that should be monitored for reorganization out of the chain. + * Returns transactions that must be monitored for reorganization out of the chain along + * with the hash of the block as part of which it had been previously confirmed. * - * Should include any transactions passed to [`transactions_confirmed`] that have insufficient - * confirmations to be safe from a chain reorganization. Should not include any transactions - * passed to [`transaction_unconfirmed`] unless later reconfirmed. + * Note that the returned `Option` might be `None` for channels created with LDK + * 0.0.112 and prior, in which case you need to manually track previous confirmations. * - * May be called to determine the subset of transactions that must still be monitored for + * Will include any transactions passed to [`transactions_confirmed`] that have insufficient + * confirmations to be safe from a chain reorganization. Will not include any transactions + * passed to [`transaction_unconfirmed`], unless later reconfirmed. + * + * Must be called to determine the subset of transactions that must be monitored for * reorganization. Will be idempotent between calls but may change as a result of calls to the - * other interface methods. Thus, this is useful to determine which transactions may need to be + * other interface methods. Thus, this is useful to determine which transactions must be * given to [`transaction_unconfirmed`]. * + * If any of the returned transactions are confirmed in a block other than the one with the + * given hash, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and + * [`transactions_confirmed`], respectively. + * * [`transactions_confirmed`]: Self::transactions_confirmed * [`transaction_unconfirmed`]: Self::transaction_unconfirmed */ - public byte[][] get_relevant_txids() { - byte[][] ret = bindings.Confirm_get_relevant_txids(this.ptr); + public TwoTuple_ThirtyTwoBytesCOption_ThirtyTwoBytesZZ[] get_relevant_txids() { + long[] ret = bindings.Confirm_get_relevant_txids(this.ptr); Reference.reachabilityFence(this); - return ret; + int ret_conv_49_len = ret.length; + TwoTuple_ThirtyTwoBytesCOption_ThirtyTwoBytesZZ[] ret_conv_49_arr = new TwoTuple_ThirtyTwoBytesCOption_ThirtyTwoBytesZZ[ret_conv_49_len]; + for (int x = 0; x < ret_conv_49_len; x++) { + long ret_conv_49 = ret[x]; + TwoTuple_ThirtyTwoBytesCOption_ThirtyTwoBytesZZ ret_conv_49_hu_conv = new TwoTuple_ThirtyTwoBytesCOption_ThirtyTwoBytesZZ(null, ret_conv_49); + if (ret_conv_49_hu_conv != null) { ret_conv_49_hu_conv.ptrs_to.add(this); }; + ret_conv_49_arr[x] = ret_conv_49_hu_conv; + } + return ret_conv_49_arr; } }