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

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 beacuse 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 beacuse only current asset pre issuer can change asset pre issuer

Signer Role Requirements

No signer rule required beacuse 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

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

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 UPDATE_LIMITS CREATE allTasks == null
source REVIEWABLE_REQUEST UPDATE_LIMITS 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 beacuse 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

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"

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

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

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

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
  • 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;
        uint64 assetType;

        EmptyExt ext;
    } asset;
case ANY:
    void;
case OFFER_ENTRY:
    //: Describes properties which are equal to managed offer entry fields and their properties
    struct
    {
        //: type of base asset
        uint64 baseAssetType;
        //: type of quote asset
        uint64 quoteAssetType;

        //: code of base asset
        AssetCode baseAssetCode;
        //: code of quote asset
        AssetCode quoteAssetCode;

        bool isBuy;

        EmptyExt ext;
    } offer;
case SALE:
    //: Describes properties which are equal to managed offer entry fields
    struct
    {
        uint64 saleID;
        uint64 saleType;

        EmptyExt ext;
    } sale;
case ATOMIC_SWAP_BID:
    struct
    {
        uint64 assetType;
        AssetCode assetCode;

        EmptyExt ext;
    } atomicSwapBid;
case SIGNER_RULE:
    //: Describes properties which are equal to managed signer rule entry fields
    struct
    {
        //: True means that resource will be triggered if default rule is managed
        //: or changing of `isDefault` property for signer rule
        bool isDefault;

        EmptyExt ext;
    } signerRule;
case SIGNER_ROLE:
    //: Describes properties which are equal to managed signer role entry fields
    struct
    {
        //: For signer role creating resource will be triggered if `roleID` equals `0`
        uint64 roleID;

        EmptyExt ext;
    } signerRole;
case SIGNER:
    //: Describes properties which are equal to managed signer entry fields
    struct
    {
        uint64 roleID;

        EmptyExt ext;
    } signer;
case KEY_VALUE:
    //: Describes properties which are equal to managed key value entry fields
    struct
    {
        //: prefix of key
        longstring keyPrefix;

        //: reserved for future extension
        EmptyExt ext;
    } keyValue;
default:
    //: reserved for future extension
    EmptyExt ext;
};

Account Roles

Account Role - entry that consists of Account Rules and can be attached to account.

Manage Account Role

Allows to create, update or remove account roles.

Account Role Requirements

Account Resource Type Action
source ACCOUNT_ROLE MANAGE

Signer Role Requirements

Resource Type Action
ACCOUNT_ROLE MANAGE
ManageAccountRoleOp

ManageAccountRoleOp is used to create, update or remove account role

Data
One of multiple values

data is used to pass one of ManageAccountRoleAction with required params

Ext
ManageAccountRoleOpExtArmEmptyVersion (object)

reserved for future use

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

This means that the specified action in data of ManageAccountRoleOp was successfully performed

success
object (ManageAccountRoleResultSuccess)

Account Rules

Account Rule 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 account and consits of resource and action to be performed. Requirement is fulfilled if account'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.

Account Rules Resources

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

AccountRuleResource

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

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

Code samples

Copy
//: Describes properties of some entries that can be used to restrict the use of entries
union AccountRuleResource switch (LedgerEntryType type)
{
case ASSET:
    //: Describes properties which are equal to managed asset entry fields
    struct
    {
        AssetCode assetCode;
        uint64 assetType;

        EmptyExt ext;
    } asset;
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;

        //: reserved for future extension
        EmptyExt ext;
    } reviewableRequest;
case ANY:
    void;
case OFFER_ENTRY:
    //: Describes properties which are equal to managed offer entry fields and their properties
    struct
    {
        //: type of base asset
        uint64 baseAssetType;
        //: type of quote asset
        uint64 quoteAssetType;

        //: code of base asset
        AssetCode baseAssetCode;
        //: code of quote asset
        AssetCode quoteAssetCode;

        bool isBuy;

        //: reserved for future extension
        EmptyExt ext;
    } offer;
case SALE:
    //: Describes properties which are equal to managed offer entry fields
    struct
    {
        uint64 saleID;
        uint64 saleType;

        //: reserved for future extension
        EmptyExt ext;
    } sale;
case ATOMIC_SWAP_BID:
    struct
    {
        uint64 assetType;
        AssetCode assetCode;

        EmptyExt ext;
    } atomicSwapBid;
case KEY_VALUE:
    struct
    {
        //: prefix of key
        longstring keyPrefix;

        //: reserved for future extension
        EmptyExt ext;
    } keyValue;
default:
    //: reserved for future extension
    EmptyExt ext;
};

//: Describes properties of some reviewable request types that
//: can be used to restrict the using of reviewable requests
union ReviewableRequestResource switch (ReviewableRequestType requestType)
{
case CREATE_SALE:
    //: is used to restrict using of reviewable request with create_sale type
    struct
    {
        //: type of sale
        uint64 type;

        //: reserved for future extension
        EmptyExt ext;
    } createSale;
case CREATE_ISSUANCE:
    //: is used to restrict using of reviewable request with create_issuance type
    struct
    {
        //: code of asset
        AssetCode assetCode;
        //: type of asset
        uint64 assetType;

        //: reserved for future extension
        EmptyExt ext;
    } createIssuance;
case CREATE_WITHDRAW:
    //: is used to restrict using of reviewable request with create_withdraw type
    struct
    {
        //: code of asset
        AssetCode assetCode;
        //: type of asset
        uint64 assetType;

        //: reserved for future extension
        EmptyExt ext;
    } createWithdraw;
default:
    //: reserved for future extension
    EmptyExt ext;
};

Manage Account Rule

Allows to create, update or remove account rules.

Account Role Requirements

Account Resource Type Action
source ACCOUNT_RULE MANAGE

Signer Role Requirements

Resource Type Action
ACCOUNT_RULE MANAGE
ManageAccountRuleOp

ManageAccountRuleOp is used to create, update or remove account rule

Data
One of multiple values

data is used to pass one of ManageAccountRuleAction with required params

Ext
ManageAccountRuleOpExtArmEmptyVersion (object)

reserved for future use

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

Means that specified action in data of ManageAccountRuleOp was successfully performed

success
object (ManageAccountRuleResultSuccess)

Account Specific Rules

Account Specific Rules are similar in functionality to Account Rules - they define permissions to interact with various TokenD entities on account level. The main difference between Account Specific Rules and Account Rules is that with Account Specific Rules it's possible to define permissions for particular account without need to create separate role for this account. What is more, Account Specific Rules are managed by both Admins and entry owners. Main use case for this feature is white/black lists for particular entity. In current version it's only possible to manage white/black lists for sales.

Create Account Specific Rule

Allows to create account specific rules. Only rules for sales now supported.

Account Role Requirements

No account rule required beacuse only entry owner or admin can create specific rules

Signer Role Requirements

Resource Type Action
ACCOUNT_SPECIFIC_RULE CREATE
ManageAccountSpecificRuleOp

ManageAccountSpecificRuleOp is used to create or remove account specific rule

Data
ManageAccountSpecificRuleOpDataArmCreate (object) or ManageAccountSpecificRuleOpDataArmRemove (object)

data is used to pass one of ManageAccountSpecificRuleAction with required params

Ext