cosmic-lib / Documentation • Examples • Contributing • Changelog
Readme
cosmic-lib is a JavaScript implementation of the CosmicLink protocol that comes with a few useful additional tools.
(Weekly updates: Reddit, Twitter, Keybase, Telegram)
What are CosmicLinks?
CosmicLinks are normal URL or URI that contains a Stellar transaction encoded in their query. It allows to pass Stellar transaction to any webpage or any software. Here's an example on the https://cosmic.link website:
https://cosmic.link/?payment&amount=100&destination=tips*cosmic.link
CosmicLinks use a simple syntax that allow to write any arbitrary transaction:
It can be used to pass transaction XDR as well:
While the https://cosmic.link website provides a convenient way to share transactions over social medias, emails and static documents, any wallet/service can issue or accept CosmicLinks. One big advantage of using queries is that they can be used to pass transactions without having to rely on any particular service.
This is a generalization of tools like Metamask for Ethereum, as it allows any service to communicate with any (compatible) wallet; And users to sign transactions from any service without ever divulging private keys.
The ultimate goal of the CosmicLink protocol is to enable wallet-less applications for Stellar.
Installation
Node / Yarn
-
NPM:
npm install --save cosmic-lib -
Yarn:
yarn add cosmic-lib
In your script:
const cosmicLib = require("cosmic-lib")
const CosmicLink = cosmicLib.CosmicLinkBower
bower install cosmic-libIn your HTML pages:
<script src="./bower_components/stellar-sdk/stellar-sdk.min.js"></script>
<script src="./bower_components/cosmic-lib/cosmic-lib.js"></script>Web
<script src="https://cdn.cosmic.plus/stellar-sdk"></script>
<script src="https://cdn.cosmic.plus/cosmic-lib@2.x"></script>Note: For production release it is advised to serve your own copy of the libraries.
Basic Usage
Create CosmicLinks
New Transaction
The transaction builder is similar to the one provided by StellarSdk. Additionally, it accepts federated addresses and offer syntactic sugar for memos, dates and assets.
const cosmicLink = new CosmicLink({ network: 'test', memo: 'Demo', maxTime: '2019-01' })
.addOperation('payment', { destination: 'tips*cosmic.link', amount: 10 }) // XLM is implied
.addOperation('changeTrust', { asset: 'CNY:admin*ripplefox.com' }) // Max limit is implied
.addOperation(...)From an Existing Transaction
- From a StellarSdk Transaction:
new CosmicLink(transaction, { network: "public" | "test" | passphrase }) - From an XDR:
new CosmicLink(xdr, { network: "public" | "test" | passphrase }) - From a CosmicLink URI/query:
new CosmicLink(uri|query) - From a SEP-0007 link:
new CosmicLink(sep7)
Edit a CosmicLink
- Change transaction fields:
cosmicLink.setTxFields(parameters) - Add operation:
cosmicLink.addOperation(name, parameters) - Set operation:
cosmicLink.setOperation(index, name, parameters) - Remove operation:
cosmicLink.setOperation(index, null)
Example:
cosmicLink
.setTxFields({ memo: "newMemo", source: null, sequence: null })
.addOperation("manageData", { name: "foo", value: "bar" })
.setOperation(1, "mergeAccount", { destination: "in*tempo.eu.com" })
.setOperation(0, null)Get the Link
- Get the HTML link element:
cosmicLink.htmlLink - Get the URI:
cosmicLink.uri - Get the query:
cosmicLink.query
If your webpage contains an HTML link element with id="cosmiclink", it will
automatically get updated with the latest CosmicLink URI.
Display the Transaction
You'll probably want to load the StyleSheet for cosmic-lib first:
await cosmicLib.load.styles()Then, you can get the HTML description element at: cosmicLink.htmlDescription.
If your webpage contains an HTML element with id="cosmiclink_description",
it will automatically get updated with the latest CosmicLink description.
Formats conversion
console.log(cosmicLink.json)
console.log(cosmicLink.tdesc) // The most convenient format to manipulate transactions
// Lock CosmicLink to a network & a source account to compute its Transaction & XDR.
await cosmicLink.lock()
console.log(cosmicLink.transaction)
console.log(cosmicLink.xdr)
console.log(cosmicLink.sep7)Note: If you parsed CosmicLink from an XDR/Transaction/SEP-0007 link you
don't need to use cosmicLink.lock() for conversion purpose.
Sign & Send the Transaction
// Lock CosmicLink to a network & a source account to fetch signers data.
await cosmicLink.lock()
cosmicLink.sign(...(keypair | preimage))
await cosmicLink.send()Note: the transaction will automatically be transmitted to StellarGuard when relevant.
Global Configuration
/**
* Fallback network for network-less transaction requests.
* @default "public"
*/
cosmicLib.config.network = "test"
/**
* Fallback account for source-less transaction requests.
* @default undefined
*/
cosmicLib.config.source = "tips*cosmic.link" // Undefined by default
/**
* Base URL to use when building CosmicLinks.
* @default "https://cosmic.link/"
*/
cosmicLib.config.page = "https://cosmic.link/"Advanced configuration
Setting the Horizon node for a given network:
cosmicLib.config.setupNetwork("test", "https://horizon.example.org")Adding a custom network:
cosmicLib.config.setupNetwork(
"myCustomNetwork",
"https://horizon.example.org",
"MyCustomPassphrase"
)Other Utilities
cosmic-lib exposes part of its underlying code as additional modules.
Resolve
- Get the Server object for a network
cosmicLib.resolve.server("public" | "test" | passphrase) - Resolve a federated address:
await cosmicLib.resolve.address("tips*cosmic.link") - Resolve an account:
await cosmicLib.resolve.account("tips*cosmic.link") - Resolve transaction signers list:
await cosmicLib.resolve.txSignersList(transaction)
Signers Utils
Extends a StellarSdk Transaction object with convenient multi-signature utilities:
cosmicLib.signersUtils.extends(transaction)
console.log(transaction.signers)
console.log(transaction.signersList)
transaction.hasSigner("GB...DECX")
transaction.hasSigned("GB...DECX")Additional ressources
Documentation
cosmic-lib packs more that showed in this brief presentation. Please take a look at the manual:
- Complete documentation
- Cosmic queries specification
- Cosmic queries cheatsheet
- Emitting CosmicLinks without this library
Related tools
Related articles
- 23 Jan 2018: One Year Later: Walletless Stellar Applications Are Finally Coming
- 26 Jul 2018: Understanding Cosmic Links
- 22 Jan 2018: A standardized way of handling Stellar transactions
Services that uses CosmicLinks
- Equilibre.io portfolio balancer: https://equilibre.io
- The Cosmic.Link website: https://cosmic.link
- Stellar Authenticator: https://stellar-authenticator.org
Links
Organization: Cosmic.plus | @GitHub | @NPM