Allow Re-Entry for Read-Only (View) Functions

[NatureLab]

[Discussion] Allow Re-Entry for Read-Only (View) Functions

Repository: stellar/stellar-core or stellar/rs-soroban-sdk
Category: Feature Request / Protocol Design

---

TL;DR

Soroban blocks all re-entry at the host level, including read-only queries that do not modify state. This prevents a common DeFi pattern: Contract A calls Contract B, and B needs to read back from A to independently verify a value.

We propose allowing read-only (view) functions to be called re-entrantly, enforced by the host at compile time or runtime.

---

The Problem

The Pattern That Broke

In DeFi protocols, it is common for two contracts to need mutual read access:

Contract A owns data X (e.g., total supply, utilization, balance)
Contract B manages policy about X (e.g., cap enforcement, rate decisions)

A calls B: "should I proceed?"
  → B needs to read X from A to decide
  → B calls A: "what is X?"     ← re-entry blocked

This is not a re-entrancy attack. No state is modified. It is two contracts reading each other's data in a single atomic call.

Concrete Example

Consider a lending pool and a cap manager:

User calls Pool.borrow(collateral, amount)
  → Pool calls CapManager.check_cap(collateral)
    → CapManager reads its own cap[C] from storage          ✅ OK
    → CapManager calls Pool.get_total_borrowed(collateral)   ❌ BLOCKED: re-entry
    → CapManager returns cap - total_borrowed                never reached

get_total_borrowed is a read-only function. It reads one value from persistent storage and returns it. It modifies no state, calls no other contracts, emits no events. It is the exact Soroban equivalent of a Solidity view function.

---

Current Workaround: Trusted Caller + Passed Args

The Stellar team's suggested approach is a combination of two patterns:

1. Pass the needed data as call arguments — rather than B calling back to A, A pre-computes the value and passes it to B
2. Validate the caller via require_auth — B checks that the caller is indeed the trusted contract A, so A cannot fabricate values

// CapManager trusts only Pool to call it
impl CapManager {
    fn check_cap(env: Env, pool_addr: Address, token: Address, current_borrowed: u128) -> u128 {
        pool_addr.require_auth();                            // ✅ verify: only Pool can call this
        let cap = env.storage().persistent().get(&key).unwrap_or(0);
        cap.saturating_sub(current_borrowed)                  // trust: Pool passed the right value
    }
}

// Pool pre-computes and passes the value
impl Pool {
    fn borrow(env: Env, caller: Address, token: Address, amount: u128) {
        let current_borrowed = pool_state.total_borrowed;     // pre-compute locally
        let remaining = env.invoke_contract::<u128>(
            &cap_manager_addr,
            &Symbol::new(&env, "check_cap"),
            vec![&env, env.current_contract_address().into_val(&env), token, current_borrowed],
        );
        assert!(amount <= remaining);
    }
}

This workaround is fully functional and secure. It works for the single-caller case. The require_auth check ensures that the value comes from a trusted source.

Why This Workaround Has Downstream Costs

The issue emerges when the protocol grows beyond one caller:

Scenario	Impact
Multiple callers integrate with CapManager	Each caller must independently know to pass current_borrowed. One omission = one cap bypass.
A new contract joins the protocol	The developer must read the source code of 3 other contracts to understand what arguments to pass.
An auditor reviews the protocol	They must verify argument-passing correctness across N call sites instead of one centralized function.
A governance upgrade adds a new field to the cap check	Every caller's argument list must be updated.

In contrast, if CapManager could make a re-entrant view call to Pool.get_total_borrowed:

Scenario	With Re-Entrant View Calls
Multiple callers	CapManager handles it — callers don't need to know implementation details
New contract joins	Just call CapManager with the token address
Auditor reviews	Verify one function in CapManager
Governance upgrade	Update one function in CapManager

The require_auth workaround is correct — it just distributes responsibility across the codebase rather than centralizing it.

---

Proposal

Core Idea

Allow contract developers to declare that certain functions are read-only and therefore safe for re-entry. The host enforces this guarantee — either at compile time (by validating the function body) or at runtime (by rejecting any call that would mutate state).

Syntax (Strawman)

#[contract]
pub struct Pool;

#[contractimpl]
impl Pool {
    // Normal function — re-entry blocked (default, unchanged)
    pub fn borrow(env: Env, ...) { ... }

    // Read-only view — marked safe for re-entry
    #[view]
    pub fn get_total_borrowed(env: Env, token: Address) -> u128 {
        env.storage().persistent().get(&key).unwrap_or(0)
    }
}

