Cosmic links specifications
Cosmic links syntax mimic js-stellar-sdk
Transactions
and Operations
methods.
General syntax
One-operation link
...?type={operation}&{field}={value}&{...more_fields}
Where {field}
can be either a meta field, a transaction field or a valid field
for {operation}
.
Example:
https://cosmic.link/?payment&memo=Donation&destination=tips*cosmic.link&amount=100
Multi-operation link
...?type=transaction&{...metaFields|transactionFields}&operation={operation}&{...operationFields}&{...more_operations}
Meta fields and transactions fields have to be provided prior to any operation, then the operations should be described sequentially.
Example:
XDR link
...?xdr={xdr}&{...metaFields}[&strip=source|sequence|signatures]
&strip
: Remove an element from the original XDR transaction. 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.
Example:
https://cosmic.link/?xdr=AAAA...AA==&network=public&strip=source
Fields
Meta Fields
Those fields contains data that is not strictly-speaking part of the transaction object, but that is essential to its validation. Those fields are optional.
network
&network=public|test|{passphrase}
Tie the transaction to a specific network. Network-less transaction requests are interpreted as transactions that can be validated on any network.
horizon
&horizon={url}
Provide a fallback Horizon node for custom network in case the client doesn't know any.
callback
&callback={url}
Provide the destination at which the signed transaction must be posted.
Transaction fields
Those fields may be used in any transaction and are all of them are optionals.
For multi-operations links, source
will become the default source for any
operation that doesn't define one. In cosmic links, having a source
is
optional as the source can be set by the wallet service when signing.
memo
The general syntax for memos is:
&memo={memoType}:{memoValue}
Where {memoType}
is one of: text
, id
, hash
, return
. A short syntax
for text memo exist aswell:
&memo={memoValue}
source
&source={address}
Where {address}
is either a federated address or an account ID, as any address
in js-cosmic-lib
.
minTime / maxTime
&minTime|maxTime={YYYY-MM-DD} &minTime|maxTime={YYYY-MM-DDTHH:mm:ssZ}
This is the ISO 8601 date format.
&minTime|maxTime=+{minutes}
This is a syntactic sugar to define minTime/maxTime relatively to the current time, in minutes. This gets immediately computed into the corresponding UTC date.
sequence
&sequence={integer}
The sequence number for this transaction.
fee
&fee={integer}
Fees for this transaction. Should at least egual the minimum network fee.
Operation fields
accountMerge
Destroy source
account and send its lumens to destination
.
Mandatory fields:
...?accountMerge&destination={address}
Optional fields:
- &source={address}
allowTrust
Allow trustor
to hold your asset assetCode
.
Mandatory fields:
...?allowTrust&assetCode={string}&trustor={address}
Optional fields:
- &authorize=false Revoke
trustor
permission to holdassetCode
- &source={address}
bumpSequence
Set account sequence number to bumpTo
.
Mandatory fields:
...?bumpSequence&bumpTo={sequenceNumber}
Optional fields:
- &source={address}
changeTrust
Accept asset
.
...?changeTrust&asset={assetCode}:{assetIssuer}
Optional fields:
- &limit={integer} Maximum holding, if set to zero
source
will not acceptasset
anymore. - &source={address}
claimClaimableBalance
Claim claimable balance balanceId
...?claimclaimableBalance&balanceId={id}
Optional fields:
- &source={address}
createAccount
Create account destination
and send it initialBalance
lumens.
...?createAccount&destination={address}&initialBalance={amount}
Optional fields:
- &source={address}
createPassiveSellOffer
Offer to passively sell amount
selling
for price
buying
/ unit.
...?createPassiveSellOffer&selling={assetCode}:{assetIssuer}&buying={assetCode}:{assetIssuer}&amount={amount}&price={price}
Notes:
- Before protocol 11 update, this operation was named
createPassiveOffer
. The old name is still supported for backward compatibility. selling
orbuying
field may be omitted when it is lumens.price
can also be a fraction in the form{1:2}
or{sellAmount}:{buyAmount}
.
Optional fields:
- &source={address}
inflation
Run inflation
...?inflation
Optional fields:
- &source={address}
manageData
Clear data entry name
/ Set name
value as value
.
...?manageData&name={string}
Optional fields
- &value={string} If omitted, clear
name
, else setname
tovalue
. - &source={address}
manageBuyOffer
Offer to buy buyAmount
buying
for price
selling
/ unit.
...?manageBuyOffer&selling={assetCode}:{assetIssuer}&buying={assetCode}:{assetIssuer}&buyAmount={amount}&price={price}
Notes:
selling
orbuying
field may be omitted when it is lumens.price
can also be a fraction in the form{1:2}
or{sellAmount}:{buyAmount}
.
Optional fields:
- &offerId={integer} Allow to edit an existing offer. Will delete it if
amount
is set to 0. - &source={address}
Syntactic sugar for deleting offer:
...?manageBuyOffer&offerId={integer}&amount=0
manageSellOffer
Offer to sell amount
selling
for price
buying
/ unit.
...?manageSellOffer&selling={assetCode}:{assetIssuer}&buying={assetCode}:{assetIssuer}&amount={amount}&price={price}
Notes:
selling
orbuying
field may be omitted when it is lumens.price
can also be a fraction in the form{1:2}
or{sellAmount}:{buyAmount}
.- Before protocol 11 update, this operation was named
manageOffer
. The old name is still supported for backward compatibility.
Optional fields:
- &offerId={integer} Allow to edit an existing offer. Will delete it if
amount
is set to 0. - &source={address}
Syntactic sugar for deleting offer:
...?manageSellOffer&offerId={integer}&amount=0
pathPaymentStrictReceive
Send destAmount
destAsset
to destination
for at most sendMax
sendAsset
using the available offers for the conversion.
...?pathPaymentStrictReceive&destination={address}&destAmount={amount}&destAsset={assetCode}:{assetIssuer}&sendMax={amount}&sendAsset={assetCode}:{assetIssuer}
Notes:
destAsset
orsendAsset
field may be omitted when it is lumens.- Before protocol 12 update, this operation was named
pathPayment
. The old name is still supported for backward compatibility.
Optional fields:
- &path={asset1},{asset2},...,{assetN} Where each asset is
{assetCode}:{assetIssuer}
orXLM
. Define a conversion path to follow. If neitherdestAsset
orsendAsset
are lumens, you'll likely need&path=XLM
to set lumens as an intermediate conversion step. - &source={address}
pathPaymentStrictSend
Send at least destMin
destAsset
to destination
for sendAmount
sendAsset
using the available offers for the conversion.
...?pathPaymentStrictSend&destination={address}&destMin={amount}&destAsset={assetCode}:{assetIssuer}&sendAmount={amount}&sendAsset={assetCode}:{assetIssuer}
Notes:
destAsset
orsendAsset
field may be omitted when it is lumens.
Optional fields:
- &path={asset1},{asset2},...,{assetN} Where each asset is
{assetCode}:{assetIssuer}
orXLM
. Define a conversion path to follow. If neitherdestAsset
orsendAsset
are lumens, you'll likely need&path=XLM
to set lumens as an intermediate conversion step. - &source={address}
payment
Send amount
asset
to destination
.
...?payment&amount={amount}&destination={address}
Optional fields:
- &asset={assetCode}:{assetIssuer} Define
asset
when it is not lumens. - &source={address}
setOptions
Allow various actions depending on the optional fields you use. Without any field this is a void operation.
...?setOptions
Optional fields:
- &inflationDest={address} Set
{address}
as the inflation destination forsource
. - &clearFlags={integer} Bitmap integer for which account flags to clear
- &setFlags={integer} Bitmap integer for which account flags to set.
- &masterWeight={weight} The master key weight.
- &lowThreshold={weight} The sum weight for the low threshold.
- &medThreshold={weight} The sum weight for the medium threshold.
- &highThreshold={weight} The sum weight for the high threshold.
- &signer={weight}:{type}:{value} If
weight
is set to 0, remove a signer fromsource
account, else edit or add one.type
can be either:key
: refer to another accounttx
: refer to a transaction hashhash
: refer to a preimage or hash(x) signer
- &homeDomain={string} set homedomain, or unset it if
string
is empty - &source={address}