Merge branch 'main' into old-meetings

Author: JFWooten4

config/theme/navbar.ts

@@ -79,6 +79,11 @@ const build: NavbarItem = {
       label: 'Tutorial: Dapp Frontend',
       activeBasePath: 'docs/build/apps/dapp-frontend',
     },
+    {
+      to: '/docs/build/apps/x402',
+      label: 'x402 on Stellar',
+      activeBasePath: 'docs/build/apps/x402',
+    },
     {
       to: '/docs/build/apps/zk',
       label: 'ZK Proofs on Stellar',

docs/build/apps/dapp-frontend.mdx

@@ -0,0 +1,49 @@
+---
+title: x402 on Stellar
+sidebar_position: 74
+sidebar_label: x402
+description: "Use the x402 protocol for per-request HTTP payments on Stellar, with support for AI agents and APIs."
+---
+
+## What is x402?
+
+x402 is an open protocol from the Coinbase Developer Platform that enables programmatic, per request payments over HTTP, designed especially for AI agents and APIs. It effectively turns the old “402 Payment Required” HTTP status code into something usable, for both humans and AI agents.
+
+On Stellar, x402 works with Soroban authorization so that clients can pay for API requests via signed auth entries, ideal for micropayments and payment enabled apps. To build an x402-enabled service or integrate payments into your app, see [Build Applications](./README.mdx) and the resources below.
+
+## x402 Compatible Wallets
+
+To support x402 on Stellar, a wallet must support [auth-entry signing](../guides/transactions/signing-soroban-invocations.mdx#method-2-auth-entry-signing) (Soroban authorization entry signing). The following wallets support auth-entry signing:
+
+- Freighter Browser Extension
+- Albedo
+- Hana
+- HOT
+- Klever
+- One Key
+
+:::note
+
+Freighter Mobile does not currently support x402; use the Freighter browser extension. Mobile support is planned for a future release.
+
+:::
+
+## x402 Facilitator from OpenZeppelin
+
+The [OpenZeppelin Relayer x402 Plugin for x402](https://github.com/OpenZeppelin/relayer-plugin-x402-facilitator) implements the x402 facilitator API so you can serve x402 payments directly from a Relayer instance. It works with the Coinbase x402 ecosystem (e.g., @x402/express) and exposes the expected `/verify`, `/settle`, and `/supported` endpoints under the Relayer plugin router.
+
+:::note
+
+This version supports x402 v2 specification. For x402 v1 support, please use a previous version of this plugin (check git history for v1 compatible releases).
+
+:::
+
+## Resources
+
+- **x402 Starter Template** — A starter template for building payment-enabled applications with x402. Simplified scaffolding demonstrating x402 payment protocol integration with browser wallet support; use it as a foundation for micropayment-enabled services, SaaS applications, or any project that needs frictionless web payments. [View on GitHub](https://github.com/ElliotFriend/x402/tree/stellar-browser-wallet-example/examples/typescript/fullstack/browser-wallet-example)
+- **Economic Load Balancer** — An intelligent multi-chain payment router that automatically selects the most cost-efficient network for high-frequency AI agent micropayments. [View on GitHub](https://github.com/marcelosalloum/x402/tree/x402-hackathon)
+
+## Learn more
+
+- [x402 protocol (Coinbase Developer Platform)](https://docs.cdp.coinbase.com/x402) — Official x402 protocol overview and spec
+- [Signing Soroban invocations](../guides/transactions/signing-soroban-invocations.mdx) — Auth-entry signing and transaction signing on Stellar

docs/build/apps/x402.mdx

@@ -3,7 +3,7 @@ title: Making cross-contract calls
 description: Call a smart contract from within another smart contract
 ---
 
-As with developing software in any language, developing a Stellar smart contract with a rich feature set can be a challenging and time-consuming task. Thankfully, someone else might already have solved part of your issues or build components which could be reused. The open source community is vibrant and Stellar's community does not disappoint.
+As with developing software in any language, developing a Stellar smart contract with a rich feature set can be a challenging and time-consuming task. Thankfully, someone else might already have solved part of your issues or built components which can be reused. The open source community is vibrant and Stellar's community does not disappoint.
 
 There are two kinds of dependencies that can be introduced in a Stellar smart contract:
 
@@ -14,7 +14,7 @@ In the following, we will see how contracts can be leveraged from within another
 
 ## Contract as a dependency
 
-While finding a contract is out of scope for this guide, there are a few place to be on the lookout. Most projects and dApps publicly disclose the address of their Stellar smart contract on their website. With this information, a [block explorer](../../../tools/developer-tools/block-explorers.mdx) is a powerful tool to understand how a contract is being used. Some explorers also allow you to download the compiled contract as a Wasm file. There are also projects that provide a link to access the code itself.
+While finding a contract is out of scope for this guide, there are a few places to be on the lookout. Most projects and dApps publicly disclose the address of their Stellar smart contract on their website. With this information, a [block explorer](../../../tools/developer-tools/block-explorers.mdx) is a powerful tool to understand how a contract is being used. Some explorers also allow you to download the compiled contract as a Wasm file. There are also projects that provide a link to access the code itself.
 
 :::info[Contract address]
 
@@ -24,17 +24,17 @@ To depend on a project, we need to know the contract address of the contract to
 
 ## Public API
 
-All public functions of a contract can be called. Using a network explorer can be helpful as some propose to see the Rust interface of a contract. Bindings can also be generated using the CLI:
+All public functions of a contract can be called. Using a network explorer can be helpful as some allow you to see the Rust interface of a contract. Bindings can also be generated using the CLI:
 
 ```bash
 stellar contract bindings rust --network --contract-id ... --output-dir ...
 ```
 
 ## Making a cross-contract call
 
-Once we know which function to call and which arguments to use, there are two main ways to make a cross-contract call: we can either load the Wasm or call the contract.
+Once we know which function to call and which arguments to use, there are two main ways to make a cross-contract call: we can either manually invoke the contract or use a contract client.
 
-Let's start by using only a contract's address. In this example, we have an external contract with a public function named `add_with` which takes two `u32` as input values to sum them.
+Let's start by manually invoking the contract using only a contract's address. In this example, we have an external contract with a public function named `add_with` which takes two `u32` as input values to sum them.
 
 ```rust
 #[contract]
@@ -48,7 +48,9 @@ impl ContractB {
 }
 ```
 
-Only using the contract comes with its own challenges. Because we don't have access to the Wasm code, we don't have any typing inference and have to manually convert function inputs to `Val`. If we want more tools to help us, we can load the Wasm code in the contract. This allows us to pass normal types without needing manual conversions from our side. Behind the scenes, this way of doing it is simply a convenient wrapper around `env.invoke_contract`.
+Only using the contract address comes with its own challenges. We don't have a contract client so we don't have any typing inference, and have to manually convert function inputs to `Val`.
+
+If we want more tools to help us, we need to get access to a contract client. A common way to do this is to load the Wasm of a contract using `contractimport!`. This allows us to pass normal types without needing manual conversions from our side. Behind the scenes, this way of doing it is simply a convenient wrapper around `env.invoke_contract`.
 
 ```rust
 mod contract_a {
@@ -83,7 +85,7 @@ client::ContractAEnum::SomeField
 
 ## Handling responses
 
-In the examples above, we have used `env.invoke_contract` and `client.some_function`. In both cases, if there is an issue with the underlying contract call, the contract will panic. This might be a valid approach, but in some cases we want to catch errors and handle them depending on the outcome. This is to forward a custom error message, or even triggers an alternative code path.
+In the examples above, we have used `env.invoke_contract` and `client.some_function`. In both cases, if there is an issue with the underlying contract call, the contract will panic. This might be a valid approach, but in some cases we want to catch errors and handle them depending on the outcome. This allows you to forward a custom error message, or even trigger an alternative code path.
 
 Enter `try_`. By using `env.try_invoke_contract` or `client.try_some_function`, underlying errors won't make the contract panic. Instead, errors will be wrapped and can be handled. For example if we wanted to default to 0 in case of an error:
 

docs/build/guides/conventions/cross-contract.mdx

@@ -35,7 +35,7 @@ The [deployer example](https://github.com/stellar/soroban-examples/tree/v22.0.1/
 1. Clone the Soroban Examples Repository:
 
 ```bash
-git clone -b v20.2.0 https://github.com/stellar/soroban-examples
+git clone -b v22.0.1 https://github.com/stellar/soroban-examples
 ```
 
 2. Navigate to the Deployer Example:
@@ -46,7 +46,7 @@ cd soroban-examples/deployer/deployer
 
 :::note
 
-For this example to work, you should navigate to `deployer/contracts` and `deployer/deployer` and run the command `stellar contract build` in each directory to generate the target files.
+For this example to work, you should navigate to `deployer/contract` and `deployer/deployer` and run the command `stellar contract build` in each directory to generate the target files.
 
 :::
 
@@ -219,8 +219,6 @@ stellar contract invoke \
   --init_args '[{"u32":8}]'
 ```
 
-replace `alice` with your own identity
-
 The deployer contract invocation will return the Contract address (For example: `CCTVFX6BFTQHTGAHA5TY4YZQJRUKRE2RRNUTGVBNKE3PJF5C7CI53APY`) of the newly deployed test contract.
 
 Invoke the deployed test contract using the address returned from the previous command.

docs/build/guides/conventions/deploy-contract.mdx

@@ -20,7 +20,7 @@ description: Deploy a SAC for a Stellar asset using Javascript SDK
 
 ## Overview
 
-In this guide, you'll learn how to deploy a [Stellar Asset Contract (SAC)](../../../tokens/stellar-asset-contract.mdx) for a Stellar asset using the [Stellar SDK](../../../tools/sdks/client-sdks.mdx#javascript-sdk). The Stellar SDK is a set of tools and library designed to help developers build applications that interact with the Stellar blockchain network.
+In this guide, you'll learn how to deploy a [Stellar Asset Contract (SAC)](../../../tokens/stellar-asset-contract.mdx) for a Stellar asset using the [Stellar SDK](../../../tools/sdks/client-sdks.mdx#javascript-sdk). The Stellar SDK is a set of tools and libraries designed to help developers build applications that interact with the Stellar blockchain network.
 
 ### Prerequisites:
 
@@ -33,10 +33,9 @@ In this guide, you'll learn how to deploy a [Stellar Asset Contract (SAC)](../..
 
 ```javascript title="deployassetcontract.js"
 import * as StellarSdk from "@stellar/stellar-sdk";
-import { Server } from "@stellar/stellar-sdk/rpc";
 
 const networkRPC = "https://soroban-testnet.stellar.org";
-const server = new Server(networkRPC);
+const server = new StellarSdk.rpc.Server(networkRPC);
 const networkPassphrase = StellarSdk.Networks.TESTNET;
 
 const deployStellarAssetContract = async () => {
@@ -90,20 +89,19 @@ import * as StellarSdk from "@stellar/stellar-sdk";
 
 const networkRPC = "https://soroban-testnet.stellar.org";
 const server = new StellarSdk.rpc.Server(networkRPC);
-const network_passphrase = StellarSdk.Networks.TESTNET;
+const networkPassphrase = StellarSdk.Networks.TESTNET;
 ```
 
 - `networkRPC`: The URL for the Soroban testnet.
 - `server`: A new instance of `rpc.Server` is created, which will be used to interact with the Soroban testnet.
-- `network_passphrase`: sets the network passphrase to the TESTNET
+- `networkPassphrase`: sets the network passphrase to the TESTNET
 
 **`DeployStellarAssetContract` function**
 
 ```javascript
 const deployStellarAssetContract = async () => {
   const sourceSecrets =
     "SASI6PA4K52GQJF6BC263GLYOADVKFJ4SZ7TFX4QQF2U76T3EJ54DT7Y"; // Replace with your Secret Key
-  const networkPassphrase = StellarSdk.Networks.TESTNET;
   const sourceKeypair = StellarSdk.Keypair.fromSecret(sourceSecrets);
   const sourceAccount = await server.getAccount(sourceKeypair.publicKey());
 
@@ -139,8 +137,6 @@ const deployStellarAssetContract = async () => {
     console.error("An error occurred while Deploying assets:", e);
   }
 };
-
-await deployStellarAssetContract();
 ```
 
 This function is designed to deploy a Stellar Asset Contract (SAC) on the Soroban testnet.
@@ -150,4 +146,4 @@ This function is designed to deploy a Stellar Asset Contract (SAC) on the Soroba
 - **Custom Asset**: Defines a custom asset with the code `JOEBOY` and the issuer's public key.
 - **Transaction Building**: A transaction is built using the `TransactionBuilder`, which includes the `createStellarAssetContract` operation for the custom asset. The transaction is then prepared and signed.
 - **Send Transaction**: The signed transaction is sent to the network using `server.sendTransaction`.
-- **Feedback Handling**: It waits for the transaction feedback using the `submitTx` function to ensure it has succeeded. extracts the contract buffer from the feedback and converts it to a contract ID using `StellarSdk.Address`. finally, it logs the contract ID for the deployed asset.
+- **Feedback Handling**: It waits for the transaction feedback using the `submitTx` function to ensure it has succeeded. Then, it extracts the return value and converts it to a contract ID using `StellarSdk.Address`. Finally, it logs the contract ID for the deployed asset.

docs/build/guides/conventions/deploy-sac-with-code.mdx

@@ -1,10 +1,10 @@
 ---
 title: Organize contract errors with an error enum type
 hide_table_of_contents: true
-description: Manage and communicate contract errors using an enum struct stored as Status values
+description: Manage and communicate contract errors using an enum struct
 ---
 
-A convenient way to manage and meaningfully communicate contract errors is to collect them into an `enum` struct. These errors are a special type of enum integer type that are stored on ledger as Status values containing a `u32` code. First, create the `Error` struct in your smart contract.
+A convenient way to manage and meaningfully communicate contract errors is to collect them into an `enum` struct. These errors are a special type of enum integer type that are stored on the ledger as Error values containing a `u32` code. First, create the `Error` struct in your smart contract.
 
 ```rust
 #[contracterror]
@@ -18,18 +18,36 @@ pub enum Error {
 }
 ```
 
-Then, panic with an error when the conditions are met. This example will panic with the specified error.
+Smart contracts can fail with error enums in two different ways. They can either return a `Result` with their intended return value and the `#[contracterror]` struct as the error, or just invoke `panic_with_error!` with the appropriate Error enum value whenever an error condition is reached. By default, most ecosystem standards assume that contract functions do not return a `Result`, so using `panic_with_error!` is recommended.
+
+However, both styles behave in the same way. If an error is returned or `panic_with_error!` is invoked, the transaction will fail. Contracts making cross contract calls have the ability to catch and handle these failures with `try_` functions.
 
 ```rust
 #[contractimpl]
 impl Contract {
-    pub fn causeerror(env: Env, error_code: u32) -> Result<(), Error> {
-        match error_code {
-            1 => Err(Error::FirstError),
-            2 => Err(Error::AnotherError),
-            3 => Err(Error::YetAnotherError),
-            _ => Err(Error::GenericError),
-        }
+    /// Call `panic_with_error!` to fail with custom errors
+    /// This is the default, recommended approach adopted by most SEP standards
+    pub fn cause_error(env: Env, error_code: u32) -> u32 {
+        let error_type = match error_code {
+            0 => return 0,
+            1 => Error::FirstError,
+            2 => Error::AnotherError,
+            3 => Error::YetAnotherError,
+            _ => Error::GenericError,
+        };
+        panic_with_error!(env, error_type);
+    }
+
+    /// Return `Err` to fail with custom errors
+    pub fn cause_error_result(env: Env, error_code: u32) -> Result<u32, Error> {
+        let error_type = match error_code {
+            0 => return Ok(0),
+            1 => Error::FirstError,
+            2 => Error::AnotherError,
+            3 => Error::YetAnotherError,
+            _ => Error::GenericError,
+        };
+        return Err(error_type);
     }
 }
 ```