XDR (3.3.1)

This repo defines structures used to communicate with Core of TokenD based networks.

Transaction

Transactions are commands that modify the ledger state. If you think of the ledger as a database, then Operations are SQL commands and Trannsactions are SQL transactions.

Transactions allows you to combine several operations (even from different sources) into one atomic command (if one operation fails, whole transaction rollbacks). What is more, it's possible to specify different source account for different operation. This can be used to implement features like over-the-counter exchange (include into transaction two operations: one sending assets from A to B; one sending assets from B to A; such transaction requires signatures from both A and B).

Transaction Envelope

Account Role Requirements

Account Resource Type Action
source TRANSACTION SEND

Signer Role Requirements

Signers rules required on operation level.

TransactionEnvelope
Tx
object

Transaction is a container for a set of operations

  • is executed by an account
  • operations are executed in order as one ACID transaction (either all operations are applied or none are if any returns a failing code)
Signatures
Array of object

list of signatures used to authorize transaction

Response Schema result
FeeCharged
long
Result
One of multiple values
Ext
TransactionResultExtArmEmptyVersion (object)

Accounts

Defines operations to manage Accounts

Create Account

Allows creating account with specific role and signers. Balances for assets with policy BASE_ASSET will be created for the account automatically.

Account Role Requirements

Account Resource Type Action
source ACCOUNT CREATE

Signer Role Requirements

Resource Type Rule Action
ACCOUNT CREATE
CreateAccountOp

CreateAccountOp is used to create new account

Destination
AccountId

ID of account to be created

Referrer
AccountId

ID of an another account that introduced this account into the system. If account with such ID does not exist or it's Admin Account. Referrer won't be set.

RoleId
uint64

ID of the role that will be attached to an account

SignersData
Array of object

Array of data about 'destination' account signers to be created

Ext
CreateAccountOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • InvalidSignerData
  • InvalidDestination
  • AlreadyExists
  • InvalidWeight
  • NoSuchRole
  • NoSignerData
code
string
Value:"SUCCESS"

Means that destination account has been successfully created with signers specified in signersData

success
object (CreateAccountSuccess)

Result of successful application of CreateAccount operation

Assets

Defines operations to manage Assets

Create Request For Asset Creation

Allows to create or update CREATE_ASSET reviewable request CREATE_ASSET request is used to create asset entry

Account Role Requirements

Account Resource Type Rule Action Condition
source ASSET CREATE allTasks == null
source ASSET CREATE_WITH_TASKS allTasks != null

Signer Role Requirements

Resource Type Rule Action Details
ASSET CREATE Resource includes code and type of asset
ManageAssetOp

ManageAssetOp is used to:

  • create or update CREATE_ASSET request;
  • create or update UPDATE_ASSET request;
  • cancel CREATE_ASSET or UPDATE_ASSET request
  • change asset pre issuer
  • update max issuance of an asset
RequestId
uint64

ID of a reviewable request If requestID == 0, operation creates a new reviewable request; otherwise, it updates the existing one

Request
One of multiple values

data is used to pass one of ManageAssetAction with required params

Ext
ManageAssetOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • RequestNotFound
  • InvalidSignature
  • AssetAlreadyExists
  • InvalidMaxIssuanceAmount
  • InvalidCode
  • InvalidPreIssuer
  • InvalidPolicies
  • AssetNotFound
  • RequestAlreadyExists
  • StatsAssetAlreadyExists
  • InitialPreissuedExceedsMaxIssuance
  • InvalidCreatorDetails
  • InvalidTrailingDigitsCount
  • InvalidPreissuedAmountPrecision
  • InvalidMaxIssuanceAmountPrecision
  • AssetCreateTasksNotFound
  • AssetUpdateTasksNotFound
  • NotAllowedToSetTasksOnUpdate
code
string
Value:"SUCCESS"

Specified action in data of ManageSignerOp was successfully performed

success
object (ManageAssetSuccess)

Is used to pass useful params after the successful operation application

Asset Resources

Describes the asset pairs as a set of properties and policies for two particular assets (i.e. base and quote assets).

AssetEntry
Code
string

Code of the asset

Owner
AccountId

Owner(creator) of the asset

PreissuedAssetSigner
AccountId

Account responsible for preissuance of the asset

Details
string

Arbitrary stringified JSON object that can be used to attach data to asset

MaxIssuanceAmount
uint64

Maximal amount of tokens that can be issued

AvailableForIssueance
uint64

Amount of tokens available for issuance

Issued
uint64

Amount of tokens issued already

PendingIssuance
uint64

Amount of tokens to be issued which is locked. pendingIssuance+issued <= maxIssuanceAmount

Policies
uint32

Policies of the asset

Type
uint64

Used to restrict usage. Used in account rules

TrailingDigitsCount
uint32

Number of decimal places. Must be <= 6

Ext
EmptyExtArmEmptyVersion (object)

Reserved for future use

Code samples

Copy

enum AssetPolicy
{
  //: Defines whether or not asset can be transfered using payments
	TRANSFERABLE = 1,
	//: Defines whether or not asset is considered base
	BASE_ASSET = 2,
	//: [[Deprecated]]
	STATS_QUOTE_ASSET = 4,
	//: Defines whether or not asset can be withdrawed from the system
	WITHDRAWABLE = 8,
	//: Defines whether or not manual review for issuance of asset is required
	ISSUANCE_MANUAL_REVIEW_REQUIRED = 16,
	//: Defines whether or not asset can be base in atomic swap
	CAN_BE_BASE_IN_ATOMIC_SWAP = 32,
	//: Defines whether or not asset can be quote in atomic swap
	CAN_BE_QUOTE_IN_ATOMIC_SWAP = 64
};


