Document and test get_payment_token None semantics before first deposit in README integrator section

README.md

@@ -25,7 +25,7 @@ Soroban contract for revenue-share offerings and blacklist management.
 |--------|------------|---------|------|-------------|
 | `register_offering` | `issuer: Address`, `token: Address`, `revenue_share_bps: u32` | `Result<(), RevoraError>` | issuer | Register a revenue-share offering. Fails with `InvalidRevenueShareBps` if `revenue_share_bps > 10000`. |
 | `get_offering` | `issuer: Address`, `token: Address` | `Option<Offering>` | — | Fetch one offering by issuer and token. |
-| `get_payment_token` | `issuer: Address`, `namespace: Symbol`, `token: Address` | `Option<Address>` | — | Return the payment token locked by the first successful deposit. Returns `None` before the first successful deposit or for an unknown offering. |
+| `get_payment_token` | `issuer: Address`, `namespace: Symbol`, `token: Address` | `Option<Address>` | — | Return the payment token locked by the first successful deposit. Returns `None` if the offering is unknown or if the offering exists but has not yet received a successful deposit. |
 | `list_offerings` | `issuer: Address` | `Vec<Address>` | — | List offering tokens for issuer (first page only, up to 20). |
 | `report_revenue` | `issuer: Address`, `token: Address`, `amount: i128`, `period_id: u64` | `Result<(), RevoraError>` | issuer | Emit or correct a revenue report. New periods update `AuditSummary`; existing periods may be corrected with `override_existing=true`, which emits explicit override events and applies the net delta to `total_revenue` without incrementing `report_count`. |
 | `get_offering_count` | `issuer: Address` | `u32` | — | Total offerings registered by issuer. |

docs/payment-token-locking.md

@@ -16,7 +16,7 @@ deposit processing or `get_payment_token` reads.
 
 ## Behavior
 
-- `get_payment_token` returns `None` before the first successful deposit.
+- `get_payment_token` returns `None` if the offering is unknown or if the offering exists but has not yet recorded a successful deposit.
 - The first successful deposit writes `PaymentToken = payment_token`.
 - Subsequent deposits must use that exact token or fail with
   `RevoraError::PaymentTokenMismatch`.

src/lib.rs

@@ -2136,7 +2136,12 @@ impl RevoraRevenueShare {
 
     /// Return the locked payment token for an offering.
     ///
-    /// Returns `None` until the first successful deposit persists the `PaymentToken` key.
+    /// Returns `None` when:
+    /// - the offering is unknown, or
+    /// - the offering exists but has not yet recorded a successful deposit.
+    ///
+    /// Once the first successful deposit persists the `PaymentToken` key, this returns
+    /// `Some(payment_token)` for that locked token.
     pub fn get_payment_token(
         env: Env,
         issuer: Address,

src/test.rs

@@ -1959,6 +1959,37 @@ fn get_payment_token_returns_none_for_unknown_offering() {
     assert_eq!(client.get_payment_token(&issuer, &symbol_short!("def"), &offering_token), None);
 }
 
+#[test]
+fn failed_invalid_first_deposit_does_not_lock_payment_token() {
+    let env = Env::default();
+    env.mock_all_auths();
+    let client = make_client(&env);
+    let issuer = Address::generate(&env);
+    let offering_token = Address::generate(&env);
+    let payment_token = Address::generate(&env);
+
+    client.register_offering(
+        &issuer,
+        &symbol_short!("def"),
+        &offering_token,
+        &5_000,
+        &payment_token,
+        &0,
+    );
+
+    let result = client.try_deposit_revenue(
+        &issuer,
+        &symbol_short!("def"),
+        &offering_token,
+        &payment_token,
+        &100_000,
+        &0,
+    );
+
+    assert_eq!(result, Err(Ok(RevoraError::InvalidPeriodId)));
+    assert_eq!(client.get_payment_token(&issuer, &symbol_short!("def"), &offering_token), None);
+}
+
 #[test]
 fn deposit_revenue_multiple_periods() {
     let (_env, client, issuer, token, payment_token, _contract_id) = claim_setup();