Work on bsip-1203, recognition of incoming transactions.

bsip-1203.md

@@ -27,10 +27,72 @@ Additionally, the WS/RPC API offered by network nodes will need to be extended t
 
 ## Rationale
 ## Specifications
+
+We specify two protocols. In the first subsection we will specify wallet behaviors for (1) creating transaction outputs that can be recognized by their recipients, and (2) recognizing transaction outputs that are destined to the wallet.  In the second subsection we propose a new API call for querying nodes for transaction outputs to be scanned for recognizable markers.
+
+### Wallet procedure for recognizing own commitments
+
+Assumptions:
+
+1. Wallet has access to a set of private keys corresponding to stealth addresses which may own commitments on the blockchain.  These private keys are needed to "recognize" incoming transactions.
+2. Wallet can query an API node for commitments occurring between specified block heights, to obtain a set to scan for owned commitment. ([See below](#api-requirements-to-allow-detection-of-inbound-commitments) for this process.)
+
+In what follows, we detail procedures for two different stealth address formats: one which encodes a single public key, and one which encodes two public keys. The two formats serve a similar purpose of allowing for unlinkable transactions, but the dual-key format allows for watch-only wallets, whereas the single-key format does not.  The single key format is borrowed from Confidential Transactions, whereas the dual-key format is standard in CryptoNote-based coins such as Monero.
+
+The dual-key format separates the duties of spending a commitment from those of reading the commitment, such that a person in possession of only the "viewing key" (the private key corresponding to the additional pubkey in the address) can discover, interpret, and tally incoming transactions, but _cannot_ spend them.  The "spending key" (private key corresponding to the primary pubkey in the address) is needed to authorize the spending of a commitment. The dual-key address format and signing procedures are described in detail in [[vS13]](#references) and reviewed below.
+
+#### Procedure for single-key stealth addresses (CT-style)
+
+A short, single-key stealth address (of the type used in Confidential Transactions) has format:
+
+  `BTSaaaaaaaaaaaaaaaaaaaacccc`
+
+where `BTS` is a format identifier specifying a BitShares PubKey address format, and `aaaa...cccc` is the base58check encoding of a public key _A_ concatenated with four checksum bytes. (C.f. [Base58Check encoding](https://en.bitcoin.it/wiki/Base58Check_encoding), but note that we omit the version byte used in Bitcoin addresses.)
+
+We assume the address encodes public key _A_, and that the wallet owner is in posession of (_A_, _a_), where _a_ is the corresponding private key.
+
+##### Embedding recognizability data in the transaction
+
+Embedding recognizability data in the transaction is an optional, though highly recommended, wallet behavior, so that the receiving wallet can recognize incoming commitments.  The network will not reject a transaction which is missing this data, because the [Stealth Phase I (BSIP 0007)](bsip-0007.md) specification called for the receiver to be notified via an out-of-band communication of a "transaction receipt".  Nevertheless, the implemented transaction output format contains a field called `stealth_memo` into which this data may be embedded, although the structure of this data has not been formally standardized. (We propose a standard below.)
+
+Because of the free-form nature of this extra recognizability data, some wallets engage in the very poor behavior of directly identifying the receiving stealth address in the transaction.  This, of course, completely negates the unlinkability property provided by stealth addresses, and this behavior should be highly discouraged.
+
+Here is a brief overview of the structure of an individual commitment on the blockchain with associated recognizability data:
+
+[TABLE]
+
+As alluded to above, the existing (bad) practice is to either leave the recognizability data blank (relying on transaction receipts), or to populate the XXXX field with the receiving address public key (negates unlinkability).
+
+We propose the following alternative:
+
+XXXXX   
+
+##### Detecting inbound transaction (single-key)
+
+
+#### Procedure for dual-key stealth addresses (CryptoNote-style)
+
+##### Embedding recognizability data in the transaction
+
+##### Detecting inbound transaction (single-key)
+
+ 
+### API Requirements to Allow Detection of Inbound Commitments
+
+(Discuss here a proposed API call for retrieving commitments by block height range)
+
+(Note: the data returned by this call should also include (or, perhaps this should be a separate call) a list of all commitments that were SPENT in the same block height range.  In the case of RingCT this would be a list of key-images used, since with RingCT the network doesn't know which commitments are spent or not.)
+
+(Discuss also possible optimizations such as batching historical commitment and spend data into ranges of fixed size (say intervals of 2^17 blocks, representing a little over four days) so that these data-balls can be cached and returned efficiently without the node needing to satisfy a unique query every time.)
+
 ## Discussion
 ## Summary for Shareholders
 ## Copyright
 
 This document is placed in the public domain.
 
+## References
+
+[vS13] - Nicolas van Saberhagen, _Cryptonote v 2.0_, 2013 - https://cryptonote.org/whitepaper.pdf
+
 ## See Also