walletunlocker.swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "walletunlocker.proto",
    "version": "version not set"
  },
  "tags": [
    {
      "name": "WalletUnlocker"
    }
  ],
  "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": "WalletUnlocker_ChangePassword",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/lnrpcChangePasswordResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "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": "WalletUnlocker_GenSeed",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/lnrpcGenSeedResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "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": "WalletUnlocker_InitWallet",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/lnrpcInitWalletResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "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": "WalletUnlocker_UnlockWallet",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/lnrpcUnlockWalletResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "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",
          "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",
          "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",
          "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!"
        },
        "extended_master_key": {
          "type": "string",
          "description": "extended_master_key is an alternative to specifying cipher_seed_mnemonic and\naezeed_passphrase. Instead of deriving the master root key from the entropy\nof an aezeed cipher seed, the given extended master root key is used\ndirectly as the wallet's master key. This allows users to import/use a\nmaster key from another wallet. When doing so, lnd still uses its default\nSegWit only (BIP49/84) derivation paths and funds from custom/non-default\nderivation paths will not automatically appear in the on-chain wallet. Using\nan 'xprv' instead of an aezeed also has the disadvantage that the wallet's\nbirthday is not known as that is an information that's only encoded in the\naezeed, not the xprv. Therefore a birthday needs to be specified in\nextended_master_key_birthday_timestamp or a \"safe\" default value will be\nused."
        },
        "extended_master_key_birthday_timestamp": {
          "type": "string",
          "format": "uint64",
          "description": "extended_master_key_birthday_timestamp is the optional unix timestamp in\nseconds to use as the wallet's birthday when using an extended master key\nto restore the wallet. lnd will only start scanning for funds in blocks that\nare after the birthday which can speed up the process significantly. If the\nbirthday is not known, this should be left at its default value of 0 in\nwhich case lnd will start scanning from the first SegWit block (481824 on\nmainnet)."
        },
        "watch_only": {
          "$ref": "#/definitions/lnrpcWatchOnly",
          "description": "watch_only is the third option of initializing a wallet: by importing\naccount xpubs only and therefore creating a watch-only wallet that does not\ncontain any private keys. That means the wallet won't be able to sign for\nany of the keys and _needs_ to be run with a remote signer that has the\ncorresponding private keys and can serve signing RPC requests."
        },
        "macaroon_root_key": {
          "type": "string",
          "format": "byte",
          "description": "macaroon_root_key is an optional 32 byte macaroon root key that can be\nprovided when initializing the wallet rather than letting lnd generate one\non its own."
        }
      }
    },
    "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",
          "description": "stateless_init is an optional argument instructing the daemon NOT to create\nany *.macaroon files in its file system."
        }
      }
    },
    "lnrpcUnlockWalletResponse": {
      "type": "object"
    },
    "lnrpcWatchOnly": {
      "type": "object",
      "properties": {
        "master_key_birthday_timestamp": {
          "type": "string",
          "format": "uint64",
          "description": "The unix timestamp in seconds of when the master key was created. lnd will\nonly start scanning for funds in blocks that are after the birthday which\ncan speed up the process significantly. If the birthday is not known, this\nshould be left at its default value of 0 in which case lnd will start\nscanning from the first SegWit block (481824 on mainnet)."
        },
        "master_key_fingerprint": {
          "type": "string",
          "format": "byte",
          "description": "The fingerprint of the root key (also known as the key with derivation path\nm/) from which the account public keys were derived from. This may be\nrequired by some hardware wallets for proper identification and signing. The\nbytes must be in big-endian order."
        },
        "accounts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/lnrpcWatchOnlyAccount"
          },
          "description": "The list of accounts to import. There _must_ be an account for all of lnd's\nmain key scopes: BIP49/BIP84 (m/49'/0'/0', m/84'/0'/0', note that the\ncoin type is always 0, even for testnet/regtest) and lnd's internal key\nscope (m/1017'/\u003ccoin_type\u003e'/\u003caccount\u003e'), where account is the key family as\ndefined in `keychain/derivation.go` (currently indices 0 to 9)."
        }
      }
    },
    "lnrpcWatchOnlyAccount": {
      "type": "object",
      "properties": {
        "purpose": {
          "type": "integer",
          "format": "int64",
          "description": "Purpose is the first number in the derivation path, must be either 49, 84\nor 1017."
        },
        "coin_type": {
          "type": "integer",
          "format": "int64",
          "description": "Coin type is the second number in the derivation path, this is _always_ 0\nfor purposes 49 and 84. It only needs to be set to 1 for purpose 1017 on\ntestnet or regtest."
        },
        "account": {
          "type": "integer",
          "format": "int64",
          "title": "Account is the third number in the derivation path. For purposes 49 and 84\nat least the default account (index 0) needs to be created but optional\nadditional accounts are allowed. For purpose 1017 there needs to be exactly\none account for each of the key families defined in `keychain/derivation.go`\n(currently indices 0 to 9)"
        },
        "xpub": {
          "type": "string",
          "description": "The extended public key at depth 3 for the given account."
        }
      }
    },
    "protobufAny": {
      "type": "object",
      "properties": {
        "type_url": {
          "type": "string"
        },
        "value": {
          "type": "string",
          "format": "byte"
        }
      }
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    }
  }
}