Constructor
new CosmicLink(transaction, options) → {CosmicLink}
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
|
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:
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 (eithertx
orpay
).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 isundefined
when the link has no origin_domain.cosmicLink.extra.signature
contains the link signature, if any.cosmicLink.extra.pubkey
contains the tx operationpubkey
, if any.cosmicLink.extra.msg
contains the parsedmsg
, 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:
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:
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:
- setTxFields: set/clear transaction fields
- addOperation: add a new operation
- setOperation: edit/clear an operation
- 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> |
|
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 |
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.