You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Figure above shows the message flow during the game setup and playing phase. _A_ and _D_ are players of an off-chain game App channel. Black lines represent messages related to game logic, while purple and orange lines represent conditional payment messages from _A_ and _D_, respectively. Dashed lines indicate direct communication between _A_ and _D_, without involving relay nodes.
48
48
@@ -56,15 +56,15 @@ The steps are summarized as follows:
56
56
57
57
### **Settle the Payments When the Loser Is Cooperative**
Figure above shows the message flow when _A_, after losing the game off-chain, follows the protocol to settle payments cooperatively. The honest loser _A_ initiates the settlement of both conditional payments: [paying the full amount](off-chain-protocols/end-to-end-protocols.md#source-pays-in-full-amount-on-true-outcome) for its own conditional payment to _D_, and [rejecting the conditional payment](off-chain-protocols/end-to-end-protocols.md#destination-rejects-the-payment-on-false-outcome) from _D_. The workflow completes once the winner _D_ confirms settlement of both payments.
62
62
63
63
**There are zero on-chain transactions throughout the entire lifecycle**—from when the two players agree to play the game, to the final prize distribution—so long as all participants behave cooperatively. The App contract and its logic remain purely virtual and only need to appear on-chain in the rare case of a dispute.
64
64
65
65
### **Settle the Payments When the Loser Is Uncooperative**
Figure above shows the message flow when _A_ loses the game but refuses to settle the conditional payments off-chain. To claim the prize, the winner _D_ initiates a dispute, resolves the payment on-chain, and completes settlement with its upstream peer. **Relay nodes (**_**B**_** and **_**C**_**) never need to perform any on-chain transactions**, even when the end players (_A_ and _D_) fail to cooperate.
Copy file name to clipboardExpand all lines: src/agentpay-architecture/off-chain-protocols/end-to-end-protocols.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,7 +32,7 @@ The setup process for an end-to-end multi-hop conditional payment is the same fo
32
32
33
33
The figure below illustrates the message flow where payment source **A** sends a conditional payment to destination **D** through relay nodes **B** and **C**.
The conditional payment is established sequentially through simplex channels **A–B**, **B–C**, and **C–D**, following the [_Send Conditional Payment_](single-hop-protocols.md#send-conditional-payment) procedure described earlier.
38
38
@@ -46,7 +46,7 @@ Once the conditional payment is successfully set up, the nodes along the route c
46
46
47
47
The figure below shows the message flow when the payment source initiates settlement by paying the full amount to its peer. This can occur immediately after **A** receives the `RevealSecretAck` for a payment protected by a single hash lock, or after the associated CelerApp boolean conditions are finalized (off-chain) as _true_.
As shown above, when the condition evaluates to _true_, settlement begins from the payment source (**A**) and proceeds downstream toward the destination (**D**).
52
52
@@ -56,7 +56,7 @@ Each relay node (**B**, **C**) transfers the full amount to its downstream peer
56
56
57
57
The figure below shows the message flow when the payment destination rejects the conditional payment. This occurs after the associated boolean conditions are finalized (off-chain) as _false_.
When a conditional payment should not be paid, cooperative off-chain settlement begins from the payment destination (**D**) and proceeds upstream toward the source (**A**).
62
62
@@ -72,7 +72,7 @@ For payments with **boolean conditions**, relay nodes never need to initiate dis
72
72
73
73
The figure below illustrates a case where the payment destination (**D**) starts an on-chain dispute because it did not receive the full payment amount, possibly due to a failure or malicious action by an upstream node (**A**, **B**, or **C**).
If the destination **D** does not receive the expected settlement, it can submit an on-chain transaction to resolve the payment by conditions. Once the payment result is finalized in the **PayRegistry**, **D** sends a `PaymentSettleProof` message to its upstream peer (**C**) to request settlement.
78
78
@@ -114,7 +114,7 @@ The setup process for an end-to-end multi-hop payment with numeric conditions is
114
114
115
115
The figure below illustrates the cooperative settlement flow for payments with numeric conditions when all nodes behave honestly. The process begins at the payment destination (_D_) once the final payment result is determined to be a value between zero and the maximum amount.
The destination _D_ first sends a `PayResultVouchRequest` to the payment source _A_, producing a co-signed [VouchedCondPayResult](../on-chain-contracts/channel-operations.md#resolve-payment-by-vouched-result) that confirms both parties agree on the payment outcome. Then, _D_ sends a `PaymentSettleProof` message to its upstream peer _C_, using the vouched result as proof. _C_ verifies that the payment is not finalized at a smaller amount by querying the PayRegistry, then pays _D_ the vouched amount off-chain. After receiving the settlement response, _C_ forwards the same vouched result upstream to _B_, which repeats the same process. Finally, _A_ settles with _B_ directly without querying the registry, since _A_ is itself the payment source that signed the vouched result.
120
120
@@ -124,7 +124,7 @@ Relay nodes perform the **PayRegistry check** to protect themselves against pote
124
124
125
125
After a relay node pays its downstream peer the vouched amount, it must ensure it can receive the same amount from its upstream peer. If this does not occur in time—or if the relay detects that the payment has been maliciously resolved on-chain to a smaller amount—it can initiate an on-chain dispute using the co-signed vouched result.
In the example shown, relay node _C_ disputes the payment on-chain after paying _D_ the vouched amount but failing to receive settlement from _B_. _C_ submits a transaction to resolve the payment by vouched result. The **PayResolver** contract guarantees that the finalized result in the **PayRegistry** will never be smaller than the vouched amount submitted by _C_, ensuring that _C_ can always recover at least what it has paid out.
Copy file name to clipboardExpand all lines: src/agentpay-architecture/off-chain-protocols/single-hop-protocols.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ Because both simplex directions operate independently yet symmetrically, the fol
17
17
18
18
Sending a conditional payment involves creating a new co-signed [simplex channel state](../on-chain-contracts/core-data-structures.md#simplex-channel-state) that adds a new entry to the pending pay list (field 5) and updates related metadata. The process requires one round trip of two off-chain messages — `CondPayRequest` and `CondPayResponse`.
**`CondPayRequest`** — sent by the peer initiating or forwarding a conditional payment. It includes:
23
23
@@ -39,7 +39,7 @@ Once a conditional payment’s outcome is finalized, the two peers can cooperati
39
39
40
40
The process uses up to three off-chain messages — `PaymentSettleRequest`, `PaymentSettleResponse`, and (optionally) `PaymentSettleProof`, which is used when the receiving peer initiates the settlement.
**`PaymentSettleRequest`** is sent by the `peer_from` side of the channel to clear one or more payments. It includes:
45
45
@@ -70,7 +70,7 @@ The previous section described the basic single-hop message flow between two cha
70
70
71
71
Unlike TCP or other data transmission protocols, simplex state update messages are not independent packets — each new message depends on the previous simplex state. This means one invalid message invalidates all subsequent messages derived from it. AgentPay modifies the traditional sliding window design to support these dependencies while still achieving high concurrency and throughput.
The figure above illustrates the sliding window workflow under two types of failures: message loss and request rejection. **S** represents the new simplex state, **b** the base sequence number, and **R** the request type (e.g., send or settle). For example, “_S7,b4,R5_” denotes a message carrying a one-signed simplex state with sequence number 7, built on the previous state 4, for request R5. **A** denotes acknowledgment (ACK), and **N** denotes negative acknowledgment (NACK). AgentPay assumes messages may be lost but are always delivered in order, as guaranteed by the underlying transport layer (e.g., [gRPC](https://grpc.io/)).
Copy file name to clipboardExpand all lines: src/agentpay-architecture/on-chain-contracts/contracts-architecture.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Contracts Architecture
2
2
3
-
<figure><imgsrc="../../.gitbook/assets/Screenshot 2025-10-29 at 11.26.58 PM (1).png"alt=""><figcaption></figcaption></figure>
3
+
<imgsrc="../../.gitbook/assets/Screenshot 2025-10-29 at 11.26.58 PM (1).png"alt=""><figcaption></figcaption>
4
4
5
5
The figure above illustrates the AgentPay on-chain contract architecture. The white dashed boxes at the bottom represent user-side off-chain components. Each colored rectangle denotes an individual on-chain contract: blue modules are **AgentPay core contracts** (those with dashed borders are _versioned contracts_ that can evolve over time through peer-agreed migration), while green modules represent **external condition contracts** defined by applications. Orange arrows indicate inter-contract function calls with their primary purpose, and black arrows show user interactions from Agent nodes.
The figure above illustrates the logical data model of an AgentPay state channel between two peers, Alice and Bob. Not all information shown here resides on-chain. The model consists of two types of peer-related data:
Copy file name to clipboardExpand all lines: src/agentpay-architecture/system-overview.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ The system architecture separates payment execution, application logic, and netw
8
8
9
9
### System Architecture 
10
10
11
-
<figure><imgsrc="../.gitbook/assets/Screenshot 2025-10-29 at 10.57.23 AM.png"alt=""><figcaption></figcaption></figure>
11
+
<imgsrc="../.gitbook/assets/Screenshot 2025-10-29 at 10.57.23 AM.png"alt=""><figcaption></figcaption>
12
12
13
13
The figure above illustrates the high-level architecture of the AgentPay network. It consists of three main components: the **payment channel**, the **app channel**, and the **nodes connected by these channels**. Together they enable secure, low-latency economic interactions off-chain, with on-chain settlement only when necessary.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments