From e2b00e4cda9329066757fd94dec508c2f95286ac Mon Sep 17 00:00:00 2001
From: Adam Mackler <AdamMackler@gmail.com>
Date: Fri, 14 Nov 2014 10:37:17 -0500
Subject: [PATCH] Clarify javadoc comments regarding whether HD derivations are
 hardened.

---
 .../main/java/org/bitcoinj/crypto/DeterministicKey.java   | 4 +++-
 .../main/java/org/bitcoinj/crypto/HDKeyDerivation.java    | 8 ++++++--
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/core/src/main/java/org/bitcoinj/crypto/DeterministicKey.java b/core/src/main/java/org/bitcoinj/crypto/DeterministicKey.java
index c5921149..ba793cd6 100644
--- a/core/src/main/java/org/bitcoinj/crypto/DeterministicKey.java
+++ b/core/src/main/java/org/bitcoinj/crypto/DeterministicKey.java
@@ -293,7 +293,9 @@ public class DeterministicKey extends ECKey {
     }
 
     /**
-     * Derives a child at the given index (note: not the "i" value).
+     * Derives a child at the given index using hardened derivation.  Note: <code>index</code> is
+     * not the "i" value.  If you want the softened derivation, then use instead
+     * <code>HDKeyDerivation.deriveChildKey(this, new ChildNumber(child, false))</code>.
      */
     public DeterministicKey derive(int child) {
         return HDKeyDerivation.deriveChildKey(this, new ChildNumber(child, true));
diff --git a/core/src/main/java/org/bitcoinj/crypto/HDKeyDerivation.java b/core/src/main/java/org/bitcoinj/crypto/HDKeyDerivation.java
index 90a57117..4ced76b1 100644
--- a/core/src/main/java/org/bitcoinj/crypto/HDKeyDerivation.java
+++ b/core/src/main/java/org/bitcoinj/crypto/HDKeyDerivation.java
@@ -90,8 +90,12 @@ public final class HDKeyDerivation {
     }
 
     /**
-     * Derives a key given the "extended" child number, ie. with the 0x80000000 bit specifying whether to use hardened
-     * derivation or not.
+     * Derives a key given the "extended" child number, ie. the 0x80000000 bit of the value that you
+     * pass for <code>childNumber</code> will determine whether to use hardened derivation or not.
+     * Consider whether your code would benefit from the clarity of the equivalent, but explicit, form
+     * of this method that takes a <code>ChildNumber</code> rather than an <code>int</code>, for example:
+     * <code>deriveChildKey(parent, new ChildNumber(childNumber, true))</code>
+     * where the value of the hardened bit of <code>childNumber</code> is zero.
      */
     public static DeterministicKey deriveChildKey(DeterministicKey parent, int childNumber) {
         return deriveChildKey(parent, new ChildNumber(childNumber));