@perawallet/connect
Version:
JavaScript SDK for integrating Pera Wallet to web applications.
247 lines (167 loc) • 9.31 kB
Markdown
## @perawallet/connect
JavaScript SDK for integrating [Pera Wallet](https://perawallet.app) to web applications. For more detailed information, please check our [Pera Connect Docs](https://docs.perawallet.app/references/pera-connect/). You may also want to check the [use-wallet](https://github.com/TxnLab/use-wallet). Use-wallet provides an easy way to integrate multiple wallets into your dApp.
[](https://www.npmjs.com/package/@perawallet/connect) [](https://www.npmjs.com/package/@perawallet/connect)
## Getting Started
[Learn how to integrate with your JavaScript application](#guide)
[Learn how to Sign Transactions](#sign-transaction)
[Try it out using CodeSandbox](#example-applications)
## Example Applications
<details>
<summary>Expand details</summary>
- [Using React Hooks](https://codesandbox.io/s/perawallet-connect-react-demo-zlvokc)
- [Using React Hooks with React@18](https://codesandbox.io/s/perawallet-connect-react-18-demo-tig2md)
- [Using Vue3](https://codesandbox.io/s/perawallet-connect-vue3-demo-yiyw4b)
- [Using Svelte](https://codesandbox.io/s/perawallet-connect-svelte-demo-ys1m4x)
- [Using Next.js](https://codesandbox.io/s/perawallet-connect-next-js-demo-ryhbdb)
- [Using Nuxt.js](https://codesandbox.io/s/perawallet-connect-nuxt-js-demo-s65z58)
- [Vanilla JS](https://codesandbox.io/s/perawallet-connect-vanillajs-demo-s5pjeo)
</details>
## Quick Start
Let's start with installing `@perawallet/connect`
```
npm install --save @perawallet/connect
```
```jsx
// Connect handler
peraWallet
.connect()
.then((newAccounts) => {
// Setup the disconnect event listener
peraWallet.connector?.on("disconnect", handleDisconnectWalletClick);
setAccountAddress(newAccounts[0]);
})
.catch((error) => {
// You MUST handle the reject because once the user closes the modal, peraWallet.connect() promise will be rejected.
// For the async/await syntax you MUST use try/catch
if (error?.data?.type !== "CONNECT_MODAL_CLOSED") {
// log the necessary errors
}
});
```
If you don't want the user's account information to be lost by the dApp when the user closes the browser with user’s wallet connected to the dApp, you need to handle the reconnect session status. You can do this in the following way.
```jsx
// On the every page refresh
peraWallet.reconnectSession().then((accounts) => {
// Setup the disconnect event listener
peraWallet.connector?.on("disconnect", handleDisconnectWalletClick);
if (accounts.length) {
setAccountAddress(accounts[0]);
}
});
```
After that you can sign transaction with this way
```jsx
// Single Transaction
try {
const signedTxn = await peraWallet.signTransaction([singleTxnGroups]);
} catch (error) {
console.log("Couldn't sign Opt-in txns", error);
}
```
## Options
| option | default | value | |
| ------------------------ | ------- | ------------------------------------- | -------- |
| `chainId` | `4160` | `416001`, `416002`, `416003` , `4160` | optional |
| `shouldShowSignTxnToast` | `true` | `boolean` | optional |
| `compactMode` | `false` | `boolean` | optional |
#### **`chainId`**
Determines which Algorand network your dApp uses.
**MainNet**: 416001
**TestNet**: 416002
**BetaNet**: 416003
**All Networks**: 4160
#### **`shouldShowSignTxnToast`**
<img width="422" alt="Group 48096937" src="https://user-images.githubusercontent.com/54077855/202682828-9ac57b62-58c1-4a83-af3b-e1b7ffad2d89.png">
It's enabled by default but in some cases, you may not need the toast message (e.g. you already have signing guidance for users). To disable it, use the `shouldShowSignTxnToast` option.
#### **`compactMode`**
It offers a compact UI optimized for smaller screens, with a minimum resolution of 400x400 pixels.
## Methods
#### `PeraWalletConnect.connect(): Promise<string[]>`
Starts the initial connection flow and returns the array of account addresses.
#### `PeraWalletConnect.reconnectSession(): Promise<string[]>`
Reconnects to the wallet if there is any active connection and returns the array of account addresses.
#### `PeraWalletConnect.disconnect(): Promise<void | undefined>`
Disconnects from the wallet and resets the related storage items.
#### `PeraWalletConnect.platform: PeraWalletPlatformType`
Returns the platform of the active session. Possible responses: _`mobile | web | null`_
#### `PeraWalletConnect.isConnected: boolean`
Checks if there's any active session regardless of platform. Possible responses: _`true | false`_
#### `PeraWalletConnect.isPeraDiscoverBrowser: boolean`
Checks if it is on Pera Discover Browser. Possible responses: _`true | false`_
#### `PeraWalletConnect.signTransaction(txGroups: SignerTransaction[][], signerAddress?: string): Promise<Uint8Array[]>`
Starts the sign process and returns the signed transaction in `Uint8Array`
#### `PeraWalletConnect.signData(data: PeraWalletArbitraryData[], signer: string, verifySignature?: boolean): Promise<Uint8Array[]>`
Starts the signing process for arbitrary data signing and returns the signed data in `Uint8Array`. Uses `signBytes` method of `algosdk` behind the scenes. `signer` should be a valid Algorand address that exists in the user's wallet.
**Parameters:**
- `data`: Array of arbitrary data to sign
- `signer`: Algorand address that will sign the data
- `verifySignature` (optional): If `true`, automatically detects if the account is rekeyed (has `authAddr`) and uses the `authAddr` as the signer. After signing, verifies each signature against the original data. Defaults to `false`.
**Note:** When `verifySignature` is `true`, the function will:
1. Fetch account information from the Algorand network
2. Check if the account has an `authAddr` (rekeyed account)
3. Automatically use the `authAddr` as the signer if it exists, otherwise use the provided `signer` address
4. Verify each signature after signing using the `verifySignature` method (see below)
<details>
<summary>See example</summary>
```typescript
// Basic usage
const signedData: Uint8Array[] = await peraWallet.signData([
{
data: new Uint8Array(Buffer.from(`timestamp//${Date.now()}`)),
message: "Timestamp confirmation"
},
{
data: new Uint8Array(Buffer.from(`agent//${navigator.userAgent}`)),
message: "User agent confirmation"
}
], "SAHBJDRHHRR72JHTWSXZR5VHQQUVC7S757TJZI656FWSDO3TZZWV3IGJV4");
// With signature verification (automatically handles rekeyed accounts)
const verifiedSignedData: Uint8Array[] = await peraWallet.signData([
{
data: new Uint8Array(Buffer.from(`timestamp//${Date.now()}`)),
message: "Timestamp confirmation"
}
], "SAHBJDRHHRR72JHTWSXZR5VHQQUVC7S757TJZI656FWSDO3TZZWV3IGJV4", true);
```
</details>
#### `PeraWalletConnect.verifySignature(data: Uint8Array, signature: Uint8Array, signerAddress: string): boolean`
Verifies a signature against the provided data and signer address. This method can be used independently to verify signatures returned from `signData` or other sources. When `signData` is called with `verifySignature: true`, it uses this method internally to verify the signatures.
**Parameters:**
- `data`: The original data that was signed (as `Uint8Array`)
- `signature`: The signature to verify (as `Uint8Array`)
- `signerAddress`: The Algorand address that should have signed the data
**Returns:** `true` if the signature is valid, `false` otherwise.
**Note:** This method automatically prefixes the data with "MX" (bytes `[77, 88]`) before verification to be consistent with `algosdk.verifyBytes` function. This ensures compatibility with Algorand's standard signature verification format. The data passed to this method should be the original data without the "MX" prefix, as the prefix is added internally.
<details>
<summary>See example</summary>
```typescript
// Verify a signature independently
const isValid = peraWallet.verifySignature(
originalData,
signature,
"SAHBJDRHHRR72JHTWSXZR5VHQQUVC7S757TJZI656FWSDO3TZZWV3IGJV4"
);
if (isValid) {
console.log("Signature is valid!");
} else {
console.log("Signature verification failed!");
}
```
</details>
## Customizing Style
You can override the z-index using the `.pera-wallet-modal` class so that the modal does not conflict with another component on your application.
```scss
.pera-wallet-modal {
// The default value of z-index is 10. You can lower and raise it as much as you want.
z-index: 11;
}
```
## Your app name on Pera Wallet
By default, the connect wallet drawer on Pera Wallet gets the app name from `document.title`.
In some cases, you may want to customize it. You can achieve this by adding a meta tag to your HTML between the `head` tag.
```html
<meta name="name" content="My dApp" />
```
## Contributing
All contributions are welcomed! To get more information about the details, please read the [contribution](./CONTRIBUTING.md) guide first.