Walkthrough
Follow a complete multi-party cross-chain settlement where a Builder sells tokenized real estate to two Buyers, with a Notary receiving fees across Ethereum and Polygon.
This walkthrough demonstrates a complex multi-party HTLC settlement involving four parties across two blockchains. You'll see how XvP coordinates cross-chain exchanges and handles multiple flows.
Prerequisites
This walkthrough assumes you understand how HTLC works. If you're new to HTLCs, we recommend reading the HTLC explanation first to learn about hashlocks, timelocks, and why the mechanism is cryptographically secure.
Scenario: Tokenized real estate sale
The parties
| Party | Role | Chain |
|---|---|---|
| Builder | Sells property tokens | Ethereum |
| Buyer 1 | Purchases 50% ownership | Polygon |
| Buyer 2 | Purchases 50% ownership | Polygon |
| Notary | Handles legal transfer, receives fee | Polygon |
The deal
- Builder sells an apartment tokenized as 100 APT-101 tokens on Ethereum
- Buyer 1 and Buyer 2 each purchase 50% (50 tokens each)
- Total price: 500,000 USDC + 5,000 USDC notary fee
| Item | Amount |
|---|---|
| Property price | 500,000 USDC |
| Buyer 1's share | 250,000 USDC + 2,500 notary fee |
| Buyer 2's share | 250,000 USDC + 2,500 notary fee |
| Notary fee | 5,000 USDC total |
Settlement structures
Ethereum settlement (created by Builder)
| Field | Value |
|---|---|
| Local flows | |
| Flow 1 | Builder → Buyer 1: 50 APT-101 |
| Flow 2 | Builder → Buyer 2: 50 APT-101 |
| External flows (informational) | |
| Flow 3 | Buyer 1 → Builder: 250,000 USDC (on Polygon) |
| Flow 4 | Buyer 2 → Builder: 250,000 USDC (on Polygon) |
| Flow 5 | Buyer 1 → Notary: 2,500 USDC (on Polygon) |
| Flow 6 | Buyer 2 → Notary: 2,500 USDC (on Polygon) |
| Hashlock | 0xdef456... |
| Timelock | January 20, 2025 at 5:00 PM |
| Auto-execute | Enabled |
Polygon settlement (created by Buyer 1)
| Field | Value |
|---|---|
| Local flows | |
| Flow 1 | Buyer 1 → Builder: 250,000 USDC |
| Flow 2 | Buyer 2 → Builder: 250,000 USDC |
| Flow 3 | Buyer 1 → Notary: 2,500 USDC |
| Flow 4 | Buyer 2 → Notary: 2,500 USDC |
| External flows (informational) | |
| Flow 5 | Builder → Buyer 1: 50 APT-101 (on Ethereum) |
| Flow 6 | Builder → Buyer 2: 50 APT-101 (on Ethereum) |
| Hashlock | 0xdef456... (same as Ethereum) |
| Timelock | January 19, 2025 at 5:00 PM (24 hours before Ethereum) |
| Auto-execute | Enabled |
Only senders approve
On Ethereum, only the Builder approves (sending tokens). On Polygon, only Buyer 1 and Buyer 2 approve (sending USDC). Recipients don't take action.
Balance tracking
Ethereum chain
| Step | Action | Builder | Buyer 1 | Buyer 2 | XvP Contract |
|---|---|---|---|---|---|
| Initial | - | 100 APT-101 | 0 | 0 | 0 |
| Create | Builder creates settlement | 100 APT-101 | 0 | 0 | 0 |
| Approve | Builder approves → Armed | 0 | 0 | 0 | 100 APT-101 |
| Execute | Secret revealed | 0 | 50 APT-101 | 50 APT-101 | 0 |
Polygon chain
| Step | Action | Builder | Notary | Buyer 1 | Buyer 2 | XvP Contract |
|---|---|---|---|---|---|---|
| Initial | - | 0 | 0 | 252,500 USDC | 252,500 USDC | 0 |
| Create | Buyer 1 creates settlement | 0 | 0 | 252,500 USDC | 252,500 USDC | 0 |
| Approve 1 | Buyer 1 approves | 0 | 0 | 0 | 252,500 USDC | 252,500 USDC |
| Approve 2 | Buyer 2 approves → Armed | 0 | 0 | 0 | 0 | 505,000 USDC |
| Execute | Secret revealed | 500,000 USDC | 5,000 USDC | 0 | 0 | 0 |
Step-by-step walkthrough
Builder generates the secret
Builder opens the settlement wizard on Ethereum and generates a cryptographic secret:
- Secret:
0x7a8b9c...(Builder saves this securely) - Hashlock:
keccak256(secret) = 0xdef456...
The Builder keeps the secret private and shares only the hashlock with the Buyers.
Builder creates settlement on Ethereum
Builder configures the settlement:
- Adds two local flows (property tokens to each Buyer)
- Adds four external flows (USDC from Buyers on Polygon)
- Sets timelock to January 20, 2025 at 5:00 PM
- Enables auto-execute
- Submits the transaction
Builder shares hashlock with Buyers
Builder shares the hashlock 0xdef456... with Buyer 1 and Buyer 2. The Buyers can verify:
- The settlement exists on Ethereum
- It contains the correct flows (they'll receive property tokens)
- The hashlock matches what they'll use on Polygon
Important: Builder does NOT share the secret yet - only the hashlock.
Buyer 1 creates settlement on Polygon
Buyer 1 creates the matching settlement on Polygon:
- Adds four local flows (USDC from both Buyers to Builder and Notary)
- Enters the same hashlock
0xdef456... - Sets timelock to January 19, 2025 at 5:00 PM (24 hours before Ethereum)
- Enables auto-execute
- Submits the transaction
Builder approves on Ethereum
Builder approves the Ethereum settlement:
- Opens the settlement detail page
- Clicks Approve
- Confirms the transaction (transfers 100 APT-101 to the XvP contract)
The Ethereum settlement enters Armed state (only one local sender: Builder).
Buyers approve on Polygon
Buyer 1 approves:
- Opens the Polygon settlement
- Clicks Approve
- Confirms (transfers 252,500 USDC to XvP contract)
Settlement shows "1 of 2 approvals."
Buyer 2 approves:
- Opens the Polygon settlement
- Clicks Approve
- Confirms (transfers 252,500 USDC to XvP contract)
The Polygon settlement enters Armed state.
Builder reveals secret on Polygon
Builder reveals the secret to claim the USDC:
- Opens the Polygon settlement
- Clicks Reveal Secret
- Enters the secret
0x7a8b9c... - Confirms the transaction
Auto-execute triggers immediately:
- Builder receives 500,000 USDC
- Notary receives 5,000 USDC
The Polygon settlement is now Executed.
Secret is revealed on Ethereum
Now that the secret is public (visible on Polygon), anyone can use it on Ethereum.
Option A: Buyers find the secret on-chain in the Polygon transaction.
Option B: Builder emails the secret to Buyers (it's already public, no security risk).
One of the Buyers reveals the secret on Ethereum:
- Opens the Ethereum settlement
- Clicks Reveal Secret
- Enters
0x7a8b9c... - Confirms
Auto-execute triggers immediately:
- Buyer 1 receives 50 APT-101
- Buyer 2 receives 50 APT-101
The Ethereum settlement is now Executed.
What if something goes wrong?
| Scenario | What happens |
|---|---|
| Secret never revealed before January 19 | Polygon settlement expires. Buyers withdraw their USDC. |
| Secret revealed on Polygon but not Ethereum before January 20 | Buyers have until January 20 to reveal on Ethereum. After that, Builder can withdraw property tokens. |
| One Buyer doesn't approve on Polygon | Settlement never reaches Armed state. After timelock, all approved parties can withdraw. |
| Network congestion on Ethereum | Buyers should reveal the secret well before the January 20 deadline to account for delays. |
Next steps
HTLC explained
Understand how Hash Time-Locked Contracts enable trustless cross-chain asset exchanges. Learn about hashlocks, timelocks, and why the mechanism is cryptographically secure.
Create
Learn how to create a new XvP settlement using the wizard. Configure flows, set cutoff dates, and enable cross-chain coordination with hashlocks.