struct AssetEntry
{
  //: Code of the asset
  AssetCode code;
  //: Owner(creator) of the asset
	AccountID owner;
	//: Account responsible for preissuance of the asset
	AccountID preissuedAssetSigner;
    //: Arbitrary stringified JSON object that can be used to attach data to asset
	longstring details;
	//: Maximal amount of tokens that can be issued
	uint64 maxIssuanceAmount;
	//: Amount of tokens available for issuance
	uint64 availableForIssueance;
	//: Amount of tokens issued already
	uint64 issued;
	//: Amount of tokens to be issued which is locked. `pendingIssuance+issued <= maxIssuanceAmount`
	uint64 pendingIssuance;
	//: Policies of the asset
  uint32 policies;
  //: Used to restrict usage. Used in account rules
  uint64 type;
  //: Number of decimal places. Must be <= 6
  uint32 trailingDigitsCount;

  //: Reserved for future use
  EmptyExt ext;
};

Create Request To Update Asset

Allows to create or update UPDATE_ASSET reviewable request UPDATE_ASSET request is used to update asset entry

Account Role Requirements

Account Resource Type Reviewable Request Type Action Condition
source REVIEWABLE_REQUEST UPDATE_ASSET CREATE allTasks == null
source REVIEWABLE_REQUEST UPDATE_ASSET CREATE_WITH_TASKS allTasks != null

Signer Role Requirements

Resource Type Rule Action Details
ASSET UPDATE Resource includes code and type of asset
ManageAssetOp

ManageAssetOp is used to:

  • create or update CREATE_ASSET request;
  • create or update UPDATE_ASSET request;
  • cancel CREATE_ASSET or UPDATE_ASSET request
  • change asset pre issuer
  • update max issuance of an asset
RequestId
uint64

ID of a reviewable request If requestID == 0, operation creates a new reviewable request; otherwise, it updates the existing one

Request
One of multiple values

data is used to pass one of ManageAssetAction with required params

Ext
ManageAssetOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • RequestNotFound
  • InvalidSignature
  • AssetAlreadyExists
  • InvalidMaxIssuanceAmount
  • InvalidCode
  • InvalidPreIssuer
  • InvalidPolicies
  • AssetNotFound
  • RequestAlreadyExists
  • StatsAssetAlreadyExists
  • InitialPreissuedExceedsMaxIssuance
  • InvalidCreatorDetails
  • InvalidTrailingDigitsCount
  • InvalidPreissuedAmountPrecision
  • InvalidMaxIssuanceAmountPrecision
  • AssetCreateTasksNotFound
  • AssetUpdateTasksNotFound
  • NotAllowedToSetTasksOnUpdate
code
string
Value:"SUCCESS"

Specified action in data of ManageSignerOp was successfully performed

success
object (ManageAssetSuccess)

Is used to pass useful params after the successful operation application

Cancel Asset Request

Allows to cancel CREATE_ASSET or UPDATE_ASSET reviewable request

Account Role Requirements

No account rule required because only requestor can remove own request

Signer Role Requirements

Resource Type Rule Action Details
ASSET CANCEL Resource includes code and type of asset
ManageAssetOp

ManageAssetOp is used to:

  • create or update CREATE_ASSET request;
  • create or update UPDATE_ASSET request;
  • cancel CREATE_ASSET or UPDATE_ASSET request
  • change asset pre issuer
  • update max issuance of an asset
RequestId
uint64

ID of a reviewable request If requestID == 0, operation creates a new reviewable request; otherwise, it updates the existing one

Request
One of multiple values

data is used to pass one of ManageAssetAction with required params

Ext
ManageAssetOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • RequestNotFound
  • InvalidSignature
  • AssetAlreadyExists
  • InvalidMaxIssuanceAmount
  • InvalidCode
  • InvalidPreIssuer
  • InvalidPolicies
  • AssetNotFound
  • RequestAlreadyExists
  • StatsAssetAlreadyExists
  • InitialPreissuedExceedsMaxIssuance
  • InvalidCreatorDetails
  • InvalidTrailingDigitsCount
  • InvalidPreissuedAmountPrecision
  • InvalidMaxIssuanceAmountPrecision
  • AssetCreateTasksNotFound
  • AssetUpdateTasksNotFound
  • NotAllowedToSetTasksOnUpdate
code
string
Value:"SUCCESS"

Specified action in data of ManageSignerOp was successfully performed

success
object (ManageAssetSuccess)

Is used to pass useful params after the successful operation application

Change current pre issuer of asset

Allows to change asset pre issuer

Account Role Requirements

No account rule required because only current asset pre issuer can change asset pre issuer

Signer Role Requirements

No signer rule required because only current asset pre issuer can change asset pre issuer

ManageAssetOp

ManageAssetOp is used to:

  • create or update CREATE_ASSET request;
  • create or update UPDATE_ASSET request;
  • cancel CREATE_ASSET or UPDATE_ASSET request
  • change asset pre issuer
  • update max issuance of an asset
RequestId
uint64

ID of a reviewable request If requestID == 0, operation creates a new reviewable request; otherwise, it updates the existing one

Request
One of multiple values

data is used to pass one of ManageAssetAction with required params

Ext
ManageAssetOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • RequestNotFound
  • InvalidSignature
  • AssetAlreadyExists
  • InvalidMaxIssuanceAmount
  • InvalidCode
  • InvalidPreIssuer
  • InvalidPolicies
  • AssetNotFound
  • RequestAlreadyExists
  • StatsAssetAlreadyExists
  • InitialPreissuedExceedsMaxIssuance
  • InvalidCreatorDetails
  • InvalidTrailingDigitsCount
  • InvalidPreissuedAmountPrecision
  • InvalidMaxIssuanceAmountPrecision
  • AssetCreateTasksNotFound
  • AssetUpdateTasksNotFound
  • NotAllowedToSetTasksOnUpdate
