MVR Docs work (#194)

* MVR docs

---------

Co-authored-by: stefan-mysten <[email protected]>
Co-authored-by: Ronny Roland <[email protected]>
Co-authored-by: ronny-mysten <[email protected]>

documentation/components/beta.js

@@ -0,0 +1,28 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import React from 'react';
+import { useRouter } from 'next/router';
+import { Callout } from 'nextra/components';
+
+const Beta = () => {
+  const location = useRouter();
+  const isLanding = location.asPath === "/move-registry";
+	return (
+    <>
+		<Callout type="error" emoji="👀">
+			This is a developer preview of the Move Registry. It is experimental and therefore provides no
+			guarantees of uptime or correctness. Use at your own risk.
+		</Callout>
+    { isLanding && 
+      <div className="mt-6">
+        <p className="nx-mt-6 nx-leading-7 first:nx-mt-0">The main point of failure MVR users need to be aware of is the experimental indexer backing the registry. Whether you run your own instance of the MVR indexer or use the Mysten Lab operated public good indexer, there is always risk that the service is not available, so build your application accordingly.</p>
+        <p className="nx-mt-6 nx-leading-7 first:nx-mt-0 hidden">
+        Here's how you (can use a fallback address in your typescript to easily fall back to not using MVR / should structure your application so it's easy to maintain uptime in the face of MVR outage / however else users can de-risk using MVR) 
+        </p>
+      </div> }
+    </>
+	);
+};
+
+export default Beta;

documentation/pages/_meta.json

@@ -4,6 +4,7 @@
     "developer": "Developer",
     "user": "User",
     "node-operator": "Node Operator",
