# Cosmic links specifications Cosmic links syntax mimic `js-stellar-sdk` [Transactions](https://stellar.github.io/js-stellar-sdk/Transaction.html) and [Operations](https://stellar.github.io/js-stellar-sdk/Operation.html) 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: > ### 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](https://cosmic.link/?xdr=AAAAAL2ef/Z7FpGtgUvkKaEg3uvy9IH+T9chWSUhQILKTk/NAAAAZAEMX34AAAADAAAAAAAAAAAAAAABAAAAAAAAAAUAAAABAAAAAIQ/AS7GRUBBd96ykumKKUFE92+oiwRuJ7KXuvPwwTQWAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==&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 hold `assetCode` * &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 accept `asset` anymore. * &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` or `buying` 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 set `name` to `value`. * &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` or `buying` 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` or `buying` 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` or `sendAsset` 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}` or `XLM`. Define a conversion path to follow. If neither `destAsset` or `sendAsset` 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` or `sendAsset` field may be omitted when it is lumens. Optional fields: * &path={asset1},{asset2},...,{assetN} Where each asset is `{assetCode}:{assetIssuer}` or `XLM`. Define a conversion path to follow. If neither `destAsset` or `sendAsset` 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 for `source`. * &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 from `source` account, else edit or add one. `type` can be either: * `key`: refer to another account * `tx`: refer to a transaction hash * `hash`: refer to a preimage or hash(x) signer * &homeDomain={string} set homedomain, or unset it if `string` is empty * &source={address}