Serve Your Own CosmicLink Front-End

Photo by Clark Tibbs

What makes CosmicLink different from most Stellar-related services is that it is an open solution. In other words, instead of jailing users for growth & profit, it gives the keys to everyone. Let’s dig together into one of the greatest feature of such an open system: forks.

Why?

CosmicLinks offers applications to send transaction requests to user wallets, where the transaction can get signed without compromising private keys. The flow is as follows:

User wallet is known:

1. The application passes the transaction request directly to the user wallet.
2. The user signs the request which is then submitted to the network.

User wallet is not known:

1. The application passes the transaction request to a CosmicLink front-end.
2. The CosmicLink front-end passes the transaction request to the user wallet.
3. The user signs the request which is then submitted to the network.

Problems:

• Cosmic.link being the only production-ready service relaying transactions request, it creates a single point of failure.
• Companies such as exchanges may no be willing to depend on external services for sensitive operations.
• Applications using Cosmic.link need the guarantee that they can switch to an alternative in case Cosmic.link goes down or rogue (e.g: tracking users, advertisement, …).

Solution:

Providing an easy way for anyone to host their own CosmicLink front-end.

Cosmic.link has been designed in such a way that this can be achieved in a few clicks − at no cost − by whoever own a GitHub account. Yeah!

Who?

This solution is mainly intended for services that have many users regularly signing transactions, and that need to enforce the highest security standards. Serving your own front-end induce additional friction: Cosmic.link users already set up their public keys & wallets of choice, but will have to do so again when using a front-end served from another domain.

If you expect your users to use the signing interface dozens of times on average, then it may be for you. If you expect them to use it only once or a few times, or if you don’t intend to audit code updates, you better stick with Cosmic.link.

In any case, you are welcome to try the forking process as it is easy, fast and educational. :)

How?

Step 1 − Fork from the parent repository

1. Browse to git.cosmic.plus/https-cosmic-link: this is the repository from which Cosmic.link is served.
2. Click on Fork.
3. Select a location if prompted for one.

Step 2 − Serve your fork on GitHub pages

1. From the forked repository, click on Settings.
2. Scroll down until the GitHub Pages section.
3. Set Source as master branch.
4. Reload the page, and copy the GitHub page address from the same section.

Step 3 − Test your fork

1. Wait a couple of minutes for GitHub to generate the page.

2. Go to the copy/pasted address. (https://${username}.github.io/https-cosmic-link)

1. Check that the page displays & is functional.
2. Append this transaction request to the address and browse: ?type=payment&amount=10&asset=GILS:gils*cosmic.plus&destination=tips*cosmic.link
3. Check that the transaction displays properly.

Step 4 − Link it with your domain

You can link this page with a domain of yours. The instruction bellow works for domain providers supporting CNAME records. If you need a more generic explanation, please see GitHub instructions.

1. Edit the CNAME file at the root of your repository, and set it as the domain of your choice.
2. In the DNS configuration of that domain, add a CNAME record that points to ${username}.github.io.
3. Check that the page is indeed served at your domain. Depending on your configuration, changes make take more or less time to propagate.

The example fork I created while writing this article is available at tifa.cosmic.plus (and will not get updated).

Step 5 − Update your fork

This part is slightly more technical. GitHub doesn’t provide a way to do it, so we’ll go for some command line.

Setup:

# Clone your repository.
git clone https://github.com/${username}/https-cosmic-link
cd https-cosmic-link
# Add parent remote.
git remote add parent https://git.cosmic.plus/https-cosmic-link

Update:

# Pull new commits.
git pull parent master
# Merge new commits.
git merge parent/master
# Push updates to your repository.
git push --follow-tags

Extras

More Testing

1. Go to the Stellar Laboratory transaction editor.
2. Create a transaction.
3. Copy the XDR at the end of the page.
4. Go to the cosmic-lib demo page.
5. Paste the XDR in the dedicated field.
6. Set the page field, under Meta Parameters, to your fork URL (including thehttps:// prefix).
7. Click on Open in side-frame. Enjoy. :)

Federated Server

Setup your federated domain by editing the .well_known/stellar.toml file of your forked repository. Cloudflare users can use this minimalist federated server implementation.

Custom Stylesheet

1. Fork the sources repository from git.cosmic.plus/webapp-cosmic-link.
2. Edit stylesheet sources in the style/ directory.
3. Build the css stylesheet using npm run build-css
4. Copy the stylesheet atweb/index.css into your served repository.

Going Further

The point of this article was to explain how to fork https-cosmic-link, which is the repository from which Cosmic.link is served.

Forkers who want to edit the sources, or to audit updates before serving, have to fork the source repository & build the served repository on their own.

While this is possible to do right now (as of Dec 2019), those sources, as well as the related documentation, are about to get rewritten & the whole code base will be made easier to deal with. I’d advise waiting for Cosmic.link v2 before going through that task.

And yes… this is an announcement. ;)