docs: update Namespaces page & fix minor typos
#2599
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,109 @@ | ||||||
| --- | ||||||
| id: package-paths | ||||||
| --- | ||||||
|
|
||||||
| # Package Paths | ||||||
|
|
||||||
| A package path is a unique identifier for each package/realm. It specifies the | ||||||
| location of the package source code which helps differentiate it from others. | ||||||
| You can use a package path to: | ||||||
|
|
||||||
| - Call a specific function from a package/realm. (e.g using `gnokey maketx call`) | ||||||
| - Import it in other packages/realms. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| Here's a breakdown of the structure of a package path: | ||||||
|
|
||||||
| - Domain: The domain of the blockchain where the package is deployed. | ||||||
| Currently, only `gno.land/` is supported. | ||||||
| - Type: Defines the type of package. | ||||||
| - `p/`: [Package](packages.md) | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| - `r/`: [Realm](realms.md) | ||||||
| - Namespace: A namespace can be included after the type (e.g., user or organization name). Namespaces are a | ||||||
| way to group related packages or realms. A user can register a namespace for | ||||||
| themselves, or use the anonymous namespace. Read more [below](#namespaces). | ||||||
|
|
||||||
| Here are some examples of package paths: | ||||||
|
|
||||||
| - `gno.land/p/demo/avl`: This signifies a package named `avl` within the `demo` namespace. | ||||||
| - `gno.land/r/gnoland/home`: This signifies a realm named `home` within the `gnoland` namespace. | ||||||
|
|
||||||
| ## Namespaces | ||||||
|
|
||||||
| Namespaces provide users with the exclusive ability to publish code under | ||||||
| their designated namespaces, similar to GitHub's user and organization model. | ||||||
| A namespace follows these rules: | ||||||
| - Needs to be between 6 and 17 characters. | ||||||
| - Can only contain alphanumeric characters. | ||||||
| - No special characters are allowed (except underscore). | ||||||
| - Cannot consist solely of underscores. A namespace must have at least one | ||||||
| allowed alphanumeric character. | ||||||
| - Cannot start with a number. A namespace must begin with a letter. | ||||||
| - Cannot end with a trailing slash (`/`). | ||||||
|
|
||||||
| :::warning Namespaces on gno.land testnets | ||||||
|
|
||||||
| This feature is currently only enabled on the [Test4 testnet](./testnets.md#test4). | ||||||
|
There was a problem hiding this comment. Maybe reword this to clarify it is enabled on all networks from test4 and beyond, excluding portal loop. This way it won't have to be updated when we launch (test5? 😅 ) mainnet. |
||||||
| Other networks, such as the Portal Loop, do not have this feature enabled. | ||||||
|
|
||||||
| ::: | ||||||
|
|
||||||
| ## Registering a namespace | ||||||
|
|
||||||
| To register a namespace, you need to use the `r/demo/users` realm. It allows | ||||||
| users to register a username for a fee of 200 `GNOTs`, which is in turn used as | ||||||
|
There was a problem hiding this comment.
Suggested change
Makes it clear that the username is the thing being used as a reference for the namespace of the user. There was a problem hiding this comment. Also, I've not typed out a lot of digital currency amounts in markdown, but it seems like |
||||||
| a reference for the namespace of the user. | ||||||
|
|
||||||
| Once a username is registered, `r/sys/users` is used as a filtering mechanism | ||||||
| which will allow code deployments from the registering address to the namespace | ||||||
| matching the username. | ||||||
|
|
||||||
| A username can be registered by calling the `Register()` function in `r/demo/users`. | ||||||
| The `Register()` function will also allow you to add a string as a description | ||||||
| of your profile. Check out [`r/demo/users` on Test4](https://test4.gno.land/r/demo/users). | ||||||
|
|
||||||
| For example, the following `gnokey` command will register `patrick` as the username | ||||||
| for the address `mykey`. | ||||||
|
|
||||||
| ```bash | ||||||
| $ gnokey maketx call -pkgpath gno.land/r/demo/users \ | ||||||
| -func Register \ | ||||||
| -gas-fee 1000000ugnot -gas-wanted 2000000 \ | ||||||
| -broadcast \ | ||||||
| -chainid=test4 \ | ||||||
| -remote https://rpc.test4.gno.land | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| -send=20000000ugnot \ | ||||||
| -args '' \ | ||||||
| -args 'patrick' \ | ||||||
| -args 'My Profile Quote' mykey | ||||||
| ``` | ||||||
|
|
||||||
| :::note Interacting with the correct network | ||||||
|
|
||||||
| Make sure to use the proper chain ID and remote when interacting with a | ||||||
| gno.land network. Check out the [Network Configurations](../reference/network-config.md) | ||||||
| page for a list of all available endpoints. | ||||||
|
|
||||||
| ::: | ||||||
|
|
||||||
| After successful registration, you can add a package under your registered namespace. | ||||||
|
|
||||||
| ## Anonymous Namespace | ||||||
|
There was a problem hiding this comment. I wouldn't describe the namespace as anonymous -- there is an address associated with it. Perhaps "Eponymous Namespace" is more fitting here. |
||||||
|
|
||||||
| gno.land offers the ability to deploy code without having a registered namespace. | ||||||
| You can do this by using your own address as a namespace. This is formatted as `{p,r}/{std.Address}/**`. | ||||||
|
|
||||||
| For example, with `mykey` being `g1zmgrq5y2vxuqc8shkuc0vr5dj23eklf2xr720x`, | ||||||
| the following deployment would work: | ||||||
|
|
||||||
| ```bash | ||||||
| $ gnokey maketx addpkg \ | ||||||
| --pkgpath "gno.land/r/g1zmgrq5y2vxuqc8shkuc0vr5dj23eklf2xr720x/myrealm" \ | ||||||
| --pkgdir "." \ | ||||||
| --deposit 100000000ugnot \ | ||||||
| --gas-fee 1000000ugnot \ | ||||||
| --gas-wanted 2000000 \ | ||||||
| --broadcast \ | ||||||
| --chainid test4 \ | ||||||
| -remote https://rpc.test4.gno.land | ||||||
|
There was a problem hiding this comment.
Suggested change
Also when we have blocks of multiline commands in the same doc like this, it would be good to keep the flags consistent -- one dash vs two for example. You and I know there is no difference, but it might be confusing to a newbie just getting started with command line tools. |
||||||
| mykey | ||||||
| ``` | ||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think there needs to be
package/realmeverywhere. We can just refer to them generally as packages and make the distinction between pure packages and realms when it is necessary.Edit after looking through this and existing package docs more:
IMO we should refer to things throughout the docs as "pure packages" or "realms" as necessary and reserve "package" as a term that refers to both. This way the term "package path" makes sense that is should apply to both pure packages and realms, not only to what we currently refer to as packages (actually pure packages). What do you think?