CosmicLink

CosmicLink

Formats Data Actions Editor HTML
--------------------- --------------------- --------------------- --------------------- ---------------------
uri page open parse htmlDescription
query network lock async setTxFields htmlLink
tdesc horizon sign addOperation
json callback send async setOperation
transaction source signSep7 insertOperation
xdr status verifySep7 async
sep7 errors
locker
cache
extra

The CosmicLink class represents Stellar transactions encoded in various formats. It allows to convert between those formats, to edit the underlying transaction, to build it, to sign it and to send it to the blockchain.

There are 3 main formats from which the other are derived:

  • The StellarSdk Transaction} object. (transaction)
  • The CosmicLink, which is a transaction encoded as a query. (query)
  • The Tdesc, which is an internal JSON-compatible format in-between those two. It is the easier format to work with. (tdesc)

Those formats can be derived into other related formats:

  • The XDR, which's a base64 representation of StellarSdk Transaction. (xdr)
  • The Sep-0007 link, in its XDR form. (sep7)
  • The CosmicLink URL/URI, which is a page plus the query. (uri)
  • The Tdesc JSON, which is its stringified version. (json)

A CosmicLink object can be created from any of those formats. Some of the other formats are immediately available, while others may need an await cosmicLink.lock() operation to become computable:

  • If you create a CosmicLink from an uri, a query, a tdesc or a json, only those 4 formats are available at first. Transaction, xdr & sep7 will become available after a cosmicLink.lock(). (free formats)
  • If you create a CosmicLink from a transaction, an xdr or a sep7, all formats will immediately be available. (locked formats)

For a better efficiency, formats are lazy-evaluated. This means that they are computed once only if/when you call them:

const cosmicLink = new CosmicLink(xdr, { network: 'test' })
console.log(cosmicLink.query)

The role of cosmicLink.lock() is centric to this class. In practice, the free formats don't have to be tied to a network, a source or a sequence number. For example, the CosmicQuery ?inflation is a valid generic transaction that can be locked to any network/source/sequence combination.

On the other hand, locked formats are always tied to a particular combination of those, hence the need for a lock command:

const cosmicLib = require('cosmic-lib')
cosmicLib.network = 'test'
cosmicLib.source = 'tips*cosmic.link'

const cosmicLink = new cosmicLib.CosmicLink('?inflation')

console.log(cosmicLink.tdesc.source)    // => undefined
console.log(cosmicLink.tdesc.network)   // => undefined
console.log(cosmicLink.tdesc.sequence)  // => undefined
console.log(cosmicLink.xdr)             // => undefined

