From ce1ccd3c894656a38c3738f0ec1751c9ab197a64 Mon Sep 17 00:00:00 2001
From: Aumetra Weisman <aumetra@cryptolab.net>
Date: Wed, 19 Jun 2024 17:35:55 +0200
Subject: [PATCH] Add page about transactions

---
 src/pages/core/architecture/_meta.json       |  3 ++-
 src/pages/core/architecture/transactions.mdx | 27 ++++++++++++++++++++
 src/pages/core/entrypoints/reply.mdx         |  7 +++++
 3 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 src/pages/core/architecture/transactions.mdx

diff --git a/src/pages/core/architecture/_meta.json b/src/pages/core/architecture/_meta.json
index 32ac66fa..bb3f986d 100644
--- a/src/pages/core/architecture/_meta.json
+++ b/src/pages/core/architecture/_meta.json
@@ -1,4 +1,5 @@
 {
   "actor-model": "Actor Model",
-  "events": "Events"
+  "events": "Events",
+  "transactions": "Transactions"
 }
diff --git a/src/pages/core/architecture/transactions.mdx b/src/pages/core/architecture/transactions.mdx
new file mode 100644
index 00000000..25db7429
--- /dev/null
+++ b/src/pages/core/architecture/transactions.mdx
@@ -0,0 +1,27 @@
+---
+tags: ["core", "architecture"]
+---
+
+# Transactions
+
+Every contract invocation is wrapped into a transaction. If you know about
+transactions in SQL databases, you can consider them as the same basic concept.
+You execute multiple operations in a single transaction, and if one of them
+fails, the whole transaction is rolled back.
+
+In our case, these operations are invocations of contract entrypoints. If one of
+the invocations in the chain fails, the whole transaction is usually rolled
+back.
+
+## Preventing rollbacks in case of failure
+
+If you don't want your entire transaction to be rolled back in case of a
+failure, you can use the `reply_on` field in the message you send. Set the field
+to one of the following values and instead of rolling back the transaction, you
+will receive a message containing the error:
+
+- `ReplyOn::Always`
+- `ReplyOn::Error`
+
+That way you can handle the error and decide what to do next, whether you want
+to propagate the error, retry the operation, ignore it, etc.
diff --git a/src/pages/core/entrypoints/reply.mdx b/src/pages/core/entrypoints/reply.mdx
index c56b2ab7..690e0bea 100644
--- a/src/pages/core/entrypoints/reply.mdx
+++ b/src/pages/core/entrypoints/reply.mdx
@@ -29,6 +29,11 @@ and set it to one of the following values:
 - `ReplyOn::Error`
 - `ReplyOn::Success`
 
+<Callout>
+  The `reply_on` value has an impact on when a transaction is cancelled. For
+  more info, check the page about [transactions].
+</Callout>
+
 ```rust filename="contract.rs" template="core"
 const CONTRACT_ADDR: &str = "other_contract";
 const SUBMSG_ID: u64 = 1; // This is a unique identifier so we can associate a reply with a specific submessage. It can be any numeric value.
@@ -65,3 +70,5 @@ pub fn reply(deps: DepsMut, env: Env, msg: cosmwasm_std::Reply) -> StdResult<Res
     Ok(Response::default())
 }
 ```
+
+[transactions]: ../architecture/transactions