From ff4da20a73ad407f98c25b4dc7b079bb9f332274 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Mon, 8 Sep 2025 11:05:22 -0300
Subject: [PATCH 01/12] doc: onramp token transfer flow

---
 docs/contracts/flow.md | 74 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/contracts/flow.md

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
new file mode 100644
index 000000000..3bee8655b
--- /dev/null
+++ b/docs/contracts/flow.md
@@ -0,0 +1,74 @@
+# CCIP Flow
+
+## Token Transfer
+
+### Token Transfer OnRamp Flow
+
+```mermaid
+---
+config:
+  sequence:
+    
+---
+sequenceDiagram
+    box User 
+    participant U as User
+    participant UJW as User's <br>Jetton A Wallet
+    end
+
+    box Router
+    participant R as Router
+    participant RJW as Router's <br>Jetton A Wallet
+    end
+
+    participant FQ as FeeQuoter
+
+    box Token Registry<br>(not a contract but<br>a collection)
+    participant TRC as TR Cell (Jetton A)
+    end
+
+    box Token Pools
+    participant TP as Token Pool A
+    participant TPJW as TokenPool's <br>Jetton A Wallet
+    end
+
+    U ->> UJW: TransferRequest {<br>amount,<br>destination: Router,<br>fwdPayload: ccipSend }
+    
+    UJW ->> RJW: Transfer { amount,<br>fwdPayload: ccipSend }
+    RJW ->> R: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
+    Note over R: Check enough TON for gas 
+    R ->> FQ: getValidatedFee{ccipSend}
+
+    alt not enough to cover fee
+    FQ ->> R: feeNotValidated{ccipSend}
+    Note over R: Refund Jettons [...]
+
+    else enough to cover for fee
+    FQ ->> R: feeValidated{ccipSend}
+    Note over R: Calculate TR Cell based<br>on Token Addres
+
+    R ->> TRC: GetTokenPoolInfo{ccipSend}
+
+    alt Token not supported (contract not deployed)
+    TRC ->> R: Bounced{GetTokenPoolInfo{ccipSend}}
+    Note over R: TODO where do we store the<br>relevant info to refund the sender?
+    else Supported Token
+    TRC ->> R: TokenPoolInfo{tokenPoolAddress, ccipSend}
+ 
+    R ->> RJW: TransferRequest {<br>amount,<br>destination: Router,<br>responseDestination: Router,<br>fwdPayload: ccipSend }
+    
+    RJW ->> TPJW: Transfer { amount,<br>fwdPayload: ccipSend }
+    TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend }
+    participant OR as OnRamp
+    Note over TP: consume rate limit
+    alt Rate limit error
+    Note over TP: Refund Jettons [...]
+
+    else Consumes rate limit
+    TP ->> R: commitedLockOrBurn{ccipSend}
+    R ->> OR: send{ccipSend}
+    note over OR  : ...
+    end
+    end
+    end
+```
\ No newline at end of file

From 3898b11900fe7cd39ba911117542b20cfc657f69 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Mon, 8 Sep 2025 11:24:46 -0300
Subject: [PATCH 02/12] fix: move logic to onramp

---
 docs/contracts/flow.md | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index 3bee8655b..b4ee28ee4 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -21,6 +21,8 @@ sequenceDiagram
     participant RJW as Router's <br>Jetton A Wallet
     end
 
+    participant OR as OnRamp
+
     participant FQ as FeeQuoter
 
     box Token Registry<br>(not a contract but<br>a collection)
@@ -37,36 +39,41 @@ sequenceDiagram
     UJW ->> RJW: Transfer { amount,<br>fwdPayload: ccipSend }
     RJW ->> R: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
     Note over R: Check enough TON for gas 
-    R ->> FQ: getValidatedFee{ccipSend}
+    R ->> OR: ccipSend
+
+    OR ->> FQ: getValidatedFee{ccipSend}
+
 
     alt not enough to cover fee
-    FQ ->> R: feeNotValidated{ccipSend}
-    Note over R: Refund Jettons [...]
+    FQ ->> OR: feeNotValidated{ccipSend}
+    Note over OR: Refund Jettons [...]
 
     else enough to cover for fee
-    FQ ->> R: feeValidated{ccipSend}
-    Note over R: Calculate TR Cell based<br>on Token Addres
+    FQ ->> OR: feeValidated{ccipSend}
+    Note over OR: Calculate TR Cell based<br>on Token Addres
 
-    R ->> TRC: GetTokenPoolInfo{ccipSend}
+    OR ->> TRC: GetTokenPoolInfo{ccipSend}
 
     alt Token not supported (contract not deployed)
-    TRC ->> R: Bounced{GetTokenPoolInfo{ccipSend}}
-    Note over R: TODO where do we store the<br>relevant info to refund the sender?
+    TRC ->> OR: Bounced{GetTokenPoolInfo{ccipSend}}
+    Note over OR: TODO where do we store the<br>relevant info to refund the sender?
     else Supported Token
-    TRC ->> R: TokenPoolInfo{tokenPoolAddress, ccipSend}
+
+    TRC ->> OR: TokenPoolInfo{tokenPoolAddress, ccipSend}
+
+    OR ->> R: lockTokens{tokenPoolAddr, ccipSend}
  
     R ->> RJW: TransferRequest {<br>amount,<br>destination: Router,<br>responseDestination: Router,<br>fwdPayload: ccipSend }
     
     RJW ->> TPJW: Transfer { amount,<br>fwdPayload: ccipSend }
     TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend }
