cosmic-lib - JavaScript library - Alpha release

MisterTicot

Hi all,

I just released the first alpha for cosmic-lib.
The code is at https://github.com/MisterTicot/cosmic-lib
This is a library implementing the cosmic link protocol.
It allows to encode a Stellar transaction as an URL.
Custom URI scheme like "stellar:?payment..." will also be supported.

This library is for any developer who wish to support this protocol. At this time, it allows to parse URL and sign/send the transaction. It also generates an HTML node that describe the transaction and eventual errors. Later I'll implement XDR parsing as well.

This is a testing phase for curious who would like to try the code. There's still a lot to be done and I need to properly document the library and how to use it. It's on my list for the next week.

If you want to try right now, you can simply link the JS file and try to

var cosmicLink = new CosmicLink(URL, defaultPublicKey, defaultNetwork)

HTML node will be at cosmicLink.transactionNode and cosmicLink.statusNode
Signing is cosmicLink.sign(secretSeed)
Sending is cosmicLink.send()

More details are in the library file.

I'm going to release two website based on the library later this day: https://cosmic.link and https://stellar-authenticator.org

MisterTicot

Hi all ?
I hope your week was as good as mine!

cosmic-lib now allow to convert XDR to URL. I still want to implement some additional subtleties, but the tool is here so I pushed the code to the repos. In case you want to try it the coder way, here's what to do:

download the javascript & the css from https://github.com/MisterTicot/cosmic-lib/
link it from your html page
you can create a cosmic link from a XDR this way:

var cosmicLink = new CosmicLink(XDR, [network])

If your page include a div whose id is "CL_transactionNode", it will get populated with transaction description and (unlikely) error reports. The URL can be accessed through the getUri() promise :

cosmicLink.getUri(function(uri){ ... })
// or
cosmicLink.getUri(uri => ...)

I also added a debug page and checked every and each operation and possible field handled by cosmic links. I found my some bugs and got them all fixed. The debug process include take a cosmic link XDR, transform it to URL, then back to XDR and check that both XDR matches. So I'm pretty confident that now all should work as expected - except I need to figure out the standard way to remove a homeDomain field from an account. Anyway, the debug.html page is public and include the semantic of the links for each operation:

https://misterticot.github.io/cosmic-lib/debug.html

Well, that's it for today. I think the changes will propagate to Stellar Authenticator with the next cache update.

Next steps are a bit of code cleaning, refining XDR parsing and work on some way to configure values for thing such as default network/user/webpage. I'd like to have add "sequence" and "network" fields to cosmic link as well.

MisterTicot

Hi ?

This week-end I realized that as the codebase is growing the code looks more and more like a spaghetti plate.
It became tedious to work on it.

I decided to refactor it to use a modern stack made of node.js, webpack, babel & jsdoc. The main point being make the codebase as easy to understand as possible. This means posponing features implementation and beta release but I'm pretty confident that tackling this early will speed-up development on the long term. It's going to be my main task this week.

cosmic-lib have to be auditable, properly documented and properly packaged for various type of uses anyway.

MisterTicot

Hi !

I finally went through the task of rewriting the library in JS6 and setting up a functional development stack for it ?

The source code is now available at https://github.com/MisterTicot/js-cosmic-lib-src and is much more cleaner and commented. I still plan to make a more complete documentation later for beta release.

The building repository is available at https://github.com/MisterTicot/js-cosmic-lib/

The debug page is now at https://misterticot.github.io/js-cosmic-lib/debug.html

I created new repositories as the old cosmic-lib is still in use in Cosmic.Link and Stellar Authenticator. I split them it two so the source code commits are not polluted by build changes.

The next steps will be to integrate the new version of the library with Cosmic.Link and Stellar Authenticator, and to update Stellar Authenticator codebase the same way I just did for cosmic-lib. I'd also like to support direct support for XDR in cosmic links in the form:

https://cosmic.link/?xdr={XDR}

Just for you to know, I'm going to be absent from the 10th to the 20th or so and I won't be available to answer at all during that period.

jed

Hi cool project. you should make sure it is compatible with this: https://github.com/stellar/stellar-protocol/pull/95

dzham

jed

Can you guys please fix the SEP process...