await cosmicLink.lock({)

console.log(cosmicLink.tdesc.source)    // => 'GC6Z...2JVW'
console.log(cosmicLink.tdesc.network)   // => 'test'
console.log(cosmicLink.tdesc.sequence)  // => 29...3903
console.log(cosmicLink.xdr)             // => 'AAAA....AA=='

The lock command is asynchronous because free formats accept federated addresses, but locked formats don't. The library automatically resolve those and this is an asynchronous operation. At the same time, it downloads the required data from the blockchain to handle multi-signers transactions.

After the lock operation, all free formats are updated according to the new state of the transaction. It is now possible to cosmicLink.sign(keypair) it, and to cosmicLink.send() it to the blockchain.

Constructor

Create a new CosmicLink object. transaction can be one of the accepted format: uri, query, json, tdesc, transaction, xdr or sep7.

Source:
Parameters:
Name Type Description
transaction string | Object | Transaction

A transaction in one of thoses formats: uri, query, json, tdesc, transaction, xdr, sep7

options Object

Additional options

Name Type Description
page string

The base URI to use when converting transaction to URI format.

network string

For Transaction/XDR formats, the network for which it have been created

strip string

Remove an element from the original XDR transaction. Valid values are source, sequence and signatures. Stripping out sequence means that the transaction request can get signed anytime in the future, possibly several times. Stripping out source means that it can get signed by any account.

stripNeutralAccount boolean

If set, strip source account out of SEP-0007/XDR requests when it is equal to the neutral account (GAAA...AWHF).

stripNeutralSequence boolean

If set, strip sequence out of SEP-0007/XDR requests when it is equal to 0.

Returns:
Type:
CosmicLink

Members

cache

The CosmicLink cache contains the resolved federations addresses and the accounts object. Using the same set of data for all the CosmicLink related computations ensure consistent results.

Source:

callback

The URL at which the signed transaction will be posted. This can be defined either locally (cosmicLink.tdesc.callback) or globally (cosmicLib.config.callback). The local configuration takes precedence.

When no callback is defined, the signed transaction is posted to Horizon. This is the default behavior.

Note: cosmicLink.tdesc should be edited using setTxFields.

Source:

errors

By default false, or an Array of errors.

Source:

extra

After parsing a SEP-0007 link, cosmicLink.extra contains SEP-0007 specific information:

  • cosmicLink.extra.type indicates the operation encoded into the SEP-0007 link (either tx or pay).
  • cosmicLink.extra.originDomain is a Promise that resolves to the origin_domain parameter when the link signature is valid. It rejects an error when the signature check fails. This property is undefined when the link has no origin_domain.
  • cosmicLink.extra.signature contains the link signature, if any.
  • cosmicLink.extra.pubkey contains the tx operation pubkey, if any.
  • cosmicLink.extra.msg contains the parsed msg, if any. This is provided for compatibility purpose only. Displaying messages from untrusted sources into trusted interfaces opens hard to mitigate attack vectors & is discouraged.
Source:

horizon

The URL of the horizon node from which ledger data will be retrieved, and to which the signed transaction will be posted if there's no callback.

This can be defined either locally (cosmicLink.tdesc.horizon) or globally (using setupNetwork). This parameter is special in the sense that it's the only one for which the global configuration takes precedence.

The rationale for this behavior is that we want transaction emitter to provide a fallback Horizon URL in the special case none is known for a custom network, but generally speaking it won't be right to allow the transaction emitter to force us to use a particular Horizon node.

Note: cosmicLink.tdesc should be edited using setTxFields.

Source:

htmlDescription

The HTML DOM node that displays a description of the current transaction. This is a browser-only property.

If your HTML page contains an element with id="cosmiclink_description", it will automatically get populated with the description of the last CosmicLink created.

Source:

A link HTML Element that points to cosmicLink.uri

Source:

json

CosmicLink's transaction in JSON format. This is a stringified version of Tdesc format.

Source:

locker

The locker property tells that a CosmicLink have been locked, and exposes the network & source values to which it have been locked.

Source:

network

The network for this transaction. This can be defined either locally (cosmicLink.tdesc.network) or globally (cosmicLib.config.network). The local configuration takes precedence, or, in other words, the global network is a fallback value in case the transaction emitter doesn't set one.

Note: cosmicLink.tdesc should be edited using setTxFields.

Source:

page

The page this CosmicLink uses to construct its URI.

Source:

query

CosmicLink's transaction encoded in the Cosmic Query format. This format allows to conveniently pass around Stellar transactions over any URI.

Source:

sep7

CosmicLink transaction in SEP-0007 link format. Only the XDR part of this protocol is currently supported by CosmicLink, minus the signature verification.

If you created the CosmicLink from uri, query, tdesc or json format, a lock() operation is needed to make this format available.

Source:

source

The source for this transaction. This can be defined either locally (cosmicLink.tdesc.source) or globally (cosmicLib.config.source). The local configuration takes precedence, or, in other words, the global source is a fallback value in case the transaction emitter doesn't set one.

Note: cosmicLink.tdesc should be edited using setTxFields.

Source:

status

The status of a CosmicLink. It becomes non-null in case of failure.

Source:

tdesc

CosmicLink's transaction in Tdesc format. This is in-between an objectified query representation and a simplified StellarSdk Transaction object. It has been created to be convenient to understand, use and manipulate.

If you need to read the transaction parameters, this is the format of choice:

console.log(cosmicLink.tdesc.network) // Does the transaction enforce a network?
console.log(cosmicLink.tdesc.source)  // Does the transaction enforce a source?
console.log(cosmicLink.tdesc.memo)    // A simplified memo object or undefined
console.log(cosmicLink.operations)    // Transaction operations in simplified format

This formats authorize federated addresses everywhere StellarSdk Transaction accept public keys. Those addresses are resolved when running the lock method, and the tdesc is replaced by a resolved one.

Tdesc is also very convenient to edit. To keep the CosmicLink in sync, you either need to parse the edited tdesc, or to edit it using the dedicated methods:

Source:

transaction

CosmicLink's transaction in StellarSdk Transaction format.

If you created the CosmicLink from uri, query, tdesc or json format, a lock() operation is needed to make this format available.

Source:

uri

A CosmicLink is a URI that embed a Cosmic Query. This format is simply the cosmicLink.query appended to the cosmicLink.page

Source:

xdr

CosmicLink's transaction in XDR format.

If you created the CosmicLink from uri, query, tdesc or json format, a lock() operation is needed to make this format available.

Source:

Methods

addOperation(type, params) → {CosmicLink}

Add a new operation to CosmicLink. params should follow the Tdesc format, but fields values can be written using query or StellarSdk format as well.

Source:
Parameters:
Name Type Description
type string

The operation type.

params Object

The operation parameters.

Returns:
Type:
CosmicLink
Examples
cosmicLink.addOperation('changeTrust', { asset: 'CNY:admin*ripplefox' })
cosmicLink.addOperation('changeTrust', { asset: { code: 'CNY', issuer: 'admin*ripplefox } })
cosmicLink.addOperation('changeTrust', { asset: new StellarSdk.Asset('CNY', ...) })

insertOperation(index, type, params) → {CosmicLink}

Insert an operation at index. params should follow the Tdesc format, but fields can be written using query or StellarSdk format as well.

Source:
Parameters:
Name Type Description
index integer

The operation index.

type string

The operation type.

params params

The operation parameters.

Returns:
Type:
CosmicLink
Example
cosmicLink.insertOperation(0, 'changeTrust', {
  asset: 'CNY:admin*ripplefox'
})

(async) lock(optionsopt)

Lock a CosmicLink to a network/source pair. If the cosmicLink was created from a query/uri/tdesc/json, it will create the corresponding transaction/xdr/sep7 formats.

This operation must be performed by the wallet before signing & sending the transaction.

Source:
Parameters:
Name Type Attributes Description
options Object <optional>
Name Type Description
network string

Local fallback network

horizon string

Local fallback horizon (overwrited by global configuration)

callback string

Local fallback callback

source string

Local fallback source

Example
cosmicLib.config.network = "test"
const cosmicLink = new CosmicLink("?setOptions")
console.log(cosmicLink.network) // => undefined
console.log(cosmicLink.xdr)     // => undefined
await cosmicLink.lock()
console.log(cosmicLink.network) // => "test"
console.log(cosmicLink.xdr)     // => "AAAA...AA=="

open(targetopt)

Open CosmicLink in target.

  • frame (default): Open cosmicLink in a side-frame.
  • tab: Open cosmicLink in a new tab.
  • current: Open cosmicLink into the current window.
  • sep7: Open cosmicLink using user's SEP-0007 handler.
Source:
Parameters:
Name Type Attributes Default Description
target String <optional>
"frame"

Open cosmicLink into the requested target. Valid targets are: frame, tab, current and sep7.

parse()

Re-parse this CosmicLink. Useful in implementing transaction editors. The parameters are the same than Constructor, and the result is similar except that no new CosmicLink object is created.

Source:

selectNetwork()

Select the network that this CosmicLink uses.

Deprecated:
  • StellarSdk global `Network` setting is deprecated.
Source:

send(horizonopt) → {Object}

Send CosmicLink's transaction to a blockchain validator, or to StellarGuard when relevant. A CosmicLink have to be locked before sending.

Returns a promise that resolve/reject to the horizon server response.

Source:
Parameters:
Name Type Attributes Description
horizon horizon <optional>

An horizon node URL

Returns:
Type:
Object

The server response

Example
cosmicLink.send()
  .then(console.log)
  .catch(console.error)

setOperation(index, type, params) → {CosmicLink}

Set/remove one of the CosmicLink operations. params should follow the Tdesc format, but fields can be written using query or StellarSdk format as well. If type is set to null, the operation at index is deleted.

Source:
Parameters:
Name Type Description
index integer

The operation index.

type string

The operation type.

params params

The operation parameters.

Returns:
Type:
CosmicLink
Examples
cosmicLink.setOperation(1, 'setOptions', { homeDomain: 'example.org' })
cosmicLink.setOperation(2, null)

setTxFields(object) → {CosmicLink}

Add/remove transaction fields and reparse the CosmicLink. object should follow the Tdesc format, but fields values can be written using query or StellarSdk format as well.

Source:
Parameters:
Name Type Description
object Object

Transaction fields definition. Fields can be either written using the JSON format or the query format

Returns:
Type:
CosmicLink
Examples
cosmicLink.setTxFields({ minTime: '2018-10', maxTime: '2019-01' })
cosmicLink.setTxFields({ minTime: null, maxTime: null })
cosmicLink.setTxFields({ memo: 'Bonjour!' })

sign()

Sign CosmicLink's Transaction with keypairs_or_preimage and update the other formats accordingly. Only legit signers are allowed to sign, and a CosmicLink have to be locked before signing.

Source:
Parameters:
Name Type Description
...keypairs_or_preimage Keypair | Buffer | string

signSep7(domain, keypair)

Sign SEP-0007 link for domain, using keypair.

Source:
See:
Parameters:
Name Type Description
domain String

The domain or subdomain you want to sign the request for. (example: "a-domain.org")

keypair Keypair

A StellarSdk Keypair.

(async) verifySep7() → {undefined|String}

Verify SEP-0007 signature by resolving cosmicLink.extra.domain, if any. Throw an error if the signature is not valid.

Source:
Returns:
Type:
undefined | String

The resolved cosmicLink.extra.domain, if any.