diff --git a/documentation/pages/_meta.json b/documentation/pages/_meta.json index 922cbce8..6bfe0cad 100644 --- a/documentation/pages/_meta.json +++ b/documentation/pages/_meta.json @@ -3,6 +3,7 @@ "developer": "Developer", "user": "User", "node-operator": "Node Operator", + "move-registry": "Move Registry (beta)", "dashboard": { "title": "SuiNS Dashboard ↗", "type": "page", diff --git a/documentation/pages/move-registry.mdx b/documentation/pages/move-registry.mdx new file mode 100644 index 00000000..4516606a --- /dev/null +++ b/documentation/pages/move-registry.mdx @@ -0,0 +1,19 @@ +# Move Registry + +Move Registry is built to provide a name service for interacting / building with packages from the ecosystem. You could consider it the name service for packages. + +Move Registry is currently used for the following scenarios: + +1. To reference packages and types in PTBs using their names. +2. To depend on other packages when developing with Move. + +## Why use the Move Registry? + +Move Registry provides a uniform (single source of truth) naming service for packages in the Move ecosystem. +This means that you can reference packages by their names, and the Move Registry will resolve the package address for you, despite the network*. + +Additionally, Move Registry helps with working with versioning of packages. You can call a specific version of a package easily, without having to +resolve the addresses yourself, or worry about the package being updated (name without a specified version defaults to the latest). + + +*Move Registry default service currently supports Mainnet and testnet.* diff --git a/documentation/pages/move-registry/_meta.json b/documentation/pages/move-registry/_meta.json new file mode 100644 index 00000000..041ceabc --- /dev/null +++ b/documentation/pages/move-registry/_meta.json @@ -0,0 +1,7 @@ +{ + "design": "Design of the Move Registry", + "managing-package-info": "Managing Package Metadata", + "mvr-names": "Managing MVR Names", + "maintainer-practises": "Package Maintainer Best-Practices", + "tooling": "Tooling" +} diff --git a/documentation/pages/move-registry/design.mdx b/documentation/pages/move-registry/design.mdx new file mode 100644 index 00000000..bf80456e --- /dev/null +++ b/documentation/pages/move-registry/design.mdx @@ -0,0 +1,36 @@ +# Design of the Move Registry + +Before diving into specifics, we first need to analyze the design. The Move Registry consists of two independent components: + +1. Package Info registration: Exists independently on each network. +2. Move Registry: A single source of truth located on mainnet. + +![High level design](/images/mvr/mvr-overall.svg) + + +## Package Info objects + +The first step when publishing a package is to register its metadata object. This metadata object serves as a key source of information for: + +1. Locating the source code across different versions of the package. +2. (Future) Providing text-based metadata (title, description, tags) for the package, which can be used in the MVR search engine. + +This metadata object can be reused when authorizing any package upgrades to supply source information for the new version. +It is designed to be indexable by Sui Indexers, as it cannot be stored within another object. + +![Package Info Objects](/images/mvr/mvr-package-info.svg) + + +## Move Registry + +Move Registry registration is separate from the PackageInfo registration process. This separation is necessary because the PackageInfo object acts as both the source of truth for package metadata and a proof of package ownership, whereas the Move Registry is used to register applications that can be resolved using MVR tooling. + +The steps to register a package are as follows: + +1. Using your SuiNS name, register an application. +2. Based on the network, associate the application name with a `PackageInfo` object: +- **Mainnet**: Associate the application name with a complete PackageInfo object, which provides the full metadata and ownership proof. +- **Other Networks**: Associate the application name with only the PackageInfo object ID, acting as a pointer without ensuring a full mapping. + + +![Move Registry](/images/mvr/mvr-registry.svg) diff --git a/documentation/pages/move-registry/maintainer-practises.mdx b/documentation/pages/move-registry/maintainer-practises.mdx new file mode 100644 index 00000000..5c60ff27 --- /dev/null +++ b/documentation/pages/move-registry/maintainer-practises.mdx @@ -0,0 +1,10 @@ +# Best Practises + +For package authors/maintainers, the following best practises are recommended when saving your source code to make sure +that your package is easily usable by other developers. + +1. Whenever you publish/upgrade a package, you need to use the [Automated Address Management](https://docs.sui.io/concepts/sui-move-concepts/packages/automated-address-management) +2. It's recommended to switch your `Sui` dependency to the correct network you're publishing/upgrading against (e.g. `framework/testnet` for testnet, `framework/mainnet` for mainnet). +3. After properly configuring your Automated Address Management, you should commit your changes to your git repository. +4. Make sure this commit is also tagged OR is part of your main branch. A good practise is tagging your releases with network/verson (e.g. `mainnet/v1`). +5. You can then use the commit SHA or the tag to update the source code origin in the `PackageInfo` object. diff --git a/documentation/pages/move-registry/managing-package-info.mdx b/documentation/pages/move-registry/managing-package-info.mdx new file mode 100644 index 00000000..c56e7880 --- /dev/null +++ b/documentation/pages/move-registry/managing-package-info.mdx @@ -0,0 +1,9 @@ +# Creating/Maintaining `PackageInfo` object + +[ +TODO!!!: Add sui client ptb commands to: +1. Create a `PackageInfo` object for your package. +2. Add the source code information to the `PackageInfo` object. + + +] diff --git a/documentation/pages/move-registry/mvr-names.mdx b/documentation/pages/move-registry/mvr-names.mdx new file mode 100644 index 00000000..0d1f1156 --- /dev/null +++ b/documentation/pages/move-registry/mvr-names.mdx @@ -0,0 +1,7 @@ +# Managing MVR names + +[TODO!!!: Add sui client ptb commands to: + +1. Create a new MVR app by presenting a SuiNS name and a package name. +2. Linking a MVR app with a `PackageInfo` object. +] diff --git a/documentation/pages/move-registry/tooling.mdx b/documentation/pages/move-registry/tooling.mdx new file mode 100644 index 00000000..b6e299e6 --- /dev/null +++ b/documentation/pages/move-registry/tooling.mdx @@ -0,0 +1,6 @@ +# Tooling + +Two main tools have been developed using the Move Registry: + +- A TypeScript SDK plugin for building PTBs with MVR names. +- An MVR CLI tool for Move development. diff --git a/documentation/pages/move-registry/tooling/_meta.json b/documentation/pages/move-registry/tooling/_meta.json new file mode 100644 index 00000000..9f5f94a1 --- /dev/null +++ b/documentation/pages/move-registry/tooling/_meta.json @@ -0,0 +1,4 @@ +{ + "typescript-sdk": "Typescript SDK Plugin", + "mvr-cli": "MVR CLI" +} diff --git a/documentation/pages/move-registry/tooling/mvr-cli.mdx b/documentation/pages/move-registry/tooling/mvr-cli.mdx new file mode 100644 index 00000000..a6d6bf96 --- /dev/null +++ b/documentation/pages/move-registry/tooling/mvr-cli.mdx @@ -0,0 +1,45 @@ +import { Tabs } from 'nextra/components' +import { Callout } from 'nextra/components' + +# MVR CLI + +MVR CLI is used to manage your package dependencies and to interact with the Move Registry. It is a command-line tool that allows you to: + +1. Add dependencies to your Move project. +2. Build your Move project with MVR dependencies. + + +## Installation + +To install the MVR CLI, you can use the following command: + +```bash +TODO: add installation command +``` + +## Adding dependencies + +To add a dependency to your move code, you can use the `mvr add` command. This command will add the dependency to your `Move.toml` file. + +```bash +mvr add --network +``` + +Using this, a new entry will be added to your `Move.toml` file. + +```toml +[dependencies] +... +app = { r.mvr = "@mvr/app" } + +[r.mvr] +network = "mainnet" +``` + +## Building against MVR dependencies + +You can use `sui move build` as usual, and the MVR CLI will be automatically invoked to resolve dependencies and build your project. + +```bash +sui move build +``` diff --git a/documentation/pages/move-registry/tooling/typescript-sdk.mdx b/documentation/pages/move-registry/tooling/typescript-sdk.mdx new file mode 100644 index 00000000..cb6375b7 --- /dev/null +++ b/documentation/pages/move-registry/tooling/typescript-sdk.mdx @@ -0,0 +1,86 @@ +import { Tabs } from 'nextra/components' +import { Callout } from 'nextra/components' + +# Typescript SDK plugin + +The purpose of the MVR TypeScript SDK plugin is to offer developers a seamless experience when building PTBs with MVR names. +This plugin resolves MVR names to their respective addresses before constructing the PTB, caching the results during each runtime. + +This also applies to type names, which have traditionally been harder to refer to, especially across package upgrades. + +## How to use + +The MVR plugin is exported directly from the @mysten/sui package. To enable the plugin, register it either globally or per PTB in your dApp. + +[TODO: Add the public good endpoints] + +```typescript +import { namedPackagesPlugin, Transaction } from "@mysten/sui/transactions"; + +/** Register the MVR plugin globally (once) for our PTB construction */ +Transaction.registerGlobalSerializationPlugin('namedPackagesPlugin', namedPackagesPlugin({ + suiGraphQLClient: new SuiGraphQLClient({ + url: `` + }), + // You can also define overrides for packages and types optionally. + // The following example shows how to override the sui@framework package to resolve 0x1. + // Attention: Types need to be strictly defined in the overrides. + overrides: { + packages: { 'sui@framework': '0x2' }, + types: {} + } +})); +``` + + +## Before / after example + + The examples in the tabs are simplified for clarity. Actual addresses or names may differ. + + + + + +Example of a PTB before MVR: +```typescript +const transaction = new Transaction(); + +// testnet +// Notice how the suifren type has a V1 outer package id, and a V2 inner type package id, +// even if they are part of the same package upgrades. +transaction.moveCall({ + target: `0xe177697e191327901637f8d2c5ffbbde8b1aaac27ec1024c4b62d1ebd1cd7430::accessories::equip`, + arguments: [..], + typeArguments: [ + `0x80d7de9c4a56194087e0ba0bf59492aa8e6a5ee881606226930827085ddf2332::suifren::SuiFren<0x297d8afb6ede450529d347cf9254caeea2b685c8baef67b084122291ebaefb38::bullshark::Bullshark>` + ] +}); + +// mainnet +transaction.moveCall({ + target: `0x54800ebb4606fd0c03b4554976264373b3374eeb3fd63e7ff69f31cac786ba8c::accessories::equip`, + arguments: [..], + typeArguments: [ + `0xee496a0cc04d06a345982ba6697c90c619020de9e274408c7819f787ff66e1a1::suifren::SuiFren<0x8894fa02fc6f36cbc485ae9145d05f247a78e220814fb8419ab261bd81f08f32::bullshark::Bullshark>` + ] +}); +``` + + +Example of a PTB after MVR, consistent across networks: + +```typescript +const transaction = new Transaction(); + +// Now we can use `@suifrens/core` across all package upgrades for type reference. +// And we also have the guarantee to call the latest version of the accessories package. +transaction.moveCall({ + target: `@suifrens/accessories::accessories::equip`, + arguments: [..], + typeArguments: [ + `@suifrens/core::suifren::SuiFren<@suifrens/core::bullshark::Bullshark>` + ] +}) +``` + + diff --git a/documentation/public/images/mvr/mvr-overall.svg b/documentation/public/images/mvr/mvr-overall.svg new file mode 100644 index 00000000..afa13712 --- /dev/null +++ b/documentation/public/images/mvr/mvr-overall.svg @@ -0,0 +1,10 @@ + + + + + + + + @mvr/appSuiNs Name(e.g. @mvr)App name(e.g `app`)+UpgradeCapPackageInfoMAINNETUpgradeCapPackageInfoTESTNETresolves this package on testnetresolves this package on mainnetMAINNET \ No newline at end of file diff --git a/documentation/public/images/mvr/mvr-package-info.svg b/documentation/public/images/mvr/mvr-package-info.svg new file mode 100644 index 00000000..d5dbdf32 --- /dev/null +++ b/documentation/public/images/mvr/mvr-package-info.svg @@ -0,0 +1,10 @@ + + + + + + + + UpgradeCapPackageInfoContains metadata for a package including:1. Source code location per version (github repo / subdir /commit sha or tag)2. (Future) Title, description, tags for the move registrysearch enginePackageInfo exists on all networks.So we register our PackageInfo across mainnet, testnet \ No newline at end of file diff --git a/documentation/public/images/mvr/mvr-registry.svg b/documentation/public/images/mvr/mvr-registry.svg new file mode 100644 index 00000000..78f7ede9 --- /dev/null +++ b/documentation/public/images/mvr/mvr-registry.svg @@ -0,0 +1,10 @@ + + + + + + + + Move Registry has a single source of truth, on mainnet. SuiNs Name(e.g. @mvr)App name(e.g `app`)@mvr/app+Move Registry application can point to a PackageInfo on each networkMove Registry \ No newline at end of file