From 495aa244b0de359cf38de80d67a08bf3be87fbb1 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Fri, 4 Sep 2026 14:55:55 -0700 Subject: [PATCH] update vault data types and add number type --- docs/references/protocol/binary-format.md | 14 ++++++++++++++ .../ledger-data/ledger-entry-types/vault.md | 12 ++++++------ .../protocol/transactions/types/vaultclawback.md | 10 +++++----- .../protocol/transactions/types/vaultcreate.md | 2 +- .../protocol/transactions/types/vaultdeposit.md | 8 ++++---- .../protocol/transactions/types/vaultset.md | 4 ++-- .../protocol/transactions/types/vaultwithdraw.md | 12 ++++++------ 7 files changed, 38 insertions(+), 24 deletions(-) diff --git a/docs/references/protocol/binary-format.md b/docs/references/protocol/binary-format.md index 4d58d70b5..a03f2e0a6 100644 --- a/docs/references/protocol/binary-format.md +++ b/docs/references/protocol/binary-format.md @@ -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 diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/vault.md b/docs/references/protocol/ledger-data/ledger-entry-types/vault.md index 0ed24d266..cc7e17662 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/vault.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/vault.md @@ -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 10Scale 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 × 10Scale). 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 diff --git a/docs/references/protocol/transactions/types/vaultclawback.md b/docs/references/protocol/transactions/types/vaultclawback.md index b822aa509..bac460f94 100644 --- a/docs/references/protocol/transactions/types/vaultclawback.md +++ b/docs/references/protocol/transactions/types/vaultclawback.md @@ -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. diff --git a/docs/references/protocol/transactions/types/vaultcreate.md b/docs/references/protocol/transactions/types/vaultcreate.md index 41fb0c027..6b7115ae4 100644 --- a/docs/references/protocol/transactions/types/vaultcreate.md +++ b/docs/references/protocol/transactions/types/vaultcreate.md @@ -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. | diff --git a/docs/references/protocol/transactions/types/vaultdeposit.md b/docs/references/protocol/transactions/types/vaultdeposit.md index 87105a3d3..bba5f01ec 100644 --- a/docs/references/protocol/transactions/types/vaultdeposit.md +++ b/docs/references/protocol/transactions/types/vaultdeposit.md @@ -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: diff --git a/docs/references/protocol/transactions/types/vaultset.md b/docs/references/protocol/transactions/types/vaultset.md index 413f02790..11669cb1e 100644 --- a/docs/references/protocol/transactions/types/vaultset.md +++ b/docs/references/protocol/transactions/types/vaultset.md @@ -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 diff --git a/docs/references/protocol/transactions/types/vaultwithdraw.md b/docs/references/protocol/transactions/types/vaultwithdraw.md index b9034f613..ebe8dd10d 100644 --- a/docs/references/protocol/transactions/types/vaultwithdraw.md +++ b/docs/references/protocol/transactions/types/vaultwithdraw.md @@ -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: