@portal-hq/core
v4.0.3
Published
Portal MPC Support for React Native
Downloads
1,096
Readme
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 apimpc
facilitates the generation, backup, and recovery of MPC walletsprovider
the core Portal provider (EIP-1139 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
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 APIbackupConfig
objectgdrive
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 settingportal.chainId
property
- You can update this property on your
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 futureGatewayConfig
– 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 thekey
is thechainId
as a number and the value is the base url you'd like to use when performing actions on thischainId
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 transactionsmpcEnabled
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
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
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
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.createWallet()
}
backup
Performs the MPC backup process to create the backup shares for the generated MPC wallet.
Example usage
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.backupWallet(BackupMethods.GDrive)
}
recover
Performs the MPC recovery process to generate new signing shares for the MPC wallet.
Example usage
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.recoverWallet(cipherText, BackupMethods.GDrive)
}
provider
The provider
property contains an EIP-1139 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.
Example usage
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.
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 yourPortal
instance to the components in your app
Getters
usePortal
a React hook to use thePortal
instance in any component within thePortalContextProvider
scope (any component being rendered as either a shallow or deep child of thePortalContextProvider
)
For more info on working with React Context, check out the docs.
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
// MyRootComponent.tsx
import { Portal, PortalContextProvider } from '@portal-hq/react-native'
import { useEffect, useState } from 'react'
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.
// 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 sharesAddress
- a type representing Portal Address recordsDapp
- a type representing Portal Dapp records (portal.api.getEnabledDapps()
returnsDapp[]
)PortalOptions
- a type representing the object used to configure thePortal
class on initialization