Skip to content

Latest commit

 

History

History
647 lines (451 loc) · 15.2 KB

mod_debot.md

File metadata and controls

647 lines (451 loc) · 15.2 KB

Module debot

UNSTABLE Module for working with debot.

Functions

start – UNSTABLE Starts an instance of debot.

fetch – UNSTABLE Fetches debot from blockchain.

execute – UNSTABLE Executes debot action.

send – UNSTABLE Sends message to Debot.

remove – UNSTABLE Destroys debot handle.

Types

DebotErrorCode

DebotHandle – UNSTABLE Handle of registered in SDK debot

DebotAction – UNSTABLE Describes a debot action in a Debot Context.

ParamsOfStart – UNSTABLE Parameters to start debot.

RegisteredDebot – UNSTABLE Structure for storing debot handle returned from start and fetch functions.

ParamsOfAppDebotBrowser – UNSTABLE Debot Browser callbacks

ResultOfAppDebotBrowser – UNSTABLE Returning values from Debot Browser callbacks.

ParamsOfFetch – UNSTABLE Parameters to fetch debot.

ParamsOfExecute – UNSTABLE Parameters for executing debot action.

ParamsOfSend – UNSTABLE Parameters of send function.

AppDebotBrowser

Functions

start

UNSTABLE Starts an instance of debot.

Downloads debot smart contract from blockchain and switches it to context zero. Returns a debot handle which can be used later in execute function. This function must be used by Debot Browser to start a dialog with debot. While the function is executing, several Browser Callbacks can be called, since the debot tries to display all actions from the context 0 to the user.

Remarks

start is equivalent to fetch + switch to context 0.

type ParamsOfStart = {
    address: string
}

type RegisteredDebot = {
    debot_handle: DebotHandle,
    debot_abi: string
}

function start(
    params: ParamsOfStart,
    obj: AppDebotBrowser,
): Promise<RegisteredDebot>;

Parameters

  • address: string – Debot smart contract address

Result

  • debot_handle: DebotHandle – Debot handle which references an instance of debot engine.
  • debot_abi: string – Debot abi as json string.

fetch

UNSTABLE Fetches debot from blockchain.

Downloads debot smart contract (code and data) from blockchain and creates an instance of Debot Engine for it.

Remarks

It does not switch debot to context 0. Browser Callbacks are not called.

type ParamsOfFetch = {
    address: string
}

type RegisteredDebot = {
    debot_handle: DebotHandle,
    debot_abi: string
}

function fetch(
    params: ParamsOfFetch,
    obj: AppDebotBrowser,
): Promise<RegisteredDebot>;

Parameters

  • address: string – Debot smart contract address

Result

  • debot_handle: DebotHandle – Debot handle which references an instance of debot engine.
  • debot_abi: string – Debot abi as json string.

execute

UNSTABLE Executes debot action.

Calls debot engine referenced by debot handle to execute input action. Calls Debot Browser Callbacks if needed.

Remarks

Chain of actions can be executed if input action generates a list of subactions.

type ParamsOfExecute = {
    debot_handle: DebotHandle,
    action: DebotAction
}

function execute(
    params: ParamsOfExecute,
): Promise<void>;

Parameters

  • debot_handle: DebotHandle – Debot handle which references an instance of debot engine.
  • action: DebotAction – Debot Action that must be executed.

send

UNSTABLE Sends message to Debot.

Used by Debot Browser to send response on Dinterface call or from other Debots.

type ParamsOfSend = {
    debot_handle: DebotHandle,
    message: string
}

function send(
    params: ParamsOfSend,
): Promise<void>;

Parameters

  • debot_handle: DebotHandle – Debot handle which references an instance of debot engine.
  • message: string – BOC of internal message to debot encoded in base64 format.

remove

UNSTABLE Destroys debot handle.

Removes handle from Client Context and drops debot engine referenced by that handle.

type RegisteredDebot = {
    debot_handle: DebotHandle,
    debot_abi: string
}

function remove(
    params: RegisteredDebot,
): Promise<void>;

Parameters

  • debot_handle: DebotHandle – Debot handle which references an instance of debot engine.
  • debot_abi: string – Debot abi as json string.

Types

DebotErrorCode

enum DebotErrorCode {
    DebotStartFailed = 801,
    DebotFetchFailed = 802,
    DebotExecutionFailed = 803,
    DebotInvalidHandle = 804,
    DebotInvalidJsonParams = 805,
    DebotInvalidFunctionId = 806,
    DebotInvalidAbi = 807,
    DebotGetMethodFailed = 808,
    DebotInvalidMsg = 809,
    DebotExternalCallFailed = 810
}

