From 41ba0618048b7b2d7e257bb52cf8f138d29dabd3 Mon Sep 17 00:00:00 2001
From: John Newbery <john@johnnewbery.com>
Date: Mon, 9 Apr 2018 17:22:50 -0400
Subject: [PATCH] [docs] Add release notes for wallet 'label' API.

---
 doc/release-notes-pr12892.md | 32 ++++++++++++++++++++++++++++++++
 doc/release-notes.md         | 10 ----------
 2 files changed, 32 insertions(+), 10 deletions(-)
 create mode 100644 doc/release-notes-pr12892.md

diff --git a/doc/release-notes-pr12892.md b/doc/release-notes-pr12892.md
new file mode 100644
index 00000000000..894bf19deeb
--- /dev/null
+++ b/doc/release-notes-pr12892.md
@@ -0,0 +1,32 @@
+'label' API for wallet
+----------------------
+
+A new 'label' API has been introduced for the wallet. This is intended as a
+replacement for the deprecated 'account' API.
+
+The label RPC methods mirror the account functionality, with the following functional differences:
+
+- Labels can be set on any address, not just receiving addresses. This functionality was previously only available through the GUI.
+- Labels can be deleted by reassigning all addresses using the `setlabel` RPC method.
+- There isn't support for sending transactions _from_ a label, or for determining which label a transaction was sent from.
+- Labels do not have a balance.
+
+Here are the changes to RPC methods:
+
+| Deprecated Method       | New Method            | Notes       |
+| :---------------------- | :-------------------- | :-----------|
+| `getaccount`            | `getaddressinfo`      | `getaddressinfo` returns a json object with address information instead of just the name of the account as a string. |
+| `getaccountaddress`     | `getlabeladdress`     | `getlabeladdress` throws an error by default if the label does not already exist, but provides a `force` option for compatibility with existing applications. |
+| `getaddressesbyaccount` | `getaddressesbylabel` | `getaddressesbylabel` returns a json object with the addresses as keys, instead of a list of strings. |
+| `getreceivedbyaccount`  | `getreceivedbylabel`  | _no change in behavior_ |
+| `listaccounts`          | `listlabels`          | `listlabels` does not return a balance or accept `minconf` and `watchonly` arguments. |
+| `listreceivedbyaccount` | `listreceivedbylabel` | Both methods return new `label` fields, along with `account` fields for backward compatibility. |
+| `move`                  | n/a                   | _no replacement_ |
+| `sendfrom`              | n/a                   | _no replacement_ |
+| `setaccount`            | `setlabel`            | Both methods now: <ul><li>allow assigning labels to any address, instead of raising an error if the address is not receiving address.<li>delete the previous label associated with an address when the final address using that label is reassigned to a different label, instead of making an implicit `getaccountaddress` call to ensure the previous label still has a receiving address. |
+
+| Changed Method         | Notes   |
+| :--------------------- | :------ |
+| `addmultisigaddress`   | Renamed `account` named parameter to `label`. Still accepts `account` for backward compatibility. |
+| `getnewaddress`        | Renamed `account` named parameter to `label`. Still accepts `account` for backward compatibility. |
+| `listunspent`          | Returns new `label` fields, along with `account` fields for backward compatibility. |
diff --git a/doc/release-notes.md b/doc/release-notes.md
index 0a72f3fe4a6..9e9c891de91 100644
--- a/doc/release-notes.md
+++ b/doc/release-notes.md
@@ -63,16 +63,6 @@ RPC changes
 
 - The `createrawtransaction` RPC will now accept an array or dictionary (kept for compatibility) for the `outputs` parameter. This means the order of transaction outputs can be specified by the client.
 - The `fundrawtransaction` RPC will reject the previously deprecated `reserveChangeKey` option.
-- Wallet `getnewaddress` and `addmultisigaddress` RPC `account` named
-  parameters have been renamed to `label` with no change in behavior.
-- Wallet `getlabeladdress`, `getreceivedbylabel`, `listreceivedbylabel`, and
-  `setlabel` RPCs have been added to replace `getaccountaddress`,
-  `getreceivedbyaccount`, `listreceivedbyaccount`, and `setaccount` RPCs,
-  which are now deprecated. There is no change in behavior between the
-  new RPCs and deprecated RPCs.
-- Wallet `listreceivedbylabel`, `listreceivedbyaccount` and `listunspent` RPCs
-  add `label` fields to returned JSON objects that previously only had
-  `account` fields.
 - `sendmany` now shuffles outputs to improve privacy, so any previously expected behavior with regards to output ordering can no longer be relied upon.
 - The new RPC `testmempoolaccept` can be used to test acceptance of a transaction to the mempool without adding it.