Take a look at how ethereum does it.

github issues

not PRs

They get numbers right away, and people can read them without going through hoops, and they can be discussed

MisterTicot

jed

I'll implement whatever please you but please make my life easy and don't introduce useless semantic changes.

Also I already support 'stellar://' URIs but it is fundamentally insecure and have this as a standard will most likely lead to a big drama.

Edit: I think I've been a bit strong on this assertion. Phishing attacks are clearly easiers with stellar:// scheme though.

MisterTicot

Hi,

I updated the specifications as I released version 0.2.1 of the library.
The methods starting by an asterisk are not implemented yet.

// --- Constructor ---
// new CosmicLink(uri, "[userNetwork]", "[userAddress]")
// new CosmicLink(query, "[userNetwork]", "[userAddress]")
// new CosmicLink(transaction, "[userNetwork]", "[userAddress]", {options...})
// new CosmicLink(xdr, "[userNetwork]", "[userAddress]", {options...})
//
// --- Options for transaction & xdr ---
// stripSource = true   < Don't keep source account when converting to URI
// network = ...        < Specify a network for this transaction
//
// --- Formats (get) ---
// CosmicLink.getUri()          < Return a promise of the URI string
// CosmicLink.getQuery()        < Return a promise of the query string
// CosmicLink.getJson()         < Return a promise of the JSON for CosmicLink
// CosmicLink.getTdesc()        < Return a promise of the transaction descriptor
// CosmicLink.getTransaction()  < Return a promise of the transaction
// CosmicLink.getXdr()          < Return a promise of the transaction's XDR
//
// --- Formats (parse) ---    <<< Update everything on the go >>>
// *CosmicLink.parse          < Same use than constructor. Update the link.
//
// --- Datas ---           <<< Update everything on the go >>>
// CosmicLink.user         < User address
// *CosmicLink.aliases     < Local aliases for public keys
// CosmicLink.network      < Test/Public network
// CosmicLink.server       < The horizon server to use
// CosmicLink.status       < Status of the CosmicLink (valid or specific error)
// CosmicLink.errors       < An array of errors (or undefined if no error)
// CosmicLink.page         < The base URI, without the query
//
// --- Actions ---
// *CosmicLink.resolve()       < Resolve addresses and fetch sequence for offline signing
// CosmicLink.sign("seed")     < Sign the transaction
// CosmicLink.send("[server]") < Send the transaction to the network
//
// --- Tools ---
// *CosmicLink.builder         < Builder akin to StellarSdk.TransactionBuilder
// CosmicLink.onClick.format   < For onClick events on the HTML description
// *CosmicLink.onParse.format  < Trigger when cosmicLink is re-parsed
//
// --- HTML Nodes ---
// CosmicLink.transactionNode  < HTML description of the transaction
// CosmicLink.statusNode       < HTML box for the signing & sending status

MisterTicot

Hi ! ?

I'm doing a partial release along the way so we can all benefit from the recent developments.

cosmic-lib now works properly in server-side node environment. The HTML nodes could not be made available easily, but you can convert/sign/send transactions and use all other features from the library.

I added format handlers that call a callback each time a format gets modified. Stellar Authenticator uses it to update on-the-fly the XDR after it gets signed. You can define them for a particular cosmic Link object or class-wide like:

CosmicLink.addFormatHandler('xdr', event => {
  if (event.error) console.log('Error: ' + event.error.message)
  else console.log(event.value)
})

Now you can also setup the default web page or the network for cosmic links globally:

CosmicLink.page = 'https://mysite.org'
CosmicLink.network = 'test'

I reworked the HTML nodes so that they are generated only on-demand. The main node is now called cosmicLink.htmlNode as it's more meaningful, and it will display automatically in the HTML element whose id is CL_htmlNode if it exist on the current web page.

I implemented some multi-signature support and a way to get source account easily

