Creating a spec in the IIP for an "ICON Provider JS API" and "BIP44 coin_type and path derivation" (discussion)

ICON-Development Improvement Proposals
1

The following thread is to open a discussion in regards to 2 subjects and to eventually arrive to an agreement in order to propose an IPP (ICON Improvement Proposal) to standardize these subjects.

The subjects to discuss are:

  • the current ICONex Connect which is an event based communication protocol to allow external webpages to communicate with the ICONex Chrome wallet. This protocol was also used by Reliant Node Team in the development of both Hana and MyIconWallet to ensure compatibility.

  • the BIP44 standard in regards to coin_type and derivation paths for ICON.

Background and reasoning behind this post.

Making an standard for an “ICON Provider JS API” (currently the ICONex connect specs) and “BIP44 coin_type and derivation paths” are important to ensure web applications and wallets across the entire ICON ecosystem.

An standardized “ICON Provider JS API” will ensure that all the wallets in the ecosystem implement the same communication protocol, the benefit of this is to allow web app developers to implement 1 communication protocol and have support for several wallets.

Creating an standard for the BIP44 coin_type and derivation paths for ICX wallets will allow for compatibility for wallet generation based on mnemonic seeds across the ICON ecosystem. The benefit of this are the following:

  • Allow backup compatibility between wallets that generate addresses based on mnemonic seeds.
  • Create a seamless user experience in web apps that allow for users to login or sign transactions with ledger devices. To explain this point a bit further, currently to use a ledger device you have to use either ICONex or Hana as middlewares for the ledger device, these wallets will connect to the ledger device, supply a BIP44 derivation path and the ledger device will reply with a public address. If lets say Balanced implements ledger support for its users and supply a different BIP44 derivation path to the ledger device, the wallet addresses that the user will see in Balanced will be different than the wallets that the user will see in ICONex or Hana, even if the ledger device is the same.

here are a couple of links where ive been having these discussions before posting this thread:

https://github.com/icon-project/ledger-app-icx/issues/23
https://github.com/icon-project/devportal/issues/35

EDIT: The following thread has been created to discuss the BIP44 derivation path standard

2 Likes
2

@espanicon Can you please propose an initial specification? It does not have to be correct. We will work through it. Additionally, can you tag some other developers that you would like input from?

3

in the subject of the IIP I think that we should create 2 separate proposals.

One to create the ICON Provider JS API and one for the BIP44 derivation paths for ICON addresses.

I can make an initial specification, for the ICON Provider JS API it would be an initial draft with the current ICONex connect specs as they are right now, but for the BIP44 derivation paths for ICON addresseswe would need to have a discussion on what would the correct path be going forward because right now ledger wallets use one path and Hana is using another path for their own generated wallets.

on the subject of who to tag in this thread I honestly dont know anyone outside Ben from @ReliantNode that has actually worked in subjects like these.

4

ICON Provider JS API

The following is a proposal to create an ICON Provider JS API specification to provide consistency across clients and applications in the ICON network.

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.

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.

API

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);
5

Can you please edit the API post to lay out the possible types of interactions that a developer would want for the user to have access to? This will help inform other viewers of the specification as to whether all of those interactions are accomplished and whether that list of interaction types is the correct list to pursue

6

@espanicon I would additionally recommend to move the discussion about creating a ICON Provider JS API into a Github Issue as soon as tomorrow because you have already created the proposed specification

7

for this I would like to wait and read the recommendation of other developers in this subject, specially those that have already created web apps and wallets and have a better idea of what type of interactions will be needed in this specifications.

If you dont have any issue I think that it would be best to wait a few days to allow other developers in the community to give their input in this matter, this can allow us to create a more functional and better detailed specification.

8

That’s fine with me. Note that these discussions may also take place on the Github (e.g. here), which can potentially make it easier to link to specifics of the proposal as well as the updates made to the proposal during discussion

9

Sorry I was confused, I understand now that you want for this discussion to be done in a github issue to better track the progress.

