# Messages

The messages used in the Beacon communication are defined in the tzip-10 proposal.

Every message contains a unique, random ID that allows use to match request and response. It also contains the ID (public key) of the sender. In the future, this public key can be used to verify the authenticity of a message.

import { BeaconMessageType } from '../..'

export interface BeaconBaseMessage {
  type: BeaconMessageType
  version: string
  id: string // ID of the message. The same ID is used in the request and response
  senderId: string // ID of the sender. This is used to identify the sender of the message. This should be the hash of the public key of the peer.
}

Some of the messages accept a network as input (default is mainnet). This is used to ask for permissions or broadcast a transaction on another network. This can either be a testnet, or a local development setup.

import { NetworkType } from '../..'

export interface Network {
  type: NetworkType
  name?: string
  rpcUrl?: string
}

In total, there are request / response messages defined in the tzip-10 standard.

# Permission

The permission request is always the first request that has to be sent to the wallet. The user will be able to select which of the following permissions he wants to grant the DApp.

export enum PermissionScope {
  SIGN = 'sign', // Allows the DApp to send requests to sign arbitrary payload
  OPERATION_REQUEST = 'operation_request', // Allows the DApp to send requests to sign and broadcast Tezos Operations
  THRESHOLD = 'threshold' // Allows the DApp to sign transactions below a certain threshold. This is currently not fully defined and unused
}

The user will also be able to see some additional information about the requesting DApp.

export interface AppMetadata {
  senderId: string
  name: string
  icon?: string // URL
}

# Request

import {
  BeaconBaseMessage,
  BeaconMessageType,
  PermissionScope,
  AppMetadata,
  Network
} from '../../..'

export interface PermissionRequest extends BeaconBaseMessage {
  type: BeaconMessageType.PermissionRequest
  appMetadata: AppMetadata // Some additional information about the DApp
  network: Network // Network on which the permissions are requested. Only one network can be specified. In case you need permissions on multiple networks, you need to request permissions multiple times
  scopes: PermissionScope[] // The permission scopes that the DApp is asking for
}

# Response

import {
  AppMetadata,
  BeaconBaseMessage,
  BeaconMessageType,
  Network,
  PermissionScope,
  Threshold
} from '../../..'

export interface PermissionResponse extends BeaconBaseMessage {
  type: BeaconMessageType.PermissionResponse
  appMetadata: AppMetadata // Some additional information about the Wallet
  publicKey: string // Public Key, because it can be used to verify signatures
  network: Network // Network on which the permissions have been granted
  scopes: PermissionScope[] // Permissions that have been granted for this specific address / account
  threshold?: Threshold
}

# Errors

NetworkNotSupportedBeaconError

NoAddressBeaconError

UnknownBeaconError

# Operation

After asking for permissions, the user can send an operation request to the wallet. The operation accepts the following object as input

# Request

import { BeaconBaseMessage, BeaconMessageType, Network } from '../../..'
import { PartialTezosOperation } from '../../tezos/PartialTezosOperation'

export interface OperationRequest extends BeaconBaseMessage {
  type: BeaconMessageType.OperationRequest
  network: Network // Network on which the operation will be broadcast
  operationDetails: PartialTezosOperation[] // Partial TezosOperation that may lack certain information like counter and fee. Those will be added by the wallet.
  sourceAddress: string
}

# Response

import { BeaconBaseMessage, BeaconMessageType } from '../../..'

export interface OperationResponse extends BeaconBaseMessage {
  type: BeaconMessageType.OperationResponse
  transactionHash: string // Hash of the broadcast transaction
}

# Errors

BroadcastBeaconError

ParametersInvalidBeaconError

TooManyOperationsBeaconError

UnknownBeaconError

# Sign Payload

# Request

import { BeaconBaseMessage, BeaconMessageType, SigningType } from '../../..'

export interface SignPayloadRequest extends BeaconBaseMessage {
  type: BeaconMessageType.SignPayloadRequest
  signingType: SigningType // How the payload should be signed. If the wallet cannot handle this type, it has to fail and send back an error
  payload: string // The payload that will be signed. Can be any string and does not have to be a valid tezos operation
  sourceAddress: string // The user can specify an address that should be pre-selected in the wallet
}

# Response

import { BeaconBaseMessage, BeaconMessageType, SigningType } from '../../..'

export interface SignPayloadResponse extends BeaconBaseMessage {
  type: BeaconMessageType.SignPayloadResponse
  signingType: SigningType
  signature: string // Signature of the payload
}

# Errors

NoPrivateKeyBeaconError

NotGrantedBeaconError

UnknownBeaconError

# Broadcast

# Request

import { BeaconBaseMessage, BeaconMessageType, Network } from '../../..'

export interface BroadcastRequest extends BeaconBaseMessage {
  type: BeaconMessageType.BroadcastRequest
  network: Network // Network on which the transaction will be broadcast
  signedTransaction: string // Signed transaction that will be broadcast
}

# Response

import { BeaconBaseMessage, BeaconMessageType } from '../../..'

export interface BroadcastResponse extends BeaconBaseMessage {
  type: BeaconMessageType.BroadcastResponse
  transactionHash: string // Hash of the broadcast transaction
}

# Errors

BroadcastBeaconError

TransactionInvalidBeaconError

UnknownBeaconError

Last Updated: 2/3/2021, 5:43:54 PM