Skip to content

Commit

Permalink
Merge branch 'xchain-bridge-docs' of https://github.com/XRPLF/xrpl-de…
Browse files Browse the repository at this point in the history 
…v-portal into xchain-bridge-docs
  • Loading branch information
@oeggert
oeggert committed Jan 9, 2024
2 parents 3d01278 + 5520788 commit 4d5db1a
Show file tree
Hide file tree
Showing 4 changed files with 445 additions and 1 deletion.
229 changes: 229 additions & 0 deletions content/_img-sources/serialization-xchainbridge.uxf
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,229 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<diagram program="umlet" version="14.2">
<zoom_level>10</zoom_level>
<element>
<id>UMLClass</id>
<coordinates>
<x>770</x>
<y>240</y>
<w>310</w>
<h>30</h>
</coordinates>
<panel_attributes>Issuer AccountID (160 bits)
lt=.</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>480</x>
<y>240</y>
<w>280</w>
<h>30</h>
</coordinates>
<panel_attributes>Currency code (160 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>460</x>
<y>90</y>
<w>400</w>
<h>160</h>
</coordinates>
<panel_attributes>lt=..</panel_attributes>
<additional_attributes>10.0;140.0;380.0;10.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>1080</x>
<y>90</y>
<w>30</w>
<h>160</h>
</coordinates>
<panel_attributes>lt=..</panel_attributes>
<additional_attributes>10.0;140.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>50</x>
<y>30</y>
<w>160</w>
<h>30</h>
</coordinates>
<panel_attributes>XChainBridge Format</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>50</x>
<y>60</y>
<w>1050</w>
<h>50</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>580</x>
<y>200</y>
<w>240</w>
<h>30</h>
</coordinates>
<panel_attributes>STIssue Format</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>470</x>
<y>230</y>
<w>620</w>
<h>50</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>100</x>
<y>70</y>
<w>210</w>
<h>30</h>
</coordinates>
<panel_attributes>Locking chain door (160 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>320</x>
<y>70</y>
<w>250</w>
<h>30</h>
</coordinates>
<panel_attributes>Locking Chain Issue</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>60</x>
<y>70</y>
<w>40</w>
<h>30</h>
</coordinates>
<panel_attributes>0x14</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>100</x>
<y>120</y>
<w>270</w>
<h>40</h>
</coordinates>
<panel_attributes>Door account length prefixes (8 bits)
Always 0x14</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>60</x>
<y>90</y>
<w>60</w>
<h>70</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;50.0;40.0;50.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>580</x>
<y>70</y>
<w>40</w>
<h>30</h>
</coordinates>
<panel_attributes>0x14</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>360</x>
<y>90</y>
<w>250</w>
<h>70</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>230.0;10.0;230.0;50.0;10.0;50.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>620</x>
<y>70</y>
<w>210</w>
<h>30</h>
</coordinates>
<panel_attributes>Issuing chain door (160 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>840</x>
<y>70</y>
<w>250</w>
<h>30</h>
</coordinates>
<panel_attributes>Issuing Chain Issue</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>770</x>
<y>260</y>
<w>60</w>
<h>70</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;50.0;40.0;50.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>810</x>
<y>290</y>
<w>270</w>
<h>30</h>
</coordinates>
<panel_attributes>Omitted if the currency code is all 0's</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>170</x>
<y>210</y>
<w>260</w>
<h>80</h>
</coordinates>
<panel_attributes>*Note:*
Unlike in Object and Array fields, the nested STIssue types here do not begin with a Field ID.
bg=yellow
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
</diagram>
21 changes: 20 additions & 1 deletion content/references/protocol/binary-format.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ Transaction instructions may contain fields of any of the following types:
| [UInt8][] | 16 | 8 | No | An 8-bit unsigned integer. |
| [UInt16][] | 1 | 16 | No | A 16-bit unsigned integer. The `TransactionType` is a special case of this type, with specific strings mapping to integer values. |
| [UInt32][] | 2 | 32 | No | A 32-bit unsigned integer. The `Flags` and `Sequence` fields on all transactions are examples of this type. |
| XCHAIN_BRIDGE | 25 | Variable | No | A bridge between two blockchains, identified by the door accounts and issued assets on the locking chain and issuing chain. `XCHAIN_BRIDGE` is serialized in this order: locking chain door, locking chain issue, issuing chain door, issuing chain issue. |
| [XChainBridge][] | 25 | Variable | No | A bridge between two blockchains, identified by the door accounts and issued assets on both chains. |

[Length-prefixed]: #length-prefixing

Expand Down Expand Up @@ -369,6 +369,25 @@ When representing these fields in JSON objects, most are represented as JSON num

Another special case is the `TransactionType` field. In JSON, this field is conventionally represented as a string with the name of the transaction type, but in binary, this field is a UInt16. The `TRANSACTION_TYPES` object in the [definitions file](#definitions-file) maps these strings to specific numeric values.


### XChainBridge Fields
[XChainBridge]: #xchainbridge-fields

{{ include_svg("img/serialization-xchainbridge.svg", "XChainBridge format diagram") }}

The `XChainBridge` field, used in transactions and ledger entries related to [cross-chain bridges](cross-chain-bridges.html), is the only field of the XChainBridge type. It consists of 4 parts which together define a bridge between blockchains:

- The locking chain door account, a length-prefixed [AccountID][].
- The locking chain asset type, an [STIssue][].
- The issuing chain door account, a length-prefixed [AccountID][].
- The issuing chain asset type, an [STIssue][].

The two nested [STIssue][] types are each either 160 or 320 bits. The STIssue field is 160 bits if the currency code it contains is all 0's, meaning that the bridged asset is the native asset of its respective chain, for example XRP on the XRP Ledger Mainnet. If the currency code is nonzero, then the STIssue field also contains the (non-length-prefixed) AccountID of the token's issuer on its native chain.

**Note:** The door AccountID values are length-prefixed, but the issuer AccountID values are not.

In total, an XChainBridge field is always either 656, 816, or 976 bits (82, 102, or 122 bytes) depending on whether zero, one, or both of the assets are the native asset on their respective chain.

<!-- SPELLING_IGNORE: pathset, stobject, starray, ledgerentry, vector256, accountids, uint -->
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
Expand Down
1 change: 1 addition & 0 deletions dactyl-config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3004,6 +3004,7 @@ pages:
- en

- md: "@i18n/ja/references/protocol/binary-format.md"
outdated_translation: true
targets:
- ja

Expand Down
Loading

0 comments on commit 4d5db1a

Please sign in to comment.