code
string
Value:"SUCCESS"

Specified action in data of ManageSignerOp was successfully performed

success
object (ManageAssetSuccess)

Is used to pass useful params after the successful operation application

Remove Asset

Removes asset.

Account Role Requirements

Account Resource Type Action Condition
source ASSET REMOVE source == assetOwner
source ASSET REMOVE_FOR_OTHER source != assetOwner

Signer Role Requirements

Resource Type Rule Action
ASSET REMOVE
ASSET REMOVE_FOR_OTHER
RemoveAssetOp

RemoveAssetOp removes specified asset pair

Code
string

Defines an asset

Ext
RemoveAssetOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • InvalidAssetCode
  • HasPair
  • HasActiveOffers
  • HasActiveSales
  • HasActiveAtomicSwaps
  • HasActiveSwaps
  • CannotRemoveStatsQuoteAsset
  • HasPendingMovements
code
string
Value:"SUCCESS"

Operation is successfully applied

success
object (RemoveAssetSuccess)

Result of successful RemoveAssetOp application

Update Max Issuance

Allows to change max issuance of asset

Account Role Requirements

Account Resource Type Rule Action Details
source ASSET UPDATE_MAX_ISSUANCE Only asset owner can update max issuance of asset

Signer Role Requirements

Resource Type Rule Action
ASSET UPDATE_MAX_ISSUANCE
ManageAssetOp

ManageAssetOp is used to:

  • create or update CREATE_ASSET request;
  • create or update UPDATE_ASSET request;
  • cancel CREATE_ASSET or UPDATE_ASSET request
  • change asset pre issuer
  • update max issuance of an asset
RequestId
uint64

ID of a reviewable request If requestID == 0, operation creates a new reviewable request; otherwise, it updates the existing one

Request
One of multiple values

data is used to pass one of ManageAssetAction with required params

Ext
ManageAssetOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • RequestNotFound
  • InvalidSignature
  • AssetAlreadyExists
  • InvalidMaxIssuanceAmount
  • InvalidCode
  • InvalidPreIssuer
  • InvalidPolicies
  • AssetNotFound
  • RequestAlreadyExists
  • StatsAssetAlreadyExists
  • InitialPreissuedExceedsMaxIssuance
  • InvalidCreatorDetails
  • InvalidTrailingDigitsCount
  • InvalidPreissuedAmountPrecision
  • InvalidMaxIssuanceAmountPrecision
  • AssetCreateTasksNotFound
  • AssetUpdateTasksNotFound
  • NotAllowedToSetTasksOnUpdate
code
string
Value:"SUCCESS"

Specified action in data of ManageSignerOp was successfully performed

success
object (ManageAssetSuccess)

Is used to pass useful params after the successful operation application

Payment

Defines access points to get Payments

Create payment request

Allows to create request to transfer some amount of asset from source balance to destination account/balance. Payment request is a reviewable request. It uses tasks - bitmask, where each bit represents conditions under which request can be approved. Tasks can be set or cleared both manually(by reviewer) and automatically. Tasks bit mask can be provided either from KeyValueEntry by key payment_tasks:<asset_code> (which specify tasks for asset) or by key payment_tasks:* if there are no payment tasks for provided asset. If field allTasks is set, KeyValueEntry won't be used.

Account Role Requirements

Account Resource Type Reviewable Request Type Action Condition
receiver ASSET - RECEIVE_PAYMENT -
source REVIEWABLE_REQUEST CREATE_PAYMENT CREATE allTasks == null
source REVIEWABLE_REQUEST CREATE_PAYMENT CREATE_WITH_TASKS allTasks != null

Signer Role Requirements

Resource Type Reviewable Request Type Action Condition
REVIEWABLE_REQUEST CREATE_PAYMENT CREATE allTasks == null
REVIEWABLE_REQUEST CREATE_PAYMENT CREATE_WITH_TASKS allTasks != null
CreatePaymentRequestOp
Request
object

Payment request details

AllTasks
uint32

(optional) Bit mask whose flags must be cleared in order for CreateSale request to be approved, which will be used by key sale_create_tasks: instead of key-value

Ext
EmptyExtArmEmptyVersion (object)

reserved for future extension

Response Schema
One of
  • Success
  • InvalidPayment
  • PaymentTasksNotFound
code
string
Value:"SUCCESS"

CreatePaymentRequestOp was successfully applied

success
object (CreatePaymentRequestSuccessResult)

Result of the successful payment request creation

Payment operantion

Allows to transfer some amount of asset from source balance to destination account/balance.

Account Role Requirements

Account Resource Type Action
source ASSET SEND
destination ASSET RECEIVE_PAYMENT

Signer Role Requirements

Resource Type Rule Action
ASSET SEND
PaymentOp

PaymentOp is used to transfer some amount of asset from the source balance to destination account/balance

SourceBalanceId
BalanceId

ID of the source balance of payment

Destination
PaymentOpDestinationArmAccount (object) or PaymentOpDestinationArmBalance (object)

destination defines the type of instance that receives the payment based on given PaymentDestinationType

Amount
uint64

Amount of payment

FeeData
object

feeData defines all data about the payment fee

Subject
string

subject is a user-provided info about the real-life purpose of payment

Reference
string

reference is a string formed by a payment sender. Reference-sender account pair is unique.