-    participant OR as OnRamp
     Note over TP: consume rate limit
     alt Rate limit error
     Note over TP: Refund Jettons [...]
 
     else Consumes rate limit
-    TP ->> R: commitedLockOrBurn{ccipSend}
-    R ->> OR: send{ccipSend}
+    TP ->> OR: commitedLockOrBurn{ccipSend}
+    OR ->> OR: send{ccipSend}
     note over OR  : ...
     end
     end

From 4a3ae8e35e423e533d11d399e4942cacfc714db0 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Mon, 8 Sep 2025 11:27:27 -0300
Subject: [PATCH 03/12] fix: name on destination

---
 docs/contracts/flow.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index b4ee28ee4..7cafcefc7 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -63,7 +63,7 @@ sequenceDiagram
 
     OR ->> R: lockTokens{tokenPoolAddr, ccipSend}
  
-    R ->> RJW: TransferRequest {<br>amount,<br>destination: Router,<br>responseDestination: Router,<br>fwdPayload: ccipSend }
+    R ->> RJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: ccipSend }
     
     RJW ->> TPJW: Transfer { amount,<br>fwdPayload: ccipSend }
     TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend }

From 1834fc4672936287644e122ea8540c0b3bdb6586 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Mon, 8 Sep 2025 18:41:59 -0300
Subject: [PATCH 04/12] fix: reduce dependance of onramp fix: handle bounced
 messages

---
 docs/contracts/flow.md | 55 ++++++++++++++++++++++++------------------
 1 file changed, 32 insertions(+), 23 deletions(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index 7cafcefc7..de23b4d71 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -17,15 +17,33 @@ sequenceDiagram
     end
 
     box Router
-    participant R as Router
     participant RJW as Router's <br>Jetton A Wallet
+    participant R as Router
     end
 
+    U ->> UJW: TransferRequest {<br>amount,<br>destination: Router,<br>fwdPayload: ccipSend }
+    
+    UJW ->> RJW: Transfer { amount,<br>fwdPayload: ccipSend }
+    RJW ->> R: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
+    Note over R: Check enough TON for gas 
+    alt Not enough TON for gas
+    Note over R: Refund Jettons
+    else Enough TON
+
+    R ->> RJW: TransferRequest {<br>amount,<br>destination: Router,<br>fwdPayload: ccipSend }
+    
+    RJW ->> ORJW: Transfer { amount,<br>fwdPayload: ccipSend }
+    ORJW ->> OR: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
+    Note over OR: Assign msgId<br>Store ccipSend by msgId
+
+    box OnRamp
+    participant ORJW as OnRamp's <br>Jetton A Wallet
     participant OR as OnRamp
+    end
 
     participant FQ as FeeQuoter
 
-    box Token Registry<br>(not a contract but<br>a collection)
+    box Token Registry<br>(not a contract but<br>a sharded collection)
     participant TRC as TR Cell (Jetton A)
     end
 
@@ -34,38 +52,27 @@ sequenceDiagram
     participant TPJW as TokenPool's <br>Jetton A Wallet
     end
 
-    U ->> UJW: TransferRequest {<br>amount,<br>destination: Router,<br>fwdPayload: ccipSend }
-    
-    UJW ->> RJW: Transfer { amount,<br>fwdPayload: ccipSend }
-    RJW ->> R: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
-    Note over R: Check enough TON for gas 
-    R ->> OR: ccipSend
-
-    OR ->> FQ: getValidatedFee{ccipSend}
+    OR ->> FQ: getValidatedFee{msgId, ccipSend}
 
 
     alt not enough to cover fee
-    FQ ->> OR: feeNotValidated{ccipSend}
+    FQ ->> OR: feeNotValidated{msgId, ccipSend}
     Note over OR: Refund Jettons [...]
 
     else enough to cover for fee
-    FQ ->> OR: feeValidated{ccipSend}
+    FQ ->> OR: feeValidated{msgId, ccipSend}
     Note over OR: Calculate TR Cell based<br>on Token Addres
 
-    OR ->> TRC: GetTokenPoolInfo{ccipSend}
+    OR ->> TRC: GetTokenPoolInfo{msgId, ccipSend}
 
     alt Token not supported (contract not deployed)
-    TRC ->> OR: Bounced{GetTokenPoolInfo{ccipSend}}
-    Note over OR: TODO where do we store the<br>relevant info to refund the sender?
+    TRC ->> OR: Bounced{GetTokenPoolInfo{msgId, ccipSend}}
+    Note over OR: get ccipSend from msgId<br>Refund Jettons [...]
     else Supported Token
 
-    TRC ->> OR: TokenPoolInfo{tokenPoolAddress, ccipSend}
-
-    OR ->> R: lockTokens{tokenPoolAddr, ccipSend}
- 
-    R ->> RJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: ccipSend }
+    OR ->> ORJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: {msgId,ccipSend} }
     
-    RJW ->> TPJW: Transfer { amount,<br>fwdPayload: ccipSend }
+    ORJW ->> TPJW: Transfer { amount,<br>fwdPayload: ccipSend }
     TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend }
     Note over TP: consume rate limit
     alt Rate limit error
@@ -73,8 +80,10 @@ sequenceDiagram
 
     else Consumes rate limit
     TP ->> OR: commitedLockOrBurn{ccipSend}
