iip-49.md

iip	title	author	discussions-to	status	type	category	created
<to be assigned>	ICON Provider JS API	Fidel (github.com/FidelVe), Ben (github.com/bkbooth), Eric (github.com/han-so1omon)	https://forum.icon.community/t/creating-a-spec-in-the-iip-for-an-icon-provider-js-api-and-bip44-coin-type-and-path-derivation-discussion/2700/21	Draft	Standards Track	IRC	2022-06-04

Simple Summary

An specification to provide consistency across clients and applications in the ICON network for communication between software wallets and web applications.

Abstract

To allow communication between software wallets and web applications is necessary for these software wallets to expose an API via Javascript in the web page. For the wallets and web apps to communicate it is necessary the creation of dispatching and listening events using Javascript in the browser.

Motivation

To ensure seamless user experience and avoid implementation of several API communication protocols in each web application to support several software wallets, it is necessary to implement a standardized protocol for all software wallets and web applications to adhere to.

Specification

The following specification requires that a dispatching and a listening event be created using CustomEvent in the web applications. The type and payload of the events are assigned to the detail field in the CustomEvent.

Data in detail field:

Field	Type	Description
type	string	Predefined type of events
payload	any	Data required for the request or response.

Dispatch Event for Request

const customEvent = new CustomEvent('ICONEX_RELAY_REQUEST', {
	detail: {
		type: '...',
		payload: {...}
	}
});
window.dispatchEvent(customEvent);

Listening Event for Response

const eventHandler = event => {
	const { type, payload } = event.detail;
	switch (type) { ...	}
}
window.addEventListener('ICONEX_RELAY_RESPONSE', eventHandler);

Methods

HAS_ACCOUNT

REQUEST_HAS_ACCOUNT Requests for whether the software wallet has any ICON wallet.

RESPONSE_HAS_ACCOUNT Returns boolean-typed results.

const customEvent = new CustomEvent('ICONEX_RELAY_REQUEST', {
	detail: {
		type: 'REQUEST_HAS_ACCOUNT'
	}
});
window.dispatchEvent(customEvent);

const eventHandler = event => {
	const { type, payload } = event.detail;
	if (type === 'RESPONSE_HAS_ACCOUNT') {
		console.log(payload.hasAccount); // true or false
	}
}
window.addEventListener('ICONEX_RELAY_RESPONSE', eventHandler);

HAS_ADDRESS

REQUEST_HAS_ADDRESS Requests for whether the software wallet has the specified wallet address.

RESPONSE_HAS_ADDRESS Returns boolean-typed results.

const customEvent = new CustomEvent('ICONEX_RELAY_REQUEST', {
	detail: {
		type: 'REQUEST_HAS_ADDRESS',
		payload: 'hx19870922...'
	}
});
window.dispatchEvent(customEvent);

const eventHandler = event => {
	const { type, payload } = detail
	if (type === 'RESPONSE_HAS_ADDRESS') {
		console.log(payload); // true or false
	}
}
window.addEventListener('ICONEX_RELAY_RESPONSE', eventHandler);

ADDRESS

REQUEST_ADDRESS Requests for the address to be used for service.

RESPONSE_ADDRESS Returns the icx address selected by the user.

const customEvent = new CustomEvent('ICONEX_RELAY_REQUEST', {
	detail: {
 		type: 'REQUEST_ADDRESS'
	}
});
window.dispatchEvent(customEvent);

const eventHandler = event => {
	const { type, payload } = detail;
	if (type === 'RESPONSE_ADDRESS') {
		console.log(payload); // e.g., hx19870922...
	}
}
window.addEventListener('ICONEX_RELAY_RESPONSE', eventHandler);

JSON-RPC

REQUEST_JSON-RPC Requests for calling standard ICON JSON-RPC API. (User confirmation is required in some cases.)

RESPONSE_JSON-RPC Returns the JSON-RPC response.

CANCEL_JSON-RPC User canceled the JSON-RPC request.

const customEvent = new CustomEvent('ICONEX_RELAY_REQUEST', {
	detail: {
		type: 'REQUEST_JSON-RPC',
		payload: {
			jsonrpc: "2.0",
			method: "icx_method",
			id: 6339,
			params: {
				from: "hx19870922...",
				...
			}
		}
	}
});
window.dispatchEvent(customEvent);

const eventHandler = event => {
	const { type, payload } = detail;
	if (type === 'RESPONSE_JSON-RPC') {
		console.log(payload); // e.g., {"jsonrpc": "2.0", "id": 6339, "result": { ... }}
	}
	else if (type === 'CANCEL_JSON-RPC') {
		console.error('User canceled JSON-RPC request')
	}
}
window.addEventListener('ICONEX_RELAY_RESPONSE', eventHandler);

SIGNING

REQUEST_SIGNING Request for only signing tx hash. (User confirmation is always required.)

RESPONSE_SIGNING Returns signature.

CANCEL_SIGNING User canceled the signing request.

const customEvent = new CustomEvent('ICONEX_RELAY_REQUEST', {
	detail: {
		type: 'REQUEST_SIGNING',
		payload: {
			from: 'hx19870922...',
			hash: '0x13979...'
		}
	}
});
window.dispatchEvent(customEvent);

const eventHandler = event => {
	const { type, payload } = detail
	if (type === 'RESPONSE_SIGNING') {
		console.log(payload) // e.g., 'q/dVc3qj4En0GN+...'
	}
	else if (type === 'CANCEL_SIGNING') {
		console.error('User canceled signing request')
	}
}
window.addEventListener('ICONEX_RELAY_RESPONSE', eventHandler);

Rationale

Backwards Compatibility

Test Cases

Implementation

Copyright

Copyright and related rights waived via CC0.