Ext
PaymentOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • Malformed
  • Underfunded
  • LineFull
  • DestinationBalanceNotFound
  • BalanceAssetsMismatched
  • SrcBalanceNotFound
  • ReferenceDuplication
  • StatsOverflow
  • LimitsExceeded
  • NotAllowedByAssetPolicy
  • InvalidDestinationFee
  • InsufficientFeeAmount
  • PaymentAmountIsLessThanDestFee
  • DestinationAccountNotFound
  • IncorrectAmountPrecision
code
string
Value:"SUCCESS"

Payment was successfully completed

paymentResponse
object (PaymentResponse)

PaymentResponse defines the response on the corresponding PaymentOp

Issuance

Defines access points to get Issuance Reviewable Requests

Create issuance request

Allows to create request to emit provided amount of specified asset to destination balance. Issuance request is a reviewable request. It uses tasks - bitmask, where each bit represents conditions under which request can be approved. Tasks can be set or cleared both manually(by reviewer) and automatically. Tasks bit mask can be provided either from KeyValueEntry by key issuance_tasks:<asset_code> (which specify tasks for asset) or by key issuance_tasks:* if there are no issuance tasks for provided asset. If field allTasks is set, KeyValueEntry won't be used.

Account Role Requirements

Account Resource Type Reviewable Request Type Action Condition
receiver ASSET RECEIVE_ISSUANCE - -
source REVIEWABLE_REQUEST CREATE_ISSUANCE CREATE allTasks == null
source REVIEWABLE_REQUEST CREATE_ISSUANCE CREATE_WITH_TASKS allTasks != null

Signer Role Requirements

Resource Type Reviewable Request Type Action
REVIEWABLE_REQUEST CREATE_ISSUANCE CREATE
CreateIssuanceRequestOp

CreateIssuanceRequestOp is used to create a reviewable request that, after reviewer's approval, will issue the specified amount of asset to a receiver's balance

Request
object

Issuance request to create

Reference
string

Reference of the request

AllTasks
uint32

(optional) Bit mask whose flags must be cleared in order for IssuanceRequest to be approved, which will be used by key issuance_tasks: instead of key-value

Ext
CreateIssuanceRequestOpExtArmEmptyVersion (object)

Reserved for future use

Response Schema
One of
  • Success
  • AssetNotFound
  • InvalidAmount
  • ReferenceDuplication
  • NoCounterparty
  • NotAuthorized
  • ExceedsMaxIssuanceAmount
  • ReceiverFullLine
  • InvalidCreatorDetails
  • FeeExceedsAmount
  • RequiresKyc
  • RequiresVerification
  • IssuanceTasksNotFound
  • SystemTasksNotAllowed
  • InvalidAmountPrecision
code
string
Value:"SUCCESS"

CreateIssuanceRequest operation application was successful

success
object (CreateIssuanceRequestSuccess)

Result of successful application of CreateIssuanceRequest operation

Create Pre Issuance Request

Allows creating CREATE_PRE_ISSUANCE reviewable request. CREATE_PRE_ISSUANCE request is used to increase available for issuance amount of asset.

Account Role Requirements

Account Resource Type Reviewable Request Type Action Condition
source REVIEWABLE_REQUEST CREATE_PRE_ISSUANCE CREATE allTasks == null
source REVIEWABLE_REQUEST CREATE_PRE_ISSUANCE CREATE_WITH_TASKS allTasks != null

Signer Role Requirements

No singer rule required because only asset pre issuer can do pre issuance.

CreatePreIssuanceRequestOp

CreatePreIssuanceRequestOp is used to create a reviewable request, which, after admin's approval, will change availableForIssuance amount of asset

Request
object

Body of PreIssuanceRequest to be created

AllTasks
uint32

(optional) Bit mask whose flags must be cleared in order for PreIssuanceRequest to be approved, which will be used by key preissuance_tasks instead of key-value

Ext
CreatePreIssuanceRequestOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • AssetNotFound
  • ReferenceDuplication
  • NotAuthorizedUpload
  • InvalidSignature
  • ExceededMaxAmount
  • InvalidAmount
  • InvalidReference
  • IncorrectAmountPrecision
  • PreissuanceTasksNotFound
  • InvalidCreatorDetails
code
string
Value:"SUCCESS"

Preissuance request is either successfully created or auto approved if pending tasks of requests is equal to 0

success
object (CreatePreIssuanceRequestResultSuccess)

Withdrawal

Defines access points to get Withdrawal Reviewable Requests

Create withdrawal request

Allows to create request to withdraw assets from system. On request creation, withdrawn amount will be locked on target balance. For withdrawal reviewable request REJECT action is not allowed. On PERMANENT REJECT, withdrawn amount is unlocked. On APPROVE, tasks can be added and removed. If pendingTasks == 0 and action being performed is APPROVE, withdrawn amount is sent to external account. Withdrawn amount is subtracted for issued field of the asset Withdrawal request cannot be autoapproved, i.e. it's not allowed to set empty (zero tasks) in any way, either through KeyValueEntry or on request creation(through allTasks).

Account Role Requirements

Account Resource Type Action
source WITHDRAW CREATE

Signer Role Requirements

Resource Type Reviewable Request Type Action
REVIEWABLE_REQUEST CREATE_WITHDRAW CREATE
CreateWithdrawalRequestOp

CreateWithdrawalRequest operation is used to create a reviewable request, which, after reviewer's approval, will charge the specified amount from balance and send it to external wallet/account

Request
object

Withdrawal request to create

AllTasks
uint32

(optional) Bit mask whose flags must be cleared in order for WithdrawalRequest to be approved, which will be used by key withdrawal_tasks: instead of key-value

Ext
CreateWithdrawalRequestOpExtArmEmptyVersion (object)

Reserved for future use

