mirror of
https://github.com/lightningnetwork/lnd.git
synced 2024-11-19 18:10:34 +01:00
4c8d374007
This commit adds the --stateless_init flag to all three wallet unlocker operations. Once you initialize a wallet stateless, you need to set this flag for every further wallet unlocker operation. Otherwise you risk non-encrypted macaroon information to leak to the underlying system.
393 lines
16 KiB
JSON
393 lines
16 KiB
JSON
{
|
|
"swagger": "2.0",
|
|
"info": {
|
|
"title": "walletunlocker.proto",
|
|
"version": "version not set"
|
|
},
|
|
"consumes": [
|
|
"application/json"
|
|
],
|
|
"produces": [
|
|
"application/json"
|
|
],
|
|
"paths": {
|
|
"/v1/changepassword": {
|
|
"post": {
|
|
"summary": "lncli: `changepassword`\nChangePassword changes the password of the encrypted wallet. This will\nautomatically unlock the wallet database if successful.",
|
|
"operationId": "ChangePassword",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/lnrpcChangePasswordResponse"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "body",
|
|
"in": "body",
|
|
"required": true,
|
|
"schema": {
|
|
"$ref": "#/definitions/lnrpcChangePasswordRequest"
|
|
}
|
|
}
|
|
],
|
|
"tags": [
|
|
"WalletUnlocker"
|
|
]
|
|
}
|
|
},
|
|
"/v1/genseed": {
|
|
"get": {
|
|
"summary": "GenSeed is the first method that should be used to instantiate a new lnd\ninstance. This method allows a caller to generate a new aezeed cipher seed\ngiven an optional passphrase. If provided, the passphrase will be necessary\nto decrypt the cipherseed to expose the internal wallet seed.",
|
|
"description": "Once the cipherseed is obtained and verified by the user, the InitWallet\nmethod should be used to commit the newly generated seed, and create the\nwallet.",
|
|
"operationId": "GenSeed",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/lnrpcGenSeedResponse"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "aezeed_passphrase",
|
|
"description": "aezeed_passphrase is an optional user provided passphrase that will be used\nto encrypt the generated aezeed cipher seed. When using REST, this field\nmust be encoded as base64.",
|
|
"in": "query",
|
|
"required": false,
|
|
"type": "string",
|
|
"format": "byte"
|
|
},
|
|
{
|
|
"name": "seed_entropy",
|
|
"description": "seed_entropy is an optional 16-bytes generated via CSPRNG. If not\nspecified, then a fresh set of randomness will be used to create the seed.\nWhen using REST, this field must be encoded as base64.",
|
|
"in": "query",
|
|
"required": false,
|
|
"type": "string",
|
|
"format": "byte"
|
|
}
|
|
],
|
|
"tags": [
|
|
"WalletUnlocker"
|
|
]
|
|
}
|
|
},
|
|
"/v1/initwallet": {
|
|
"post": {
|
|
"summary": "InitWallet is used when lnd is starting up for the first time to fully\ninitialize the daemon and its internal wallet. At the very least a wallet\npassword must be provided. This will be used to encrypt sensitive material\non disk.",
|
|
"description": "In the case of a recovery scenario, the user can also specify their aezeed\nmnemonic and passphrase. If set, then the daemon will use this prior state\nto initialize its internal wallet.\n\nAlternatively, this can be used along with the GenSeed RPC to obtain a\nseed, then present it to the user. Once it has been verified by the user,\nthe seed can be fed into this RPC in order to commit the new wallet.",
|
|
"operationId": "InitWallet",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/lnrpcInitWalletResponse"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "body",
|
|
"in": "body",
|
|
"required": true,
|
|
"schema": {
|
|
"$ref": "#/definitions/lnrpcInitWalletRequest"
|
|
}
|
|
}
|
|
],
|
|
"tags": [
|
|
"WalletUnlocker"
|
|
]
|
|
}
|
|
},
|
|
"/v1/unlockwallet": {
|
|
"post": {
|
|
"summary": "lncli: `unlock`\nUnlockWallet is used at startup of lnd to provide a password to unlock\nthe wallet database.",
|
|
"operationId": "UnlockWallet",
|
|
"responses": {
|
|
"200": {
|
|
"description": "A successful response.",
|
|
"schema": {
|
|
"$ref": "#/definitions/lnrpcUnlockWalletResponse"
|
|
}
|
|
},
|
|
"default": {
|
|
"description": "An unexpected error response",
|
|
"schema": {
|
|
"$ref": "#/definitions/runtimeError"
|
|
}
|
|
}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"name": "body",
|
|
"in": "body",
|
|
"required": true,
|
|
"schema": {
|
|
"$ref": "#/definitions/lnrpcUnlockWalletRequest"
|
|
}
|
|
}
|
|
],
|
|
"tags": [
|
|
"WalletUnlocker"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"definitions": {
|
|
"lnrpcChanBackupSnapshot": {
|
|
"type": "object",
|
|
"properties": {
|
|
"single_chan_backups": {
|
|
"$ref": "#/definitions/lnrpcChannelBackups",
|
|
"description": "The set of new channels that have been added since the last channel backup\nsnapshot was requested."
|
|
},
|
|
"multi_chan_backup": {
|
|
"$ref": "#/definitions/lnrpcMultiChanBackup",
|
|
"description": "A multi-channel backup that covers all open channels currently known to\nlnd."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcChangePasswordRequest": {
|
|
"type": "object",
|
|
"properties": {
|
|
"current_password": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "current_password should be the current valid passphrase used to unlock the\ndaemon. When using REST, this field must be encoded as base64."
|
|
},
|
|
"new_password": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "new_password should be the new passphrase that will be needed to unlock the\ndaemon. When using REST, this field must be encoded as base64."
|
|
},
|
|
"stateless_init": {
|
|
"type": "boolean",
|
|
"format": "boolean",
|
|
"title": "stateless_init is an optional argument instructing the daemon NOT to create\nany *.macaroon files in its filesystem. If this parameter is set, then the\nadmin macaroon returned in the response MUST be stored by the caller of the\nRPC as otherwise all access to the daemon will be lost!"
|
|
},
|
|
"new_macaroon_root_key": {
|
|
"type": "boolean",
|
|
"format": "boolean",
|
|
"description": "new_macaroon_root_key is an optional argument instructing the daemon to\nrotate the macaroon root key when set to true. This will invalidate all\npreviously generated macaroons."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcChangePasswordResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"admin_macaroon": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The binary serialized admin macaroon that can be used to access the daemon\nafter rotating the macaroon root key. If both the stateless_init and\nnew_macaroon_root_key parameter were set to true, this is the ONLY copy of\nthe macaroon that was created from the new root key and MUST be stored\nsafely by the caller. Otherwise a copy of this macaroon is also persisted on\ndisk by the daemon, together with other macaroon files."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcChannelBackup": {
|
|
"type": "object",
|
|
"properties": {
|
|
"chan_point": {
|
|
"$ref": "#/definitions/lnrpcChannelPoint",
|
|
"description": "Identifies the channel that this backup belongs to."
|
|
},
|
|
"chan_backup": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "Is an encrypted single-chan backup. this can be passed to\nRestoreChannelBackups, or the WalletUnlocker Init and Unlock methods in\norder to trigger the recovery protocol. When using REST, this field must be\nencoded as base64."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcChannelBackups": {
|
|
"type": "object",
|
|
"properties": {
|
|
"chan_backups": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/lnrpcChannelBackup"
|
|
},
|
|
"description": "A set of single-chan static channel backups."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcChannelPoint": {
|
|
"type": "object",
|
|
"properties": {
|
|
"funding_txid_bytes": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "Txid of the funding transaction. When using REST, this field must be\nencoded as base64."
|
|
},
|
|
"funding_txid_str": {
|
|
"type": "string",
|
|
"description": "Hex-encoded string representing the byte-reversed hash of the funding\ntransaction."
|
|
},
|
|
"output_index": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"title": "The index of the output of the funding transaction"
|
|
}
|
|
}
|
|
},
|
|
"lnrpcGenSeedResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"cipher_seed_mnemonic": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "cipher_seed_mnemonic is a 24-word mnemonic that encodes a prior aezeed\ncipher seed obtained by the user. This field is optional, as if not\nprovided, then the daemon will generate a new cipher seed for the user.\nOtherwise, then the daemon will attempt to recover the wallet state linked\nto this cipher seed."
|
|
},
|
|
"enciphered_seed": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "enciphered_seed are the raw aezeed cipher seed bytes. This is the raw\ncipher text before run through our mnemonic encoding scheme."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcInitWalletRequest": {
|
|
"type": "object",
|
|
"properties": {
|
|
"wallet_password": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "wallet_password is the passphrase that should be used to encrypt the\nwallet. This MUST be at least 8 chars in length. After creation, this\npassword is required to unlock the daemon. When using REST, this field\nmust be encoded as base64."
|
|
},
|
|
"cipher_seed_mnemonic": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "cipher_seed_mnemonic is a 24-word mnemonic that encodes a prior aezeed\ncipher seed obtained by the user. This may have been generated by the\nGenSeed method, or be an existing seed."
|
|
},
|
|
"aezeed_passphrase": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "aezeed_passphrase is an optional user provided passphrase that will be used\nto encrypt the generated aezeed cipher seed. When using REST, this field\nmust be encoded as base64."
|
|
},
|
|
"recovery_window": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "recovery_window is an optional argument specifying the address lookahead\nwhen restoring a wallet seed. The recovery window applies to each\nindividual branch of the BIP44 derivation paths. Supplying a recovery\nwindow of zero indicates that no addresses should be recovered, such after\nthe first initialization of the wallet."
|
|
},
|
|
"channel_backups": {
|
|
"$ref": "#/definitions/lnrpcChanBackupSnapshot",
|
|
"description": "channel_backups is an optional argument that allows clients to recover the\nsettled funds within a set of channels. This should be populated if the\nuser was unable to close out all channels and sweep funds before partial or\ntotal data loss occurred. If specified, then after on-chain recovery of\nfunds, lnd begin to carry out the data loss recovery protocol in order to\nrecover the funds in each channel from a remote force closed transaction."
|
|
},
|
|
"stateless_init": {
|
|
"type": "boolean",
|
|
"format": "boolean",
|
|
"title": "stateless_init is an optional argument instructing the daemon NOT to create\nany *.macaroon files in its filesystem. If this parameter is set, then the\nadmin macaroon returned in the response MUST be stored by the caller of the\nRPC as otherwise all access to the daemon will be lost!"
|
|
}
|
|
}
|
|
},
|
|
"lnrpcInitWalletResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"admin_macaroon": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "The binary serialized admin macaroon that can be used to access the daemon\nafter creating the wallet. If the stateless_init parameter was set to true,\nthis is the ONLY copy of the macaroon and MUST be stored safely by the\ncaller. Otherwise a copy of this macaroon is also persisted on disk by the\ndaemon, together with other macaroon files."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcMultiChanBackup": {
|
|
"type": "object",
|
|
"properties": {
|
|
"chan_points": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/lnrpcChannelPoint"
|
|
},
|
|
"description": "Is the set of all channels that are included in this multi-channel backup."
|
|
},
|
|
"multi_chan_backup": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "A single encrypted blob containing all the static channel backups of the\nchannel listed above. This can be stored as a single file or blob, and\nsafely be replaced with any prior/future versions. When using REST, this\nfield must be encoded as base64."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcUnlockWalletRequest": {
|
|
"type": "object",
|
|
"properties": {
|
|
"wallet_password": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "wallet_password should be the current valid passphrase for the daemon. This\nwill be required to decrypt on-disk material that the daemon requires to\nfunction properly. When using REST, this field must be encoded as base64."
|
|
},
|
|
"recovery_window": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "recovery_window is an optional argument specifying the address lookahead\nwhen restoring a wallet seed. The recovery window applies to each\nindividual branch of the BIP44 derivation paths. Supplying a recovery\nwindow of zero indicates that no addresses should be recovered, such after\nthe first initialization of the wallet."
|
|
},
|
|
"channel_backups": {
|
|
"$ref": "#/definitions/lnrpcChanBackupSnapshot",
|
|
"description": "channel_backups is an optional argument that allows clients to recover the\nsettled funds within a set of channels. This should be populated if the\nuser was unable to close out all channels and sweep funds before partial or\ntotal data loss occurred. If specified, then after on-chain recovery of\nfunds, lnd begin to carry out the data loss recovery protocol in order to\nrecover the funds in each channel from a remote force closed transaction."
|
|
},
|
|
"stateless_init": {
|
|
"type": "boolean",
|
|
"format": "boolean",
|
|
"description": "stateless_init is an optional argument instructing the daemon NOT to create\nany *.macaroon files in its file system."
|
|
}
|
|
}
|
|
},
|
|
"lnrpcUnlockWalletResponse": {
|
|
"type": "object"
|
|
},
|
|
"protobufAny": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type_url": {
|
|
"type": "string"
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"format": "byte"
|
|
}
|
|
}
|
|
},
|
|
"runtimeError": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string"
|
|
},
|
|
"code": {
|
|
"type": "integer",
|
|
"format": "int32"
|
|
},
|
|
"message": {
|
|
"type": "string"
|
|
},
|
|
"details": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/protobufAny"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|