One of the following value:

  • DebotStartFailed = 801
  • DebotFetchFailed = 802
  • DebotExecutionFailed = 803
  • DebotInvalidHandle = 804
  • DebotInvalidJsonParams = 805
  • DebotInvalidFunctionId = 806
  • DebotInvalidAbi = 807
  • DebotGetMethodFailed = 808
  • DebotInvalidMsg = 809
  • DebotExternalCallFailed = 810

DebotHandle

UNSTABLE Handle of registered in SDK debot

type DebotHandle = number

DebotAction

UNSTABLE Describes a debot action in a Debot Context.

type DebotAction = {
    description: string,
    name: string,
    action_type: number,
    to: number,
    attributes: string,
    misc: string
}
  • description: string – A short action description.
    Should be used by Debot Browser as name of menu item.
  • name: string – Depends on action type.
    Can be a debot function name or a print string (for Print Action).
  • action_type: number – Action type.
  • to: number – ID of debot context to switch after action execution.
  • attributes: string – Action attributes.
    In the form of "param=value,flag". attribute example: instant, args, fargs, sign.
  • misc: string – Some internal action data.
    Used by debot only.

ParamsOfStart

UNSTABLE Parameters to start debot.

type ParamsOfStart = {
    address: string
}
  • address: string – Debot smart contract address

RegisteredDebot

UNSTABLE Structure for storing debot handle returned from start and fetch functions.

type RegisteredDebot = {
    debot_handle: DebotHandle,
    debot_abi: string
}
  • debot_handle: DebotHandle – Debot handle which references an instance of debot engine.
  • debot_abi: string – Debot abi as json string.

ParamsOfAppDebotBrowser

UNSTABLE Debot Browser callbacks

Called by debot engine to communicate with debot browser.

type ParamsOfAppDebotBrowser = {
    type: 'Log'
    msg: string
} | {
    type: 'Switch'
    context_id: number
} | {
    type: 'SwitchCompleted'
} | {
    type: 'ShowAction'
    action: DebotAction
} | {
    type: 'Input'
    prompt: string
} | {
    type: 'GetSigningBox'
} | {
    type: 'InvokeDebot'
    debot_addr: string,
    action: DebotAction
} | {
    type: 'Send'
    message: string
}

Depends on value of the type field.

When type is 'Log'

Print message to user.

  • msg: string – A string that must be printed to user.

When type is 'Switch'

Switch debot to another context (menu).

  • context_id: number – Debot context ID to which debot is switched.

When type is 'SwitchCompleted'

Notify browser that all context actions are shown.

When type is 'ShowAction'

Show action to the user. Called after switch for each action in context.

  • action: DebotAction – Debot action that must be shown to user as menu item. At least description property must be shown from [DebotAction] structure.

When type is 'Input'

Request user input.

  • prompt: string – A prompt string that must be printed to user before input request.

When type is 'GetSigningBox'

Get signing box to sign data.

Signing box returned is owned and disposed by debot engine

When type is 'InvokeDebot'

Execute action of another debot.

  • debot_addr: string – Address of debot in blockchain.
  • action: DebotAction – Debot action to execute.

When type is 'Send'

Used by Debot to call DInterface implemented by Debot Browser.

  • message: string – Internal message to DInterface address.
    Message body contains interface function and parameters.

Variant constructors:

function paramsOfAppDebotBrowserLog(msg: string): ParamsOfAppDebotBrowser;
function paramsOfAppDebotBrowserSwitch(context_id: number): ParamsOfAppDebotBrowser;
function paramsOfAppDebotBrowserSwitchCompleted(): ParamsOfAppDebotBrowser;
function paramsOfAppDebotBrowserShowAction(action: DebotAction): ParamsOfAppDebotBrowser;
function paramsOfAppDebotBrowserInput(prompt: string): ParamsOfAppDebotBrowser;
function paramsOfAppDebotBrowserGetSigningBox(): ParamsOfAppDebotBrowser;
function paramsOfAppDebotBrowserInvokeDebot(debot_addr: string, action: DebotAction): ParamsOfAppDebotBrowser;
function paramsOfAppDebotBrowserSend(message: string): ParamsOfAppDebotBrowser;

ResultOfAppDebotBrowser

UNSTABLE Returning values from Debot Browser callbacks.

type ResultOfAppDebotBrowser = {
    type: 'Input'
    value: string
} | {
    type: 'GetSigningBox'
    signing_box: SigningBoxHandle
} | {
    type: 'InvokeDebot'
}

Depends on value of the type field.

When type is 'Input'

Result of user input.

  • value: string – String entered by user.

When type is 'GetSigningBox'

Result of getting signing box.

  • signing_box: SigningBoxHandle – Signing box for signing data requested by debot engine.
    Signing box is owned and disposed by debot engine

When type is 'InvokeDebot'

Result of debot invoking.

Variant constructors:

