Merge pull request #276 from Tonomy-Foundation/feature/252-integratio…

…n-documentation

Feature/252 integration documentation

.vscode/settings.json

@@ -17,5 +17,9 @@
  "jest.jestCommandLine": "npm run test",
  "jest.testExplorer": {
  "enabled": true
+ },
+ "markdownlint.config": {
+ "default": true,
+ "MD033": false
  }
 }

docs/examples.md

@@ -0,0 +1,18 @@
+# Example Applications
+
+Open-source applications that illustrate how to use Tonomy ID.
+
+## Tonomy Demo integration application
+
+A web app that shows how to integrate with Tonomy ID.
+
+- <a href="https://demo.demo.tonomy.foundation" target="_blank">Try me out here</a>
+- <a href="https://github.com/Tonomy-Foundation/Tonomy-App-Websites/tree/master/src/demo" target="_blank">Github code</a>
+
+## Tonomy ID - Demo wallet
+
+Tonomy ID mobile wallet (Android and iOS)
+
+- <a href="https://play.google.com/store/apps/details?id=foundation.tonomy.projects.tonomyiddemo" target="_blank">Try me out here Android</a>
+- <a href="https://testflight.apple.com/join/7Bdd9jdB" target="_blank">Try me out here iOS</a>
+- <a href="https://github.com/Tonomy-Foundation/Tonomy-ID" target="_blank">Github code</a>

docs/guides/deploy-wallet.md

@@ -0,0 +1,38 @@
+# Deploy a web wallet with the Tonomy SDK
+
+The Tonomy SDK powers Tonomy ID to manage users keys. You can use it to create your own wallet (web or mobile) with a fully customized UI to suite your needs.
+
+We suggest one of the following strategies:
+
+## 1. Deploy a web version of the Tonomy ID wallet
+
+Run <a href="https://github.com/Tonomy-Foundation/Tonomy-ID" target="_blank">Tonomy ID</a> and instead of compiling the Android and iOS applications, compile to web instead. Fork the repository to customize the UI.
+
+Please <a href="https://tonomy.io/contact" target="_blank">contact us</a> for assistance in deploying your bespoke solution.
+
+## 2. Install the Tonomy SDK in your project
+
+Install the <a href="https://github.com/Tonomy-Foundation/Tonomy-ID-SDK" target="_blank">Tonomy SDK</a> in your project and manage identities directly.
+
+How to use the SDK as a web wallet:
+
+1. Choose a `KeyManager` class implementation:
+
+ - <a href="https://github.com/Tonomy-Foundation/Tonomy-ID-SDK/blob/master/src/sdk/storage/jsKeyManager.ts" target="_blank">jsKeyManager</a> - for web browsers
+ - <a href="https://github.com/Tonomy-Foundation/Tonomy-ID/blob/development/src/utils/RNKeyManager.ts" target="_blank">RNKeyManager</a> - for React Native mobile apps
+
+2. Choose a `Storage` class implementation:
+
+ - <a href="https://github.com/Tonomy-Foundation/Tonomy-ID-SDK/blob/master/src/sdk/storage/browserStorage.ts" target="_blank">browserStorage</a> - for web browsers
+ - <a href="https://github.com/Tonomy-Foundation/Tonomy-ID/blob/development/src/utils/storage.ts
+" target="_blank">storage</a> - for React Native mobile apps
+
+3. Create a new user. We suggest you familiarize yourself with how this is done by looking at the integration tests by checking the <a href="https://github.com/Tonomy-Foundation/Tonomy-ID-SDK/blob/master/test-integration/helpers/user.ts#L22" target="_blank">User controller</a> test which manages a Tonomy ID account and DID
+
+4. Get the `KeyManager` object from the `User` object
+
+```ts
+const keyManager = user.keyManager;
+```
+
+5. Use the `keyManager` object for signatures. See the <a href="https://github.com/Tonomy-Foundation/Tonomy-ID-SDK/blob/master/src/sdk/storage/keymanager.ts" target="_blank">signData()</a> function in the interface for signing data.

docs/guides/deploy.md

