Builder's Guide
  • Welcome to the Builder's Guide to the LND Galaxy!
  • The Lightning Network
    • Overview
    • Payment Channels
      • Lifecycle of a Payment Channel
      • Watchtowers
      • Understanding Sweeping
      • Etymology
    • The Gossip Network
      • Identifying Good Peers on the Lightning Network
    • Pathfinding
      • Finding routes in the Lightning Network
      • Channel Fees
      • Multipath Payments (MPP)
    • Lightning Network Invoices
      • Understanding Lightning Invoices
    • Making Payments
      • The Payment Cycle
      • Timelocks
      • ⭐Hashed Timelock Contract (HTLC)
      • Payment Etymology
      • ⭐What Makes a Good Routing Node
      • Understanding Submarine Swaps
      • Instant Submarine Swaps
    • Liquidity
      • ⭐Understanding Liquidity
      • Managing Liquidity on the Lightning Network
      • Liquidity Management for Lightning Merchants
      • How to Get Inbound Capacity on the Lightning Network
      • Lightning Service Provider
    • L402: Lightning HTTP 402 Protocol
      • Macaroons
      • L402
      • 📋Protocol Specification
      • Implementations and Links
    • Taproot Assets
      • Taproot Assets Protocol
      • Taproot Assets on Lightning
      • Edge Nodes
      • Taproot Assets Trustless Swap
      • FAQ
      • Glossary
  • Lightning Network Tools
    • LND
      • 🛠️Get Started
      • lnd.conf
      • First Steps With LND
      • Wallet Management
      • Sending Payments
      • Atomic Multi-path Payments (AMP)
      • Receiving Payments
      • Unconfirmed Bitcoin Transactions
      • Channel Fees
      • Inbound Channel Fees
      • Macaroons
      • Configuring Watchtowers
      • Pathfinding
      • Blinded Paths
      • Key Import
      • Secure Your Lightning Network Node
      • Configuration of a Routing Node
      • Quick Tor Setup
      • Configuring Tor
      • Enable ‘Neutrino mode’ in Bitcoin Core
      • Send Messages With Keysend
      • Partially Signed Bitcoin Transactions
      • Bulk onchain actions with PSBTs
      • Sweeper
      • Debugging LND
      • Fuzzing LND
      • LND API documentation
      • Channel Acceptor
      • RPC Middleware Interceptor
      • HTLC Interceptor
      • NAT Traversal
      • Recovery: Planning for Failure
      • Migrating LND
      • Disaster recovery
      • Contribute to LND
    • Lightning Terminal
      • What is Lightning Terminal?
      • 🛠️Get litd
      • Run litd
      • Integrating litd
      • Demo: Litd Speed Run
      • Connect to Terminal
      • Recommended Channels
      • Rankings
      • Health Checks
      • Liquidity Report
      • Opening Lightning Network Channels
      • Managing Channel Liquidity
      • Autofees
      • AutoOpen
      • LND Accounts
      • Loop and Lightning Terminal
      • Loop Fees
      • Pool and Lightning Terminal
      • Command Line Interface
      • Troubleshooting
      • Lightning Node Connect: Under the hood
      • LNC Node Package
      • LITD API Documentation
      • Privacy and Security
      • Privacy Policy
      • Terms of Use
    • Loop
      • 🛠️Get Started
      • The Loop CLI
      • Autoloop
      • Static Loop In Addresses
      • Instant Loop Outs
      • Peer with Loop
      • Loop API Documentation
    • Pool
      • Overview
      • Quickstart
      • 🛠️Installation
      • First Steps
      • Accounts
      • Orders and Asks
      • Sidecar Channels
      • Zero-confirmation Channels
      • Channel Leases
      • Batch Execution
      • Account Recovery
      • Pool API Documentation
      • FAQs
    • Taproot Assets
      • Get Started
      • First Steps
      • Taproot Assets Channels
      • Asset Decimal Display
      • Become an Edge Node
      • RFQ
      • Collectibles
      • Universes
      • Asset Loop
      • Debugging Tapd
      • Multisignature
      • Minting Assets With an External Signer
      • Lightning Polar
      • Operational Safety Guidelines
      • Taproot Assets API Documentation
    • Aperture
      • ⚒️Get Aperture
      • LNC Backend
      • LNC Mailbox
      • Pricing
    • Faraday
      • 🛠️Get Started
      • The Faraday CLI
      • Faraday API Documentation
  • LAPPs
    • Guides
      • Use Polar to Build Your First LAPP
        • Setup: Local Cluster with Polar
        • Setup: Run the Completed App
        • Setup: Run the App Without LND
      • Add Features
        • Feature 1: Connect to LND
        • Feature 2: Display Node Alias and Balance
        • Feature 3: Sign and Verify Posts
        • Feature 4: Modify Upvote Action
      • Make Your own LNC-powered Application
    • Next Steps
  • Community Resources
    • Resource List
    • Lightning Bulb 💡
    • Glossary
    • FAQ