Im going to open an issue and continue the discussion there.

10

Please link the issue here. As well as any pull request that you may make with the proposed specification

11

I see that in the template for the issues there is a “label” category, is there a list of predefined labels to be used? what label do you recommend for this specific proposal?

since I dont know the internal process in which the foundation works for this type of proposals If you can give me some pointers on how should I fill the header section i would appreciate it, for example

iip: 16
title: ICON Security Token Standard
author: Patrick Park (@cordiallys)
discussions-to: https://github.com/icon-project/IIPs/issues/16
status: Draft
type: Standards Track
category: IRC
created: 2019-01-21

Or you can open the issue if you prefer.

1 Like
12

I’m making an updated template for this. I would recommend to discuss here in the meantime. Taking inspiration from Ethereum Magicians on this. I would also recommend splitting the BIP44 discussion into a different topic. I’ll let you know once the updated template is pushed through, and then you can use that

13

I’m going to copy some of my thoughts for extending the spec from Discord into here. For now I think we should just formalise the spec that everyone is already using.

  • Should there be an error response, or a CANCEL_ADDRESS response if the user rejects the REQUEST_ADDRESS request? At the moment I’m assuming dApp developers just have to guess after a timeout that the user rejected it.

  • Should there be a concept of an active/current network like Ethereum providers/dApps. At the moment Hana could be connected to no ICON network (ICON chain disabled, or user has selected a testnet from a different chain), or it could be connected to ICON mainnet, or one of the testnets. But there’s no way to communicate this with dApps, and no way for dApps to communicate which network they’re trying to use. A suite of REQUEST_NETWORK, REQUEST_ADD_NETWORK and REQUEST_SWITCH_NETWORK messages/responses might be useful?

  • Should there be a suite of messages that the provider/Hana can send to dApps without getting a request first? E.g. if user revokes dApp permission, if user changes active wallet/address, if user disables ICON chain or changes network

1 Like
14

do you think we should change the CustomEvent name from ICONEX_RELAY_REQUEST to ICON_RELAY_REQUEST?

I think it would be a more general and appropriate name but it will add unnecessary work to the current wallets and web apps.

15

Yeah, I go back and forth on it. I do think it’s a good idea, just not sure if it’s worth the churn in the ICON dApp ecosystem.

If we wanted to do this, we could make it so that Hana supports both, and put a console warning that ICONEX_RELAY_REQUEST is deprecated (similar to what MetaMask does with deprecated messages). I’m sure other wallets would follow suit, especially if there’s a clear spec in place to reference.

That said I don’t think ICONex is being actively maintained, so it’s likely that it would never be updated, so there might not be much incentive for dApp developers to make the change. I’m not sure how many users ICONex still has.

16

@espanicon @bb_reliantnode Linking the forum post about the updated IIP process here for convenience

Forum post

17

my impression with ICONex is that is not being actively developed in terms of having a team behind it constantly creating new features, but the repo can still receive pull request and get updates like this.

If we create a spec with a new CustomEvent name, the necessary change in the code is minimal for ICONex, and I (or anyone) can make the change and propose it in a pull request, the only thing that will be missing is to build the dapp and upload and update in the chrome webstore, so it will be good if we have a confirmation from the ICONex repository collaborators that if we implement this change and then make a pull request they will continue follow with the build and update steps.

@errcsool is it possible to contact the person in charge of the ICONex repo and have a confirmation that this is possible or not?

18

Sure, that might be Jinwoo from IconLoop. Looks like they are the one merging a lot of the Pull Requests

Edit: I’ve reached out to IconLoop team to confirm who is in charge of that project and will get back to you with the response

19

Just found out that a similar standard already exist but for communicating with ICONex in mobile (IIP-14)

now im wondering if we should expand the IIP-14 to also detail the communication protocol for web or we should create a separate IIP for this.

20

@espanicon Sorry for the delay. I was at a conference last week with the rest of the Icon Foundation team. Separate standard is better for sure