@@ -0,0 +1,80 @@
+# Deploy Tonomy ID
+
+Deployment of the full Tonomy ID involves several integrated services and is **expected to take several hours for someone not familiar with the system**
+
+Please <a href="https://tonomy.io/contact" target="_blank">contact us</a> for assistance in your on-site deployment, or to help run a fully managed service with updates.
+
+## Prerequisites
+
+- Tonomy ID services run exclusively in `Linux`, we recommend Ubuntu 20.04 or 22.04.
+- `npm` with `corepack enabled`, we recommend v18.12.1. Suggested to install with nvm v0.35+
+
+## Services to run Tonomy ID
+
+- Tonomy ID (React Native mobile wallet) - <a href="https://github.com/Tonomy-Foundation/Tonomy-ID" target="_blank">Github source</a>
+- Tonomy Account Website (Reactjs) - <a href="https://github.com/Tonomy-Foundation/Tonomy-App-Websites" target="_blank">Github source</a>
+- Blockchain and `id.tonomy` smart contracts (Antelope protocol) - <a href="https://github.com/Tonomy-Foundation/Tonomy-Contracts" target="_blank">Github source</a>
+- Tonomy Communication (nestjs) - <a href="https://github.com/Tonomy-Foundation/Tonomy-Communication" target="_blank">Github source</a>
+
+## Deployment
+
+### Locally
+
+The easiest way is to use the automated scripts with the <a href="https://github.com/Tonomy-Foundation/Tonomy-ID-Integration" target="_blank">Tonomy-ID-Integration repository</a>
+
+Check the `README.md` for dependencies and instructions.
+
+```bash
+git clone https://github.com/Tonomy-Foundation/Tonomy-ID-Integration
+cd Tonomy-ID-Integration
+./app.sh gitinit
+./app.sh install
+./app.sh init
+./app.sh start
+```
+
+### On-site / cloud
+
+We suggest that you look at the `./app.sh` and `./scripts/helpers.sh` files in the <a href="https://github.com/Tonomy-Foundation/Tonomy-ID-Integration" target="_blank">Tonomy-ID-Integration repository</a> to get an idea of how to run and bootstrap the network.
+
+Read the `README.md` for each of the services before you start!
+
+Then you will need to deploy each service, with configuration so that they connect with each other:
+
+1. Deploy an and initialize an Antelope blockchain - see the <a href="https://docs.eosnetwork.com/docs/latest/node-operation/getting-started/" target="_blank">official Antelope node guide</a>
+
+ - For a production grade network, we suggest 3 nodes if run by the same entity, or 5 nodes if run by separate entities
+ - For maximum scaleability, run using bare-metal servers.
+ - Please <a href="https://tonomy.io/contact" target="_blank">contact us</a> for assistance running a production Antelope network or setting up governance.
+
+2. Create the `id.tonomy` account on the blockchain
+3. Deploy the <a href="https://github.com/Tonomy-Foundation/Tonomy-Contracts/tree/master/contracts/id.tonomy" target="_blank">id.tonomy</a> contract to the `id.tonomy` account on the blockchain
+4. [Register your applications](../../start/register-app) that you wish to connect to Tonomy ID
+5. Configure the software with the `config.json` file in the repository so that they are connected correctly using your domains, and to white-label the applications:
+
+ - Copy the following files and use environment variables to change which configuration file is used
+ - <a href="https://github.com/Tonomy-Foundation/Tonomy-ID/blob/master/src/config/config.json" target="_blank">Tonomy ID config.json</a>
+ - <a href="https://github.com/Tonomy-Foundation/Tonomy-App-Websites/blob/master/src/common/config/config.json" target="_blank">Tonomy App Websites config.json</a>
+ - <a href="https://github.com/Tonomy-Foundation/Tonomy-Communication/blob/master/src/config/config.json" target="_blank">Tonomy Communication config.json</a>
+
+6. Create a new Google Play store and Apple App store listing.
+7. Use <a href="https://expo.dev" target="_blank">Expo</a> or <a href="https://expo.dev/eas" target="_blank">Expo Application Services</a> to build Tonomy ID and submit it to your app store listings.
+8. Deploy <a href="https://github.com/Tonomy-Foundation/Tonomy-App-Websites" target="_blank">Tonomy App Websites</a>
+
+ - You need to use the `accounts.` subdomain to run the Tonomy Accounts website
+ - You need to use the `demo.` subdomain to run the Tonomy Demo website
+
+9. Deploy <a href="https://github.com/Tonomy-Foundation/Tonomy-Communication" target="_blank">Tonomy Communication</a>
+
+#### (Optional) Sign blockchain transactions in your apps
+
+If you want to have your applications sign blockchain transactions, see [Sign a blockchain transaction](../../start/usage/#sign-a-blockchain-transaction) for how to configure your smart contracts.
+
+#### (Optional) Run the [Demo website](../../examples/#tonomy-demo-integration-application)
+
+To run the [Demo website](../../examples/#tonomy-demo-integration-application) in your network follow these extra steps:
+
+1. [Register the application](../../start/register-app) using the domain you wish to run the Demo website from
+2. Deploy the <a href="https://github.com/Tonomy-Foundation/Tonomy-Contracts/tree/master/contracts/eosio.token" target="_blank">eosio.token</a> contract to the `eosio.token` account (or modify the Demo website to connect to a different account)
+3. Call `addperm()` function with the account name of the registered Demo application (Step 1)
+4. Create dummy accounts as shown in the <a href="https://github.com/Tonomy-Foundation/Tonomy-ID-SDK/blob/9061250ffceeddbbbf183a6ea03dfe7d5e1685c0/src/cli/bootstrap/bootstrap.ts#L88" target="_blank">bootstrap script here</a>

docs/index.md

@@ -1,26 +1,13 @@
-# Tonomy SDK
+# Tonomy ID Documentation
 
-The Tonomy SDK manages all the business logic, cryptography and interactions between identities and applications.
+Welcome to the Tonomy developer documentation. Tonomy ID is a self-sovereign identity and single-sign on system with the ability to use end-to-end cryptography in user devices.
 
-## Installation
+Read the White Paper to understand Tonomy ID features and how it works:
 
-```bash
-npm install @tonomy/tonomy-id-sdk
-```
+<a href="https://www.canva.com/design/DAFnktNOWKU/Ps1zXw3XICaEMiB0R4Ghkg/view" target="_blank">**Tonomy ID - White Paper**</a>
 
-## Usage
+## Try it out now
 
-- [Integrate with Tonomy ID](/api): API to manage single sign-on (SSO) and other interactions with Tonomy identities such as signature requests, transactions and messaging for web and mobile apps
-- [Command line interface](/cli): CLI to manage Tonomy Apps for use in SSO
-- [Build apps like Tonomy ID using the SDK](/sdk): SDK for building smart wallet applications like Tonomy ID
+Integrate your existing app in less then 10 minutes. Follow the [Quick start](/start/start) with the Demo network (default).
 
-### Compatibility
-
-The SDK has been tested with nodejs v18.12.1+.
-
-### Demo Applications
-
-Applications that illustrate how to use the SDK:
-
-1. <a href="https://github.com/Tonomy-Foundation/Tonomy-App-Websites/tree/master/src/demo" target="_blank">Tonomy Demo (uses the API)</a>
-2. <a href="https://github.com/Tonomy-Foundation/Tonomy-ID/tree/master" target="_blank">Tonomy ID smart wallet (uses the SDK)</a>
+Check out how it works by using the Demo integration app on the Demo network. <a href="https://demo.demo.tonomy.foundation" target="_blank">Click here</a>

docs/reference/api.md

@@ -0,0 +1,7 @@
+# Application Interface (API)
+
+The API is used by integration applications to do interact with Tonomy ID, such as using the single sign-on (SSO) flow and signing data.
+
+- <a href="https://unpkg.com/@tonomy/tonomy-id-sdk/build/sdk/types/api/externalUser.d.ts" target="_blank">ExternalUser class reference</a>
+
+Try import into <a href="https://insiders.vscode.dev/tsplay" target="_blank">VS Code online Typescript editor</a> for best viewing.