Bitmessage/bitmessage-js
2
0
Fork 1
Code Issues 1 Pull Requests 1 Actions Packages Releases Activity

docs: objects

Browse Source
This commit is contained in:
Kagami Hiiragi 2015-02-11 22:56:14 +03:00
parent 96d7074b2d
commit e70acd6b99
4 changed files with 197 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
lib/address.js
View File

@ -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

1
lib/messages.js
View File

@ -5,7 +5,6 @@
* @see {@link https://bitmessage.org/Bitmessage%20Technical%20Paper.pdf}
* @module bitmessage/messages
*/
// TODO(Kagami): Document object-like params.
"use strict";

245
lib/objects.js
View File

@ -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.<Object>} 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.<DecodeResult>} 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.<Object>} 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.<Buffer>} 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.<Buffer>} 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.<Object>} 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.<DecodeResult>} 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.<Object>} 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.<Buffer>} 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.<Buffer>} 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.<Object>} 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.<DecodeResult>} 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.<Object>} 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.<Buffer>} 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.<Buffer>} 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.<Object>} 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.<DecodeResult>} 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.<Object>} 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.<Buffer>} 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.<Buffer>} 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) {

8
lib/wif.js
View File

@ -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]);