Powered by GitBook
On this page
  • The default macaroons
  • Baking custom macaroons
  • Restraining macaroons
  • Revoking macaroons
  • Using Macaroons with GRPC clients
  • Stateless initialization
  • Actions and RPC permissions
  • Onchain
  • Address
  • Message
  • Peers
  • Offchain
  • Info
  • Invoices
  • Macaroon

Was this helpful?

  1. Lightning Network Tools
  2. LND

Macaroons

Macaroons are fancy cookies. You use LND to create custom macaroons that limit their permissions with great granularity, down to the exact RPC calls.

PreviousInbound Channel FeesNextConfiguring Watchtowers

Last updated 24 days ago

Was this helpful?

LND, Loop, Pool and litd all use macaroons to authenticate RPC calls. Macaroons are similar to cookies in that they are bearer instruments, but they can be more easily verified by the server using HMACs and a root key alone. They can also be attenuated, both by the server and by the user. This greatly simplifies how LND authenticates RPC calls while expanding the detail in which authority over specific RPC calls is permissioned.

The default macaroons

By default, LND will generate eight macaroons, created for specific purposes. You can inspect the permissions of each macaroon with the command lncli printmacaroon --macaroon_file ~/path/to/macaroon

admin.macaroon

permissions: all

chainnotifier.macaroon

onchain: read

invoices.macaroon

invoices: read & write

invoice.macaroon

address, invoice: read & write; onchain: read

readonly.macaroon

address, info, invoices, macaroon, message, offchain, onchain, peers, signer: read

router.macaroon

offchain: read & write

signer.macaroon

signer: generate & read

walletkit.macaroon

address, onchain: read & write

Baking custom macaroons

The process of creating a custom macaroon is called “baking.” For this process, LND includes the LND macaroon bakery that can be invoked with lncli bakemacaroon

For instance, a macaroon that is only allowed to manage peers could be created with the command:

lncli bakemacaroon peers:read peers:write

For even more granularity, it is possible to specify individual RPC calls.

lncli bakemacaroon uri:/lnrpc.Lightning/GetInfo uri:/verrpc.Versioner/GetVersion

To get a list of all available restrictions, run lncli listpermissions

By default, LND will generate new macaroons with the root key 0. You can specify another root key ID, even one that does not yet exist, using the flag --root_key_id. To save your macaroon to a file rather than returning its hex value, use the --save_to flag. Additionally, macaroons can be bound by IP address as well.

LND supports adding external permissions, even if LND does not understand these permissions, with the --allow_external_permissions flag.

LND does not include a tool to convert a macaroon back to its hex value, but you may run the xxd utility if it is installed on your system.

xxd -ps -u -c 1000 /path/to.macaroon

Restraining macaroons

Using the macaroon bakery, you can take any existing macaroon and restrain it further, even if the macaroon was not issued by you.

For example, we can limit our admin macaroon to only be valid for calls made from localhost, as well as take away its authority to perform on-chain actions:

lncli constrainmacaroon --ip_address 127.0.0.1 --custom_caveat_name onchain --custom_caveat_condition read admin.macaroon constrained.macaroon

We can now inspect the permissions of this new macaroon with:

lncli printmacaroon --macaroon_file constrained.macaroon

{
    "version": 2,
    "location": "lnd",
    "root_key_id": "0",
    "permissions": [
   	 "address:read",
   	 "address:write",
   	 "info:read",
   	 "info:write",
   	 "invoices:read",
   	 "invoices:write",
   	 "macaroon:generate",
   	 "macaroon:read",
   	 "macaroon:write",
   	 "message:read",
   	 "message:write",
   	 "offchain:read",
   	 "offchain:write",
   	 "onchain:read",
   	 "onchain:write",
   	 "peers:read",
   	 "peers:write",
   	 "signer:generate",
   	 "signer:read"
    ],
    "caveats": [
   	 "ipaddr 127.0.0.1",
   	 "lnd-custom onchain read"
    ]
}

Revoking macaroons

To revoke a macaroon, it is not sufficient to delete the macaroon. Instead, its root key has to be deleted. Which root key is used for a macaroon can be found out using the lncli printmacaroon command above.

lncli deletemacaroonid root_key_id

Using Macaroons with GRPC clients

When interacting with lnd using the GRPC interface, the macaroons are encoded as a hex string over the wire and can be passed to lnd by specifying the hex-encoded macaroon as GRPC metadata:

GET https://localhost:8080/v1/getinfo
Grpc-Metadata-macaroon: <macaroon>

Where <macaroon> is the hex encoded binary data from the macaroon file itself.

A very simple example using curl may look something like this:

curl --insecure --header "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000  $HOME/.lnd/data/chain/bitcoin/simnet/admin.macaroon)" https://localhost:8080/v1/getinfo

Stateless initialization

As mentioned above, by default lnd creates several macaroon files in its directory. These are unencrypted and in case of the admin.macaroon provide full access to the daemon. This can be seen as quite a big security risk if the lnd daemon runs in an environment that is not fully trusted.

The macaroon files are the only files with highly sensitive information that are not encrypted (unlike the wallet file and the macaroon database file that contains the root key, these are always encrypted, even if no password is used).