const signers = await cosmicLink.getSigners()
if (await cosmicLink.hasSigner(publicKey) ...
if (await cosmicLink.hasSigned(publicKey) ...

const account = await cosmicLink.getSourceAccount()

XDR/transaction & XDR queries can now accept the options stripSequence and stripSignatures and the sequence number / signatures are now kept by default.

The debug page have been updated and information is now easier to read: https://cosmic.link/cosmic-lib/debug.html

If you were using cosmicLink.sign() without await or .then, you should now use them as signing is now asynchronous because of the check performed on the account signers object which may not be available immediately, else you may encounter odd behaviors.

My next goal is the implementation of aliases for known addresses and the support of multi-operation transactions with proper multisignature handling; which's quite a challenge if you ask me ?

I leave you with the updated cheat sheet ~ have a good week-end !

// --- Constructor ---
// new CosmicLink(uri, "[userNetwork]", "[userAddress]")
// new CosmicLink(query, "[userNetwork]", "[userAddress]")
// new CosmicLink(transaction, "[userNetwork]", "[userAddress]", {...options})
// new CosmicLink(xdr, "[userNetwork]", "[userAddress]", {...options})
//
// --- Options for transaction & xdr ---
// stripSource = true      < Strip out source account
// stripSequence = true    < Strip out sequence number
// stripSignatures = true  < Strip out signatures
// network = ...           < Specify a network for this transaction (kept in URI after conversion)
//
// --- Edit ---
// CosmicLink.parse(any-format, {...options})
// *CosmicLink.setField(field, value)
// *CosmicLink.addOperation({...params})
// *CosmicLink.changeOperation(index, {...params})
// *CosmicLink.removeOperation(index)
//
// --- Formats (get) ---
// CosmicLink.getUri()          < Return a promise of the URI string
// CosmicLink.getQuery()        < Return a promise of the query string
// CosmicLink.getJson()         < Return stringified JSON of the object
// CosmicLink.getTdesc()        < Return a promise of the transaction descriptor
// CosmicLink.getTransaction()  < Return a promise of the transaction
// CosmicLink.getXdr()          < Return a promise of the transaction's XDR
//
// --- Handlers ---
// CosmicLink.addFormatHandler(format, callback)
// CosmicLink.removeFormatHandler(format, callback)
// callback will receive event = { cosmicLink: ..., value: ..., error: ... }
//
// --- Datas ---           <<< Update everything on the go >>>
// CosmicLink.user         < User address
// *CosmicLink.aliases     < Local aliases for public keys
// CosmicLink.network      < Test/Public network
// CosmicLink.server       < The horizon server to use
// CosmicLink.status       < Status of the CosmicLink (valid or specific error)
// CosmicLink.errors       < An array of errors (or undefined if no error)
// CosmicLink.page         < The base URI, without the query
//
// --- Datas (asynchronous)
// CosmicLink.getSource()         < Transaction source
// CosmicLink.getSourceAccount()  < Transaction source account object
// CosmicLink.getSigners()        < Array of legit signers
//
// --- Tests ---
// CosmicLink.hasSigner(publicKey)   < Test if `publicKey` is a signer for CosmicLink
// CosmicLink.hasSigned(publicKey)   < Test if `publicKey` signature is available
//
// --- Actions ---
// CosmicLink.selectNetwork()  < Select CosmicLink network for Stellar SDK
// CosmicLink.sign(seed)       < Sign the transaction
// CosmicLink.send([server])   < Send the transaction to the network
//
// --- Events ---
// CosmicLink.onClick.type      < For onClick events on the HTML description
//
// --- HTML Nodes ---
// CosmicLink.htmlNode         < HTML element for CosmicLink
// CosmicLink.transactionNode  < HTML description of the transaction
// CosmicLink.signersNode      < HTML element for the signers list
// CosmicLink.statusNode       < HTML element for the transaction status & errors

MisterTicot

Ho and I update my TODO to something less ambitious:

Before beta release (planned for this summer):
* Class-wide configuration and dynamical update for datas
* Support custom aliases for addresses
* Support multi-operation transactions
* Support hash signatures
* Write a demo page & examples

Before stable release (planned for this autumn):
* Have a native english speaker check all the texts
* Support DKIF
* Support SEP-0007
* Implement on-chain signatures & transactions sharing
* Implement better handlers for onclick events
* Implement cosmic link builder
* Extensive documentation for developpers

Later:
* Internationalization support
* First translations
* Implement reverse-address name resolution
* Implement asset verification
* Support Ledger nano S
* Support private networks