-    OR ->> OR: send{ccipSend}
-    note over OR  : ...
+    note over OR: assign seqNum
+    note over OR: emit{ccipSend}
+    note over OR: remove ccipSend<br>from storage
+    end
     end
     end
     end

From 846667387c9d67ff3036c072fd10ef4f546762e8 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Mon, 8 Sep 2025 18:51:54 -0300
Subject: [PATCH 05/12] fix: don't share information to pool

---
 docs/contracts/flow.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index de23b4d71..600f68a7f 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -67,19 +67,20 @@ sequenceDiagram
 
     alt Token not supported (contract not deployed)
     TRC ->> OR: Bounced{GetTokenPoolInfo{msgId, ccipSend}}
-    Note over OR: get ccipSend from msgId<br>Refund Jettons [...]
+    Note over OR: get ccipSend from storage by<br>msgId Refund Jettons [...]
     else Supported Token
 
-    OR ->> ORJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: {msgId,ccipSend} }
+    OR ->> ORJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: msgId }
     
-    ORJW ->> TPJW: Transfer { amount,<br>fwdPayload: ccipSend }
-    TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend }
+    ORJW ->> TPJW: Transfer { amount,<br>fwdPayload: msgId }
+    TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: msgId }
     Note over TP: consume rate limit
     alt Rate limit error
     Note over TP: Refund Jettons [...]
 
     else Consumes rate limit
-    TP ->> OR: commitedLockOrBurn{ccipSend}
+    TP ->> OR: commitedLockOrBurn{msgId}
+    note over OR: get ccipSend from<br>storage by msgId
     note over OR: assign seqNum
     note over OR: emit{ccipSend}
     note over OR: remove ccipSend<br>from storage

From 47ccc5796c33c0fe8ea26bf2666ba2691f293d99 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Tue, 9 Sep 2025 12:45:43 -0300
Subject: [PATCH 06/12] fix: missing reply from token pool

---
 docs/contracts/flow.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index 600f68a7f..faf07dc45 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -69,6 +69,7 @@ sequenceDiagram
     TRC ->> OR: Bounced{GetTokenPoolInfo{msgId, ccipSend}}
     Note over OR: get ccipSend from storage by<br>msgId Refund Jettons [...]
     else Supported Token
+    TRC ->> OR: TokenPoolInfo{address}
 
     OR ->> ORJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: msgId }
     
@@ -76,7 +77,7 @@ sequenceDiagram
     TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: msgId }
     Note over TP: consume rate limit
     alt Rate limit error
-    Note over TP: Refund Jettons [...]
+    Note over TP, TPJW: Refund Jettons [...]
 
     else Consumes rate limit
     TP ->> OR: commitedLockOrBurn{msgId}

From bce627a090ade4623d94727f5c56e645cdccff30 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Mon, 8 Sep 2025 18:49:35 -0300
Subject: [PATCH 07/12] feat: sharded storage of message state

---
 docs/contracts/flow.md | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index faf07dc45..f10966f7d 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -34,11 +34,15 @@ sequenceDiagram
     
     RJW ->> ORJW: Transfer { amount,<br>fwdPayload: ccipSend }
     ORJW ->> OR: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
-    Note over OR: Assign msgId<br>Store ccipSend by msgId
+
+    Note over OR: Create msgId
+    create participant CS as CCIPSendStorage
+    OR ->> CS: deployCCIPSendStorage{initData{msgId}, initCCIPSend{msg: ccipSend}}
 
     box OnRamp
     participant ORJW as OnRamp's <br>Jetton A Wallet
     participant OR as OnRamp
+    participant CS as CCIPSendStorage
     end
 
     participant FQ as FeeQuoter
@@ -66,8 +70,10 @@ sequenceDiagram
     OR ->> TRC: GetTokenPoolInfo{msgId, ccipSend}
 
     alt Token not supported (contract not deployed)
-    TRC ->> OR: Bounced{GetTokenPoolInfo{msgId, ccipSend}}
-    Note over OR: get ccipSend from storage by<br>msgId Refund Jettons [...]
+    TRC ->> OR: Bounced{truncatedGetTokenPoolInfo{msgId}}
+    OR ->> CS: getInfo{msgId}
+    CS ->> OR: refund{ccipSend}
+    Note over OR: Refund Jettons
     else Supported Token
     TRC ->> OR: TokenPoolInfo{address}
 
@@ -84,7 +90,9 @@ sequenceDiagram
     note over OR: get ccipSend from<br>storage by msgId
     note over OR: assign seqNum
     note over OR: emit{ccipSend}
-    note over OR: remove ccipSend<br>from storage
+    OR ->> CS: destroy
+    destroy CS
+    CS ->> OR: TON remaining balance
     end
     end
     end

From a9c9a78cd86e222db68e765accba9ea3b5da3b8d Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Mon, 8 Sep 2025 18:54:01 -0300
Subject: [PATCH 08/12] ref: styling

---
 docs/contracts/flow.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index f10966f7d..259205a5e 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -37,7 +37,7 @@ sequenceDiagram
 
     Note over OR: Create msgId
     create participant CS as CCIPSendStorage
