public testnet instructions (#83)

* public testnet instructions

* wallet id

* document pab-local-cluster

* refine the note

.gitignore

@@ -109,10 +109,8 @@ node.sock
 secrets/*/.gpg-id
 ghcid.txt
 plutus-pab/test-node/testnet/db
+plutus-pab/test-node/testnet/restore-wallet.json
 plutus-pab/test-node/alonzo-purple/db
 # profiling output files
 *.timelog
 *.stacks
-
-# testnet configs
-testnet/

plutus-pab/README.md

@@ -28,6 +28,7 @@ $ nix-build ../default.nix -A plutus-apps.haskell.packages.plutus-pab
 ## PAB Components
 PAB contains several commands and services, which are outlined below.
 
+- [pab-local-cluster](#pab-local-cluster)
 - [psgenerator](#psgenerator)
 - [migrate](#migrate)
 - [all-servers](#all-servers)
@@ -38,6 +39,51 @@ PAB contains several commands and services, which are outlined below.
 - [chain-index](#chain-index)
 - [default-logging-config](#default-logging-config)
 
+
+### pab-local-cluster
+
+#### Description
+
+Can be used to run end-to-end tests using a private local testnet.
+
+#### Example
+
+1. Build necessary components:
+
+```
+> cabal build plutus-pab-local-cluster cardano-node cardano-wallet
+```
+
+2. Get config data:
+
+  Clone <https://github.com/input-output-hk/cardano-wallet/> to $DIR and set the
+  `SHELLEY_TEST_DATA` environment variable:
+
+  ```
+  export SHELLEY_TEST_DATA=$DIR/lib/shelley/test/data/cardano-node-shelley
+  ```
+
+3. Run the local cluster:
+
+```
+> cabal exec plutus-pab-local-cluster
+```
+
+4. Wait until the message `Starting PAB backend server on port 9080` appears.
+
+5. Run the integration test:
+
+```
+curl -H "Content-Type: application/json" -v \
+       -X POST \
+       -d '{"caID":{"tag":"IntegrationTest"},"caWallet":{"getWalletId":"2d4cc31a4b3116ab86bfe529d30d9c362acd0b44"}}' \
+       localhost:9080/api/contract/activate
+```
+
+A couple of log messages appear, the last one should say something like "Tx
+confirmed. Integration test complete."
+
+
 ### psgenerator
 
 ```

plutus-pab/test-node/README.md

@@ -0,0 +1,172 @@
+## Instructions for running a public testnet end-to-end integration test
+
+What follows is a series of steps to demonstrate running an end-to-end
+integration test of the PAB on the public testnet.
+
+#### Process
+
+Assumptions:
+
+- You have the `plutus-apps` repo checked out at `$PLUTUS`
+- You have [jq](https://stedolan.github.io/jq/)
+- You have a few hours to wait for everything to sync (the first time.)
+
+Steps:
+
+You will need ~6 terminals to run all the different components.
+
+
+1. Build all the necessary components:
+
+  ```
+  > cd $PLUTUS
+  > cabal build plutus-pab-examples plutus-chain-index cardano-node cardano-wallet
+  ```
+
+2. Start the testnet node locally:
+
+  ```
+  > cd $PLUTUS/plutus-pab/test-node/
+  > ./start-testnet-node.sh
+  ```
+
+  Note: It's important that this is done from the specific directory, because
+  the config paths are relative.
+
+3. Run the cardano wallet backend:
+
+  ```
+  > cd $PLUTUS/plutus-pab/test-node/
+  > cabal exec -- cardano-wallet serve \
+      --testnet testnet/testnet-byron-genesis.json \
+      --node-socket testnet/node.sock
+  ```
+
+4. Create or restore a public testnet wallet:
+
+  Here you have a few options. You can re-use an existing wallet, or create
+  one.
+
+  **Create a new wallet**
+
+  - Generate a recovery phrase:
+
+  ```
+  > cabal exec -- cardano-wallet recovery-phrase generate
+  ```
+
+  - Save this in a file named `restore-wallet.json` in the `testnet` folder:
+
+  ```
+  > cd $PLUTUS/plutus-pab/test-node/
+  > cat testnet/restore-wallet.json
+  { "name": "PAB testing wallet"
+  , "mnemonic_sentence": ["word1", "word2", ...]
+  , "passphrase": "pab123456789"
+  }
+  ```
+
+  - Load the wallet:
+
+  ```
+  > cd $PLUTUS/plutus-pab/test-node/
+  > curl -H "content-type: application/json" -XPOST \
+    -d @testnet/restore-wallet.json \
+    localhost:8090/v2/wallets
+  ```
+
+  Then, take note of the Wallet ID that is created, and save that:
+
+  ```
+  > export WALLET_ID=...
+  ```
+
+  - Put some tAda in it, by first obtaining an address:
+
+  ```
+  > curl -H "content-type: application/json" \
+      -XGET localhost:8090/v2/wallets/$WALLET_ID/addresses | jq '.'
+  ```
+
+  (Any address will do.)
+
+  - Then, navigate over to the [tesnet
+  faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/) and
+  send it some tAda.
+
+  You can verify that the transfer has taken place by clicking the link the
+  faucet application gives you; you see a transaction like so:
+
+  ![](faucet-example.png)
+
+5. Start the chain index:
+
+  ```
+  > cd $PLUTUS/plutus-pab/test-node/
+  > cabal exec -- plutus-chain-index --config testnet/chain-index-config.json start-index
+  ```
+
+6. Start the PAB:
+
+  If it's the first time your running, you'll need to ask the PAB to make the
+  database:
+
+  ```
+  > cd $PLUTUS/plutus-pab/test-node/
+  > cabal exec -- plutus-pab-examples \
+    --config testnet/pab-config.yml migrate
+  ```
+
+  Then, run the PAB
+
+  ```
+  > cd $PLUTUS/plutus-pab/test-node/
+  > cabal exec -- plutus-pab-examples \
+    --config testnet/pab-config.yml webserver \
+    --passphrase pab123456789
+  ```
+
+7. Wait for all chain clients (`cardano-node`, `cardano-wallet`,
+   `plutus-pab-examples`, `plutus-chain-index`) to fully synchronise with the testnet.
+
+  On my computer, the wallet takes about 1 hour, and the chain index takes
+  about 3 hours.
+
+  You can check what slot it needs to get up to by checking [the testnet
+  explorer](https://explorer.cardano-testnet.iohkdev.io/en); and you can query
+  the status of the chain index like so:
+
+  ```
+  > curl -s localhost:9083/tip | jq '.tipSlot.getSlot'
+  ```
+
+  When it's fully synced the slot should be the same slot that the
+  plutus-pab-examples process last printed to the console. Note that the PAB
+  process will be silent for a while, after the initial log messages, before
+  it starts printing log messages about its sync status. **You _must_ wait**
+  for the PAB to start printing messages like:
+
+  ```
+  ...
+  Current block: 327295. Current slot: 41749136.
+  Current block: 327295. Current slot: 41749150.
+  ```
+
+  before running the next step. (In fact, it's okay not to wait, and it will
+  complete eventually; but if you want to see it live, then wait.)
+
+
+8. **Start the integration test**
+
+  ```
+  > curl -H "Content-Type: application/json" -v -X POST -d \
+    "{\"caID\":{\"tag\":\"IntegrationTest\"},\"caWallet\":{\"getWalletId\":\"$WALLET_ID\"}}" \
+    localhost:9080/api/contract/activate
+  ```
+
+9. Wait for the integration test to finish.
+
+  There will be a message like `"Tx confirmed. Integration test complete."`
+  printed from the console running the pab.
+
+That's it!

plutus-pab/test-node/testnet/chain-index-config.json

@@ -0,0 +1,16 @@
+{
+  "cicSlotConfig": {
+    "scSlotLength": 1000,
+    "scSlotZeroTime": 1591566291000
+  },
+  "cicPort": 9083,
+  "cicSecurityParam": 2160,
+  "cicSocketPath": "testnet/node.sock",
+  "cicDbPath": "/tmp/chain-index.db",
+  "cicNetworkId": {
+    "contents": {
+      "unNetworkMagic": 1097911063
+    },
+    "tag": "Testnet"
+  }
+}

plutus-pab/test-node/testnet/pab-config.yml

@@ -0,0 +1,52 @@
+dbConfig:
+    dbConfigFile: plutus-pab.db
+    dbConfigPoolSize: 20
+
+pabWebserverConfig:
+  baseUrl: http://localhost:9080
+  staticDir: plutus-pab-client/dist
+  permissiveCorsPolicy: False
+  # Optional timeout (in seconds) for calls to endpoints that are not currently
+  # available. If this is not set, calls to unavailable endpoints fail
+  # immediately.
+  endpointTimeout: 5
+
+walletServerConfig:
+  baseUrl: http://localhost:8090
+  wallet:
+    getWallet: 1
+
+nodeServerConfig:
+  mscSocketPath: testnet/node.sock
+  mscBaseUrl: "localhost"
+  mscKeptBlocks: 2160
+  mscNetworkId: "1097911063" # Testnet network ID (main net = empty string)
+  mscSlotConfig:
+    scSlotZeroTime: 1591566291000 # Wednesday, July 29, 2020 21:44:51 - shelley launch time in milliseconds
+    scSlotLength: 1000 # In milliseconds
+  mscFeeConfig:
+    fcConstantFee:
+      getLovelace: 10 # Constant fee per transaction in lovelace
+    fcScriptsFeeFactor: 1.0 # Factor by which to multiply size-dependent scripts fee in lovelace
+  mscInitialTxWallets: []
+  mscNodeMode: AlonzoNode
+
+chainIndexConfig:
+  ciBaseUrl: http://localhost:9083
+  ciWatchedAddresses: []
+
+requestProcessingConfig:
+  requestProcessingInterval: 1
+
+signingProcessConfig:
+  spBaseUrl: http://localhost:9084
+  spWallet:
+    getWallet: 1
+
+metadataServerConfig:
+  mdBaseUrl: http://localhost:9085
+
+# Optional EKG Server Config
+# ----
+# monitoringConfig:
+#   monitoringPort: 9090