cosmic-lib / Documentation • Examples • Contributing • Changelog
cosmic-lib is a JavaScript implementation of the CosmicLink protocol that comes with a few useful additional tools.
(Weekly updates: Reddit, Twitter, Keybase, Telegram)
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.
- NPM:
npm install --save cosmic-lib - Yarn:
yarn add cosmic-lib
In your script:
const cosmicLib = require("cosmic-lib")
const CosmicLink = cosmicLib.CosmicLinkbower 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> <script src="https://cdn.cosmic.plus/stellar-sdk"></script>
<script src="https://cdn.cosmic.plus/[email protected]"></script>Note: For production release it is advised to serve your own copy of the libraries.
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 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)
- 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 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.
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.
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.
// 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.
/**
* 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/"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"
)cosmic-lib exposes part of its underlying code as additional modules.
- 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)
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")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
- 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
- Equilibre.io portfolio balancer: https://equilibre.io
- The Cosmic.Link website: https://cosmic.link
- Stellar Authenticator: https://stellar-authenticator.org
Organization: Cosmic.plus | @GitHub | @NPM