Deeplinking to mobile app

A deeplink is a specific URL that takes users directly to a specific location or content within a mobile app.It allows you to seamlessly navigate users from a website, email, or another app to a specific section or page within your mobile app.

Supported deeplinks

Currently we support the following deeplinks:

redirecting to a website in explore ex: https://petra.app/explore?link=https://ariesmarkets.xyz (opens in a new tab)
linking to an address to send money to: ex: https://petra.app/receive?address=[0xf2...2502] (opens in a new tab)

Mobile 2 Mobile communication

Moreover your dapp can communicate directly with Petra to do the following:

Connect your dapp: This feature allows the dapp to connect to Petra Wallet. If Petra Wallet, is already connected then it will invoke the redirect link without any further action needed from the user of the petra wallet.

ex: https://petra.app/api/v1/connect?data=connect_data
Disconnect your dapp: This feature allows the dapp to disconnect to Petra Wallet. If Petra Wallet, is already disconnected then it will invoke the redirect link without any further action needed from the user of the petra wallet.

ex: https://petra.app/api/v1/disconnect?data=disconnect_data
Sign and submit transaction: This feature allows you to send a transaction to sign and submit directly to Petra Wallet. If Petra Wallet is not connected, it will prompt the petra user to connect their wallet before signing and submitting transaction.

ex: https://petra.app/api/v1/signAndSubmit?data=sign_and_submit_data

Link Variable Properties:

The data perameter of each endpoint is a json object encoded to base 64 string.

connect_data

Parameters:

Object Preparation:

stringify the connect_data
base64 encode the connect_data

ex:

// before base64 encode
{
    appInfo: {domain: 'example.dapp.com'}, // your-dapp-bundle-identifier
    redirectLink: '<your-dapp-name>://connect',
    dappEncryptionPublicKey: Buffer.from(dappEncryptionPublicKey).toString(
      'hex',
    ),
  };

//after encoding base 64
J3siZG9tYWluIjoiaHR0cHM6Ly9zYWxsZW0uZXhhbXBsZS5kYXBwIiwibmFtZSI6InNhbGxlbS1leGFtcGxlLWRhcHAifScK

disconnect_data

Parameters:

Object Preparation:

stringify the disconnect_data
base64 encode the disconnect_data

ex:

// before base64 encode
{
    appInfo: {domain: 'example.dapp.com'},
    redirectLink: 'example-dapp://connect',
    dappEncryptionPublicKey: Buffer.from(dappEncryptionPublicKey).toString(
      'hex',
    ),
  };

//after encoding base 64
J3siZG9tYWluIjoiaHR0cHM6Ly9zYWxsZW0uZXhhbXBsZS5kYXBwIiwibmFtZSI6InNhbGxlbS1leGFtcGxlLWRhcHAifScK

sign_and_submit_data

Parameters:

Object Preparation:

create a shared key from the dappEncryptionSecretKey and petraEncryptionPublicKey
Use the shared key to encypt the payload Parameter.
convert the encrypted payload to Hex string
stringify the sign_and_submit_data
base64 encode the sign_and_submit_data

ex:

// before base64 encode
{
    appInfo: {domain: 'example.dapp.com'},
    redirectLink: '<your-dapp-name>://signed',
    dappEncryptionPublicKey: Buffer.from(dappEncryptionPublicKey).toString(
      'hex',
    ),
  };

//after encoding base 64
J3siZG9tYWluIjoiaHR0cHM6Ly9zYWxsZW0uZXhhbXBsZS5kYXBwIiwibmFtZSI6InNhbGxlbS1leGFtcGxlLWRhcHAifScK

appInfo

Required Parameters:

domain

ex:

// before base64 encode
{
  domain: 'example.dapp.com',
  name: 'sallem-example-dapp', // (optional)
}

payload

Required Parameters:

arguments: array of arguments
function: string
function type: string
type_arguments: array of argument types

Object Preparation:

stringify the payload base64 encode

ex:

