From 7cd3aba20a613192cfd11457db7d09af16e8634d Mon Sep 17 00:00:00 2001
From: RogerZoe <218r1a05p1@gmail.com>
Date: Mon, 20 Oct 2025 23:19:16 +0530
Subject: [PATCH] docs(protocol): add Paymasters to Concepts section (#1716)

---
 docs.json                     |  1 +
 learn/protocol/paymasters.mdx | 57 +++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 learn/protocol/paymasters.mdx

diff --git a/docs.json b/docs.json
index 1bd123b6fd..5c229c0b2d 100644
--- a/docs.json
+++ b/docs.json
@@ -866,6 +866,7 @@
                 "group": "Concepts",
                 "pages": [
                   "learn/protocol/accounts",
+                  "learn/protocol/paymasters",
                   "learn/protocol/blocks",
                   "learn/protocol/cryptography",
                   "learn/protocol/data-availability",
diff --git a/learn/protocol/paymasters.mdx b/learn/protocol/paymasters.mdx
new file mode 100644
index 0000000000..fd33f6b83e
--- /dev/null
+++ b/learn/protocol/paymasters.mdx
@@ -0,0 +1,57 @@
+---
+title: Paymasters
+description: How Paymasters enable gasless transactions and token-based fee payments on Starknet.
+---
+
+# Paymasters
+
+A **Paymaster** is a smart contract that can pay transaction fees on behalf of a user.  
+This allows developers to sponsor transactions or accept alternative tokens for gas payments.
+
+Paymasters build upon **Account Abstraction**, which makes every account a smart contract that defines its own validation and fee logic.
+
+---
+
+## Why Paymasters Exist
+
+In most blockchains, users must hold the native token (like ETH) to pay for transaction fees.  
+This creates friction for onboarding and limits flexibility for dApps.
+
+Starknet introduces Paymasters to solve this. With Paymasters, developers can:
+
+- **Sponsor user transactions** (gasless UX)
+- **Accept ERC-20 tokens for fees**
+- **Implement custom fee logic** (for example, reward systems or whitelists)
+
+---
+
+## How They Work
+
+When a transaction is sent, the flow looks like this:
+
+1. The user's account signs and sends the transaction.
+2. The transaction references a Paymaster contract.
+3. The Paymaster validates the request and, if approved, covers the gas cost.
+4. The sequencer executes the transaction as normal.
+
+This system allows for flexibility — a Paymaster can restrict usage, set budgets, or require users to meet specific conditions.
+
+---
+
+## Example Implementations
+
+You can explore Paymaster integrations in ecosystem SDKs and libraries:
+
+- [starknet.js – Paymaster guide](https://starknetjs.com/docs/next/guides/account/paymaster/)  
+- [starknet-react Paymaster Providers](https://www.starknet-react.com/docs/paymaster-providers)  
+- [StarknetDart Avnu Provider](https://starknetdart.dev/packages/avnu_provider)
+
+Each library shows how to integrate Paymasters for your app or wallet.
+
+---
+
+## Related Topics
+
+- [Accounts](./accounts) — How Starknet accounts are smart contracts.  
+- [Fees](./fees) — How transaction costs are calculated and paid.  
+- [Transactions](./transactions) — The lifecycle of a transaction on Starknet.