If #[view] conflicts with existing semantics, an alternative name: #[allow_reentry].

Safety Rules

1. No state mutation: a #[view] function must be provably read-only. The host can enforce this:

   • Compile time: the macro verifies no env.storage().*().set(), no env.events().publish(), no env.invoke_contract(), no env.prng()
   • Runtime (fallback): the host rejects any write operation from a #[view] context with a clear error

2. No cross-contract calls: a #[view] function cannot invoke_contract. This prevents recursive re-entry through N layers.

3. Default is safe: functions without #[view] retain the current behavior (no re-entry). Developers must explicitly opt in.

4. Zero runtime cost for non-view functions: the enforcement is a compile-time check plus a flag on the function descriptor. Existing contracts see no performance regression.

What This Enables

// CapManager queries Pool's state directly — no caller needs to pre-compute anything
#[contractimpl]
impl CapManager {
    fn check_cap(env: Env, token: Address) -> u128 {
        let cap = env.storage().persistent().get(&key).unwrap_or(0);
        let pool_addr = env.storage().instance().get(&pool_key).unwrap();
        let used: u128 = env.invoke_contract(              // ✅ no longer blocked
            &pool_addr,
            &Symbol::new(&env, "get_total_borrowed"),      // #[view] function
            vec![&env, token.into_val(&env)],
        );
        cap.saturating_sub(used)
    }
}

---

Summary of Trade-offs

	require_auth + Pass Args	Re-Entrant View Calls
Security	✅ Cryptographic caller verification	✅ Host-enforced read-only
Single-caller	✅ Simple	✅ Simple
Multi-caller	❌ Each caller replicates passing logic	✅ CapManager handles it
Audit cost	❌ N call sites to verify	✅ One function to verify
Protocol upgrade	❌ All callers must update	✅ One function to update
Developer onboarding	❌ Must read multiple contracts	✅ Read CapManager interface
Implementation cost for Soroban	✅ Already works today	❌ Requires host-level change

Both approaches are secure. The trade-off is between distributed responsibility (current workaround) and centralized policy (proposed feature).

---

Precedent

• Solidity: view and pure functions can be called re-entrantly by design. DeFi relies on this extensively.
• CosmWasm: QueryMsg is a separate entry point specifically for read-only operations.
• Sui Move: #[view] functions are restricted from modifying state and can be safely re-entered.

Soroban's current behavior (blocking all re-entry including reads) is more restrictive than all three major platforms.

---

Scope

This benefits many DeFi patterns:

Protocol Pattern	Read-Only Re-Entry Use Case
Lending + Oracle	Oracle queries pool utilization for rate adjustment
Yield Aggregator + Strategy	Strategy queries vault TVL
AMM Router + Pair	Router queries pair reserves for routing
Governance + Token	Governor queries token supply for quorum
CDP + Cap Manager	Cap manager queries minted amount

---

Request