// before base64 encode
{
  arguments: [
    '0xb693adc2b70c693019217e95b539a7a3fdd92a033dc491745c0d3ec464807fb1',
    190,
    61,
    207,
    132,
    132,
  ],
  function:
    '0x481d6509302e3379b9a8cf524da0000feee18f811d1da7e5addc7f64cdaaac60::canvas_token::draw',
  type: 'entry_function_payload',
  type_arguments: [],
}

//after encoding base 64
J3siYXJndW1lbnRzIjpbIjB4YjY5M2FkYzJiNzBjNjkzMDE5MjE3ZTk1YjUzOWE3YTNmZGQ5MmEwMzNkYzQ5MTc0NWMwZDNlYzQ2NDgwN2ZiMSIsMTkwLDYxLDIwNywxMzIsMTMyXSwiZnVuY3Rpb24iOiIweDQ4MWQ2NTA5MzAyZTMzNzliOWE4Y2Y1MjRkYTAwMDBmZWVlMThmODExZDFkYTdlNWFkZGM3ZjY0Y2RhYWFjNjA6OmNhbnZhc190b2tlbjo6ZHJhdyIsInR5cGUiOiJlbnRyeV9mdW5jdGlvbl9wYXlsb2FkIiwidHlwZV9hcmd1bWVudHMiOltdfSc=

dappEncryptionPublicKey

A hex string of a public key of a x25519 keypair.

redirectLink

After the user navigates to the petra app they will be prompted with an approval modal. On response petra will redirect to the redirect link and append the users response to the redirect link.

ex:

if redirect link is https://dapp-example/response?nonce=123 petra will append the redirect link to be https://dapp-example/response?nonce=123&response=[approved|rejected|dismissed].

if redirect link is https://dapp-example/response petra will append the redirect link to be https://dapp-example/response?response=[approved|rejected|dismissed].

Understanding Encryption

Deeplinks are encrypted using symmetric key encryption generated from a Diffie-Hellman key exchange. While deeplink sessions will be created in plaintext, an encrypted channel will be created to prevent session tokens from getting hijacked. Encryption & Decryption Workflow. Diffie-Hellman work flow is made easy by using the TweetNaCl.js (opens in a new tab) library

Overview

The process of mobile 2 mobile communication will be that the dapp and petra app will create there own x25519 keypair. This key pair is a grouping of a public key and secret key. Both keys will be saved on their respective apps. However the public keys will be exchanged. Once either app has the other apps public key it can create a shared key using their secret key and other apps secret key. The shared key will be the same on both apps and will be used to encrypt and decrypt information.

Petra deeplinks are encrypted with the following workflows:

Connect

[dapp]: On the initial connect deeplink, apps should include a dapp_encryption_public_key query parameter. It's recommended to create a new x25519 keypair for every session started with connect. In all methods, the public key for this keypair is referred to as dapp_encryption_public_key.

[Petra]: Upon handling a connect deeplink, Petra will also generate a new x25519 keypair. Petra will return this public key as petra_encryption_public_key in the connect response. Petra will create a secret key using Diffie-Hellman with dapp_encryption_public_key and the private key associated with petra_encryption_public_key. Petra will locally store a mapping of dapp_encryption_public_key to shared secrets for use with decryption in subsequent deeplinks.

[dapp]: Upon receiving the connect response, the dapp should create a shared secret by using Diffie-Hellman with petra_encryption_public_key and the private key associated with dapp_encryption_public_key. This shared secret should then be used to decrypt the data field in the response. If done correctly, the user's public key will be available to share with the dapp inside the data JSON object.

Subsequent Deeplinks

[dapp]: For any subsequent methods (such as SignAndSendTransaction and SignMessage), apps should send a dapp_encryption_public_key (the public key side of the shared secret) used with Petra along with an encrypted payload object.

[Petra]: Upon approval, Petra will encrypt the signed response as a JSON object with the encryption sent as a data= query param.

[dapp]: Upon receiving the deeplink response, apps should decrypt the object in the data= query param to view the signature.

Connecting to Petra Wallet Event Listening