+    "move-registry": "Move Registry (Experimental)",
     "dashboard": {
         "title": "SuiNS Dashboard ↗",
         "type": "page",

documentation/pages/index.mdx

@@ -1,6 +1,3 @@
-import { Tabs } from 'nextra/components'
-import { Callout } from 'nextra/components'
-
 # Sui Name Service Documentation
 
 Sui Name Service (SuiNS) documentation is divided into two main sections: [**User**](./user.mdx) and [**Developer**](./developer.mdx). The **Developer** section provides integration details for adding Sui Name Service (SuiNS) to your projects. The **User** section provides instructions on how to use the SuiNS portal to register names and integrate them with your web3 identity.

documentation/pages/move-registry.mdx

@@ -0,0 +1,32 @@
+# Move Registry
+
+import { Callout } from 'nextra/components'
+import Beta from '../components/beta'
+
+Move Registry (MVR, pronounced "mover") provides a uniform naming service for interacting and building with packages from the Sui ecosystem. This means that you can reference packages by their names, and MVR resolves the package address for you, despite the network.
+
+Use MVR to: 
+
+- Reference both packages and types by name in programmable transaction blocks (PTBs).
+- Depend on other packages when developing with Move.
+
+Additionally, MVR can help you manage package versioning. With MVR, you call a specific version of a package without having to resolve the addresses yourself. You also don't need to worry about the package being updated, because if you use a name without a specified version, MVR automatically defaults to the latest version available.
+
+<Callout type="info" emoji="ℹ️">
+MVR default service currently supports Mainnet and Testnet networks.
+</Callout>
+
+## Development status
+
+<Beta/>
+
+## Source location
+
+The open-source code for MVR is located within both the [Sui](https://github.com/MystenLabs/sui) and [MVR](https://github.com/MystenLabs/mvr) repositories on GitHub. 
+
+- MVR repository houses the [MVR-CLI](https://github.com/MystenLabs/mvr/tree/main/mvr-cli) and [MVR web app](https://github.com/MystenLabs/mvr/tree/main/app) code.
+- Sui repository houses the [MVR plugin for Sui TypeScript SDK](https://github.com/MystenLabs/sui/blob/main/sdk/typescript/src/transactions/plugins/NamedPackagesPlugin.ts) and [MVR GraphQL](https://github.com/MystenLabs/sui/tree/main/crates/sui-graphql-rpc/src/types/move_registry) code.
+
+## MVR web app
+
+You can access the front end of the Move Registry online at https://www.moveregistry.com/apps.

documentation/pages/move-registry/_meta.json

@@ -0,0 +1,7 @@
+{
+    "design": "Design",
+    "managing-package-info": "Managing Package Metadata",
+    "mvr-names": "Managing MVR Names",
+    "maintainer-practices": "Package Maintainer Best Practices",
+    "tooling": "Tooling"
+}

documentation/pages/move-registry/design.mdx

@@ -0,0 +1,48 @@
+import Beta from '../../components/beta'
+import { Callout } from 'nextra/components'
+
+<Beta/>
+
+# Design of the Move Registry
+
+The Move Registry (MVR, pronounced "mover") consists of two independent components:
+
+- `PackageInfo` registration: Exists independently on each network.
+- MVR registration: A single source of truth located on Mainnet.
+
+The following diagram shows the MVR design at a high level.
+
+![High level design](/images/mvr/mvr-overall.svg)
+
+## PackageInfo 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 the MVR search engine can use.
+
+This metadata object can be reused when authorizing any package upgrades to supply source information for the new version. 
+Sui indexers can index the metadata as it cannot be stored within another object.
+
+![Package Info Objects](/images/mvr/mvr-package-info.svg)
+
+See [Managing Package Metadata](./managing-package-info.mdx) for examples of working with `PackageInfo` objects. 
+
+## MVR registration
+
+MVR 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 MVR registers applications that MVR tooling can resolve.
+
+To register a package:
+
+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 the `PackageInfo` object ID, acting as a pointer without ensuring a full mapping.
+
+![Move Registry](/images/mvr/mvr-registry.svg)
+
+<Callout type="info" emoji="ℹ️">
+The registry that stores name resolution for MVR exists only on Mainnet
+</Callout>
+
+See [Managing MVR Names](./mvr-names.mdx) for examples of MVR registration.

documentation/pages/move-registry/maintainer-practices.mdx

@@ -0,0 +1,25 @@
+import Beta from '../../components/beta'
+
+<Beta/>
+
+# Best Practices
+
+For package authors and maintainers, the following best practices are recommended for working with the Move Registry. Following these tips ensures that other builders can use your package as intended.
+
+## Automated Address Management
+
+- Whenever you publish or upgrade a package, use the Sui Automated Address Management feature.
+- After properly configuring your Automated Address Management, commit and [tag](#tagging) your changes to your git repository.
+
+For more information, see [Automated Address Management](https://docs.sui.io/concepts/sui-move-concepts/packages/automated-address-management) in the Sui documentation. 
+
+## Sui dependency
+
+Switch your `Sui` dependency to the correct network you're publishing or upgrading against (for example, `framework/testnet` for Testnet, `framework/mainnet` for Mainnet).
+
+## Tagging
+
+Proper use of tags helps code maintanence.
+
+- Tag your releases with `<network>/<verson>` (for example, `mainnet/v1`). Make sure the commit you push after configuring [Automated Address Management](#automated-address-management) is also tagged, or is part of your `main` branch.
+- After applying a release tag, use the commit SHA or the tag to update the source code origin in the `PackageInfo` object.

documentation/pages/move-registry/managing-package-info.mdx

@@ -0,0 +1,120 @@
+import Beta from '../../components/beta'
+import { Callout } from 'nextra/components';
+
+<Beta/>
+
+# Creating/Maintaining `PackageInfo` object
+
+<Callout type="warning">
+    These examples assume that you use the MVR plugin for the Sui Typescript SDK, as described in the  [`Typescript SDK`](/move-registry/tooling/typescript-sdk) section.
+</Callout>
+
+## Creating a new `PackageInfo` object
+
+You should create a `PackageInfo` object for your package when you first deploy it, once for each network.
+You can then treat the object as the source of truth for metadata of your package.
+
+The following example works for both Mainnet and Testnet.
+
+```typescript
+const transaction = new Transaction();
+// ... (other code, could also include a `transaction.publish()` 
+// call to publish & register in one step.)
+
+/// We pass in our UpgradeCap 
+const packageInfo = transaction.moveCall({
+    target: `@mvr/metadata::package_info::new`,
+    arguments: [transaction.object('<Your UpgradeCap (by value or object id)>')],
+});
+
+// We also need to create the visual representation of our "info" object.
+// You can also call `@mvr/metadata::display::new` instead, 
+// that allows customizing the colors of your metadata object!
+const display = transaction.moveCall({
+    target: `@mvr/metadata::display::default`,
+    arguments: [
+        transaction.pure.string('<Add a name to easily identify your package. This is not your MVR name.>')
+    ],
+});
+
+// Set that display object to our info object.
+transaction.moveCall({
+    target: `@mvr/metadata::package_info::set_display`,
+    arguments: [transaction.object(packageInfo), display],
+});
+
+
+// transfer the `PackageInfo` object to a safe address. 
+transaction.moveCall({
+    target: `@mvr/metadata::package_info::transfer`,
+    arguments: [transaction.object(packageInfo), transaction.pure.address('<Your safe address>')],
+});
+
+// .. you can do any other actions, like setting the source code info, in the same PTB.
+```
+
+## Adding source code information
+
+You can add source code information on your `PackageInfo` object using the following setup.
+
+To update the source for a version, first call 
+`@mvr/metadata::package_info::unset_git_versioning` to remove the existing information.
+
+
+```typescript
+const transaction = new Transaction();
+// adding source code info:
+
+// 1. Create our `GitInfo` object.
+const git = transaction.moveCall({
+    target: `@mvr/metadata::git::new`,
+    arguments: [
+        transaction.pure.string('<Your git repository, e.g. `https://github.com/mystenlabs/mvr`>'),
+        transaction.pure.string('<Your git subdirectory, e.g. `packages/mvr`>'),
+        transaction.pure.string('<Your git commit hash or tag, e.g. `636d22d6bc4195afec9a1c0a8563b61fc813acfc`>'),
+    ],
+});
+
+transaction.moveCall({
+    target: `@mvr/metadata::package_info::set_git_versioning`,
+    arguments: [
+        transaction.object(`<Your PackageInfo object>`),
+        transaction.pure.u64(`<The version number for the given source code (e.g. 1)>`),
+        git,
+    ],
+});
+```
+
+## Removing or updating source code information
+
+```typescript
+const transaction = new Transaction();
+
+transaction.moveCall({
+    target: `@mvr/metadata::package_info::unset_git_versioning`,
+    arguments: [
+        transaction.object(`<Your PackageInfo object>`),
+        transaction.pure.u64(`<The version number for the given source code (e.g. 1)>`),
+    ],
+});
+// .. you could then follow the previous steps to add the new source code info for that version.
+``` 
+
+## Tranferring the `PackageInfo` object
+
+You can transfer the `PackageInfo` object to another address (or object) by the following setup. If you want to 
+build custom access control for your object, you can utilize a transfer to object workflow (see [Transfer to Object](https://docs.sui.io/concepts/transfers/transfer-to-object) on the Sui documentation site for more information).
+
+`PackageInfo` does not allow public transfers, to ensure that the object is always indexable 
+(wrapping could hurt the discoverability of the object).
+
+```typescript
+const transaction = new Transaction();
+
+// transfer the `PackageInfo` object to a safe address. 
+transaction.moveCall({
+    target: `@mvr/metadata::package_info::transfer`,
+    arguments: [transaction.object(packageInfo), transaction.pure.address('<Your safe address>')],
+});
+```
+

documentation/pages/move-registry/mvr-names.mdx

@@ -0,0 +1,88 @@
+import Beta from '../../components/beta'
+import { Callout } from 'nextra/components';
+
+<Beta/>
+
+# Managing MVR names (Mainnet only)
+
+<Callout type="warning">
+    These examples assume that you use the MVR plugin for the Sui Typescript SDK, as described in the  [`Typescript SDK`](/move-registry/tooling/typescript-sdk) section.
+</Callout>
+
+## Creating a new application
+
+To create a new application, you must provide a SuiNS name and a package name, as long as it is not 
+already registered.
+
+```typescript
+const transaction = new Transaction();
+
+const appCap = transaction.moveCall({
+    target: `@mvr/core::move_registry::register`,
+    arguments: [
+        // the registry obj: Can also be resolved as `registry-obj@mvr` from mainnet SuiNS.
+        transaction.object('0x0e5d473a055b6b7d014af557a13ad9075157fdc19b6d51562a18511afd397727'),
+        transaction.object(suinsObjectId),
+        transaction.pure.string(name),
+        transaction.object.clock(),
+    ],
+});
+
+// we can then use the appCap to attach packages directly, or transfer (e.g. to a safe address)
+// and register packages later.
+```
+
+## Attaching a Mainnet package to an application
+
+When attaching a Mainnet package to an application, you must provide the `PackageInfo` object.
+This call is permanent, so after a `PackageInfo` object is attached to an application, it cannot be 
+detached in the future. Consequently, an app is always linked to a specific package.
+
+```typescript
+// we can then use the appCap to attach packages directly, or transfer (e.g. to a safe address)
+// and register packages later.
+
+const transaction = new Transaction();
+
+ transaction.moveCall({
+    target: `@mvr/core::move_registry::assign_package`,
+    arguments: [
+        // the registry obj: Can also be resolved as `registry-obj@mvr` from mainnet SuiNS.
+        transaction.object(`0x0e5d473a055b6b7d014af557a13ad9075157fdc19b6d51562a18511afd397727`),
+        transaction.object('<The AppCap object>'),
+        transaction.object('<The PackageInfo object on mainnet>'),
+    ],
+});
+```
+
+## Attaching a non-Mainnet package to an application
+
+For non-Mainnet networks, you only attach a "pointer" to the package, instead of strict binding (which wouldn't be possible).
+
+<Callout>
+You can always update an external network by first calling `@mvr/core::move_registry::unset_network`, and then calling `@mvr/core::move_registry::set_network` again.
+</Callout>
+
+```typescript
+const transaction = new Transaction();
+
+const appInfo = transaction.moveCall({
+    target: `@mvr/core::app_info::new`,
+    arguments: [
+        transaction.pure.option("address", '<The objectId of the `PackageInfo` object on the external network>'),
+        transaction.pure.option("address", '<The address of the package on the external network>'),
+        transaction.pure.option("address", null),
+    ],
+});
+
+transaction.moveCall({
+    target: `@mvr/core::move_registry::set_network`,
+    arguments: [
+        // the registry obj: Can also be resolved as `registry-obj@mvr` from mainnet SuiNS.
+        transaction.object('0x0e5d473a055b6b7d014af557a13ad9075157fdc19b6d51562a18511afd397727'),
+        transaction.object('<The AppCap object>'),
+        transaction.pure.string("<chain id of the network: use `4c78adac` for testnet>"),
+        appInfo,
+    ],
+});
+```

documentation/pages/move-registry/tooling.mdx

@@ -0,0 +1,15 @@
+import Beta from '../../components/beta'
+import { Callout } from 'nextra/components'
+
+<Beta/>
+
+# Tooling
+
+Two main tools are available for use with the Move Registry (MVR):
+
+- [A plugin](./tooling/typescript-sdk.mdx) for the Sui TypeScript SDK that enables building programmable transaction blocks (PTBs) using MVR names.
+- An [MVR CLI tool](./tooling/mvr-cli.mdx) for Move development.
+
+<Callout type="info" emoji="">
+To learn more about the SDK plugin API, see [Plugins](https://sdk.mystenlabs.com/typescript/plugins) in the Sui TypeScript SDK documentation.
+</Callout>

documentation/pages/move-registry/tooling/_meta.json

@@ -0,0 +1,4 @@
+{
+    "typescript-sdk": "Transaction Plugin for SDK",
+    "mvr-cli": "MVR CLI"
+}