function resultOfAppDebotBrowserInput(value: string): ResultOfAppDebotBrowser;
function resultOfAppDebotBrowserGetSigningBox(signing_box: SigningBoxHandle): ResultOfAppDebotBrowser;
function resultOfAppDebotBrowserInvokeDebot(): ResultOfAppDebotBrowser;

ParamsOfFetch

UNSTABLE Parameters to fetch debot.

type ParamsOfFetch = {
    address: string
}
  • address: string – Debot smart contract address

ParamsOfExecute

UNSTABLE Parameters for executing debot action.

type ParamsOfExecute = {
    debot_handle: DebotHandle,
    action: DebotAction
}
  • debot_handle: DebotHandle – Debot handle which references an instance of debot engine.
  • action: DebotAction – Debot Action that must be executed.

ParamsOfSend

UNSTABLE Parameters of send function.

type ParamsOfSend = {
    debot_handle: DebotHandle,
    message: string
}
  • debot_handle: DebotHandle – Debot handle which references an instance of debot engine.
  • message: string – BOC of internal message to debot encoded in base64 format.

AppDebotBrowser

type ParamsOfAppDebotBrowserLog = {
    msg: string
}

type ParamsOfAppDebotBrowserSwitch = {
    context_id: number
}

type ParamsOfAppDebotBrowserShowAction = {
    action: DebotAction
}

type ParamsOfAppDebotBrowserInput = {
    prompt: string
}

type ResultOfAppDebotBrowserInput = {
    value: string
}

type ResultOfAppDebotBrowserGetSigningBox = {
    signing_box: SigningBoxHandle
}

type ParamsOfAppDebotBrowserInvokeDebot = {
    debot_addr: string,
    action: DebotAction
}

type ParamsOfAppDebotBrowserSend = {
    message: string
}

export interface AppDebotBrowser {
    log(params: ParamsOfAppDebotBrowserLog): void,
    switch(params: ParamsOfAppDebotBrowserSwitch): void,
    switch_completed(): void,
    show_action(params: ParamsOfAppDebotBrowserShowAction): void,
    input(params: ParamsOfAppDebotBrowserInput): Promise<ResultOfAppDebotBrowserInput>,
    get_signing_box(): Promise<ResultOfAppDebotBrowserGetSigningBox>,
    invoke_debot(params: ParamsOfAppDebotBrowserInvokeDebot): Promise<void>,
    send(params: ParamsOfAppDebotBrowserSend): void,
}

log

Print message to user.

type ParamsOfAppDebotBrowserLog = {
    msg: string
}

function log(
    params: ParamsOfAppDebotBrowserLog,
): Promise<>;

Parameters

  • msg: string – A string that must be printed to user.

switch

Switch debot to another context (menu).

type ParamsOfAppDebotBrowserSwitch = {
    context_id: number
}

function switch(
    params: ParamsOfAppDebotBrowserSwitch,
): Promise<>;

Parameters

  • context_id: number – Debot context ID to which debot is switched.

switch_completed

Notify browser that all context actions are shown.

function switch_completed(): Promise<>;

show_action

Show action to the user. Called after switch for each action in context.

type ParamsOfAppDebotBrowserShowAction = {
    action: DebotAction
}

function show_action(
    params: ParamsOfAppDebotBrowserShowAction,
): Promise<>;

Parameters

  • action: DebotAction – Debot action that must be shown to user as menu item. At least description property must be shown from [DebotAction] structure.

input

Request user input.

type ParamsOfAppDebotBrowserInput = {
    prompt: string
}

type ResultOfAppDebotBrowserInput = {
    value: string
}

function input(
    params: ParamsOfAppDebotBrowserInput,
): Promise<ResultOfAppDebotBrowserInput>;

Parameters

  • prompt: string – A prompt string that must be printed to user before input request.

Result

  • value: string – String entered by user.

get_signing_box

Get signing box to sign data.

Signing box returned is owned and disposed by debot engine

type ResultOfAppDebotBrowserGetSigningBox = {
    signing_box: SigningBoxHandle
}

function get_signing_box(): Promise<ResultOfAppDebotBrowserGetSigningBox>;

Result

  • signing_box: SigningBoxHandle – Signing box for signing data requested by debot engine.
    Signing box is owned and disposed by debot engine

invoke_debot

Execute action of another debot.

type ParamsOfAppDebotBrowserInvokeDebot = {
    debot_addr: string,
    action: DebotAction
}

function invoke_debot(
    params: ParamsOfAppDebotBrowserInvokeDebot,
): Promise<void>;

Parameters

  • debot_addr: string – Address of debot in blockchain.
  • action: DebotAction – Debot action to execute.

send

Used by Debot to call DInterface implemented by Debot Browser.

type ParamsOfAppDebotBrowserSend = {
    message: string
}

function send(
    params: ParamsOfAppDebotBrowserSend,
): Promise<>;

Parameters

  • message: string – Internal message to DInterface address.
    Message body contains interface function and parameters.