MASQNode
and User InterfacesMASQNode
(or MASQNode.exe
for Windows) binary is used for two different purposes. One is called the Daemon; the other is called the Node.localhost
-only port (5333 by default) for connections from user interfaces. UIs connect first to the Daemon on its well-known port. There are certain conversations that the Daemon can carry on with the UI (one of which tells the Daemon to start up the Node), but when it's time, the Daemon will tell the UI where the Node is so that the UI can connect directly to the Node.localhost
pseudo-NIC. This means that all the UIs for a particular Daemon or Node must run on the same computer as the Daemon or Node: they cannot call in over the network from another machine. This restriction is in place for security reasons.MASQNode-UIv2
. Any other protocol name will be rejected, and no connection will be made.MASQNode-UIv2
messages is reasonably simple. It looks like this:opcode
is a short string that identifies the message type. If a message is a request (UI to Node) and the protocol dictates that a response (Node to UI) should result from it, both the request and the response will have the same opcode.contextId
is a positive integer best thought of as a conversation number. Just as there can be many UIs connected to the same Node, each UI can be carrying on many simultaneous conversations with the Node. When a request is sent as part of a unique conversation, the Daemon and the Node guarantee that the next message received in that conversation will be the response to that request. It is the responsibility of each UI to manage contextId
s. When the UI wants to start a new conversation, it merely mentions a new contextId
in the first message of that conversation; when it's done with a conversation, it just stops mentioning that conversation's contextId
.contextId
for all the messages a UI sends in its lifetime, and this is perfectly legal as far as the Node and Daemon are concerned; but if the UI does this, it will have to determine for itself which conversation each incoming message is part of. For example, if there are three conversations going on at once, this might happen:opcode
, and their contextId
should be ignored. (In the real world, it's always zero, but depending on that might be dangerous.)payload
is the body of the message, with its structure being signaled by the contents of the opcode
field. See the Message Reference section below for specifics about the payload
field for each type of message. It will be present if and only if the error
field is not present.error
field, if present, tells about the error that was encountered in the process of trying to satisfy a request. It will be present if and only if the payload
field is not present. It will have this structure:code
field is a 64-bit integer. Its numeric value is not particularly important, but it denotes a kind of error. The UI can tell whether a particular operation is producing the same kind of error repeatedly, or different kinds of errors, by comparing one code
to the next.message
field is a string with a hopefully-friendly description of the error.MASQNode-UIv2
protocol for UIs to communicate with one another. A UI may be able to deduce, from broadcasts, the existence of other UIs, but it can never be assured that there aren't any other UIs connected to the Node or Daemon.payload
of a MASQNode-UIv2
message depends on the opcode
of that message. See the Message Reference section below.localhost
, using the MASQNode-UIv2
protocol), and resend the original message--which, in case the UI doesn't remember it anymore, is helpfully included in the Redirect payload. If it's a valid Node message, the Node should respond appropriately to it.MASQNode-UIv2
messages, the UI can check to see if a password is correct; it can change the database password (if it knows the old one); and it can be notified when some other UI changes the password (so that it knows the one it's aware of is no longer valid).MASQNode-UIv2
as well. A UI can request the configuration information, and if the information changes for some reason, all UIs will be notified so that--if desired--they can request the latest version.opcode
and contextId
fields are not included in the message layouts, but they must be provided by the UI and will be specified by the Daemon or Node.changePassword
oldPasswordOpt
field. If there's already a database password, there is no way to remove it, even if the database does not yet contain secrets.changePassword
checkPassword
dbPasswordOpt
field. If you're checking to see whether there's no password, pass null
in this field, or leave it out.checkPassword
checkPassword
request to the Node, it will respond with this message. If the password you proposed (or the absence-of-password you proposed) matched the database password, the matches
field will be true
; otherwise it will be false
.configuration
configuration
checkPassword
message.blockchainServiceUrl
: The url which will be used for obtaining a communication to chosen services to interact with the blockchain. This parameter is read, if present, only if the same parameter wasn't specified at another place (UI, configuration file, environment variables).chainName
: This value reveals the chain which the open database has been created for. It is always present and once initiated, during creation of the database, it never changes. It's basically a read-only value.clandestinePort
: The port on which the Node is currently listening for connections from other Nodes.consumingWalletPrivateKey
: This is the private key of the consuming wallet, as a 64-digit hexadecimal number. It's a secret, so if you don't supply the dbPasswordOpt
in the request you won't see it.consumingWalletAddress
: This is the address of the consuming wallet, as a 40-digit hexadecimal number prefixed by "0x".currentSchemaVersion
: This will be a version number for the database schema represented as an ordinal numeral. This will always be the same for a given version of Node. If you upgrade your Node, and the new Node wants to see a later schema version in the database, it will migrate your existing data to the new schema and update its schema version. If this attempt fails for some reason, this value can be used to diagnose the issue.earningWalletAddressOpt
: The wallet address for the earning wallet. This is not secret, so if you don't get this field, it's because it hasn't been set yet.gasPrice
: The Node will not pay more than this number of wei for gas to complete a transaction.neighborhoodMode
: The neighborhood mode being currently used, this parameter has nothing to do with descriptors which may have been used in order to set the Node's nearest neighborhood. It is only informative, to know what mode is running at the moment. This value is ever present since the creation of the database.startBlock
: When the Node scans for incoming payments, it can't scan the whole blockchain: that would take much too long. So instead, it scans starting from wherever it left off last time. This block number is where it left off last time.pastNeighbors
: This is an array containing the Node descriptors of the neighbors the Node is planning to try to connect to when it starts up next time. It's a secret, so if you don't supply the dbPasswordOpt
in the request you won't see it.configurationChanged
configuration
request and get the new info; or you can just ignore this message if you don't care. If you're caching the configuration information, this would be a good time to invalidate your cache.crash
--crash-point message
parameter. It's used to test the behavior of the Node during a crash and the reactions of the software around it to that crash.actor
field in the payload is the name of the actor (Node subsystem) that will be forced to crash by the message. As of this writing, the only valid value is "BlockchainBridge".panicMessage
field in the payload is the message that will be passed to the panic!()
macro by the Node immediately upon receiving the message.crash
crash
message to all UIs connected to the Daemon. This doesn't necessarily mean the Node has experienced catastrophic failure: it may have been instructed by a UI to shut down.processId
field contains the platform-dependent process ID of the late Node.crashReason
field is rather clumsy, and there's a card (GH-323) in the backlog to improve it. At the moment, it's an object with one field, which may be named "ChildWaitFailure", "NoInformation", or "Unrecognized". If the field is named "ChildWaitFailure" or "Unrecognized", the value is a string with additional information. If the key is "NoInformation", the value is null
.descriptor
descriptor
nodeDescriptorOpt
field will be null or absent.financials
financials
totalPayable
and totalReceivable
fields will be accurate, but they will probably be larger than the sums of the payables
and receivables
amount
fields. The UI may choose to ignore this discrepancy, or it may generate an "Other" account in each case to make up the difference.wallet
fields will consist of 40 hexadecimal digits, prefixed by "0x".age
fields contain the age in seconds, at the time the request was received, of the most recent transaction on the associated account. The value will not be less than zero or longer than 64 bits.amount
fields contain the total amount in gwei owed to or due from the associated account at the time the request was received. The value will not be less than zero or longer than 64 bits.pendingTransaction
fields, if present, indicate that an obligation has been paid, but the payment is not yet confirmed on the blockchain. If they appear, they will be standard 64-digit hexadecimal transaction numbers, prefixed by "0x". If no pendingTransaction
is given, then there were no pending payments on that account at the time the request was received.payables
and receivables
arrays are not in any particular order.generateWallets
dbPassword
is the current database password. If this is incorrect or absent, the wallet generation will fail.seedSpecOpt
gives the parameters for generating the seed. This only makes sense if one or more of the derivation paths is supplied. If no derivation paths are supplied, this parameter is ignored.mnemonicPhraseSizeOpt
is the number of words that should be generated in the mnemonic phrase. The acceptable values are 12, 15, 18, 21, and 24. Default is 24.mnemonicPhraseLanguageOpt
is the language in which the mnemonic phrase should be generated. Acceptable values are "English", "Chinese", "Traditional Chinese", "French", "Italian", "Japanese", "Korean", and "Spanish". Default is "English."mnemonicPassphraseOpt
, if specified, is the "25th word" in the mnemonic passphrase: that is, an additional word (it can be any word; it's not constrained to the official mnemonic-phrase list) that will be used along with the 24 standard words to generate the seed number from which the wallet keys are derived. If this value is supplied, then the user will have to specify it as well as the 24 standard words in order to recover the wallet pair. Note that neither the 24 standard words nor this value is persisted anywhere: it's up to the user to keep track of them. Note also that the "25th word," if generated, is part of the seed and can never be changed: a different "25th word" will reference a different seed, which means that all wallets derived from it will also be different.consumingDerivationPathOpt
if supplied, is the derivation path from the generated seed number to be used to generate the consuming wallet. By convention, it is "m/44'/60'/0'/0/0", but you can supply whatever path you want. Note that if you change any of the numbers ending in ', you may have trouble getting other software and hardware to work with your wallet. If you don't supply consumingDerivationPathOpt
, your consuming wallet will be generated entirely at random.earningDerivationPathOpt
is the derivation path from the generated seed number to be used to generate the earning wallet. By convention, it is "m/44'/60'/0'/0/1", but you can supply whatever path you want. Note that if you change any of the numbers ending in ', you may have trouble getting other software and hardware to work with your wallet. If you don't supply earningDerivationPathOpt
, your earning wallet will be generated entirely at random.seedSpecOpt
and provide the same derivation path for both. (Note that just because you direct the Node to generate a mnemonic phrase, you don't necessarily have to use it. If you need to recover these wallets, you can use their private keys if you don't have their mnemonic seeds.)generateWallets
mnemonicPhraseOpt
, if present, is the requested list of 24 (or 12 or 15 or 18 or 21) words that, when combined with the mnemonic passphrase, if present, will produce the seed from which the consuming and earning wallets are derived. They are rendered in the requested language, including non-ASCII Unicode characters encoded in UTF-8 where appropriate.consumingWalletAddress
is the address of the generated consuming wallet.consumingWalletPrivateKey
is the private key of the generated consuming wallet. The Node will retain this key in its database, in encrypted form, because it needs to withdraw money from the wallet to pay other Nodes in the network.earningWalletAddress
is the address of the generated earning wallet.earningWalletPrivateKey
is the private key of the generated earning wallet. The Node does not need this key, and will not retain it; but you'll need it to withdraw earned funds from the wallet, especially if you didn't request or retain a mnemonic phrase.newPassword
recoverWallets
dbPassword
is the current database password. If this is incorrect, the wallet recovery will fail.seedSpecOpt
gives the parameters for generating the seed. This only makes sense if one or more of the derivation paths is supplied. If no derivation paths are supplied, this parameter is ignored.mnemonicPhrase
is the mnemonic phrase that represents the seed. It must have 12, 15, 18, 21, or 24 words.mnemonicPhraseLanguageOpt
is the language in which the mnemonic phrase is supplied. Acceptable values are "English", "Chinese", "Traditional Chinese", "French", "Italian", "Japanese", "Korean", and "Spanish". Default is "English."mnemonicPassphraseOpt
, if specified, is the "25th word" in the mnemonic passphrase: that is, an additional word (it can be any word; it's not constrained to the official mnemonic-phrase list) that was used along with the words of the mnemonic phrase to generate the seed number from which the consuming and possibly earning wallets were derived. If no mnemonic passphrase was used to generate the wallets, this value must be null or absent.consumingDerivationPathOpt
, if supplied, is the derivation path from the generated seed number to be used to generate the consuming wallet. By convention, it is "m/44'/60'/0'/0/0", but you can supply whatever path you want. Note that if you change any of the numbers ending in ', you may have trouble getting other software and hardware to work with your wallet. If you don't supply consumingDerivationPathOpt
, you must supply consumingPrivateKeyOpt
.consumingPrivateKeyOpt
, if specified, is the private key of the consuming wallet, represented as a string of 64 hexadecimal digits. This value supersedes consumingDerivationPathOpt
if both are supplied; but if you don't supply that value, you must supply this one.earningDerivationPathOpt
is the derivation path from the generated seed number to be used to generate the earning wallet. By convention, it is "m/44'/60'/0'/0/1", but you can supply whatever path you want. Note that if you change any of the numbers ending in ', you may have trouble getting other software and hardware to work with your wallet. If you don't supply earningDerivationPathOpt
, you must supply earningAddressOpt
.earningAddressOpt
, if specified, is the address of the earning wallet, represented as "0x" followed by a string of 40 hexadecimal digits. This value supersedes earningDerivationPathOpt
if both are supplied; but if you don't supply that value, you must supply this one.recoverWallets
redirect
port
field contains the port number on which the Node is listening for UI connections.opcode
field contains the opcode of the unrecognized message.contextId
field, if present, contains the contextId
of the unrecognized message. If not present, then the unrecognized message was not part of a conversation.payload
field is a string of JSON, containing the payload of the unrecognized message.localhost
at the indicated port, reconstruct the original message from the opcode
, contextId
, and payload
fields, and send it to the Node.setConfiguration
name
field in the payload is the name of the parameter which the user wants to modify and has this form: e.g. start-block or gas-price (with a dash between words).value
field in the payload is the value to be assigned to the parameter. It must always be specified as a string, even for parameters whose values are natively of other types.setConfiguration
setup
values
array may be empty. If it is, no modifications will be made, but a report of the existing contents of the Setup space will be returned.name
field is one of a set of known parameter names whose value should be changed. See below for a list.value
field, if present, holds the new value for the parameter. If not present, the parameter value will be cleared.name
sblockchain-service-url
- URL of the blockchain service to use: currently only Infura is supported.chain
- mainnet
or ropsten
. The blockchain the Node should connect to.clandestine-port
- The port at which other Nodes will contact this one.config-file
- Path to or name of the TOML file from which to take additional configuration.consuming-private-key
- 64-digit hexadecimal number containing the consuming wallet's private key.data-directory
- Path to data directory.db-password
- Password to unlock the sensitive values in the database.dns-servers
- Comma-separated list of DNS servers to use.earning-wallet
- Wallet into which earnings should be deposited.gas-price
- Transaction fee to offer on the blockchain.ip
- The public IP address of the Node.log-level
- The lowest level of logs that should be recorded. off
, error
, warn
, info
, debug
, trace
mapping-protocol
- The management protocol to try first with the router. pcp
, pmp
, igdp
neighborhood-mode
- zero-hop
, originate-only
, consume-only
, standard
neighbors
- Comma-separated list of Node descriptors for neighbors to contact on startupreal-user
- Non-Windows platforms only, only where required: ::setup
contextId
) if it sends a setup
request; but it will also receive this message as an unsolicited broadcast if another UI sends a setup
request that results in actual changes to the Daemon's Setup space.running
field will be true if the Node is currently running, or false otherwise. If true, the proposed changes, if any, in the request that stimulated this response or broadcast were ignored, because the Setup space is immutable while the Node is running.values
array contains a list of the values in the Setup space. For each object in the list:name
field is the name of the parameter, one of the names listed for the request above.value
field is the value of that parameter. If the parameter has no value, the value
field will be a blank string.status
field has one of the following values:Default
- The parameter has a default value, and has not been changed from it.Configured
- The parameter has taken its value from a configuration file or an environment variable.Set
- The parameter was set by a UI using a setup
message.Blank
- The parameter has no value, and no value is required.Required
- The parameter has no value, but some value is required to start the Node.errors
array will be populated with error messages about the problem parameters. It's an array of two-element arrays; each two-element array will have the name of the offending parameter first, and an appropriate error message second. If there are no detectable errors, the errors
array will be empty.Required
parameters will not prevent the Daemon from attempting to start the Node, but it will prevent the Node from starting or running properly. The UI may choose not to offer the user the option to start the Node until the Daemon is happy, but that's optional.shutdown
shutdown
message has an empty payload. As a Request, it instructs the Node to shut down. As a Response, it notifies the UI that the Node is almost shut down. (Obviously, the Node can't send a Response if it's completely shut down.)start
start
message has an empty payload. It causes the Daemon to try to start the Node with whatever configuration information is presently in its Setup space.start
start
attempt is successful, this response will arrive.newProcessId
field is the system-dependent process ID of the newly-running Node.redirectUiPort
field is the WebSockets port on which the UI can now connect to the Node. The UI that actually starts the Node can take advantage of this to preemptively connect to the Node without processing a Redirect; but a UI that starts after the Node is already running must go through the Redirect operation to find it. It requires less code to simply have your UI always use Redirects.start
request. To discover a newly-started Node's Node descriptor, send the descriptor
message directly to the Node itself.unmarshalError
message
field describes what's wrong with the unmarshallable message.badData
field contains the unmarshallable message itself.walletAddresses
dbPassword
element. If one or both wallets are not configured, an error message will be sent back.walletAddresses
consumingWalletAddress
is the address of the generated consuming wallet.earningWalletAddress
is the address of the generated earning wallet.