From c7f7fd29e00ce709ff2fd390e944c06ce3be825d Mon Sep 17 00:00:00 2001
From: Mike Hearn <mike@plan99.net>
Date: Fri, 28 Mar 2014 12:40:00 +0100
Subject: [PATCH] HD Wallets: add a REFUND key purpose and map it to the same
 branch as RECEIVE_FUNDS for now.

---
 .../bitcoin/wallet/DeterministicKeyChain.java | 24 ++++++++++++-------
 .../com/google/bitcoin/wallet/KeyChain.java   |  3 ++-
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/core/src/main/java/com/google/bitcoin/wallet/DeterministicKeyChain.java b/core/src/main/java/com/google/bitcoin/wallet/DeterministicKeyChain.java
index c222ae12..566bc606 100644
--- a/core/src/main/java/com/google/bitcoin/wallet/DeterministicKeyChain.java
+++ b/core/src/main/java/com/google/bitcoin/wallet/DeterministicKeyChain.java
@@ -235,14 +235,22 @@ public class DeterministicKeyChain implements EncryptableKeyChain {
         try {
             DeterministicKey key, parentKey;
             int index;
-            if (purpose == KeyPurpose.RECEIVE_FUNDS) {
-                index = ++issuedExternalKeys;
-                parentKey = externalKey;
-            } else if (purpose == KeyPurpose.CHANGE) {
-                index = ++issuedInternalKeys;
-                parentKey = internalKey;
-            } else {
-                throw new IllegalArgumentException("Unknown key purpose " + purpose);
+            switch (purpose) {
+                // Map both REFUND and RECEIVE_KEYS to the same branch for now. Refunds are a feature of the BIP 70
+                // payment protocol. Later we may wish to map it to a different branch (in a new wallet version?).
+                // This would allow a watching wallet to only be able to see inbound payments, but not change
+                // (i.e. spends) or refunds. Might be useful for auditing ...
+                case RECEIVE_FUNDS:
+                case REFUND:
+                    index = ++issuedExternalKeys;
+                    parentKey = externalKey;
+                    break;
+                case CHANGE:
+                    index = ++issuedInternalKeys;
+                    parentKey = internalKey;
+                    break;
+                default:
+                    throw new UnsupportedOperationException();
             }
             // TODO: Handle the case where the derived key is >= curve order.
             List<DeterministicKey> lookahead = maybeLookAhead(parentKey, index);
diff --git a/core/src/main/java/com/google/bitcoin/wallet/KeyChain.java b/core/src/main/java/com/google/bitcoin/wallet/KeyChain.java
index 574ab794..6d2ecf6e 100644
--- a/core/src/main/java/com/google/bitcoin/wallet/KeyChain.java
+++ b/core/src/main/java/com/google/bitcoin/wallet/KeyChain.java
@@ -54,7 +54,8 @@ public interface KeyChain {
 
     enum KeyPurpose {
         RECEIVE_FUNDS,
-        CHANGE
+        CHANGE,
+        REFUND
     }
 
     /** Obtains a key intended for the given purpose. The chain may create a new key, derive one, or re-use an old one. */