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 install --save cosmic-lib
yarn add cosmic-lib
In your script:
const cosmicLib = require("cosmic-lib")
const CosmicLink = cosmicLib.CosmicLink
bower install cosmic-lib
In 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(...)
new CosmicLink(transaction, { network: "public" | "test" | passphrase })
new CosmicLink(xdr, { network: "public" | "test" | passphrase })
new CosmicLink(uri|query)
new CosmicLink(sep7)
cosmicLink.setTxFields(parameters)
cosmicLink.addOperation(name, parameters)
cosmicLink.setOperation(index, name, parameters)
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)
cosmicLink.htmlLink
cosmicLink.uri
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.
cosmicLib.resolve.server("public" | "test" | passphrase)
await cosmicLib.resolve.address("tips*cosmic.link")
await cosmicLib.resolve.account("tips*cosmic.link")
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:
Organization: Cosmic.plus | @GitHub | @NPM |
Follow: Reddit | Medium | Codepen |
Talk: Telegram | Keybase |