Response Schema
One of
  • Success
  • InvalidAmount
  • InvalidCreatorDetails
  • BalanceNotFound
  • AssetIsNotWithdrawable
  • ConversionPriceIsNotAvailable
  • FeeMismatched
  • ConversionOverflow
  • ConvertedAmountMismatched
  • BalanceLockOverflow
  • Underfunded
  • InvalidUniversalAmount
  • StatsOverflow
  • LimitsExceeded
  • InvalidPreConfirmationDetails
  • LowerBoundNotExceeded
  • WithdrawalTasksNotFound
  • NotAllowedToSetWithdrawalTasks
  • WithdrawalZeroTasksNotAllowed
code
string
Value:"SUCCESS"

CreateWithdrawalRequest operation successfully applied

success
object (CreateWithdrawalSuccess)

Result of the successful withdrawal request creation

Payment

Defines access points to get Payments

Create payment request

Allows to create request to transfer some amount of asset from source balance to destination account/balance. Payment request is a reviewable request. It uses tasks - bitmask, where each bit represents conditions under which request can be approved. Tasks can be set or cleared both manually(by reviewer) and automatically. Tasks bit mask can be provided either from KeyValueEntry by key payment_tasks:<asset_code> (which specify tasks for asset) or by key payment_tasks:* if there are no payment tasks for provided asset. If field allTasks is set, KeyValueEntry won't be used.

Account Role Requirements

Account Resource Type Reviewable Request Type Action Condition
receiver ASSET - RECEIVE_PAYMENT -
source REVIEWABLE_REQUEST CREATE_PAYMENT CREATE allTasks == null
source REVIEWABLE_REQUEST CREATE_PAYMENT CREATE_WITH_TASKS allTasks != null

Signer Role Requirements

Resource Type Reviewable Request Type Action Condition
REVIEWABLE_REQUEST CREATE_PAYMENT CREATE allTasks == null
REVIEWABLE_REQUEST CREATE_PAYMENT CREATE_WITH_TASKS allTasks != null
CreatePaymentRequestOp
Request
object

Payment request details

AllTasks
uint32

(optional) Bit mask whose flags must be cleared in order for CreateSale request to be approved, which will be used by key sale_create_tasks: instead of key-value

Ext
EmptyExtArmEmptyVersion (object)

reserved for future extension

Response Schema
One of
  • Success
  • InvalidPayment
  • PaymentTasksNotFound
code
string
Value:"SUCCESS"

CreatePaymentRequestOp was successfully applied

success
object (CreatePaymentRequestSuccessResult)

Result of the successful payment request creation

Payment operantion

Allows to transfer some amount of asset from source balance to destination account/balance.

Account Role Requirements

Account Resource Type Action
source ASSET SEND
destination ASSET RECEIVE_PAYMENT

Signer Role Requirements

Resource Type Rule Action
ASSET SEND
PaymentOp

PaymentOp is used to transfer some amount of asset from the source balance to destination account/balance

SourceBalanceId
BalanceId

ID of the source balance of payment

Destination
PaymentOpDestinationArmAccount (object) or PaymentOpDestinationArmBalance (object)

destination defines the type of instance that receives the payment based on given PaymentDestinationType

Amount
uint64

Amount of payment

FeeData
object

feeData defines all data about the payment fee

Subject
string

subject is a user-provided info about the real-life purpose of payment

Reference
string

reference is a string formed by a payment sender. Reference-sender account pair is unique.

Ext
PaymentOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • Malformed
  • Underfunded
  • LineFull
  • DestinationBalanceNotFound
  • BalanceAssetsMismatched
  • SrcBalanceNotFound
  • ReferenceDuplication
  • StatsOverflow
  • LimitsExceeded
  • NotAllowedByAssetPolicy
  • InvalidDestinationFee
  • InsufficientFeeAmount
  • PaymentAmountIsLessThanDestFee
  • DestinationAccountNotFound
  • IncorrectAmountPrecision
code
string
Value:"SUCCESS"

Payment was successfully completed

paymentResponse
object (PaymentResponse)

PaymentResponse defines the response on the corresponding PaymentOp

Balances

Defines operations to manage Balances

Manage Balance

Allows to create new balance.

Account Role Requirements

Account Resource Type Action Condition
source BALANCE CREATE source accountID is equal to destination accountID
source BALANCE CREATE_FOR_OTHER source accountID differs from destination accountID

Signer Role Requirements

Resource Type Rule Action Condition
BALANCE CREATE_FOR_OTHER source accountID is equal to destination accountID
BALANCE CREATE source accountID differs from destination accountID
ManageBalanceOp

ManageBalanceOp applies an action of the ManageBalanceAction type on the balance of a particular asset (referenced to by its AssetCode) of the destination account (referenced to by its AccountID)

Action
string
Enum:"CREATE" "DELETE_BALANCE" "CREATE_UNIQUE"

Defines a ManageBalanceAction to be performed. DELETE_BALANCE is reserved and not implemented yet.

Destination
AccountId

Defines an account whose balance will be managed

Asset
string

Defines an asset code of the balance to which action will be applied

Ext
ManageBalanceOpExtArmEmptyVersion (object)
Response Schema
One of
  • Success
  • Malformed
  • NotFound
  • DestinationNotFound
  • AssetNotFound
  • InvalidAsset
  • BalanceAlreadyExists
  • VersionIsNotSupportedYet
code
string
Value:"SUCCESS"

Indicates that ManageBalanceOp is successfully applied

success
object (ManageBalanceSuccess)

Fees

Defines operations to manage Fees

Fee entry resources

Describes the fee entry which could be set by SetFeesOp.

FeeEntry

FeeEntry is used in the system configuration to set fees for different assets, operations (according to FeeType), particular account roles, particular accounts, or globally (only if both parameters particular account role and paticular account are not specified).

