DeBot Specifications

## Objective

Provide a secure and convenient environment to work with smart contracts:

* emulate calling smart contract functions locally on the client
* debug blockchain transactions
* interact with smart contracts deployed in the blockchain

## Basic terms

* DeBot — a smart contract facilitating conversation-like flow communication with a target smart contract.
* Target smart contract — a smart contract for which DeBot is created. DeBot is an interface to this smart contract.
* DeBot browser — a program that executes DeBot and parses its answer using DeBot protocol.
* DeBot protocol — a set of rules describing the communication between the browser and the DeBot: how to call DeBot functions and how to interpret its answers.

## Architecture

The DeBot platform consists of the following elements:

* DeBot smart contract;
* DeBot browser;
* Target smart contract(s)

One target smart contract can have several DeBots. DeBot is deployed to the blockchain. To run a DeBot it must be downloaded to the client and executed inside the DeBot browser instance.

The main communication unit between the browser and DeBot is Action. When the browser wants to call DeBot it must execute Action. When DeBot returns a result, it is also a set of actions.

Action contains a description, name, type, id, current step and context.

## Description

### Action types

* **run\_action** - tells the browser to receive some data from the user and call DeBot function associated with action.

Contains a user-friendly description to display to user, the name of DeBot function to call, the markup of UI elements that must be rendered by DeBot browser, current action step (if it is a complex action).

For example:
`action {
 description: "enter your name",
 name: "enterName",
 type: "run_action",
 step: 0,
 markup: "{ input: {"name": "inputName", "type": "text" } } "
}`

* **run\_method** - call the get-method of target smart contract.

Contains a name of the get-method to call from the target smart contract along with some instructions on what to do with the call results: print to user or call DeBot function.

* **send\_msg** - send a message to target smart contract.

Contains a message prepared by DeBot which has to be signed and sent to target smart contract.

* **invoke\_debot** - call action from another DeBot.

Contains an address of a target DeBot, name and parameters of the target DeBot action. The browser must download destination DeBot and execute certain action.

Current set of actions is defined by the state of DeBot. Current action set can be retrieved from DeBot by calling its getActions function, and can be verified by calling validateState function of DeBot contract on the blockchain.

### Protocol

#### Start function

The entry point to DeBot is the start function. It is used as a preparation step to correctly generate a set of initial actions. It returns a list of actions to perform before starting communication with the user. After that an action loop is started.

#### Action loop

If DeBot browser has no actions to execute it needs to call DeBot’s getActions function in order to receive current set of actions. Every DeBot action produces a set of zero or more next actions. If the DeBot browser has no actions to execute, it needs to call getActions again.

#### DeBot interface

* start() → Action[]
* getActions() → Action[] - returns the action set of the current DeBot state.
* getToken() → (uint128 balance, string name, string symbol) - returns info about the token if the target smart contract supports a token wallet interface, otherwise throws an exception.
* validateState(Action[] action\_set) - a function that must be called as a real blockchain transaction. Takes an action set that must be executed to achieve the necessary DeBot state. Then that state must be compared to the local DeBot state.
* functions that are associated with actions.

## Proof of State

In one of the embodiments of the current invention, user actions and contract state could be verified. The example below provides a system for a multisignature smart contract DeBot interface and a method for verification of user interaction with said contract.

Browser saves an interaction sequence of local DeBot actions and can at any time verify this sequence by calling the validateState function of the DeBot on the blockchain. User actions validity will therefore be verified by receiving a response from remote DeBot with the result of the actions sequence. Since Data Verification is performed as described below it could be assumed that the user actions that led to the correct DeBot execution have been verified.

## Data Verification

The verification of data an end user gets from a blockchain is done through Merkle proofs and execution of it is performed by a Local Virtual Machine (for example here is a TON Labs implementation of TON Virtual Machine https://github.com/tonlabs/ton-labs-vm).

For that we add serialized BOC (Bag of Calls in TON) into all data records we get on the client.

Here is an example of an Account proof process when it loads in SDK.

1. Deserialize BOC
2. Check JSON correctness with respect to struct from BOC
3. Load shard state root hash
4. Check proof for account in shard state
5. Load block
6. Check proof for shard state in block
7. Load shard
8. Load master chain block
9. Check shard proof (compare hashes in proof and state's merkle update in block)

## MultiSig wallet DeBot

* start function: Generates output action:

`Action {
description: "",
name: "setPendingTransactions",
type: run_method,
context: "getTransactions",
}`

to get a list of pending transactions in the multisig contract and prepare an initial list of actions for user.

* Browser calls getTransactions function of the multisig wallet and then calls debot's setPendingTransactions with a list of pending transactions.
* SetPendingTransactions: Generates a list of actions, e.g.:

`Action {
 description: "Transaction" + transId + " dest:" + dest + "amount:" + amount,
 name: "",
 type: run_action,
 context: "{input: [
 {name: confirm, type: button, run: confirmTransaction},
 {name: details, type: button, run: getTransactionDetails}
]",
}`
saves them to the DeBot state, then returns an empty action list.

* Browser calls getActions function. Debot returns actions rendered like this:

`Hello, dear custodian! You have several pending transactions:
1. Transaction 0x14224214, dest: 0x4234234234235435634654645645646, amount: 10GR
/confirm - to confirm
/details - to see more details about transaction.
2. ......`

`/submit - to create new transaction.
/manage_limits - to veiw/create/delete/confirm limits.
/update - to submit or confirm multisig wallet code update.`

User can choose to either:

* confirm a certain transaction;
* submit a new one;
* move to manage\_limits screen where new actions will be displayed to operate with multisig limits.

## DeBot Notification service

In one of the embodiments of the current invention a Decentralized Notification Service can be established which emits messages while storing their hash.

The message body together with user action and user mobile ID is stored in a smart contract persistent storage. Any oracle that listens to all the messages emitted by such smart contracts, including the messages received from DeBots, will push notifications using the user mobile ID through a centralized mobile notification provider (say Google or Apple).

In the current embodiment the oracle may store a user device token in order to be able to securely send user notifications, yet only smart contract generated messages may be verified by an end user device. The user who receives such notifications on their mobile phone will be able to safely compare its hash with the one found on a blockchain to verify the message indeed contains valid information sent by the smart contract. This way all the messages sent by DeBot could be safely verified by users protecting themselves against phishing attempts. Oracles may not be trusted either.

This solves the 2FA security problem using SMS and other push notifications.

## Links

Debot Specifications

be:Тэхнічныя характарыстыкі DeBot
fr:DeBot Specifications
it:DeBot Specifications
pt:Caraterísticas do DeBot
ru:Технические\_характеристики\_DeBot
uk:Технічні характеристики DeBot