mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2026-09-27 15:37:57 +00:00
update vault data types and add number type
This commit is contained in:
Oliver Eggert
@@ -202,6 +202,7 @@ Transactions and ledger entries may contain fields of any of the following types
|
||||
| [Blob][] | 7 | Variable | Yes | Arbitrary binary data. One important such field is `TxnSignature`, the signature that authorizes a transaction. |
|
||||
| [Currency][] | 26 | 160 | No | A currency code, such as one used in [price oracles](../../concepts/decentralized-storage/price-oracles.md). |
|
||||
| [Issue][] | 24 | 160 or 320 | No | An asset definition, XRP or a token, with no quantity. |
|
||||
| [Number][] | 9 | 96 | No | A decimal value with a 64-bit signed mantissa and a 32-bit signed exponent, used for quantities that need more range and fractional precision than an integer type. Vault and lending fields such as `AssetsTotal` are examples of this type. |
|
||||
| [Object][] | 14 | Variable | No | An object containing one or more nested fields. These "inner" objects may have additional formatting restrictions. |
|
||||
| [PathSet][] | 18 | Variable | No | A set of possible [payment paths](../../concepts/tokens/fungible-tokens/paths.md) for a [cross-currency payment](../../concepts/payment-types/cross-currency-payments.md). |
|
||||
| [UInt8][] | 16 | 8 | No | An 8-bit unsigned integer. |
|
||||
@@ -361,6 +362,19 @@ Some fields specify a _type_ of asset, which could be XRP or a fungible [token](
|
||||
2. If the first 160 bits are all 0's (the asset is XRP), the field ends there. Otherwise, the asset is a token and the next 160 bits are the [AccountID of the token issuer](#accountid-fields).
|
||||
|
||||
|
||||
### Number Fields
|
||||
[Number]: #number-fields
|
||||
|
||||
A `Number` is a decimal value stored as two fixed-size integers, serialized in order with no length prefix:
|
||||
|
||||
1. A 64-bit signed mantissa, big-endian, two's complement.
|
||||
2. A 32-bit signed exponent, big-endian, two's complement.
|
||||
|
||||
The value is the mantissa multiplied by 10 raised to the exponent, so the type can represent fractional amounts that a `UInt64` cannot, without being tied to a currency the way an [Amount][] is.
|
||||
|
||||
In JSON, `Number` fields are represented as strings, not as JSON numbers. For example, a vault holding one million units of its asset serializes `AssetsTotal` as `"1000000"`.
|
||||
|
||||
|
||||
### Object Fields
|
||||
[Object]: #object-fields
|
||||
|
||||
|
||||
@@ -51,17 +51,17 @@ In addition to the [common ledger entry fields](../../../protocol/ledger-data/co
|
||||
| `PreviousTxnID` | String | Hash256 | Yes | Identifies the transaction ID that most recently modified this object. |
|
||||
| `PreviousTxnLgrSeq` | Number | UInt32 | Yes | The sequence of the ledger that contains the transaction that most recently modified this object. |
|
||||
| `Sequence` | Number | UInt32 | Yes | The transaction sequence number that created the vault. |
|
||||
| `OwnerNode` | Number | UInt64 | Yes | Identifies the page where this item is referenced in the owner's directory. |
|
||||
| `OwnerNode` | String | UInt64 | Yes | Identifies the page where this item is referenced in the owner's directory. |
|
||||
| `Owner` | String | AccountID | Yes | The account address of the Vault Owner. |
|
||||
| `Account` | String | AccountID | Yes | The address of the vault's pseudo-account. |
|
||||
| `Data` | String | Blob | No | Arbitrary metadata, in hex format, about the vault. Limited to 256 bytes. See [Data Field Format](#data-field-format) for more information. |
|
||||
| `Asset` | Object | Issue | Yes | The asset of the vault. The vault supports XRP, trust line tokens, and MPTs. |
|
||||
| `AssetsTotal` | Number | Number | Yes | The total value of the vault. |
|
||||
| `AssetsAvailable` | Number | Number | Yes | The asset amount that is available in the vault. |
|
||||
| `AssetsMaximum` | Number | Number | No | The maximum asset amount that can be held in the vault. If set to 0, this indicates there is no cap. |
|
||||
| `LossUnrealized` | Number | Number | Yes | The potential loss amount that is not yet realized, expressed as the vault's asset. Only a protocol connected to the vault can modify this attribute. |
|
||||
| `AssetsTotal` | String | Number | Yes | The total value of the vault. Calculated as: `assets available + assets on loan`. |
|
||||
| `AssetsAvailable` | String | Number | Yes | The amount of assets available for loans and withdrawals. |
|
||||
| `AssetsMaximum` | String | Number | No | The maximum amount of assets that can be deposited into the vault. Set to `0` for no cap. |
|
||||
| `LossUnrealized` | String | Number | Yes | The potential loss amount that is not yet realized, expressed as the vault's asset. Only a protocol connected to the vault can modify this attribute. |
|
||||
| `ShareMPTID` | String | UInt192 | Yes | The identifier of the share `MPTokenIssuance` object. |
|
||||
| `WithdrawalPolicy` | String | UInt8 | Yes | Indicates the withdrawal strategy used by the vault. |
|
||||
| `WithdrawalPolicy` | Number | UInt8 | Yes | Indicates the withdrawal strategy used by the vault. |
|
||||
| `Scale` | Number | UInt8 | No | Specifies decimal precision for share calculations. Assets are multiplied by 10<sup>Scale</sup > to convert fractional amounts into whole number shares. For example, with a `Scale` of `6`, depositing 20.3 units creates 20,300,000 shares (20.3 × 10<sup>Scale</sup >). For **trust line tokens** this can be configured at vault creation, and valid values are between 0-18, with the default being `6`. For **XRP** and **MPTs**, this is fixed at `0`. See [Scaling Factor](#scaling-factor) for more information. |
|
||||
|
||||
### Data Field Format
|
||||
|
||||
@@ -42,11 +42,11 @@ Clawbacks cannot be performed on native XRP.
|
||||
|
||||
## {% $frontmatter.seo.title %} Fields
|
||||
|
||||
| Field Name | JSON Type | [Internal Type][] | Required? | Description |
|
||||
| :--------- | :-------- | :---------------- | :-------- | :---------- |
|
||||
| `VaultID` | String | Hash256 | Yes | The unique identifier of the vault from which assets are withdrawn. |
|
||||
| `Holder` | String | AccountID | Yes | The unique identifier of the account from which to claw back the assets. |
|
||||
| `Amount` | Number | Number | No | The asset amount to claw back. When this field is set to 0, the transaction claws back all funds, up to the total shares the `Holder` owns. |
|
||||
| Field Name | JSON Type | [Internal Type][] | Required? | Description |
|
||||
| :--------- | :------------------ | :---------------- | :-------- | :---------- |
|
||||
| `VaultID` | String | Hash256 | Yes | The unique identifier of the vault from which assets are withdrawn. |
|
||||
| `Holder` | String | AccountID | Yes | The unique identifier of the account from which to claw back the assets. |
|
||||
| `Amount` | [Currency Amount][] | Amount | No | The asset amount to claw back. When this field is set to 0, the transaction claws back all funds, up to the total shares the `Holder` owns. |
|
||||
|
||||
If the requested amount exceeds the vault’s available assets, the transaction claws back only up to the vault's `AssetsAvailable` balance. Otherwise, it retrieves the exact asset amount specified in the transaction.
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ In addition to the [common fields](../../../../references/protocol/transactions/
|
||||
|:-------------------|:--------------|:------------------|:----------|:------------------|
|
||||
| `Data` | String | Blob | No | Arbitrary vault metadata, in hex format, limited to 256 bytes. See [Data Field Format](../../ledger-data/ledger-entry-types/vault.md#data-field-format) for the recommended format. |
|
||||
| `Asset` | Object | Issue | Yes | The asset to be held in the vault. This can be XRP, a trust line token, or an MPT. If the asset is a trust line token, the transaction creates a [trust line](../../../../concepts/tokens/fungible-tokens/trust-line-tokens.md#structure) between the vault's pseudo-account and the issuer of the asset. If the asset is an MPT, the transaction creates an `MPToken` object for the vault's pseudo-account. |
|
||||
| `AssetsMaximum` | Number | UInt64 | No | The maximum asset amount that can be held in a vault. |
|
||||
| `AssetsMaximum` | String | Number | No | The maximum asset amount that can be held in a vault. |
|
||||
| `MPTokenMetadata` | String | Blob | No | Arbitrary metadata about the shares issued by the vault, in hex format, limited to 1024 bytes. |
|
||||
| `WithdrawalPolicy` | Number | UInt8 | No | Indicates the withdrawal strategy used by the vault. The default value is `0x0001`, mapped to the string `vaultStrategyFirstComeFirstServe`. See [WithdrawalPolicy](#withdrawalpolicy). |
|
||||
| `DomainID` | String | Hash256 | No | The [PermissionedDomain](../../../../concepts/tokens/decentralized-exchange/permissioned-domains.md) object ID associated with the shares of this vault. If provided, the transaction creates a private vault, which restricts access to accounts with [credentials](../../../../concepts/decentralized-storage/credentials.md) in the specified Permissioned Domain. |
|
||||
|
||||
@@ -55,10 +55,10 @@ If successful, the transaction moves the assets from the depositor's account to
|
||||
|
||||
In addition to the [common fields](../../../protocol/transactions/common-fields#transaction-common-fields), {% code-page-name /%} transactions use the following fields:
|
||||
|
||||
| Field Name | JSON Type | [Internal Type][] | Required? | Description |
|
||||
| :-----------------------| :------------ | :---------------- | :-------- | :-------------------|
|
||||
| `VaultID` | String | Hash256 | Yes | The unique identifier of the vault to which the asset is deposited. |
|
||||
| `Amount` | Object | Amount | Yes | The asset and quantity to be deposited into the vault.|
|
||||
| Field Name | JSON Type | [Internal Type][] | Required? | Description |
|
||||
| :-----------------------| :------------------ | :---------------- | :-------- | :-------------------|
|
||||
| `VaultID` | String | Hash256 | Yes | The unique identifier of the vault to which the asset is deposited. |
|
||||
| `Amount` | [Currency Amount][] | Amount | Yes | The asset and quantity to be deposited into the vault.|
|
||||
|
||||
The deposited asset must match the vault’s designated asset for the transaction to succeed. Depending on the asset type, the following changes occur:
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ Once a vault is created, its public or private status is permanent and cannot be
|
||||
"Sequence": 8,
|
||||
"VaultID": "77D6234D074E505024D39C04C3F262997B773719AB29ACFA83119E4210328776",
|
||||
"Data": "5468697320697320617262697472617279206D657461646174612061626F757420746865207661756C742E",
|
||||
"AssetsMaximum": 5,
|
||||
"AssetsMaximum": "5",
|
||||
"DomainID": "77D6234D074E505024D39C04C3F262997B773719AB29ACFA83119E4210328776"
|
||||
}
|
||||
```
|
||||
@@ -47,7 +47,7 @@ In addition to the [common fields](../../../protocol/transactions/common-fields#
|
||||
| :---------------- | :-------- | :---------------- | :-------- | :-------------------|
|
||||
| `VaultID` | String | Hash256 | Yes | The unique identifier of the vault that needs to be updated. |
|
||||
| `Data` | String | Blob | No | Arbitrary vault metadata, limited to 256 bytes. See [Data Field Format](../../ledger-data/ledger-entry-types/vault.md#data-field-format) for the recommended format. |
|
||||
| `AssetsMaximum` | Number | Number | No | The maximum asset amount that can be held in a vault. The value cannot be lower than the current `AssetsTotal`, unless the value is 0. |
|
||||
| `AssetsMaximum` | String | Number | No | The maximum asset amount that can be held in a vault. The value cannot be lower than the current `AssetsTotal`, unless the value is 0. |
|
||||
| `DomainID` | String | Hash256 | No | The [PermissionedDomain](../../../../concepts/tokens/decentralized-exchange/permissioned-domains.md) object ID associated with the shares of this vault. The `DomainID` is only required when updating a private vault. |
|
||||
|
||||
## {% $frontmatter.seo.title %} Flags
|
||||
|
||||
@@ -48,12 +48,12 @@ A withdrawal whose destination is the issuer of the vault asset is never blocked
|
||||
|
||||
In addition to the [common fields](../../../protocol/transactions/common-fields#transaction-common-fields), {% code-page-name /%} transactions use the following fields:
|
||||
|
||||
| Field Name | JSON Type | [Internal Type][] | Required? | Description |
|
||||
| :-----------------------| :------------ | :---------------- | :-------- | :-------------------|
|
||||
| `VaultID` | String | Hash256 | Yes | The unique identifier of the vault to which the assets are deposited. |
|
||||
| `Amount` | Number | Amount | Yes | The exact amount of vault asset to withdraw or vault share to redeem. |
|
||||
| `Destination` | String | AccountID | No | An account to receive the assets. This account must be able to receive the vault asset or the transaction fails. |
|
||||
| `DestinationTag` | Number | UInt32 | No | Arbitrary tag identifying the reason for the withdrawal to the destination. |
|
||||
| Field Name | JSON Type | [Internal Type][] | Required? | Description |
|
||||
| :-----------------------| :------------------ | :---------------- | :-------- | :-------------------|
|
||||
| `VaultID` | String | Hash256 | Yes | The unique identifier of the vault to which the assets are deposited. |
|
||||
| `Amount` | [Currency Amount][] | Amount | Yes | The exact amount of vault asset to withdraw or vault share to redeem. |
|
||||
| `Destination` | String | AccountID | No | An account to receive the assets. This account must be able to receive the vault asset or the transaction fails. |
|
||||
| `DestinationTag` | Number | UInt32 | No | Arbitrary tag identifying the reason for the withdrawal to the destination. |
|
||||
|
||||
There are two ways to specify the transaction `Amount` field:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user