doc: OnRamp flow paying with LINK

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}`

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.

docs/flow/onramp/arbitrary-msg.md

@@ -0,0 +1,121 @@
+# 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).
+
+## Paid with TON
+
+```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
+```
+
+## 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
+```

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).

docs/flow/onramp/token-transfer.md

@@ -0,0 +1,92 @@
+# 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).
+
+## Any token transfer paid in TON or LINK transfer paid in LINK
+
+```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}
+
+    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
+    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
+```

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, LINK transfers paid in LINK and arbitrary messages paid in LINK, 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: Transfer non-LINK token transfers paid with LINK

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.