FeeType
string
Enum:"PAYMENT_FEE" "OFFER_FEE" "WITHDRAWAL_FEE" "ISSUANCE_FEE" "INVEST_FEE" "CAPITAL_DEPLOYMENT_FEE" "OPERATION_FEE" "PAYOUT_FEE" "ATOMIC_SWAP_SALE_FEE" "ATOMIC_SWAP_PURCHASE_FEE" "SWAP_FEE"

Type of a particular fee depending on the operation (e.g., PAYMENT_FEE for payment operation, WITHDRAWAL_FEE for withdrawal operation, etc.)

Asset
string

Code of an asset used in the operation for which the fee will be charged

FixedFee
long

Fixed amount of fee that will be charged for the operation

PercentFee
long

Percent from the operation amount that will be charged for the corresponding operation

AccountId
AccountId

(optional) Account for which a fee is set in the system

AccountRole
uint64

(optional) Account for which a fee is set in the system

Subtype
long

Defines a subtype of a fee if such exists (e.g., OUTGOING or INCOMING for PAYMENT_FEE)

LowerBound
long

Defines the lower bound of operation amount for which this fee is applicable

UpperBound
long

Defines the upper bound of operation amount for which this fee is applicable

Hash
array

Hash of type:<feeType>asset:<asset>subtype:<subtype> (Add accountID:<accountID> or accountRole:<accountRole> if corresponding fields are defined)

Ext
FeeEntryExtArmEmptyVersion (object)

reserved for future use

Code samples

Copy
//: `FeeType` represents different types of fees for different operations (e.g. fee charged on withdrawal or on investment)
enum FeeType
{
    PAYMENT_FEE = 0,
    OFFER_FEE = 1,
    WITHDRAWAL_FEE = 2,
    ISSUANCE_FEE = 3,
    INVEST_FEE = 4, // fee to be taken while creating the sale participation
    CAPITAL_DEPLOYMENT_FEE = 5, // fee to be taken when the sale closes
    OPERATION_FEE = 6,
    PAYOUT_FEE = 7,
    ATOMIC_SWAP_SALE_FEE = 8,
    ATOMIC_SWAP_PURCHASE_FEE = 9
};

//: (not used) `EmissionFeeType` is a subtype of `ISSUANCE_FEE`
enum EmissionFeeType
{
    PRIMARY_MARKET = 1,
    SECONDARY_MARKET = 2
};

//: `PaymentFeeType` is a subtype of the Fee used for payments
enum PaymentFeeType
{
    OUTGOING = 1,
    INCOMING = 2
};

//: `FeeEntry` is used in the system configuration to set fees for different assets, operations (according to FeeType), particular account roles, particular accounts,
//: or globally (only if both parameters particular account role and paticular account are not specified).
struct FeeEntry
{
    //: Type of a particular fee depending on the operation (e.g., PAYMENT_FEE for payment operation, WITHDRAWAL_FEE for withdrawal operation, etc.)
    FeeType feeType;
    //: Code of an asset used in the operation for which the fee will be charged
    AssetCode asset;

    //: Fixed amount of fee that will be charged for the operation
    int64 fixedFee;
    //: Percent from the operation amount that will be charged for the corresponding operation
    int64 percentFee;

    //: (optional) Account from which fee would be charged
    AccountID* accountID;
    //: (optional) Account role from which fee would be charged
    uint64*    accountRole;
    //: Defines a `subtype` of a fee if such exists (e.g., `OUTGOING` or `INCOMING` for `PAYMENT_FEE`)
    int64 subtype;

    //: Defines the lower bound of operation amount for which this fee is applicable
    int64 lowerBound;
    //: Defines the upper bound of operation amount for which this fee is applicable
    int64 upperBound;

    //: Hash of `type:<feeType>asset:<asset>subtype:<subtype>`
    //: (Add `accountID:<accountID>` or `accountRole:<accountRole>` if corresponding fields are defined)
    Hash hash;

    //: reserved for future use
    union switch (LedgerVersion v)
    {
    case EMPTY_VERSION:
        void;
    }
    ext;
};

Set Fees

Allows to set or remove relationships between fee entries and particular entities.

Account Role Requirements

Account Resource Type Action
source FEE MANAGE

Signer Role Requirements

Resource Type Rule Action
FEE MANAGE
SetFeesOp

Allows to establish or remove a relationship between a particular fee entry with the different entities

Fee
object

Fee entry to set

IsDelete
boolean

isDelete indicates that a fee should be either set or removed

Ext
SetFeesOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • InvalidAmount
  • InvalidFeeType
  • AssetNotFound
  • InvalidAsset
  • Malformed
  • MalformedRange
  • RangeOverlap
  • NotFound
  • SubTypeNotExist
  • InvalidFeeVersion
  • InvalidFeeAsset
  • FeeAssetNotAllowed
  • CrossAssetFeeNotAllowed
  • FeeAssetNotFound
  • AssetPairNotFound
  • InvalidAssetPairPrice
  • InvalidFeeHash
  • InvalidAmountPrecision
  • AccountNotFound
  • RoleNotFound
code
string
Value:"SUCCESS"

SetFeesOp was successfully applied and a fee was successfully set or deleted

success
object (SetFeesResultSuccess)

External Systems

Bind External System Account ID

Allows to bind source account to external system account ID pool. Only binded account can do deposits.

Account Role Requirements

Account Resource Type Action
source EXTERNAL_SYSTEM_ACCOUNT_ID_POOL_ENTRY BIND

Signer Role Requirements

Resource Type Action
EXTERNAL_SYSTEM_ACCOUNT_ID_POOL_ENTRY BIND
BindExternalSystemAccountIdOp

