Add Documentation for Public Universe Server and Endpoints

[ffranr]

We need to enhance the Universes documentation by adding a new section dedicated to Public Universe Servers.

Content to consider

1. Introduce Public Universe Server:

   • Provide a clear and detailed description of what a public universe server is in the context of Taproot Assets.
   • Explain its role and purpose within the tap ecosystem.
   • Explain how some organizations may run a limited public universe server that might only recognize a limited set of tap assets.
   • Explain the role of a public universe server in proof transfers for tap asset transfers.

2. Document RPC/REST Endpoints:

   • List and describe the RPC/REST endpoints available on a public universe server that developers can utilize.
   • Include direct links to the relevant endpoints in the API documentation, specifically from the Universe Service Endpoints.
     • For example, link to the InsertProof endpoint and provide a brief overview of its functionality.

3. Clarify Macaroon Authentication:

   • Explain that while the API documentation may indicate that a macaroon is required for authentication, the public universe server endpoints actually ignore the macaroon if provided.

[ZZiigguurraatt]

Found some definition of the public endpoints here: https://github.com/Roasbeef/bips/blob/bip-tap/bip-tap-universe.mediawiki#universe-grpc-api . The reference comes from here: https://github.com/lightninglabs/docs.lightning.engineering/blob/0ba7c3cccae485c76c015ca7994281d5610abf7a/the-lightning-network/taproot-assets/taproot-assets-protocol.md?plain=1#L177 .

[Liongrass]

I made edits to this guide, have a look if this is satisfactory: https://docs.lightning.engineering/lightning-network-tools/taproot-assets/universes

[ZZiigguurraatt]

I made some comments: https://github.com/lightninglabs/docs.lightning.engineering/commit/a2edb8128bb516654beaabd7c4b5ed9224f434e7#comments .

[ZZiigguurraatt]

Here is a list of the public REST endpoints

https://github.com/Roasbeef/bips/blob/bip-tap/bip-tap-universe.mediawiki#universe-rest-api

Is there any way we can label each endpoint on https://lightning.engineering/api-docs/category/universe-service/index.html to say if it is a public or private one?

[Liongrass]

Thank you very much for that! I've addressed your points in this change: https://github.com/lightninglabs/docs.lightning.engineering/commit/c3609e37c304c7730fab3f625e7cb6eaaf70b204

[ZZiigguurraatt]

Do we want to mention at all that a big reason the universe must exist is because Taproot Assets try to do as much stuff off chain as possible in order to increase scalability and improve privacy?

[ZZiigguurraatt]

How does a public universe limit what proofs it accepts in order avoid abuse/spam/overload?

[ZZiigguurraatt]

I think we are still missing some differentiation between the public and private RPC endpoints?

[Liongrass]

What's the current status with mailboxes? Are we moving away from them entirely, and universes will take over that functionality? I'm not aware of what private RPC endpoints exist so that would be very much worth documenting

[guggero]

I think we are still missing some differentiation between the public and private RPC endpoints?

By default, if you run tapd with no special configuration, all its RPC methods are macaroon protected. But you can white list certain RPC methods with two flags:

--allow-public-uni-proof-courier                          Disable macaroon authentication for universe proof courier RPC endpoints.

Allows access without macaroons to:

• /universerpc.Universe/QueryProof
• /universerpc.Universe/InsertProof

--allow-public-stats                                      Disable macaroon authentication for stats RPC endpoints.

Allows access without macaroons to:

• /universerpc.Universe/QueryAssetStats
• /universerpc.Universe/UniverseStats
• /universerpc.Universe/QueryEvents

The code for this can be found here: https://github.com/lightninglabs/taproot-assets/blob/47e78750da8269663d85bba4ffc22de813569fee/perms/perms.go#L318

What's the current status with mailboxes?

They can still be used (and are still the fallback/default if nothing is configured manually) for on-chain transfers. But because of script key collision issues with keys involved in Taproot Asset Channels (see https://github.com/lightninglabs/taproot-assets/issues/1113), the hashmail based proof courier should not be used when operating Taproot Asset channels and a universe server should be configured instead.

[Liongrass]

Thank you for the information! I'll make sure our current guides reflect that properly