-    OR ->> CS: deployCCIPSendStorage{initData{msgId}, initCCIPSend{msg: ccipSend}}
+    OR ->> CS: deployCCIPSendStorage{<br>initData{msgId},<br>initCCIPSend{msg: ccipSend}}
 
     box OnRamp
     participant ORJW as OnRamp's <br>Jetton A Wallet

From 508e86799cbbd8a52187c2866347355a90662543 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Tue, 9 Sep 2025 14:44:11 -0300
Subject: [PATCH 09/12] fix: deploy storage confirmation

---
 docs/contracts/flow.md | 33 +++++++++++++++++----------------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index 259205a5e..bd426dc49 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -35,9 +35,10 @@ sequenceDiagram
     RJW ->> ORJW: Transfer { amount,<br>fwdPayload: ccipSend }
     ORJW ->> OR: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
 
-    Note over OR: Create msgId
+    Note over OR: Create msgID
     create participant CS as CCIPSendStorage
-    OR ->> CS: deployCCIPSendStorage{<br>initData{msgId},<br>initCCIPSend{msg: ccipSend}}
+    OR ->> CS: deployCCIPSendStorage{<br>initData{msgID},<br>initCCIPSend{msg: ccipSend}}
+    CS ->> OR: deployed{msgID, ccipSend}
 
     box OnRamp
     participant ORJW as OnRamp's <br>Jetton A Wallet
@@ -56,43 +57,43 @@ sequenceDiagram
     participant TPJW as TokenPool's <br>Jetton A Wallet
     end
 
-    OR ->> FQ: getValidatedFee{msgId, ccipSend}
+    OR ->> FQ: getValidatedFee{msgID, ccipSend}
 
 
     alt not enough to cover fee
-    FQ ->> OR: feeNotValidated{msgId, ccipSend}
+    FQ ->> OR: feeNotValidated{msgID, ccipSend}
     Note over OR: Refund Jettons [...]
 
     else enough to cover for fee
-    FQ ->> OR: feeValidated{msgId, ccipSend}
+    FQ ->> OR: feeValidated{msgID, ccipSend}
     Note over OR: Calculate TR Cell based<br>on Token Addres
 
-    OR ->> TRC: GetTokenPoolInfo{msgId, ccipSend}
+    OR ->> TRC: GetTokenPoolInfo{msgID, ccipSend}
 
     alt Token not supported (contract not deployed)
-    TRC ->> OR: Bounced{truncatedGetTokenPoolInfo{msgId}}
-    OR ->> CS: getInfo{msgId}
+    TRC ->> OR: Bounced{truncatedGetTokenPoolInfo{msgID}}
+    OR ->> CS: getInfo{msgID}
     CS ->> OR: refund{ccipSend}
     Note over OR: Refund Jettons
     else Supported Token
     TRC ->> OR: TokenPoolInfo{address}
 
-    OR ->> ORJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: msgId }
+    OR ->> ORJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: msgID }
     
-    ORJW ->> TPJW: Transfer { amount,<br>fwdPayload: msgId }
-    TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: msgId }
+    ORJW ->> TPJW: Transfer { amount,<br>fwdPayload: msgID }
+    TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: msgID }
     Note over TP: consume rate limit
     alt Rate limit error
     Note over TP, TPJW: Refund Jettons [...]
 
     else Consumes rate limit
-    TP ->> OR: commitedLockOrBurn{msgId}
-    note over OR: get ccipSend from<br>storage by msgId
+    TP ->> OR: commitedLockOrBurn{msgID} 
+    OR ->> CS: consumeCcipSend 
+    Note over CS: destroy
+    destroy CS
+    CS ->> OR: commit(ccipSend) +<br>TON remaining balance
     note over OR: assign seqNum
     note over OR: emit{ccipSend}
-    OR ->> CS: destroy
-    destroy CS
-    CS ->> OR: TON remaining balance
     end
     end
     end

From e5cbb9aadbaf9323229aca09a912a8bc1d289edc Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Tue, 9 Sep 2025 14:48:00 -0300
Subject: [PATCH 10/12] fix: typos

---
 docs/contracts/flow.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
index bd426dc49..141b8ced4 100644
--- a/docs/contracts/flow.md
+++ b/docs/contracts/flow.md
@@ -66,7 +66,7 @@ sequenceDiagram
 
     else enough to cover for fee
     FQ ->> OR: feeValidated{msgID, ccipSend}
-    Note over OR: Calculate TR Cell based<br>on Token Addres
+    Note over OR: Calculate TR Cell based<br>on Token Address
 
     OR ->> TRC: GetTokenPoolInfo{msgID, ccipSend}
 
@@ -87,7 +87,7 @@ sequenceDiagram
     Note over TP, TPJW: Refund Jettons [...]
 
     else Consumes rate limit
-    TP ->> OR: commitedLockOrBurn{msgID} 
+    TP ->> OR: committedLockOrBurn{msgID} 
     OR ->> CS: consumeCcipSend 
     Note over CS: destroy
     destroy CS

From 0f5937d49f9d0af46953acf3fe5b4923d53be20f Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Tue, 9 Sep 2025 18:21:06 -0300
Subject: [PATCH 11/12] ref: modularize documentation