To avoid leaking the macaroon information, lnd supports the so called stateless initialization mode:

  • The three startup commands create, unlock and changepassword of lncli

    all have a flag called --stateless_init that instructs the daemon not

    to create *.macaroon files.

  • The two operations create and changepassword that actually create/update

    the macaroon database will return the admin macaroon in the RPC call.

    Assuming the daemon and the lncli are not used on the same machine, this

    will leave no unencrypted information on the machine where lnd runs on.

    • To be more precise: By default, when using the changepassword command, the

      macaroon root key in the macaroon DB is just re-encrypted with the new

      password. But the key remains the same and therefore the macaroons issued

      before the changepassword command still remain valid. If a user wants to

      invalidate all previously created macaroons, the --new_mac_root_key flag

      of the changepassword command should be used!

  • An user of lncli will see the returned admin macaroon printed to the screen

    or saved to a file if the parameter --save_to=some_file.macaroon is used.

  • Important: By default, lnd will create the macaroon files during the

    unlock phase, if the --stateless_init flag is not used. So to avoid

    leakage of the macaroon information, use the stateless initialization flag

    for all three startup commands of the wallet unlocker service!

Examples:

  • Create a new wallet stateless (first run):

    lncli create --stateless_init --save_to=/safe/location/admin.macaroon
  • Unlock a wallet that has previously been initialized stateless:

    lncli unlock --stateless_init
  • Use the created macaroon:

    lncli --macaroonpath=/safe/location/admin.macaroon getinfo

Actions and RPC permissions

Onchain

/lnrpc.Lightning/SendCoins /lnrpc.Lightning/ListUnspent /lnrpc.Lightning/SendMany /lnrpc.Lightning/OpenChannel /lnrpc.Lightning/BatchOpenChannel /lnrpc.Lightning/OpenChannelSync /lnrpc.Lightning/CloseChannel /lnrpc.Lightning/WalletBalance /lnrpc.Lightning/EstimateFee /lnrpc.Lightning/ChannelBalance /lnrpc.Lightning/SubscribeTransactions /lnrpc.Lightning/GetTransactions /lnrpc.Lightning/ChannelAcceptor /lnrpc.Lightning/FundingStateStep

Address

/lnrpc.Lightning/NewAddress

Message

/lnrpc.Lightning/SignMessage /lnrpc.Lightning/VerifyMessage

Peers

/lnrpc.Lightning/ConnectPeer /lnrpc.Lightning/DisconnectPeer /lnrpc.Lightning/ListPeers /lnrpc.Lightning/SubscribePeerEvents

Offchain

/lnrpc.Lightning/AbandonChannel /lnrpc.Lightning/PendingChannels /lnrpc.Lightning/ListChannels /lnrpc.Lightning/SubscribeChannelEvents /lnrpc.Lightning/ClosedChannels /lnrpc.Lightning/SendPayment /lnrpc.Lightning/SendPaymentSync /lnrpc.Lightning/SendToRoute /lnrpc.Lightning/SendToRouteSync /lnrpc.Lightning/ListPayments /lnrpc.Lightning/DeletePayment /lnrpc.Lightning/DeleteAllPayments /lnrpc.Lightning/DecodePayReq /lnrpc.Lightning/UpdateChannelPolicy /lnrpc.Lightning/ForwardingHistory /lnrpc.Lightning/RestoreChannelBackups /lnrpc.Lightning/ExportChannelBackup /lnrpc.Lightning/VerifyChanBackup /lnrpc.Lightning/ExportAllChannelBackups /lnrpc.Lightning/SubscribeChannelBackups /lnrpc.Lightning/SendCustomMessage /lnrpc.Lightning/SubscribeCustomMessages /lnrpc.Lightning/LookupHtlcResolution /lnrpc.Lightning/ListAliases

Info

/lnrpc.Lightning/GetInfo /lnrpc.Lightning/GetRecoveryInfo /lnrpc.Lightning/DescribeGraph /lnrpc.Lightning/GetNodeMetrics /lnrpc.Lightning/GetChanInfo /lnrpc.Lightning/GetNodeInfo /lnrpc.Lightning/QueryRoutes /lnrpc.Lightning/GetNetworkInfo /lnrpc.Lightning/StopDaemon /lnrpc.Lightning/SubscribeChannelGraph /lnrpc.Lightning/DebugLevel /lnrpc.Lightning/FeeReport /lnrpc.Lightning/ListPermissions

Invoices

/lnrpc.Lightning/AddInvoice /lnrpc.Lightning/LookupInvoice /lnrpc.Lightning/ListInvoices /lnrpc.Lightning/SubscribeInvoices

Macaroon

/lnrpc.Lightning/BakeMacaroon /lnrpc.Lightning/ListMacaroonIDs /lnrpc.Lightning/DeleteMacaroonID /lnrpc.Lightning/CheckMacaroonPermissions /lnrpc.RegisterRPCMiddlewareURI

Have a look at the for programmatic usage details.

Macaroons in LND may refer to one of seven actions: onchain, address, message, peers, offchain, info, invoices and macaroon. These the following RPC services:

Learn more about Macaroons here.
Java GRPC example
actions encompass