X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FKeysInterface.java;h=bbb5df9856e0c9f78ed67f9362e9d266f80bc8b1;hb=17113550a5fefab21f39f27fbfe02646b8db53ae;hp=d3463631db8a6f09ac8fa9a7e95f3af5fc4e82c5;hpb=d69a40d071871d3c0e4160744202c6e85941a4cc;p=ldk-java

diff --git a/src/main/java/org/ldk/structs/KeysInterface.java b/src/main/java/org/ldk/structs/KeysInterface.java
index d3463631..bbb5df98 100644
--- a/src/main/java/org/ldk/structs/KeysInterface.java
+++ b/src/main/java/org/ldk/structs/KeysInterface.java
@@ -5,6 +5,9 @@ import org.ldk.enums.*;
 import org.ldk.util.*;
 import java.util.Arrays;
 
+/**
+ * A trait to describe an object which can get user secrets and key material.
+ */
 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
 public class KeysInterface extends CommonBase {
 	final bindings.LDKKeysInterface bindings_instance;
@@ -20,11 +23,50 @@ public class KeysInterface extends CommonBase {
 	}
 
 	public static interface KeysInterfaceInterface {
+		/**
+		 * Get node secret key (aka node_id or network_key).
+		 * 
+		 * This method must return the same value each time it is called.
+		 */
 		byte[] get_node_secret();
+		/**
+		 * Get a script pubkey which we send funds to when claiming on-chain contestable outputs.
+		 * 
+		 * This method should return a different value each time it is called, to avoid linking
+		 * on-chain funds across channels as controlled to the same user.
+		 */
 		byte[] get_destination_script();
+		/**
+		 * Get a public key which we will send funds to (in the form of a P2WPKH output) when closing
+		 * a channel.
+		 * 
+		 * This method should return a different value each time it is called, to avoid linking
+		 * on-chain funds across channels as controlled to the same user.
+		 */
 		byte[] get_shutdown_pubkey();
+		/**
+		 * Get a new set of Sign for per-channel secrets. These MUST be unique even if you
+		 * restarted with some stale data!
+		 * 
+		 * This method must return a different value each time it is called.
+		 */
 		Sign get_channel_signer(boolean inbound, long channel_value_satoshis);
+		/**
+		 * Gets a unique, cryptographically-secure, random 32 byte value. This is used for encrypting
+		 * onion packets and for temporary channel IDs. There is no requirement that these be
+		 * persisted anywhere, though they must be unique across restarts.
+		 * 
+		 * This method must return a different value each time it is called.
+		 */
 		byte[] get_secure_random_bytes();
+		/**
+		 * Reads a `Signer` for this `KeysInterface` from the given input stream.
+		 * This is only called during deserialization of other objects which contain
+		 * `Sign`-implementing objects (ie `ChannelMonitor`s and `ChannelManager`s).
+		 * The bytes are exactly those which `<Self::Signer as Writeable>::write()` writes, and
+		 * contain no versioning scheme. You may wish to include your own version prefix and ensure
+		 * you've read all of the provided bytes to ensure no corruption occurred.
+		 */
 		Result_SignDecodeErrorZ read_chan_signer(byte[] reader);
 	}
 	private static class LDKKeysInterfaceHolder { KeysInterface held; }
@@ -61,21 +103,45 @@ public class KeysInterface extends CommonBase {
 		});
 		return impl_holder.held;
 	}
+	/**
+	 * Get node secret key (aka node_id or network_key).
+	 * 
+	 * This method must return the same value each time it is called.
+	 */
 	public byte[] get_node_secret() {
 		byte[] ret = bindings.KeysInterface_get_node_secret(this.ptr);
 		return ret;
 	}
 
+	/**
+	 * Get a script pubkey which we send funds to when claiming on-chain contestable outputs.
+	 * 
+	 * This method should return a different value each time it is called, to avoid linking
+	 * on-chain funds across channels as controlled to the same user.
+	 */
 	public byte[] get_destination_script() {
 		byte[] ret = bindings.KeysInterface_get_destination_script(this.ptr);
 		return ret;
 	}
 
+	/**
+	 * Get a public key which we will send funds to (in the form of a P2WPKH output) when closing
+	 * a channel.
+	 * 
+	 * This method should return a different value each time it is called, to avoid linking
+	 * on-chain funds across channels as controlled to the same user.
+	 */
 	public byte[] get_shutdown_pubkey() {
 		byte[] ret = bindings.KeysInterface_get_shutdown_pubkey(this.ptr);
 		return ret;
 	}
 
+	/**
+	 * Get a new set of Sign for per-channel secrets. These MUST be unique even if you
+	 * restarted with some stale data!
+	 * 
+	 * This method must return a different value each time it is called.
+	 */
 	public Sign get_channel_signer(boolean inbound, long channel_value_satoshis) {
 		long ret = bindings.KeysInterface_get_channel_signer(this.ptr, inbound, channel_value_satoshis);
 		Sign ret_hu_conv = new Sign(null, ret);
@@ -83,11 +149,26 @@ public class KeysInterface extends CommonBase {
 		return ret_hu_conv;
 	}
 
+	/**
+	 * Gets a unique, cryptographically-secure, random 32 byte value. This is used for encrypting
+	 * onion packets and for temporary channel IDs. There is no requirement that these be
+	 * persisted anywhere, though they must be unique across restarts.
+	 * 
+	 * This method must return a different value each time it is called.
+	 */
 	public byte[] get_secure_random_bytes() {
 		byte[] ret = bindings.KeysInterface_get_secure_random_bytes(this.ptr);
 		return ret;
 	}
 
+	/**
+	 * Reads a `Signer` for this `KeysInterface` from the given input stream.
+	 * This is only called during deserialization of other objects which contain
+	 * `Sign`-implementing objects (ie `ChannelMonitor`s and `ChannelManager`s).
+	 * The bytes are exactly those which `<Self::Signer as Writeable>::write()` writes, and
+	 * contain no versioning scheme. You may wish to include your own version prefix and ensure
+	 * you've read all of the provided bytes to ensure no corruption occurred.
+	 */
 	public Result_SignDecodeErrorZ read_chan_signer(byte[] reader) {
 		long ret = bindings.KeysInterface_read_chan_signer(this.ptr, reader);
 		Result_SignDecodeErrorZ ret_hu_conv = Result_SignDecodeErrorZ.constr_from_ptr(ret);