BindExternalSystemAccountIdOp is used to bind a particular account to the external system account which is represented by account ID taken from the pool

ExternalSystemType
integer

Type of external system to bind

Ext
BindExternalSystemAccountIdOpExtArmEmptyVersion (object)

Reserved for the future use

Response Schema
One of
  • Success
  • Malformed
  • NoAvailableId
code
string
Value:"SUCCESS"

Source account has been successfully bound to external system ID taken from the pool

success
object (BindExternalSystemAccountIdSuccess)

BindExternalSystemAccountIdSuccess represents details of successful result of operation application

Manage External System Pool Entry

Allows to create or remove external system account id pool entry External system account id pool entry can be binded to account.

Account Role Requirements

Account Resource Type Action
source EXTERNAL_SYSTEM_ACCOUNT_ID_POOL_ENTRY MANAGE

Signer Role Requirements

Resource Type Action
EXTERNAL_SYSTEM_ACCOUNT_ID_POOL_ENTRY MANAGE
ManageExternalSystemAccountIdPoolEntryOp

ManageExternalSystemAccountIdPoolEntryOp is used to create or remove an external system account ID from the external system ID pool

ActionInput
ManageExternalSystemAccountIdPoolEntryOpActionInputArmCreate (object) or ManageExternalSystemAccountIdPoolEntryOpActionInputArmRemove (object)

actionInput is used to pass one of ManageExternalSystemAccountIdPoolEntryAction with required params

Ext
ManageExternalSystemAccountIdPoolEntryOpExtArmEmptyVersion (object)

Reserved for future use

Response Schema
One of
  • Success
  • Malformed
  • AlreadyExists
  • NotFound
code
string
Value:"SUCCESS"

Specified action in actionInput of ManageExternalSystemAccountIdPoolEntryOp was performed successfully

success
object (ManageExternalSystemAccountIdPoolEntrySuccess)

Success result of operation application

Atomic Swap

Cancel Atomic Swap Ask Op

Allows to cancel atomic swap bid. If atomic swap bid has non zero locked amount (it means that CREATE_ATOMIC_SWAP_BID request is being processed). It will be marked as canceled and will be removed after all CREATE_ATOMIC_SWAP_BID request will be approved of permament rejected.

Account Role Requirements

No account rule required because only bid owner can perform such operation.

Signer Role Requirements

Resource Type Action
ATOMIC_SWAP_ASK CANCEL
CancelAtomicSwapAskOp

CancelAtomicSwapAskOp is used to cancel existing atomic swap ask

AskId
uint64

id of existing atomic swap ask

Ext
CancelAtomicSwapAskOpExtArmEmptyVersion (object)

reserved for future use

Response Schema
One of
  • Success
  • NotFound
  • AlreadyCancelled
code
string
Value:"SUCCESS"

Atomic swap ask was successfully removed or marked as canceled

success
object (CancelAtomicSwapAskResultSuccess)

Success result of CancelASwapAskOp application

Create Atomic Swap Ask request

Allows to create CREATE_ATOMIC_SWAP_ASK request, which approving creates atomic swap ask. Other accounts will have possibite to create CREATE_ATOMIC_SWAP_BID request for such ask to buy atomic swap ask base asset for the external system currency

Account Role Requirements

Account Resource Type Action Condition
source ATOMIC_SWAP_ASK CREATE allTasks == null
source ATOMIC_SWAP_ASK CREATE_WITH_TASKS allTasks != null

Signer Role Requirements

Resource Type ReviewableRequestType Action
REVIEWABLE_REQUEST CREATE_ATOMIC_SWAP_ASK CREATE
CreateAtomicSwapAskRequestOp

CreateAtomicSwapAskRequestOp is used to create CREATE_ATOMIC_SWAP_ASK request

Request
object

Body of request which will be created

AllTasks
uint32

(optional) Bit mask whose flags must be cleared in order for CREATE_ATOMIC_SWAP_BID request to be approved, which will be used instead of key-value by atomic_swap_bid_tasks key

Ext
CreateAtomicSwapAskRequestOpExtArmEmptyVersion (object)

reserved for the future use

Response Schema
One of
  • Success
  • InvalidAmount
  • InvalidPrice
  • InvalidDetails
  • IncorrectPrecision
  • BaseAssetNotFound
  • BaseAssetCannotBeSwapped
  • QuoteAssetNotFound
  • QuoteAssetCannotBeSwapped
  • BaseBalanceNotFound
  • AssetsAreEqual
  • BaseBalanceUnderfunded
  • InvalidQuoteAsset
  • AtomicSwapAskTasksNotFound
code
string
Value:"SUCCESS"

CREATE_ATOMIC_SWAP_BID request has either been successfully created or auto approved

success
object (CreateAtomicSwapAskRequestSuccess)

Success result of CreateASwapAskCreationRequestOp application

Create Atomic Swap Bid request

Allows to create CREATE_ATOMIC_SWAP_BID request, which approving means:

  • external system currency was received by atomic swap ask owner
  • requestor receives amout of atomic swap ask base asset

Account Role Requirements

Account Resource Type Action
source ASSET RECEIVE_ATOMIC_SWAP

Signer Role Requirements

Resource Type ReviewableRequestType Action
REVIEWABLE_REQUEST CREATE_ATOMIC_SWAP_BID CREATE
CreateAtomicSwapBidRequestOp

CreateAtomicSwapBidRequestOp is used to create CREATE_ATOMIC_SWAP_BID request

Request
object

Body of request which will be created

Ext
CreateAtomicSwapBidRequestOpExtArmEmptyVersion (object)

reserved for the future use