---
 .../contracts/ccip/onramp-ccipsend-storage.md |  13 +++
 docs/contracts/ccip/token-registry.md         |   5 +
 docs/contracts/flow.md                        | 101 ------------------
 docs/flow/onramp/arbitrary-msg.md             |  60 +++++++++++
 docs/flow/onramp/flow.md                      |   9 ++
 docs/flow/onramp/token-transfer.md            |  88 +++++++++++++++
 docs/flow/onramp/user-interface.md            |  47 ++++++++
 .../token-transfer-notation-convention.md     |  30 ++++++
 8 files changed, 252 insertions(+), 101 deletions(-)
 create mode 100644 docs/contracts/ccip/onramp-ccipsend-storage.md
 create mode 100644 docs/contracts/ccip/token-registry.md
 delete mode 100644 docs/contracts/flow.md
 create mode 100644 docs/flow/onramp/arbitrary-msg.md
 create mode 100644 docs/flow/onramp/flow.md
 create mode 100644 docs/flow/onramp/token-transfer.md
 create mode 100644 docs/flow/onramp/user-interface.md
 create mode 100644 docs/flow/token-transfer-notation-convention.md

diff --git a/docs/contracts/ccip/onramp-ccipsend-storage.md b/docs/contracts/ccip/onramp-ccipsend-storage.md
new file mode 100644
index 000000000..f47a8a444
--- /dev/null
+++ b/docs/contracts/ccip/onramp-ccipsend-storage.md
@@ -0,0 +1,13 @@
+# CCIPSendStorage
+
+This is  a contract that will be used by the OnRamp to store incoming CCIPSend messages. CCIPSend message will be presisted in a sharded map by deploing `CCIPSendStorage` contracts. This will be used to recover the message information in two situations:
+
+1. When we get a bounced.
+2. When we lockOrBurn tokens (as we won't be passing the whole ccipSend msg to the Token Pool).
+
+This contracts will be initialized with an owner (the OnRamp) and an id that must fit in a bounced message (224 bits). We can calculate its address with this information. This message id will be autoincremented on every message processed.
+
+This contract will accept two messages:
+
+1. `init{data}`: store the data cell. Returns `stored{storageID, data}`
+2. `consume{context}`: destroys the contract, returning its TON balance and `consumed{storageID, data, context}`
diff --git a/docs/contracts/ccip/token-registry.md b/docs/contracts/ccip/token-registry.md
new file mode 100644
index 000000000..a53609175
--- /dev/null
+++ b/docs/contracts/ccip/token-registry.md
@@ -0,0 +1,5 @@
+# Token Registry
+
+Unlike the EVM implementation where a single contract stores all the information about supported tokens and their Token Pools, in TON we will use a collection of contracts to store this information. This is because contract storage in TON is limited.
+
+These cells will be initialized with the owner (the OnRamp) and the token address they represent. The address of these contracts can be calculated from this information. The contract will store the address of the Token Pool, and could have a flag to enable/disable the token.
diff --git a/docs/contracts/flow.md b/docs/contracts/flow.md
deleted file mode 100644
index 141b8ced4..000000000
--- a/docs/contracts/flow.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# CCIP Flow
-
-## Token Transfer
-
-### Token Transfer OnRamp Flow
-
-```mermaid
----
-config:
-  sequence:
-    
----
-sequenceDiagram
-    box User 
-    participant U as User
-    participant UJW as User's <br>Jetton A Wallet
-    end
-
-    box Router
-    participant RJW as Router's <br>Jetton A Wallet
-    participant R as Router
-    end
-
-    U ->> UJW: TransferRequest {<br>amount,<br>destination: Router,<br>fwdPayload: ccipSend }
-    
-    UJW ->> RJW: Transfer { amount,<br>fwdPayload: ccipSend }
-    RJW ->> R: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
-    Note over R: Check enough TON for gas 
-    alt Not enough TON for gas
-    Note over R: Refund Jettons
-    else Enough TON
-
-    R ->> RJW: TransferRequest {<br>amount,<br>destination: Router,<br>fwdPayload: ccipSend }
-    
-    RJW ->> ORJW: Transfer { amount,<br>fwdPayload: ccipSend }
-    ORJW ->> OR: TransferNotification {<br>sender, amount,<br>fwdPayload: ccipSend}
-
-    Note over OR: Create msgID
-    create participant CS as CCIPSendStorage
-    OR ->> CS: deployCCIPSendStorage{<br>initData{msgID},<br>initCCIPSend{msg: ccipSend}}
-    CS ->> OR: deployed{msgID, ccipSend}
-
-    box OnRamp
-    participant ORJW as OnRamp's <br>Jetton A Wallet
-    participant OR as OnRamp
-    participant CS as CCIPSendStorage
-    end
-
-    participant FQ as FeeQuoter
-
-    box Token Registry<br>(not a contract but<br>a sharded collection)
-    participant TRC as TR Cell (Jetton A)
-    end
-
-    box Token Pools
-    participant TP as Token Pool A
-    participant TPJW as TokenPool's <br>Jetton A Wallet
-    end
-
-    OR ->> FQ: getValidatedFee{msgID, ccipSend}
-
-
-    alt not enough to cover fee
-    FQ ->> OR: feeNotValidated{msgID, ccipSend}
-    Note over OR: Refund Jettons [...]
-
-    else enough to cover for fee
-    FQ ->> OR: feeValidated{msgID, ccipSend}
-    Note over OR: Calculate TR Cell based<br>on Token Address
-
-    OR ->> TRC: GetTokenPoolInfo{msgID, ccipSend}
-
-    alt Token not supported (contract not deployed)
-    TRC ->> OR: Bounced{truncatedGetTokenPoolInfo{msgID}}
-    OR ->> CS: getInfo{msgID}
-    CS ->> OR: refund{ccipSend}
-    Note over OR: Refund Jettons
-    else Supported Token
-    TRC ->> OR: TokenPoolInfo{address}
-
-    OR ->> ORJW: TransferRequest { amount,<br>destination: TokenPoolA,<br>fwdPayload: msgID }
-    
-    ORJW ->> TPJW: Transfer { amount,<br>fwdPayload: msgID }
-    TPJW ->> TP: TransferNotification {<br>sender, amount,<br>fwdPayload: msgID }
-    Note over TP: consume rate limit
-    alt Rate limit error
-    Note over TP, TPJW: Refund Jettons [...]
-
-    else Consumes rate limit
-    TP ->> OR: committedLockOrBurn{msgID} 
-    OR ->> CS: consumeCcipSend 
-    Note over CS: destroy
-    destroy CS
-    CS ->> OR: commit(ccipSend) +<br>TON remaining balance
-    note over OR: assign seqNum
-    note over OR: emit{ccipSend}
-    end
-    end
-    end
-    end
-```
\ No newline at end of file
diff --git a/docs/flow/onramp/arbitrary-msg.md b/docs/flow/onramp/arbitrary-msg.md
new file mode 100644
index 000000000..74b20df0e
--- /dev/null
+++ b/docs/flow/onramp/arbitrary-msg.md
@@ -0,0 +1,60 @@
+# Arbitrary Message Onramp Flow
+
+> See [how CCIPSend works](../../contracts/ccip/onramp-ccipsend-storage.md) and [how the Token Registry is implemented](../../contracts/ccip/token-registry.md).
+
+```mermaid
+sequenceDiagram
+    participant R as Router
+
+    Note over R: Gets CCIPSend from User
+    Note over R: Check enough TON for gas 
+    alt Not enough TON for gas
+    Note over R: Return TON
+    else Enough TON
+
+    R ->> OR: CCIPSend{}
+    
+    Note over OR: Create msgID
+    create participant CS
+    OR ->> CS: deploy CCIPSendStorage <br>initData{msgID}<br>store{msg: CCIPSend}
+    CS ->> OR: stored{msgID, CCIPSend}
+
+    box OnRamp
+    participant OR as OnRamp
+    participant CS as CCIPSendStorage<br>{id}
+    end
+
+    participant FQ as FeeQuoter
+
+    OR ->> FQ: getValidatedFee{msgID, CCIPSend}
+
+
+    alt not enough to cover fee
+    FQ ->> OR: feeNotValidated{msgID, CCIPSend}
+    Note over OR: Reject CCIPSend
+
+    else enough to cover for fee
+    FQ ->> OR: feeValidated{msgID, CCIPSend}
+    OR ->> CS: consume{context: success} 
+    Note over CS: destroy
+    destroy CS
+    CS ->> OR: consumed{msgID, data:<br>CCIPSend,context: success} +<br>TON remaining balance
+    note over OR: assign seqNum
+    note over OR: emit{CCIPSend}
+    OR ->> R: sendConfirmation{seqNum}<br>+ Recovered TON
+    end
+    end
+```
+
+For any bounce we catch, or when we say Reject CCIPSend, it envolves:
+
+```mermaid
+sequenceDiagram
+    participant OR as OnRamp
+    participant CS as CCIPSendStorage
+    OR ->> CS: consume{context: failedValidation} 
+    Note over CS: destroy
+    destroy CS
+    CS ->> OR: consumed{storageID: CS.id, data:<br>CCIPSend, context: failedValidation}<br>+ TON remaining balance
+    Note over OR: Send rejectedCCIPSend{reason}<br>to the user + excess TON
+```
diff --git a/docs/flow/onramp/flow.md b/docs/flow/onramp/flow.md
new file mode 100644
index 000000000..0b3b7ffb6
--- /dev/null
+++ b/docs/flow/onramp/flow.md
@@ -0,0 +1,9 @@
+# CCIP Flow
+
+> Before you read, see [Jetton Transfer Notation Convention](../token-transfer-notation-convention.md)
+
+## OnRamp
+
+See the [user interface here](./user-interface.md).
+
+You can find the flows for [arbitrary message passing](./arbitrary-msg.md) and [token transfers](./token-transfer.md).
diff --git a/docs/flow/onramp/token-transfer.md b/docs/flow/onramp/token-transfer.md
new file mode 100644
index 000000000..f2c74e9e3
--- /dev/null
+++ b/docs/flow/onramp/token-transfer.md
@@ -0,0 +1,88 @@
+# Token Transfer Onramp Flow
+
+> Before you read, see [Jetton Transfer Notation Convention](../token-transfer-notation-convention.md)
+
+> See also [how CCIPSend works](../../contracts/ccip/onramp-ccipsend-storage.md) and [how the Token Registry is implemented](../../contracts/ccip/token-registry.md).
+
+```mermaid
+sequenceDiagram
+    participant R as Router
+
+    Note over R: Gets transfer<br>of T from User<br>Transfer { amount,<br>fwdPayload: CCIPSend}
+    Note over R: Check enough TON for gas 
+    alt Not enough TON for gas
+    Note over R: Refund Jettons
+    else Enough TON
+
+    R -->> OR: Transfer T { amount,<br>fwdPayload: CCIPSend }
+    
+    Note over OR: Create msgID
+    create participant CS
+    OR ->> CS: deploy CCIPSendStorage <br>initData{msgID}<br>store{msg: CCIPSend}
+    CS ->> OR: stored{msgID, CCIPSend}
+
+    box OnRamp
+    participant OR as OnRamp
+    participant CS as CCIPSendStorage<br>{id}
+    end
+
+    participant FQ as FeeQuoter
+
+    box Token Registry<br>(not a contract but<br>a sharded collection)
+    participant TRC as TR Cell (T Jetton)
+    end
+
+    participant TP as Token Pool T
+
+    OR ->> FQ: getValidatedFee{msgID, CCIPSend}
+
+
+    alt not enough to cover fee
+    FQ ->> OR: feeNotValidated{msgID, CCIPSend}
+    Note over OR: Reject CCIPSend
+
+    else enough to cover for fee
+    FQ ->> OR: feeValidated{msgID, CCIPSend}
+    Note over OR: Calculate TR Cell based<br>on Token Address
+
+    OR ->> TRC: GetTokenPoolInfo{msgID, CCIPSend}
+
+    alt Token not supported (contract not deployed)
+    TRC ->> OR: Bounced{truncatedGetTokenPoolInfo{msgID}}
+    Note over OR: Reject CCIPSend
+    else Supported Token
+    TRC ->> OR: TokenPoolInfo{address}
+
+    OR -->> TP: Transfer T { amount,<br>fwdPayload: msgID }
+    
+    Note over TP: consume rate limit
+    alt Rate limit error
+    Note over OR: Reject CCIPSend
+
+    else Consumes rate limit
+    TP ->> OR: committedLockOrBurn{msgID} 
+    OR ->> CS: consume{context: success} 
+    Note over CS: destroy
+    destroy CS
+    CS ->> OR: consumed{msgID, data:<br>CCIPSend,context: success} +<br>TON remaining balance
+    note over OR: assign seqNum
+    note over OR: emit{CCIPSend}
+    OR ->> R: sendConfirmation{seqNum}<br>+ Recovered TON
+    end
+    end
+    end
+    end
+```
+
+For any bounce we catch, or when we say Reject CCIPSend, it envolves:
+
+```mermaid
+sequenceDiagram
+    participant OR as OnRamp
+    participant CS as CCIPSendStorage
+    OR ->> CS: consume{context: failedValidation} 
+    Note over CS: destroy
+    destroy CS
+    CS ->> OR: consumed{storageID: CS.id, data:<br>CCIPSend, context: failedValidation}<br>+ TON remaining balance
+    Note over OR: Send rejectedCCIPSend{reason}<br>to the user in a Jetton transfer<br>+ excess TON
+```
diff --git a/docs/flow/onramp/user-interface.md b/docs/flow/onramp/user-interface.md
new file mode 100644
index 000000000..cf2f07d67
--- /dev/null
+++ b/docs/flow/onramp/user-interface.md
@@ -0,0 +1,47 @@
+# OnRamp User Interface
+
+For arbitrary messages paying fees in TON, the user interface is as follows:
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant R as Router
+
+    Note over U: TODO Get fee?
+
+    U ->> R: CCIPSend{}
+    
+    Note over R: [...]
+    alt Reject (Refund tokens)
+    Note over R: Low fee/Rate limit/other
+    R ->> U: rejectedCCIPSend{reason}
+  
+    else Accept msg
+    Note over R: emit{CCIPSend}
+    R ->> U: ccipSent{seqNum}
+    end
+```
+
+For token transfers paid in TON, the user interface is as follows:
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant R as Router
+
+    Note over U: TODO Get fee?
+
+    U -->> R: Transfer T { amount,<br>fwdPayload: CCIPSend }
+    
+    Note over R: [...]
+    alt Reject (Refund tokens)
+    Note over R: Low fee/Rate limit/other
+    R -->> U: Transfer T { amount,<br>fwdPayload: rejectedCCIPSend{reason} }
+  
+    else Accept msg
+    Note over R: emit{CCIPSend}
+    R ->> U: ccipSent{seqNum}
+    end
+```
+
+TODO: both paid with Link
diff --git a/docs/flow/token-transfer-notation-convention.md b/docs/flow/token-transfer-notation-convention.md
new file mode 100644
index 000000000..e8d9dee73
--- /dev/null
+++ b/docs/flow/token-transfer-notation-convention.md
@@ -0,0 +1,30 @@
+# Token Transfer Notation Convention
+
+This is a convention we will be using for our diagrams. Given to actors **A** and **B** where **A** transfer `T` Jettons to **B**, the real message flow looks like this:
+
+```mermaid
+sequenceDiagram
+
+participant A
+participant AW as A's T Jetton Wallet
+participant BW as B's T Jetton Wallet
+participant B
+
+A ->> AW: TransferRequest {<br>amount,<br>destination: B,<br>fwdPayload }
+
+AW ->> BW: Transfer { amount,<br>fwdPayload }
+BW ->> B: TransferNotification {<br>sender, amount,<br>fwdPayload}
+```
+
+To reduce noice, we will represent this flow with a doted line arrow
+
+```mermaid
+sequenceDiagram
+
+participant A
+participant B
+
+A -->> B: Transfer T { amount,<br>fwdPayload }
+```
+
+We must remind that we cannot get bounced from this transfers, and that they envolve 3 hops, so they add latency and foward fee costs.

From 454d4b1e9de9ee0fbbeabf678aee329588cd0e26 Mon Sep 17 00:00:00 2001
From: Patricio Tourne Passarino <patricio.passarino@smartcontract.com>
Date: Tue, 9 Sep 2025 18:43:03 -0300
Subject: [PATCH 12/12] wip: paying with LINK

---
 docs/flow/onramp/arbitrary-msg.md  | 61 ++++++++++++++++++++++++++++++
 docs/flow/onramp/token-transfer.md |  4 ++
 docs/flow/onramp/user-interface.md |  4 +-
 3 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/docs/flow/onramp/arbitrary-msg.md b/docs/flow/onramp/arbitrary-msg.md
index 74b20df0e..b59486070 100644
--- a/docs/flow/onramp/arbitrary-msg.md
+++ b/docs/flow/onramp/arbitrary-msg.md
@@ -2,6 +2,8 @@
 
 > See [how CCIPSend works](../../contracts/ccip/onramp-ccipsend-storage.md) and [how the Token Registry is implemented](../../contracts/ccip/token-registry.md).
 
+## Paid with TON
+
 ```mermaid
 sequenceDiagram
     participant R as Router
@@ -58,3 +60,62 @@ sequenceDiagram
     CS ->> OR: consumed{storageID: CS.id, data:<br>CCIPSend, context: failedValidation}<br>+ TON remaining balance
     Note over OR: Send rejectedCCIPSend{reason}<br>to the user + excess TON
 ```
+
+## Paid with LINK
+
+```mermaid
+sequenceDiagram
+    participant R as Router
+
+    Note over R: Gets CCIPSend from User
+    Note over R: Check enough TON for gas 
+    alt Not enough TON for gas
+    Note over R: Return TON
+    else Enough TON
+
+    R -->> OR: Transfer T { amount,<br>fwdPayload: CCIPSend }
+    
+    Note over OR: Create msgID
+    create participant CS
+    OR ->> CS: deploy CCIPSendStorage <br>initData{msgID}<br>store{msg: CCIPSend}
+    CS ->> OR: stored{msgID, CCIPSend}
+
+    box OnRamp
+    participant OR as OnRamp
+    participant CS as CCIPSendStorage<br>{id}
+    end
+
+    participant FQ as FeeQuoter
+
+    OR ->> FQ: getValidatedFee{msgID, CCIPSend}
+
+
+    alt not enough to cover fee
+    FQ ->> OR: feeNotValidated{msgID, CCIPSend}
+    Note over OR: Reject CCIPSend
+
+    else enough to cover for fee
+    FQ ->> OR: feeValidated{msgID, CCIPSend}
+    OR ->> CS: consume{context: success} 
+    Note over CS: destroy
+    destroy CS
+    CS ->> OR: consumed{msgID, data:<br>CCIPSend,context: success} +<br>TON remaining balance
+    note over OR: assign seqNum
+    note over OR: emit{CCIPSend}
+    OR ->> R: sendConfirmation{seqNum}<br>+ Recovered TON
+    end
+    end
+```
+
+For any bounce we catch, or when we say Reject CCIPSend, it envolves:
+
+```mermaid
+sequenceDiagram
+    participant OR as OnRamp
+    participant CS as CCIPSendStorage
+    OR ->> CS: consume{context: failedValidation} 
+    Note over CS: destroy
+    destroy CS
+    CS ->> OR: consumed{storageID: CS.id, data:<br>CCIPSend, context: failedValidation}<br>+ TON remaining balance
+    Note over OR: Send rejectedCCIPSend{reason}<br>to the user + excess TON
+```
diff --git a/docs/flow/onramp/token-transfer.md b/docs/flow/onramp/token-transfer.md
index f2c74e9e3..a2563d89a 100644
--- a/docs/flow/onramp/token-transfer.md
+++ b/docs/flow/onramp/token-transfer.md
@@ -4,6 +4,8 @@
 
 > See also [how CCIPSend works](../../contracts/ccip/onramp-ccipsend-storage.md) and [how the Token Registry is implemented](../../contracts/ccip/token-registry.md).
 
+## Any token transfer paid in TON or LINK transfer paid in LINK
+
 ```mermaid
 sequenceDiagram
     participant R as Router
@@ -53,6 +55,8 @@ sequenceDiagram
     else Supported Token
     TRC ->> OR: TokenPoolInfo{address}
 
+    Note over OR: If paying with LINK,<br>keep some for fee
+
     OR -->> TP: Transfer T { amount,<br>fwdPayload: msgID }
     
     Note over TP: consume rate limit
diff --git a/docs/flow/onramp/user-interface.md b/docs/flow/onramp/user-interface.md
index cf2f07d67..d0df12b43 100644
--- a/docs/flow/onramp/user-interface.md
+++ b/docs/flow/onramp/user-interface.md
@@ -22,7 +22,7 @@ sequenceDiagram
     end
 ```
 
-For token transfers paid in TON, the user interface is as follows:
+For token transfers paid in TON, LINK transfers paid in LINK and arbitrary messages paid in LINK, the user interface is as follows:
 
 ```mermaid
 sequenceDiagram
@@ -44,4 +44,4 @@ sequenceDiagram
     end
 ```
 
-TODO: both paid with Link
+TODO: Transfer non-LINK token transfers paid with LINK