lightninglabs / lightninglabs/taproot-assets

[bug]: confusing wording in docs for `tapcli universe`

Open Beginner friendly
#1,765 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Go
Stars
525
Forks
150
Avg merge
2d 15h
Merged PRs (30d)
31

Description

In a number of places we have some weird wording in the docs for the --asset_id and --group_key command line options.

   --asset_id value      the asset ID of the universe to query for
   --group_key value     the group key of the universe to query for

I'm not sure if this is supposed to be the the asset ID to query the universe for and the group key to query the universe for ?

Like the way I understand it, an asset_id and group_key aren't "owned" by a single universe, but I think the asset ID of the universe to query for and the group key of the universe to query for imply that.


Here are some examples:

002d4af395f0:/$ tapcli universe roots -h
NAME:
   tapcli universe roots - list the known asset universe roots

USAGE:
   tapcli universe roots [command options] [arguments...]

DESCRIPTION:
   Query for the set of known asset universe roots

OPTIONS:
   --asset_id value      the asset ID of the universe to query for
   --group_key value     the group key of the universe to query for
   --proof_type value    the type of proof to show the roots for, either 'issuance' or 'transfer' (default: "issuance")
   --skip_amounts_by_id  skip showing the amounts by ID for grouped assets to optimize response size and speed; only applies if no asset ID or group key is specified
   --offset value        the offset to start returning results from; only applies if no asset ID or group key is specified (default: 0)
   --limit value         the maximum number of results to return; only applies if no asset ID or group key is specified (default: 512)
   
002d4af395f0:/$ 
002d4af395f0:/$ tapcli universe leaves -h
NAME:
   tapcli universe leaves - return the known set of leaves in a Universe

USAGE:
   tapcli universe leaves [command options] [arguments...]

DESCRIPTION:
   
  Query for the set of known leaves for a given asset universe. A leaf in a
  universe is an entry that denotes either a new issuance event (asset
  minting) or an asset transfer. A leaf includes the asset under action, a
  state transition proof for that asset.

OPTIONS:
   --asset_id value    the asset ID of the universe to query for
   --group_key value   the group key of the universe to query for
   --proof_type value  the type of proof to show the leaves for, either 'issuance' or 'transfer' (default: "issuance")
   
002d4af395f0:/$ 
002d4af395f0:/$ tapcli universe keys -h
NAME:
   tapcli universe keys - return the known set of keys in a Universe

USAGE:
   tapcli universe keys [command options] [arguments...]

DESCRIPTION:
   
  Query for the set of known keys for a given asset universe. Keys take the
  form: (outpoint, script_key), where outpoint is the outpoint that anchors
  and asset, and script_key is the key for that asset within an asset_id
  tree.
  

OPTIONS:
   --asset_id value    the asset ID of the universe to query for
   --group_key value   the group key of the universe to query for
   --proof_type value  the type of proof to show the keys for, either 'issuance' or 'transfer' (default: "issuance")
   
002d4af395f0:/$ 
002d4af395f0:/$ tapcli universe proofs query -h
NAME:
   tapcli universe proofs query - query for a universe proof

USAGE:
   tapcli universe proofs query [command options] [arguments...]

DESCRIPTION:
   
  Attempt to query the target universe for a given proof based on a top
  level asset id or group key, and the leaf key of: outpoint || script key.
  

OPTIONS:
   --asset_id value    the asset ID of the universe to query for
   --group_key value   the group key of the universe to query for
   --outpoint value    the target outpoint on chain to locate a tap proof within
   --script_key value  the script key (scoped to an assetID) to query a proof for
   --proof_type value  the type of proof to query for, either 'issuance' or 'transfer' (default: "issuance")
   
002d4af395f0:/$ 

Here we have

   --asset_id value    the asset ID of the universe to query for
   --group_key value   the group key of the universe to query for

but we are not querying the universe, we are inserting, right?

002d4af395f0:/$ tapcli universe proofs insert -h
NAME:
   tapcli universe proofs insert - insert a new universe proof

USAGE:
   tapcli universe proofs insert [command options] [arguments...]

DESCRIPTION:
   
  Attempt to insert a new proof into the target universe. The proof can be
  accepted either via a file argument (proof_file), via stdin, or via a hex
  encoded string.
  

OPTIONS:
   --asset_id value    the asset ID of the universe to query for
   --group_key value   the group key of the universe to query for
   --outpoint value    the target outpoint on chain to locate a tap proof within
   --script_key value  the script key (scoped to an assetID) to query a proof for
   --proof_type value  the type of proof to query for, either 'issuance' or 'transfer' (default: "issuance")
   --proof_file value  
   
002d4af395f0:/$ 

Here we are not querying, but pushing:

002d4af395f0:/$ tapcli universe proofs push -h
NAME:
   tapcli universe proofs push - push a proof to a remote Universe

USAGE:
   tapcli universe proofs push [command options] [arguments...]

DESCRIPTION:
   
  Push a proof present in the local Universe to a remote Universe.
  

OPTIONS:
   --asset_id value       the asset ID of the universe to query for
   --group_key value      the group key of the universe to query for
   --outpoint value       the target outpoint on chain to locate a tap proof within
   --script_key value     the script key (scoped to an assetID) to query a proof for
   --proof_type value     the type of proof to query for, either 'issuance' or 'transfer' (default: "issuance")
   --universe_host value  the host:port or just host of the remote universe
   --server_id value      the ID of the universe server in our federation (default: 0)
   
002d4af395f0:/$ 

Here we have

   --asset_id value       the asset ID of the sync with the universe
   --group_key value      the group key of sync with the universe

which is even more confusing of a wording but I think it should be the asset ID to sync with the universe and the group key to sync with the universe?

002d4af395f0:/$ tapcli universe sync -h
NAME:
   tapcli universe sync - synchronize universe state with a remote instance

USAGE:
   tapcli universe sync [command options] [arguments...]

DESCRIPTION:
   Attempt to sync Universe state with a remote Universe

OPTIONS:
   --universe_host value  the host:port or just host of the remote universe
   --asset_id value       the asset ID of the sync with the universe
   --group_key value      the group key of sync with the universe
   --proof_type value     the type of proof to sync either 'issuance' or 'transfer' (default: "issuance")
   
002d4af395f0:/$ 

Also I think here we should have the asset ID to delete from the universe and the group key to delete from the universe?

002d4af395f0:/$ tapcli universe delete -h
NAME:
   tapcli universe delete - delete a known asset universe root

USAGE:
   tapcli universe delete [command options] [arguments...]

DESCRIPTION:
   Delete a known asset universe root

OPTIONS:
   --asset_id value    the asset ID of the universe to delete
   --group_key value   the group key of the universe to delete
   --proof_type value  the type of proof to delete the roots for, either 'issuance' or 'transfer' (default: "issuance")
   
002d4af395f0:/$ 

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the tapcli universe command help entry points shown in the issue, especially roots, leaves, keys, proofs, sync, and delete. Review how each command describes --asset_id and --group_key, update the wording to match the command's action, and rerun each listed -h command to confirm the help text is clear and consistent.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.