@portal-hq/web 0.0.1-beta-1

package/README.md

@@ -0,0 +1,297 @@
+# `Portal`
+
+The `@portal-hq/core` package includes a class constructor for the `Portal` class, a React Context Provider for the `PortalContext`, the `usePortal` hook for use within child components, and some helpful types and enums for working with Portal in your app. These pieces allow you to initialize `Portal` in your app, expose the instance to your component tree, and consume the instance in your child components.
+
+## The Portal Class
+
+The `Portal` class that houses three main sub-classes
+
+- `api` makes requests to the Portal api
+- `mpc` facilitates the generation, backup, and recovery of MPC wallets
+- `provider` the core Portal provider ([EIP-1139](https://eips.ethereum.org/EIPS/eip-1193) compliant)
+
+## Instantiation
+
+When instantiating the `Portal` class, you must provide a `PortalOptions` object. This object is used to initialize all of the sub-classes (and their sub-classes).
+
+### Example instantiation
+
+```typescript
+import { BackupMethods, Portal } from '@portal-hq/core'
+
+const portal = new Portal({
+  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
+  backup: {
+    gdrive: gDriveStorage, // See: @portal-hq/gdrive-storage
+    icloud: iCloudStorage, // See: @portal-hq/icloud-storage
+  },
+  chainId: 1,
+  gatewayConfig: 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
+  isSimulator: DeviceInfo.isEmulator(),
+  keychain: keychain, // See: @portal-hq/keychain
+})
+```
+
+### PortalOptions
+
+The `PortalOptions` object is where you configure your instance of `Portal`. It contains a set of required properties and a set of optional properties.
+
+#### Required properties
+
+- `apiKey` **string** a valid Portal Client API Key created via the [Portal REST API](https://api.portalhq.io/api/clients)
+- `backupConfig` **object**
+  - `gdrive` **Storage** (optional) expects an instance of `@portal-hq/gdrive-storage`
+  - `icloud` **Storage** (optional) expects an instance of `@portal-hq/icloud-storage`
+- `chainId` **number** the ID of the current Ethereum chain you'd like to perform actions on
+  - You can update this property on your `Portal` instance later – if your app requires this – by setting `portal.chainId` property
+- `gatewayConfig` **string** or **GatewayConfig** the base url (including your API key) you'd like us to use for Gateway requests (reading from and writing to chain) _**Note: this will be required in the future**_
+  - `GatewayConfig` – if you don't want to use the same url for all requests, you can instead provide a chain-level config for all Gateway RPC calls this can be passed in as an object with key/value pairs where the `key` is the `chainId` as a number and the value is the base url you'd like to use when performing actions on this `chainId`
+- `isSimulator` **boolean** whether or not you're currently running the app in a simulator (this is required to ensure that keychain storage is configured appropriately for the current device)
+- `keychain` **Keychain** expects an instance of either `@portal-hq/keychain` or `@portal-hq/mobile-key-values`
+
+#### Optional properties
+
+- `autoApprove` **boolean** (default: `false`) whether you'd like the provider to auto-approve transactions
+- `mpcEnabled` **boolean** (default: `true`) whether or not to use MPC
+
+## `api`
+
+The `api` property contains an instance of the `PortalApi` class, which has a number of helper methods to facilitate the retrieval of relevant application data from the Portal REST API.
+
+### Methods
+
+#### `getEnabledDapps`
+
+Fetches a list of allowed dApps based on your dApp settings in the Portal web app.
+
+##### Example usage
+
+```typescript
+const portal = new Portal({
+  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
+  backup: {
+    gdrive: gDriveStorage, // See: @portal-hq/gdrive-storage
+    icloud: iCloudStorage, // See: @portal-hq/icloud-storage
+  },
+  chainId: 1,
+  gatewayConfig: 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
+  isSimulator: DeviceInfo.isEmulator(),,
+  keychain: keychain // See: @portal-hq/keychain
+})
+
+const dapps = await portal.api.getEnabledDapps()
+```
+
+#### `getNetworks`
+
+Fetches a list of supported networks based on your dApp settings in the Portal web app.
+
+##### Example usage
+
+```typescript
+const portal = new Portal({
+  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
+  backup: {
+    gdrive: gDriveStorage, // See: @portal-hq/gdrive-storage
+    icloud: iCloudStorage, // See: @portal-hq/icloud-storage
+  },
+  chainId: 1,
+  gatewayConfig: 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
+  isSimulator: DeviceInfo.isEmulator(),,
+  keychain: keychain // See: @portal-hq/keychain
+})
+
+const networks = await portal.api.getNetworks()
+```
+
+## `mpc`
+
+The `mpc` property contains an instance of the `PortalMpc` class, which has a number of helper methods to facilitate the management of Portal MPC wallets.
+
+### Methods
+
+#### `generate`
+
+Performs the MPC generate process to create an MPC wallet and its signing shares
+
+##### Example usage
+
+```typescript
+const portal = new Portal({
+  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
+  backup: {
+    gdrive: gDriveStorage, // See: @portal-hq/gdrive-storage
+    icloud: iCloudStorage, // See: @portal-hq/icloud-storage
+  },
+  chainId: 1,
+  gatewayConfig: 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
+  isSimulator: DeviceInfo.isEmulator(),,
+  keychain: keychain // See: @portal-hq/keychain
+})
+
+const createWallet = async () => {
+  await portal.mpc.generate()
+}
+```
+
+#### `backup`
+
+Performs the MPC backup process to create the backup shares for the generated MPC wallet.
+
+##### Example usage
+
+```typescript
+const portal = new Portal({
+  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
+  backup: {
+    gdrive: gDriveStorage, // See: @portal-hq/gdrive-storage
+    icloud: iCloudStorage, // See: @portal-hq/icloud-storage
+  },
+  chainId: 1,
+  gatewayConfig: 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
+  isSimulator: DeviceInfo.isEmulator(),,
+  keychain: keychain, // See: @portal-hq/keychain
+})
+
+const backupWallet = async () => {
+  await portal.mpc.backup()
+}
+```
+
+#### `recover`
+
+Performs the MPC recovery process to generate new signing shares for the MPC wallet.
+
+##### Example usage
+
+```typescript
+const portal = new Portal({
+  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
+  backup: {
+    gdrive: gDriveStorage, // See: @portal-hq/gdrive-storage
+    icloud: iCloudStorage, // See: @portal-hq/icloud-storage
+  },
+  chainId: 1,
+  gatewayConfig: 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
+  isSimulator: DeviceInfo.isEmulator(),
+  keychain: keychain, // See: @portal-hq/keychain
+})
+
+const recoverWallet = async () => {
+  await portal.mpc.recover()
+}
+```
+
+## `provider`
+
+The `provider` property contains an [EIP-1139](https://eips.ethereum.org/EIPS/eip-1193) compliant provider.
+
+### Making requests through the provider
+
+In order to perform basic web3 operations, such as `eth_accounts` and `eth_sendTransaction`, you can use the provider's `request` method.
+
+This method conforms to [EIP-1139](https://eips.ethereum.org/EIPS/eip-1193).
+
+#### Example usage
+
+```typescript
+const transaction = {
+  data: '',
+  to: toAddress,
+  value: BigNumber.from('1').toHexString(),
+  gas: '0x6000',
+  from: portal.address, // The address of the current connected wallet
+}
+
+const txHash = await portal.provider.request({
+  method: 'eth_sendTransaction',
+  params: transaction,
+})
+```
+
+_For more information on how to use this provider natively within your React Native app, see the [Provider Docs](LINK_TO_PROVIDER_DOCS)._
+
+## The Portal context
+
+`PortalContext` is used to persist an instance of `Portal` within your application. This allows you to initialize `Portal` once, and easily share this instance between all of the components within a given scope in your app.
+
+The exported members allow for 2 ways to set the `PortalContext` and one way to get the `PortalContext`.
+
+### Setters
+
+You only need to choose one of these when implementing the `PortalContext` in your app.
+
+- `PortalContextProvider` a React Context Provider to provide your `Portal` instance to the components in your app
+
+### Getters
+
+- `usePortal` a React hook to use the `Portal` instance in any component within the `PortalContextProvider` scope (any component being rendered as either a shallow or deep child of the `PortalContextProvider`)
+
+_For more info on working with React Context, [check out the docs](https://reactjs.org/docs/context.html)._
+
+### `PortalContextProvider`
+
+The `PortalContextProvider` allows you to share your instance of the Portal class with all components in your component tree. Providing a `value` prop with your Portal instance and wrapping your components in the `PortalContextProvider` enables this behavior. All children of the `PortalContextProvider` can access the Portal instance using the `usePortal` hook (see below).
+
+_**Note**: The easiest way to ensure you're exposing Portal to all components in your component tree is to use it in your App component_
+
+```tsx
+// MyRootComponent.tsx
+
+import { useEffect, useState } from 'react'
+import { Portal, PortalContextProvider } from '@portal-hq/react-native'
+
+const MyRootComponent = () => {
+  const [portal, setPortal] = useState<Portal>(null)
+
+  useEffect(() => {
+    if (!portal) {
+      setPortal(
+        new Portal({
+          // TODO: Add all of the appropriate config options
+        }),
+      )
+    }
+  }, [portal])
+
+  return (
+    <PortalContextProvider value={portal}>
+      {/* Now all children rendered in this scope will have access to the `Portal` instance via the `usePortal` hook */}
+    </PortalContextProvider>
+  )
+}
+```
+
+### `usePortal`
+
+The `usePortal` hook allows any child in the component tree below a `PortalContextProvider` to access the Portal instance.
+
+```tsx
+// MyChildComponent.tsx
+
+import { usePortal } from '@portal-hq/react-native'
+
+const MyChildComponent = () => {
+  const portal = usePortal()
+
+  // You can now do things with the `Portal` instance directly, such as:
+  // - `await portal.api.getEnabledDapps()`
+  // - `await portal.mpc.generate()`
+  //
+  // For more information on this, please see the `Portal` docs in `src/lib/portal`
+
+  ...
+}
+
+```
+
+## Additional exports
+
+In addition to the `Portal` class and context exports, the `@portal-hq/core` package exports some helpful types and enums for use when building your app.
+
+The additional exports are as follows:
+
+- `BackupMethods` – an enum of supported storage methods for backup MPC key shares
+- `Address` - a type representing Portal Address records
+- `Dapp` - a type representing Portal Dapp records (`portal.api.getEnabledDapps()` returns `Dapp[]`)
+- `PortalOptions` - a type representing the object used to configure the `Portal` class on initialization

package/lib/commonjs/index.js

@@ -0,0 +1,201 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mpc_1 = __importDefault(require("./mpc"));
+const provider_1 = __importDefault(require("./provider"));
+const storage_1 = __importDefault(require("./storage"));
+class Portal {
+    constructor({ 
+    // Required
+    apiKey, gatewayConfig, 
+    // Optional
+    apiHost = 'api.portalhq.io', autoApprove = false, backup = { default: new storage_1.default() }, chainId = 1, mpcHost = 'mpc.portalhq.io', mpcVersion = 'v4', webHost = 'web.portalhq.io', }) {
+        this.ready = false;
+        this.readyCallbacks = [];
+        this.apiHost = apiHost;
+        this.apiKey = apiKey;
+        this.autoApprove = autoApprove;
+        this.backup = backup;
+        this.chainId = chainId;
+        this.gatewayConfig = gatewayConfig;
+        this.mpcHost = mpcHost;
+        this.mpcVersion = mpcVersion;
+        this.rpcUrl = this.getRpcUrl();
+        this.webHost = webHost;
+        console.log(`Backup:`, this.backup);
+        // Portal Instances
+        this.mpc = new mpc_1.default({
+            apiHost: this.apiHost,
+            apiKey: this.apiKey,
+            autoApprove: this.autoApprove,
+            chainId: this.chainId,
+            mpcHost: this.mpcHost,
+            rpcUrl: this.rpcUrl,
+            webHost: this.webHost,
+            portal: this,
+        });
+        this.provider = new provider_1.default({
+            autoApprove: this.autoApprove,
+            mpcHost: this.mpcHost,
+            mpcVersion: this.mpcVersion,
+            portal: this,
+        });
+    }
+    /*****************************
+     * Initialization Methods
+     *****************************/
+    onReady(callback) {
+        if (this.ready) {
+            callback();
+        }
+        else {
+            this.readyCallbacks.push(callback);
+        }
+    }
+    triggerReady() {
+        if (this.ready && this.readyCallbacks.length > 0) {
+            this.readyCallbacks.forEach((callback) => {
+                callback();
+            });
+            this.readyCallbacks = [];
+        }
+    }
+    /*****************************
+     * Wallet Methods
+     *****************************/
+    createWallet() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const address = yield this.mpc.generate({
+                host: this.mpcHost,
+                mpcVersion: this.mpcVersion,
+            });
+            this.address = address;
+            return address;
+        });
+    }
+    backupWallet() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.mpc.backup({
+                host: this.mpcHost,
+                mpcVersion: this.mpcVersion,
+            });
+            return '';
+        });
+    }
+    recoverWallet() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.mpc.recover({
+                host: this.mpcHost,
+                mpcVersion: this.mpcVersion,
+            });
+            return true;
+        });
+    }
+    /****************************
+     * Provider Methods
+     ****************************/
+    ethSendTransaction(transaction) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.provider.request({
+                method: 'eth_sendTransaction',
+                params: transaction,
+            });
+        });
+    }
+    ethSign(message) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.provider.request({
+                method: 'eth_sign',
+                params: [this.address, this.stringToHex(message)],
+            });
+        });
+    }
+    ethSignTransaction(transaction) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.provider.request({
+                method: 'eth_signTransaction',
+                params: transaction,
+            });
+        });
+    }
+    ethSignTypedData(data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.provider.request({
+                method: 'eth_signTypedData',
+                params: [this.address, data],
+            });
+        });
+    }
+    ethSignTypedDataV3(data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.provider.request({
+                method: 'eth_signTypedData_v3',
+                params: [this.address, data],
+            });
+        });
+    }
+    ethSignTypedDataV4(data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.provider.request({
+                method: 'eth_signTypedData_v4',
+                params: [this.address, data],
+            });
+        });
+    }
+    personalSign(message) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.provider.request({
+                method: 'personal_sign',
+                params: [this.stringToHex(message), this.address],
+            });
+        });
+    }
+    /****************************
+     * RPC Methods
+     ****************************/
+    getRpcUrl() {
+        if (typeof this.gatewayConfig === 'string') {
+            // If the gatewayConfig is just a static URL, return that
+            return this.gatewayConfig;
+        }
+        else if (typeof this.gatewayConfig === 'object' &&
+            !this.gatewayConfig.hasOwnProperty(this.chainId)) {
+            // If there's no explicit mapping for the current chainId, error out
+            throw new Error(`[PortalProvider] No RPC endpoint configured for chainId: ${this.chainId}`);
+        }
+        // Get the entry for the current chainId from the gatewayConfig
+        const config = this.gatewayConfig[this.chainId];
+        if (typeof config === 'string') {
+            return config;
+        }
+        // If we got this far, there's no way to support the chain with the current config
+        throw new Error(`[PortalProvider] Could not find a valid gatewayConfig entry for chainId: ${this.chainId}`);
+    }
+    /**************************
+     * RPC Encoding Methods
+     **************************/
+    stringToHex(str) {
+        if (str.startsWith('0x')) {
+            return str;
+        }
+        let hex = '0x';
+        for (let i = 0; i < str.length; i++) {
+            const charCode = str.charCodeAt(i);
+            const hexValue = charCode.toString(16);
+            hex += hexValue.padStart(2, '0'); // Ensure two-digit hex value
+        }
+        return hex;
+    }
+}
+exports.default = Portal;