Response Schema
One of
  • Success
  • InvalidBaseAmount
  • InvalidQuoteAsset
  • AskNotFound
  • QuoteAssetNotFound
  • AskUnderfunded
  • AtomicSwapBidTasksNotFound
  • IncorrectPrecision
  • AskIsCancelled
  • SourceAccountEqualsAskOwner
  • AtomicSwapBidZeroTasksNotAllowed
  • QuoteAmountOverflows
code
string
Value:"SUCCESS"

request was successfully created

success
object (CreateAtomicSwapBidRequestSuccess)

Success request of CreateAtomicSwapBidRequestOp application

Signers

Defines operations to manage Signers

Manage Signer

Allows managing signer for source account.

Account Role Requirements

Account Resource Type Action
source SIGNER MANAGE

Signer Role Requirements

Resource Type Action
SIGNER MANAGE
ManageSignerOp

ManageSignerOp is used to create, update or remove a signer

Data
One of multiple values

data is used to pass one of ManageSignerAction with required params

Ext
EmptyExtArmEmptyVersion (object)

reserved for future extension

Response Schema
One of
  • Success
  • InvalidDetails
  • AlreadyExists
  • NoSuchRole
  • InvalidWeight
  • NotFound
  • NumberOfAdminsExceedsLicense
code
string
Value:"SUCCESS"

Specified action in data of ManageSignerOp was successfully executed

ext
EmptyExtArmEmptyVersion (object) (EmptyExt)

Signer Roles

Signer Role - entry that consists of Signer Rules and can be attached to signer.

Manage Signer Role

Allows to create, update or remove signer roles.

Account Role Requirements

Account Resource Type Action
source SIGNER_ROLE MANAGE

Signer Role Requirements

Resource Type Action
SIGNER_ROLE MANAGE
ManageSignerRoleOp

ManageSignerRoleOp is used to create, update or remove a signer role

Data
One of multiple values

data is used to pass one of ManageSignerRoleAction with required params

Ext
ManageSignerRoleOpExtArmEmptyVersion (object)

reserved for future use

Response Schema application/vnd.api+json
One of
  • Success
  • RuleIdDuplication
  • DefaultRuleIdDuplication
  • NoSuchRule
  • TooManyRuleIds
  • NotFound
  • RoleIsUsed
  • InvalidDetails
code
string
Value:"SUCCESS"

Means that the specified action in data of ManageSignerRoleOp was successfully executed

success
object (ManageSignerRoleResultSuccess)

Signer Rules

Signer Rule - entry that defines if action can be performed for resource.

TokenD uses strict policy for rules matching. List of requirements to the roles of participants is formed based on operation (transaction) details. If one of the requirements is not fulfilled, operation is rejected. Requirement is specified for signer and consits of resource and action to be performed. Requirement is fulfilled if signer's role contains matching rule with forbids=false. If one of the matching rules has forbids=true - operation is rejected. If role does not contain any matching rules - operation is rejected.

Manage Signer Rule

Allows to create, update or remove signer rules.

Account Role Requirements

Account Resource Type Action
source SIGNER_RULE MANAGE

Signer Role Requirements

Resource Type Action
SIGNER_RULE MANAGE
ManageSignerRuleOp

ManageSignerRuleOp is used to create, update or remove signer rule

Data
One of multiple values

data is used to pass one of ManageSignerRuleAction with required params

Ext
ManageSignerRuleOpExtArmEmptyVersion (object)

reserved for future use

Response Schema application/vnd.api+json
One of
  • Success
  • RuleIsUsed
  • NotFound
  • InvalidDetails
code
string
Value:"SUCCESS"

Specified action in data of ManageSignerRuleOp was successfully executed

success
object (ManageSignerRuleResultSuccess)

Signer Rules Resources

Describes the resources on which the signer can perform an action.

SignerRuleResource

Describes properties of some entries that can be used to restrict the usage of entries

One of
  • ReviewableRequest
  • Asset
  • Any
  • OfferEntry
  • Sale
  • AtomicSwapAsk
  • SignerRule
  • SignerRole
  • Signer
  • KeyValue
  • Poll
  • Vote
  • InitiateKycRecovery
  • AccountSpecificRule
  • Swap
  • Account
  • Fee
  • Balance
  • PaymentRequest
  • ReferenceEntry
  • Statistics
  • Trust
  • AccountLimits
  • AssetPair
  • ExternalSystemAccountId
  • AccountKyc
  • ExternalSystemAccountIdPoolEntry
  • LimitsV2
  • StatisticsV2
  • PendingStatistics
  • Contract
  • AccountRole
  • AccountRule
  • Transaction
  • Stamp
  • License
type
string
Value:"REVIEWABLE_REQUEST"
reviewableRequest
object (SignerRuleResourceReviewableRequest)

Code samples

Copy
//: Describes properties of some entries that can be used to restrict the use of entries
union SignerRuleResource switch (LedgerEntryType type)
{
case REVIEWABLE_REQUEST:
    //: Describes properties which are equal to managed reviewable request entry fields
    struct
    {
        //: Describes properties of some reviewable request types that
        //: can be used to restrict the using of reviewable requests
        ReviewableRequestResource details;

        //: Bit mask of tasks which is allowed to add to reviewable request pending tasks
        uint64 tasksToAdd;
        //: Bit mask of tasks which is allowed to remove from reviewable request pending tasks
        uint64 tasksToRemove;
        //: Bit mask of tasks which is allowed to use as reviewable request pending tasks
        uint64 allTasks;

        EmptyExt ext;
    } reviewableRequest;
case ASSET:
    //: Describes properties which are equal to managed asset entry fields
    struct
    {
        AssetCode assetCode