Add Publish & Custom Genesis REST documentation.

doc/src/build/rest-api.md

@@ -2,9 +2,9 @@
 title: Local REST Server & REST API Quick Start
 ---
 
-Welcome to the Sui REST API quick start. 
+Welcome to the Sui REST API quick start.
 
-This document walks you through setting up your own local Sui REST Server and using the Sui REST API to interact with a local Sui network. This guide is useful for developers interested in Sui network interactions via API. For a similar guide on Sui network interactions via CLI, refer to the [wallet](wallet.md) documentation.  
+This document walks you through setting up your own local Sui REST Server and using the Sui REST API to interact with a local Sui network. This guide is useful for developers interested in Sui network interactions via API. For a similar guide on Sui network interactions via CLI, refer to the [wallet](wallet.md) documentation.
 
 Full [API documentation](https://app.swaggerhub.com/apis/MystenLabs/sui-api) can
 be found on SwaggerHub.
@@ -21,14 +21,14 @@ rest_server
 ```
 You will see output resembling:
 ```
-INFO listening, local_addr: 127.0.0.1:5000
+INFO listening, local_addr: 127.0.0.1:5001
 ```
 
 NOTE: For additional logs, set `RUST_LOG=debug` before invoking `rest_server`
 
 Export a local user variable to store the hardcoded hostname + port that the local REST server starts with to be used when issuing the curl commands that follow.
 ```shell
-export SUI_GATEWAY_HOST=http://127.0.0.1:5000
+export SUI_GATEWAY_HOST=http://127.0.0.1:5001
 ```
 
 To initialize and start the network, you need to invoke the /sui/genesis and /sui/start endpoints as mentioned below.
@@ -48,13 +48,30 @@ The `genesis` command creates Sui's initial state including four authorities and
 each with five gas objects:
 
 ```shell
-curl --location --request POST $SUI_GATEWAY_HOST/sui/genesis | json_pp
+curl --location --request POST $SUI_GATEWAY_HOST/sui/genesis \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "custom": false
+}' | json_pp
 ```
 
 These are Sui [objects](objects.md) used
 to pay for Sui [transactions](transactions.md#transaction-metadata),
 such as object transfers or smart contract (Move) calls.
 
+If you want to use a custom genesis you can learn more in the wallet [docs](wallet.md#customize-genesis).
+
+As per the instructions in the wallet [docs](wallet.md#customize-genesis), `genesis.conf` & `wallet.key` need to be added so you can use the following to create a
+custom genesis.
+
+```shell
+curl --location --request POST $SUI_GATEWAY_HOST/sui/genesis \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "custom": true
+}' | json_pp
+```
+
 ### POST /sui/stop
 
 The `stop` commands kills the authorities and all of the data stored in the network:
@@ -63,12 +80,12 @@ The `stop` commands kills the authorities and all of the data stored in the netw
 curl --location --request POST $SUI_GATEWAY_HOST/sui/stop
 ```
 
-Use this if you want to reset the state of the network without having to kill the 
+Use this if you want to reset the state of the network without having to kill the
 REST server.
 
 ### POST /sui/start
 
-The `start` command starts the Sui network with the genesis configuration specified: 
+The `start` command starts the Sui network with the genesis configuration specified:
 
 ```shell
 curl --location --request POST $SUI_GATEWAY_HOST/sui/start | json_pp
@@ -192,19 +209,19 @@ objects only (including gas objects). Refer to
 more information about a native transfer. Non-coin objects cannot be
 transferred natively and require a [Move call](#post-call).
 
-You should replace `{{owner_address}}` and {{to_address}}' in the
+You should replace `{{owner_address}}` and `{{to_address}}` in the
 command above with an actual address values, for example one obtained
 from [`GET /addresses`](#get-addresses). You should also replace
 `{{coin_object_id}}` and `{{gas_object_id}}` in the command above with
 an actual object ID, for example one obtained from [`GET
 /objects`](#get-objects) (from `objType` in the output of [`GET
-/objects`](#get-objects). You can see that all objects generated
-during genesis are of `Coin/GAS` type). For this call to work, objects
+/objects`](#get-objects). You can see that all gas objects generated
+during genesis are of `Coin/SUI` type). For this call to work, objects
 represented by both `{{coin_object_id}}` and `{{gas_object_id}}` must
 be owned by the address represented by `{{owner_address}}`.
 
 
