diff --git a/lib/address.js b/lib/address.js index a1c85c1..4a4a5f5 100644 --- a/lib/address.js +++ b/lib/address.js @@ -33,7 +33,8 @@ var popkey = require("./_util").popkey; * @param {Object=} opts - Address options * @param {number} opts.version - Version number (4 by default) * @param {number} opts.stream - Stream number (1 by default) - * @param {Object} opts.behavior - [Pubkey features]{@link module:bitmessage/structs.PubkeyBitfield} (`DOES_ACK` by default) + * @param {Object} opts.behavior - [Pubkey features]{@link + * module:bitmessage/structs.PubkeyBitfield} (`DOES_ACK` by default) * @param {Buffer} opts.signPrivateKey - Signing private key * @param {Buffer} opts.signPublicKey - Signing public key * @param {Buffer} opts.encPrivateKey - Encryption private key diff --git a/lib/messages.js b/lib/messages.js index 5f8d9a5..4eff3ee 100644 --- a/lib/messages.js +++ b/lib/messages.js @@ -5,7 +5,6 @@ * @see {@link https://bitmessage.org/Bitmessage%20Technical%20Paper.pdf} * @module bitmessage/messages */ -// TODO(Kagami): Document object-like params. "use strict"; diff --git a/lib/objects.js b/lib/objects.js index 675056d..46dbe4d 100644 --- a/lib/objects.js +++ b/lib/objects.js @@ -1,14 +1,10 @@ /** * Working with objects. - * NOTE: Most operations with objects in this module are asynchronous - * and return promises. + * NOTE: Most operations with objects are asynchronous and return + * promises. * @see {@link https://bitmessage.org/wiki/Protocol_specification#Object_types} * @module bitmessage/objects */ -// TODO(Kagami): Document object-like params. -// FIXME(Kagami): Think through the API, we may want to get decoded -// structure even if it contains unsupported version. Also error -// handling may need some refactoring. "use strict"; @@ -48,14 +44,7 @@ exports.getType = function(buf) { /** * Try to get type of the given object message payload. - * Note that this function doesn't do any validation because it is - * already provided by - * [object.decodePayload]{@link module:bitmessage/structs.object.decodePayload} - * routine. Normally you call this for each incoming object message - * payload and then call decode function of the appropriate object - * handler. - * @param {Buffer} buf - Buffer that starts with object message payload - * @return {?number} Object's type if any. + * The same as [getType]{@link module:bitmessage/objects.getType}. */ exports.getPayloadType = function(buf) { // Object header: 8 + 8 + 4 @@ -101,12 +90,30 @@ function prependNonce(obj, opts) { * @static */ var getpubkey = exports.getpubkey = { + /** + * @typedef {Object} DecodeResult + * @property {Buffer} nonce - A 8-byte object nonce + * @property {number} ttl - Time to live in seconds + * @property {number} type - Object type + * @property {number} version - Object version + * @property {number} stream - Object stream + * @property {number} headerLength - Length of the object header + * @property {Buffer} ripe - The RIPEMD hash of the requested public + * keys for address version <= 3 + * @property {Buffer} tag - ...or tag derived from the address object + * for address version >= 4 + * @property {number} length - Real data length + * @memberof module:bitmessage/objects.getpubkey + */ + /** * Decode `getpubkey` object message. * @param {Buffer} buf - Message - * @param {Object=} opts - Decoding options - * @return {Promise.} A promise that contains decoded - * `getpubkey` object structure when fulfilled. + * @param {Object=} opts - Any of [object.decode]{@link + * module:bitmessage/structs.object.decode} options + * @return {Promise.} A promise that contains + * [decoded `getpubkey` structure]{@link + * module:bitmessage/objects.getpubkey.DecodeResult} when fulfilled. */ decodeAsync: function(buf, opts) { return new PPromise(function(resolve) { @@ -118,10 +125,8 @@ var getpubkey = exports.getpubkey = { /** * Decode `getpubkey` object message payload. - * @param {Buffer} buf - Message payload - * @param {Object=} opts - Decoding options - * @return {Promise.} A promise that contains decoded - * `getpubkey` object structure when fulfilled. + * The same as [decodeAsync]{@link + * module:bitmessage/objects.getpubkey.decodeAsync}. */ decodePayloadAsync: function(buf, opts) { return new PPromise(function(resolve) { @@ -146,6 +151,10 @@ var getpubkey = exports.getpubkey = { /** * Encode `getpubkey` object message. * @param {Object} opts - `getpubkey` object options + * @param {number} opts.ttl - Time to live in seconds + * @param {Address} opts.to - Receiver of the message + * @param {boolean=} opts.skipPow - Do not compute POW (false by + * default) * @return {Promise.} A promise that contains encoded message * when fulfilled. */ @@ -157,9 +166,8 @@ var getpubkey = exports.getpubkey = { /** * Encode `getpubkey` object message payload. - * @param {Object} opts - `getpubkey` object options - * @return {Promise.} A promise that contains encoded message - * payload when fulfilled. + * The same as + * [encodeAsync]{@link module:bitmessage/objects.getpubkey.encodeAsync}. */ encodePayloadAsync: function(opts) { return new PPromise(function(resolve) { @@ -242,12 +250,45 @@ function findAddrByTag(addrs, tag) { * @static */ var pubkey = exports.pubkey = { + /** + * @typedef {Object} DecodeResult + * @property {Buffer} nonce - A 8-byte object nonce + * @property {number} ttl - Time to live in seconds + * @property {number} type - Object type + * @property {number} version - Object version + * @property {number} stream - Object stream + * @property {number} headerLength - Length of the object header + * @property {Buffer} tag - Tag derived from the address object + * (present only if object version is 4) + * @property {Object} behavior - [Pubkey features]{@link + * module:bitmessage/structs.PubkeyBitfield} that can be expected from + * the node + * @property {Buffer} signPublicKey - Signing public key + * @property {Buffer} encPublicKey - Encryption public key + * @property {number} nonceTrialsPerByte - Difficulty parameter of the + * node (present only for `pubkey` version >= 3) + * @property {number} payloadLengthExtraBytes - Difficulty parameter + * of the node (present only for `pubkey` version >= 3) + * @property {Buffer} signature - Signature of the message (present + * only for `pubkey` version >= 3) + * @property {number} length - Real data length + * @memberof module:bitmessage/objects.pubkey + */ + /** * Decode `pubkey` object message. * @param {Buffer} buf - Message - * @param {Object=} opts - Decoding options - * @return {Promise.} A promise that contains decoded `pubkey` - * object structure when fulfilled. + * @param {Object=} opts - Any of [object.decode]{@link + * module:bitmessage/structs.object.decode} options and: + * @param {(Address[]|Address|Object)} opts.needed - Address objects + * which represent pubkeys that we are interested in (used only for + * pubkeys v4). It is either addresses array or single address or + * Object addr-by-tag. Time to match the key is O(n), O(1), O(1) + * respectfully. + * @return {Promise.} A promise that contains + * [decoded `pubkey` structure]{@link + * module:bitmessage/objects.pubkey.DecodeResult} + * when fulfilled. */ decodeAsync: function(buf, opts) { return new PPromise(function(resolve) { @@ -259,10 +300,8 @@ var pubkey = exports.pubkey = { /** * Decode `pubkey` object message payload. - * @param {Buffer} buf - Message payload - * @param {Object=} opts - Decoding options - * @return {Promise.} A promise that contains decoded `pubkey` - * object structure when fulfilled. + * The same as [decodeAsync]{@link + * module:bitmessage/objects.pubkey.decodeAsync}. */ decodePayloadAsync: function(buf, opts) { return new PPromise(function(resolve) { @@ -341,6 +380,11 @@ var pubkey = exports.pubkey = { /** * Encode `pubkey` object message. * @param {Object} opts - `pubkey` object options + * @param {number} opts.ttl - Time to live in seconds + * @param {Address} opts.from - Originator of the message + * @param {Address} opts.to - Receiver of the message + * @param {boolean=} opts.skipPow - Do not compute POW (false by + * default) * @return {Promise.} A promise that contains encoded message * when fulfilled. */ @@ -352,9 +396,8 @@ var pubkey = exports.pubkey = { /** * Encode `pubkey` object message payload. - * @param {Object} opts - `pubkey` object options - * @return {Promise.} A promise that contains encoded message - * payload when fulfilled. + * The same as [encodeAsync]{@link + * module:bitmessage/objects.pubkey.encodeAsync}. */ encodePayloadAsync: function(opts) { return new PPromise(function(resolve) { @@ -540,12 +583,49 @@ var msg = exports.msg = { */ SIMPLE: 2, + /** + * @typedef {Object} DecodeResult + * @property {Buffer} nonce - A 8-byte object nonce + * @property {number} ttl - Time to live in seconds + * @property {number} type - Object type + * @property {number} version - Object version + * @property {number} stream - Object stream + * @property {number} headerLength - Length of the object header + * @property {number} senderVersion - Sender's address version + * @property {number} senderStream - Sender's stream + * @property {Object} behavior - Sender's [pubkey features]{@link + * module:bitmessage/structs.PubkeyBitfield} that can be expected from + * the node + * @property {Buffer} signPublicKey - Sender's signing public key + * @property {Buffer} encPublicKey - Sender's encryption public key + * @property {number} nonceTrialsPerByte - Difficulty parameter of the + * sender (present only if sender's address version >= 3) + * @property {number} payloadLengthExtraBytes - Difficulty parameter + * of the sender (present only if sender's address version >= 3) + * @property {Buffer} ripe - The RIPEMD hash of the receiver's keys + * @property {number} encoding - Message encoding + * @property {(string|Buffer)} message - Message string for + * [TRIVIAL]{@link module:bitmessage/objects.msg.TRIVIAL} and + * [SIMPLE]{@link module:bitmessage/objects.msg.SIMPLE} encodings or + * unparsed buffer data for other encodings + * @property {string=} subject - Subject string for [SIMPLE]{@link + * module:bitmessage/objects.msg.SIMPLE} encoding + * @property {Buffer} ack - Message acknowledgement + * @property {Buffer} signature - Signature of the message + * @property {number} length - Real data length + * @memberof module:bitmessage/objects.msg + */ + /** * Decode `msg` object message. * @param {Buffer} buf - Message - * @param {Object} opts - Decoding options - * @return {Promise.} A promise that contains decoded `msg` - * object structure when fulfilled. + * @param {Object} opts - Any of [object.decode]{@link + * module:bitmessage/structs.object.decode} options and: + * @param {(Address[]|Address)} opts.identities - Address objects used + * to decrypt the message + * @return {Promise.} A promise that contains [decoded + * `msg` structure]{@link module:bitmessage/objects.msg.DecodeResult} + * when fulfilled. */ decodeAsync: function(buf, opts) { return new PPromise(function(resolve) { @@ -557,10 +637,8 @@ var msg = exports.msg = { /** * Decode `msg` object message payload. - * @param {Buffer} buf - Message payload - * @param {Object} opts - Decoding options - * @return {Promise.} A promise that contains decoded `msg` - * object structure when fulfilled. + * The same as [decodeAsync]{@link + * module:bitmessage/objects.msg.decodeAsync}. */ decodePayloadAsync: function(buf, opts) { return new PPromise(function(resolve) { @@ -590,7 +668,7 @@ var msg = exports.msg = { var rest = decrypted.slice(decoded.length); // Pow extra. - if (decoded.senderVersion >= 3) { + if (senderVersion >= 3) { var decodedTrials = var_int.decode(rest); decoded.nonceTrialsPerByte = decodedTrials.value; decoded.length += decodedTrials.length; @@ -658,6 +736,18 @@ var msg = exports.msg = { /** * Encode `msg` object message. * @param {Object} opts - `msg` object options + * @param {number} opts.ttl - Time to live in seconds + * @param {Address} opts.from - Originator of the message + * @param {Address} opts.to - Receiver of the message + * @param {(string|Buffer)} opts.message - Message + * @param {(string|Buffer)=} opts.subject - Subject for [SIMPLE]{@link + * module:bitmessage/objects.msg.SIMPLE} encoding + * @param {number=} opts.encoding - Encoding of the message + * ([TRIVIAL]{@link module:bitmessage/objects.msg.TRIVIAL} by default) + * @param {boolean=} opts.friend - Whether the receiver is friend and + * should have minimal POW difficulty (false by default) + * @param {boolean=} opts.skipPow - Do not compute POW (false by + * default) * @return {Promise.} A promise that contains encoded message * when fulfilled. */ @@ -669,9 +759,8 @@ var msg = exports.msg = { /** * Encode `msg` object message payload. - * @param {Object} opts - `msg` object options - * @return {Promise.} A promise that contains encoded message - * payload when fulfilled. + * The same as [encodeAsync]{@link + * module:bitmessage/objects.msg.encodeAsync}. */ encodePayloadAsync: function(opts) { return new PPromise(function(resolve) { @@ -784,12 +873,52 @@ function tryDecryptBroadcastV4(subscriptions, buf) { * @static */ var broadcast = exports.broadcast = { + /** + * @typedef {Object} DecodeResult + * @property {Buffer} nonce - A 8-byte object nonce + * @property {number} ttl - Time to live in seconds + * @property {number} type - Object type + * @property {number} version - Object version + * @property {number} stream - Object stream + * @property {number} headerLength - Length of the object header + * @property {Buffer} tag - Tag derived from the address object used + * to send this `broadcast` (present only for object version >= 5) + * @property {number} senderVersion - Sender's address version + * @property {number} senderStream - Sender's stream + * @property {Object} behavior - Sender's [pubkey features]{@link + * module:bitmessage/structs.PubkeyBitfield} that can be expected from + * the node + * @property {Buffer} signPublicKey - Sender's signing public key + * @property {Buffer} encPublicKey - Sender's encryption public key + * @property {number} nonceTrialsPerByte - Difficulty parameter of the + * sender (present only if sender's address version >= 3) + * @property {number} payloadLengthExtraBytes - Difficulty parameter + * of the sender (present only if sender's address version >= 3) + * @property {number} encoding - Message encoding + * @property {(string|Buffer)} message - Message string for + * [TRIVIAL]{@link module:bitmessage/objects.msg.TRIVIAL} and + * [SIMPLE]{@link module:bitmessage/objects.msg.SIMPLE} encodings or + * unparsed buffer data for other encodings + * @property {string=} subject - Subject string for [SIMPLE]{@link + * module:bitmessage/objects.msg.SIMPLE} encoding + * @property {Buffer} signature - Signature of the message + * @property {number} length - Real data length + * @memberof module:bitmessage/objects.broadcast + */ + /** * Decode `broadcast` object message. * @param {Buffer} buf - Message - * @param {Object} opts - Decoding options - * @return {Promise.} A promise that contains decoded - * `broadcast` object structure when fulfilled. + * @param {Object} opts - Any of [object.decode]{@link + * module:bitmessage/structs.object.decode} options and: + * @param {(Address[]|Address|Object)} opts.subscriptions - Address + * objects which represent broadcast subscriptions. It is either + * addresses array or single address or Object + * addr-by-tag/addr-by-ripe. Time to match the key is O(n), O(1), O(1) + * respectfully. + * @return {Promise.} A promise that contains + * [decoded `broadcast` structure]{@link + * module:bitmessage/objects.broadcast.DecodeResult} when fulfilled. */ decodeAsync: function(buf, opts) { return new PPromise(function(resolve) { @@ -801,10 +930,8 @@ var broadcast = exports.broadcast = { /** * Decode `broadcast` object message payload. - * @param {Buffer} buf - Message payload - * @param {Object} opts - Decoding options - * @return {Promise.} A promise that contains decoded `pubkey` - * object structure when fulfilled. + * The same as [decodeAsync]{@link + * module:bitmessage/objects.broadcast.decodeAsync}. */ decodePayloadAsync: function(buf, opts) { return new PPromise(function(resolve) { @@ -931,6 +1058,15 @@ var broadcast = exports.broadcast = { /** * Encode `broadcast` object message. * @param {Object} opts - `broadcast` object options + * @param {number} opts.ttl - Time to live in seconds + * @param {Address} opts.from - Originator of the message + * @param {(string|Buffer)} opts.message - Message + * @param {(string|Buffer)=} opts.subject - Subject for [SIMPLE]{@link + * module:bitmessage/objects.msg.SIMPLE} encoding + * @param {number=} opts.encoding - Encoding of the message + * ([TRIVIAL]{@link module:bitmessage/objects.msg.TRIVIAL} by default) + * @param {boolean=} opts.skipPow - Do not compute POW (false by + * default) * @return {Promise.} A promise that contains encoded message * when fulfilled. */ @@ -942,9 +1078,8 @@ var broadcast = exports.broadcast = { /** * Encode `broadcast` object message payload. - * @param {Object} opts - `broadcast` object options - * @return {Promise.} A promise that contains encoded message - * payload when fulfilled. + * The same as [encodeAsync]{@link + * module:bitmessage/objects.broadcast.encodeAsync}. */ encodePayloadAsync: function(opts) { return new PPromise(function(resolve) { diff --git a/lib/wif.js b/lib/wif.js index 7bb589e..79fba9b 100644 --- a/lib/wif.js +++ b/lib/wif.js @@ -17,7 +17,8 @@ function getwifchecksum(data) { } /** - * Decode WIF encoded private key. + * Decode WIF-encoded private key (corresponded to a uncompressed public + * key). * @param {string} wif - Encoded key * @return {Buffer} Private key. */ @@ -31,9 +32,10 @@ exports.decode = function(wif) { }; /** - * Convert private key to a WIF. + * Convert private key to a WIF (corresponded to a uncompressed public + * key). * @param {Buffer} privateKey - A private key to encode - * @return {string} Encoded private key. + * @return {string} WIF-encoded private key. */ exports.encode = function(privateKey) { var data = Buffer.concat([new Buffer([0x80]), privateKey]);