We request a formal feature: allow read-only functions (declared with #[view] or similar) to bypass re-entry detection at the host level, with compile-time and/or runtime enforcement that they do not modify state.

[sueun-dev]

this looks pretty close to the older read-only invocation thread in #1454, plus stellar/rs-soroban-sdk#971. The part that seems new here is not just "mark a function read-only", it's "permit a read-only sub-invocation back into an ancestor while the parent call is still writable."

That probably needs to be spelled out separately from generic #[view]: how the host would enter read-only mode for only that callee frame, what happens to the callee's footprint/budget, and whether generated clients can refuse anything that isn't declared read-only in the contract spec. Otherwise a view flag helps tooling, but it doesn't by itself solve the re-entry edge.

[dmkozh]

I think the concrete issue of read-only data access is better addressed by the read-only storage access proposal (https://github.com/orgs/stellar/discussions/1958), though that has its own set of issues and we're also not sure if it would make it into protocol.

That said, I'm not sure I fundamentally agree with the motivation for not passing the arguments listed here:

Each caller must independently know to pass current_borrowed. One omission = one cap bypass.

I'm not sure why is this an issue. If you own both contracts, that's a non-issue. If some external contracts may be involved, that's still something reasonable to cover in the public API. Basically, I don't see why passing argument X is fine, but passing argument Y would not be fine. (Also, a side note: you probably want to use require_auth for your caller no matter what, it's not really a part of the 'workaround').

The developer must read the source code of 3 other contracts to understand what arguments to pass.

That's not true, is it? I'm not even sure what the 3 contracts are in question (given that the example provides just pool and cap manager contracts). If CapManager can be customized, then current_borrowed would just be a part of its interface. A developer that implements it just needs to know the interface and nothing else, which is actually better than the proposed option, where they also need to know how to get the total amount of borrowed token from the caller. That creates unnecessary tight coupling between the contracts and ultimately makes the developer experience worse, not better.

An auditor reviews the protocol | They must verify argument-passing correctness across N call sites instead of one centralized function.

I don't understand this argument. An auditor just needs to review the public interface between the pool and cap manager, as well as both implementations. What do you mean by 'argument-passing correctness' here? Is that simply the fact that the arguments are being passed into calls? If so, then it's of course necessary to pass the correct arguments to every cross-contract call, but it's trivial to test and shouldn't incur any meaningful additional cost for the audit. On the other hand, re-entrance is actually really tricky to audit and argue about, even if it's opt-in and only read-only functions are involved. For example, the caller contract (Pool) may mutate its state before or after making a cross-contract call, and thus the callee may observe inconsistent data that wasn't meant to be observed. The sheer possibility of re-entrance increases the audit surface and the risks dramatically.

A governance upgrade adds a new field to the cap check | Every caller's argument list must be updated.

That's the only argument I really agree with, but I think the issue here is really not about the approach in general, but specifically about sub-par data-migration support in Soroban. Specifically, it's currently not possible to add a field to a contracttype struct without breaking the compatibility. We've been considering actually supporting this for a while, and we might prioritize this sooner rather than later. This way you'd be able to do something like this:

[contracttype]
struct CheckCapArgs {
  token: Address
  current_borrowed: i128 // note: use i128 for token amounts instead of u128
}

impl CapManager {
    fn check_cap(env: Env, args: CheckCapArgs) -> i128 {
        env.storage().instance().get_unchecked(&DataKey::Pool).require_auth(); // note: it's necessary to actually verify that the registered pool have called this
        let cap = env.storage().persistent().get(&key).unwrap_or(0);
        cap.saturating_sub(args.current_borrowed);
    }
}

As soon as data migration is supported, new fields can be added to CheckCapArgs without the necessity to update any callers. Does that approach make sense to you?

[dmkozh]

Thanks for the example, I think I understand the concern better now. Basically it seems like we have a many-to-one call pattern here. But I'm still not entirely sure that I agree with most of the arguments for read-only methods. Please correct me if my understanding is wrong:

• Every caller must implement some fixed interface (say, CapManagedProtocol) that exposes every read-only protocol parameter
• CapManager relies on every caller to implement CapManagedProtocol
• If CapManagedProtocol interface is updated, every caller contract has to be upgraded to support the new interface

With argument passing approach:

• Every caller must implement a private function like fn get_cap_managed_arguments() -> CheckCapArgs, we call that function to pass arguments to CapManager
• get_cap_managed_arguments implementation is pretty much equivalent to CapManagedProtocol implementation, besides the fact that we group all the arguments in a struct instead of exposing every one of them as a separate contract function.
• If CheckCapArgs interface is updated, every caller contract has to be upgraded to fill in new arguments

Basically it seems to me like amount of maintenance is exactly the same between both approaches; upgrade process is rather brittle in either approach because every contract in the protocol has to be upgraded. Callers also must be upgraded before the CapManager. Also, every caller still needs to know how to compute every argument. Am I missing something else here?

If Soroban’s direction is to avoid read-only reentry entirely, then I think the most important mitigation is exactly the compatibility work you mentioned: making structured argument objects evolvable, so shared policy argument structs can grow without forcing all callers to change at once.

Yeah, the argument passing approach hinges on future compatibility (so that we can update callers seamlessly before upgrading CapManager). We'll try to land this soon in the protocol as this is a generally desirable feature. That said, I just wanted to make sure that we're on the same page regarding the maintainability concerns mentioned above.

[NatureLab]

Thanks, I think I understand your framing better now, and I agree with an important part of it.

If the design is:

Every caller implements a read interface such as CapManagedProtocol

then I agree that this is not materially better than:

Every caller implements a private get_cap_managed_arguments() -> CheckCapArgs

In both cases, every caller still needs to know how to expose or compute the relevant policy inputs, and every caller may need to be upgraded when those inputs change. In that framing, read-only reentry does not provide a clear maintainability win, and it also brings the additional concern of exposing caller state during cross-contract execution.

So I think the more precise conclusion for us is:

Read-only reentry is not the goal by itself.
The goal is to have a safe, maintainable, and upgrade-friendly way for shared policy contracts to validate canonical protocol state.

If Soroban's preferred model is explicit argument passing, then I think that can be a reasonable direction, provided the model has strong enough compatibility and upgrade support.

The pieces that matter most to us are:

1. Evolvable contracttype structs
2. Clear schema compatibility rules
3. A safe staged upgrade path
4. Guidance for canonical construction of policy arguments
5. Avoiding unsafe defaults for newly added safety-critical fields

Evolvable structs

The biggest practical concern with argument passing is that policy inputs evolve over time.

For example:

struct CheckCapArgs {
    collateral: Address,
    current_total_minted: u128,
}

may later become:

struct CheckCapArgs {
    collateral: Address,
    current_total_minted: u128,
    pending_exposure: u128,
    isolated_debt: u128,
}

If every caller has to be upgraded atomically with the policy contract, then the upgrade process is brittle. If Soroban supports adding fields to contracttype structs in a backward-compatible way, that removes a large part of the pain.

That said, this needs very clear semantics. For example:

• What default value does a newly added field receive when omitted by an old caller?
• Is the default always the type default, such as 0, false, or None?
• Can a contract distinguish whether a field was explicitly supplied or defaulted?
• How does this appear in generated clients and contract specs?
• Are there compatibility guarantees across SDK versions?

Staged upgrades

The argument passing model seems workable if callers can be upgraded before the policy contract starts requiring new fields.

A safe upgrade flow might look like:

1. Deploy/upgrade callers so they can construct CheckCapArgsV2.
2. Keep CapManager accepting old semantics during the migration period.
3. Upgrade CapManager to start enforcing the new policy once callers are migrated.
4. Optionally deprecate the old fields/semantics later.

This is the part where evolvable structs are especially useful. They allow protocol teams to avoid requiring every contract to be upgraded in the exact same transaction or ledger window.

Safety-critical defaults

One concern is that not every new field is safe to default.

For example, if a new field is informational or conservative, a default value may be fine. But if the field is safety-critical, such as:

pending_exposure
isolated_debt
same_tx_borrowed_amount
unsettled_mint_amount

then defaulting it to 0 may be unsafe, because old callers would silently bypass the new risk dimension.

So even if the serialization layer supports defaulted fields, policy contracts still need a way to avoid accidentally treating missing safety-critical values as safe values.

Possible approaches could include:

struct CheckCapArgs {
    version: u32,
    collateral: Address,
    current_total_minted: u128,
    pending_exposure: Option<u128>,
}

or explicit policy modes where the policy contract does not enforce the new rule until callers are known to provide the new field.

Where I think we land

I think I agree that read-only reentry is not obviously better if it simply means “every caller exposes the same read interface”. That model has roughly the same maintenance burden as every caller filling in a shared argument struct, plus additional reentry/state-observation risks.

So I would reframe our original concern as follows:

We do not need read-only reentry specifically.
We need the argument-passing model to be robust enough for shared, upgradeable policy contracts.

If Soroban provides evolvable contracttype structs, clear compatibility semantics, and guidance for staged upgrades, then the explicit argument-passing model likely addresses the most important practical concern for us.

That would make the recommended pattern something like:

- Keep policy inputs explicit.
- Group them in structured argument objects.
- Make those argument objects evolvable.
- Upgrade callers before enabling stricter policy rules.
- Avoid relying on unsafe defaults for safety-critical fields.

From that perspective, I think we are mostly aligned. The remaining thing I would like to understand is what exact compatibility guarantees Soroban intends to provide for evolving contracttype structs and generated clients.

[dmkozh]

Alright, it sounds like we're on the same page here. As I've already mentioned, we'll prioritized forward-compatible structs.

pending_exposure: Option<u128>,

That's actually something that I forgot to mention, but only the Option type would indeed be forward-compatible, so that the protocol never tries to guess the default. This is similar to e.g. design of protobufs, where all the message fields are normally optional and it's up to the consumer to decide which fields are actually required for its operation (so in our case if pending_exposure becomes required, the CapManager would just unwrap() the option and correctly fail and cause rollback if it's not supplied).

[leighmcculloch]

we'll prioritized forward-compatible structs

Is this referring to #1877? If so, +1.

[dmkozh]

Is this referring to https://github.com/orgs/stellar/discussions/1877? If so, +1.

Is, it is. Btw CAP-86 that implements this has already been published.