-#### POST /call
+### POST /call
 
 Execute a Move call transaction by calling the specified function in
 the module of a given package (smart contracts in Sui are written in
@@ -246,7 +263,95 @@ NOTE: A Publish endpoint is in the works, but for now the only way to add a new
 
 To learn more about what `args` are accepted in a Move call, refer to the [SuiJSON](sui-json.md) documentation.
 
-#### POST /sync
+### POST /publish
+
+Publish Move module.
+
+```shell
+curl --location --request POST $SUI_GATEWAY_HOST/publish \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "sender": "{{owner_address}}",
+    "compiledModules": {{vector_of_compiled_modules}},
+    "gasObjectId": "{{gas_object_id}}",
+    "gasBudget": 10000
+}' | json_pp
+```
+
+This endpoint will perform proper verification and linking to make
+sure the package is valid. If some modules have [initializers](move.md#module-initializers), these initializers
+will also be executed in Move (which means new Move objects can be created in
+the process of publishing a Move package). Gas budget is required because of the
+need to execute module initializers.
+
+You should replace `{{owner_address}}` in the
+command above with an actual address value, for example one obtained
+from [`GET /addresses`](#get-addresses). You should also replace `{{gas_object_id}}` in the command above with an actual object ID, for example one obtained from [`GET
+/objects`](#get-objects) (from `objType` in the output of [`GET
+/objects`](#get-objects). You can see that all gas objects generated
+during genesis are of `Coin/SUI` type). For this call to work, `{{gas_object_id}}` must
+be owned by the address represented by `{{owner_address}}`.
+
+To publish a Move module you also need `{{vector_of_compiled_modules}}`. To generate the value of this field you can use the `sui-move` command. The `sui-move` command supports printing the bytecodes as hex with the following option
+
+```
+sui-move --path <move-module-path> build --dump-bytecode-as-hex
+```
+
+You can copy the outputting hex into the REST publish endpoint. i.e.
+
+```
+sui-move --path <insert/some/path/here> build --dump-bytecode-as-hex
+
+["a11ceb0b0400000009010008020814031c3704530a055d7207cf017408c302280aeb02050cf0024200000101010201030000020001040c01000101010c010001030302000005000100000602010000070304000008050100010507010100010a090a0102030b0b0c00020c0d01010801070e0f01000108100101000406050607080806090603070b010108000b02010800070803000107080303070b0101080003070803010b02010800030b0101080005070803010800020b02010900070b01010900010b01010800020900070803010b01010900010608030105020900050303070b01010900070803010b02010900020b0101090005074d414e4147454404436f696e085472616e73666572095478436f6e746578740b5472656173757279436170046275726e04696e6974046d696e740c7472616e736665725f6361700b64756d6d795f6669656c640f6372656174655f63757272656e63790673656e646572087472616e736665720000000000000000000000000000000000000000000000000000000000000000000000000000000200020109010001000001040b010b0038000201000000080b0912000a0038010c010b010b002e11063802020201000001050b010b000b023803020301000001040b000b0138040200"]
+Build Successful
+```
+
+You can copy the outputting hex representation of the compiled Move module into the
+REST publish endpoint.
+
+Below you can see a sample output of [POST /publish](#post-publish). One of the results of executing this command is generation of a package object representing the published Move code. An ID of the package object can be used as an argument for subsequent Move calls to functions defined in this package.
+
+```
+{
+    "certificate": {
+        "signedAuthorities": [
+            "058ca10c6e8b0bd72a122e2519dcb9039b094fe576d4edf79b72778b6f199792",
+            "81696bc8c7926773cc8cde35be765649b5ae4a084aefe9ffe782cba2b38d3a69",
+            "4efce82bd5c51ba2ee680d05bf548ee27b26d8da9f8c30aa5b1bd8a89b61f88a"
+        ]
+    },
+    "publishResults": {
+        "createdObjects": [
+            {
+                "id": "725BD00D0EC86B434D9E88B248D58FA387B08AC9",
+                "obj_type": "0x2::Coin::TreasuryCap<0xf699a118fc809171a994bbfd4c125fb21d6d188b::MANAGED::MANAGED>",
+                "owner": "AddressOwner(k#09818aac3edf9cf9b006b70c36e7241768b26386)",
+                "readonly": "false",
+                "version": "1"
+            }
+        ],
+        "package": {
+            "object_digest": "o#6029610f83b9b73f7412441d9e44435d4c7eedd409c9ab51908270faa6c6df4c",
+            "object_id": "F699A118FC809171A994BBFD4C125FB21D6D188B",
+            "version": 1
+        },
+        "updatedGas": {
+            "id": {
+                "id": {
+                    "id": {
+                        "bytes": "0000000000000000000000000000000000000003"
+                    }
+                },
+                "version": 1
+            },
+            "value": 9999450
+        }
+    }
+}
+```
+
+### POST /sync
 
 Synchronize client state with authorities:
 
@@ -267,7 +372,7 @@ address that is managed by this server. This command has no output.
 
 
 ## Postman setup
-The recommended way to test the Sui REST API is to use Postman. 
+The recommended way to test the Sui REST API is to use Postman.
 
 Postman is an API platform for building and using APIs. Postman provides an alternative solution to accessing APIs over issuing `curl` commands in a terminal. You can use variables rather than copy-pasting addresses and object IDs for each call in a terminal. We have provided a sample Postman runbook for you to use.
 

doc/src/build/wallet.md

@@ -142,7 +142,7 @@ instance (it will not return the command prompt).
 NOTE: For logs, set `RUST_LOG=debug` before invoking `sui start`.
 
 If you see errors when trying to start Sui network, particularly if you made some custom changes
- (e.g, 
+ (e.g,
 [customized wallet configuration](#wallet-configuration)), you should [recreate Sui genesis state](#recreating-genesis).
 
 ## Using the wallet
@@ -183,20 +183,20 @@ wallet --config /path/to/wallet/config/file
 
 The Sui interactive wallet supports the following shell functionality:
 * Command History
-  The `history` command can be used to print the interactive shell's command history; 
-  you can also use Up, Down or Ctrl-P, Ctrl-N to navigate previous or next matches from history. 
+  The `history` command can be used to print the interactive shell's command history;
+  you can also use Up, Down or Ctrl-P, Ctrl-N to navigate previous or next matches from history.
   History search is also supported using Ctrl-R.
 * Tab completion
   Tab completion is supported for all commands using Tab and Ctrl-I keys.
 * Environment variable substitution
-  The wallet shell will substitute inputs prefixed with `$` with environment variables, 
-  you can use the `env` command to print out the entire list of variables and 
-  use `echo` to preview the substitution without invoking any commands.  
+  The wallet shell will substitute inputs prefixed with `$` with environment variables,
+  you can use the `env` command to print out the entire list of variables and
+  use `echo` to preview the substitution without invoking any commands.
 
 ### Command line mode
 
-The wallet can also be used without the interactive shell, which can be useful if 
-you want to pipe the output of the wallet to another application or invoke wallet 
+The wallet can also be used without the interactive shell, which can be useful if
+you want to pipe the output of the wallet to another application or invoke wallet
 commands using scripts.
 
 ```shell
@@ -712,7 +712,7 @@ initializers](move.md#module-initializers) for more details on module
 initializers.
 
 Finally, we  see that the the gas object that was used to pay for
-publishing was updated as well. 
+publishing was updated as well.
 
 ## Customize genesis
 
@@ -770,3 +770,33 @@ pre-populate two gas objects for four newly generated accounts:
   ]
 }
 ```
+
+If you use any custom accounts in `genesis.conf` ensure you have a corresponding private key in
+`wallet.key`. Ensure `wallet.key` is in the working directory of the wallet. If you do not have the private key of the addresses specified you cannot use custom genesis. Never share your private keys, but for the `genesis.conf` example below you can use the following private key
+
+`genesis.conf`
+
+```
+{
+  "authorities": [
+    {},{},{},{}
+  ],
+  "accounts": [
+    {
+      "address": "09818AAC3EDF9CF9B006B70C36E7241768B26386",
+      "gas_objects": [
+        {
+          "object_id": "0000000000000000000000000000000000000003",
+          "gas_value": 10000000
+        }
+      ]
+    }
+  ]
+}
+```
+`wallet.key`
+```
+[
+  "WKk4nT2oyPKbFrFAyepT5wEsummWsA6qdhsqzc6CVC9fvTt3J2u6yy5WuW9B6OU3mkcyPC/4Axstn0BpIhzZNg==",
+]
+```