Skip to main content

First dApp

Installation​

Let's get started with your first dApp. You have to install the necessary dependencies.

npm install --save @airgap/beacon-sdk

Setup​

You can then import the beacon-sdk package and create a DAppClient instance. This instance will be used throughout your dApp to interact with the users wallet. Once created, you can send a permission request to prompt the user to connect to his wallet.

Example
import { DAppClient } from "@airgap/beacon-sdk";

const dAppClient = new DAppClient({ name: "Beacon Docs" });

// Listen for all the active account changes
dAppClient.subscribeToEvent(BeaconEvent.ACTIVE_ACCOUNT_SET, (account) => {
  // An active account has been set, update the dApp UI
  console.log(`${BeaconEvent.ACTIVE_ACCOUNT_SET} triggered: `, account);
});

try {
  console.log("Requesting permissions...");
  const permissions = await dAppClient.requestPermissions();
  console.log("Got permissions:", permissions.address);
} catch (error) {
  console.error("Got error:", error);
}
Loading...

After the connection is successfully established and the user has shared his account, the result will be returned.

info

The DAppClient instance should be a singleton. Avoid creating multiple copies of it, which could lead to unexpected behaviour.

Check​

Now let's introduce a check to see if the SDK is already connected to the dApp. This code should be run after the page is loaded to get the users address and show it in your UI. If the following code returns an address, there is no need to send another permission request, unless you want to pair a different account.

Example
import { DAppClient } from "@airgap/beacon-sdk";

const dAppClient = new DAppClient({ name: "Beacon Docs" });

// The following code should always be run during pageload if you want to show if the user is connected.
const activeAccount = await dAppClient.getActiveAccount();
if (activeAccount) {
  // User already has account connected, everything is ready
  // You can now do an operation request, sign request, or send another permission request to switch wallet
  console.log("Already connected:", activeAccount.address);
  return activeAccount;
} else {
  // The user is not connected. A button should be displayed where the user can connect to his wallet.
  console.error("Not connected!");
}
Loading...

The beacon-sdk is now fully set up and ready to receive operation requests.

Operation Request​

This code snippet will construct an Operation request. If the user has already granted permissions and is connected, you can directly send them operation requests for signing. Remember, each operation request should be constructed carefully, considering the specific action you want the user to authorize, like transferring tokens or interacting with a smart contract.

Example
import {
  BeaconEvent,
  DAppClient,
  TezosOperationType,
} from "@airgap/beacon-sdk";

const dAppClient = new DAppClient({ name: "Beacon Docs" });

// Listen for all the active account changes
dAppClient.subscribeToEvent(BeaconEvent.ACTIVE_ACCOUNT_SET, async (account) => {
  // An active account has been set, update the dApp UI
  console.log(`${BeaconEvent.ACTIVE_ACCOUNT_SET} triggered: `, account);

  // At this point we are connected to an account.
  // Let's send a simple transaction to the wallet that sends 1 mutez to ourselves.
  const response = await dAppClient.requestOperation({
    operationDetails: [
      {
        kind: TezosOperationType.TRANSACTION,
        destination: account.address, // Send to ourselves
        amount: "1", // Amount in mutez, the smallest unit in Tezos
      },
    ],
  });

  console.log(response);
});

// Check if we are connected. If not, do a permission request first.
const activeAccount = await dAppClient.getActiveAccount();
if (!activeAccount) {
  await dAppClient.requestPermissions();
}
Loading...

Disconnect​

Please refer to our dedicated page on how to disconnect your dApp based on your needs.

Destroy​

destroy should be implemented to ensure proper lifecycle management of dAppClient.

This function is designed to be called as the final action of dAppClient when it is no longer needed.

The destroy function is used to clean up resources and remove all Beacon values from storage.

Once this function is executed, the current instance of dAppClient becomes unusable.

Example
import { DAppClient } from "@airgap/beacon-sdk";

const dAppClient = new DAppClient({ name: "Beacon Docs" });

dAppClient
  .destroy()
  .then(() => {
    logger.log("Instance destroyed.");
  })
  .catch((err) => logger.log("Error: ", err.message));
Loading...

User Interaction Best Practice​

Take a look a the best practice for recommendations on Beacon user interface components.