Skip to content

Commit 301ee85

Browse files
mohamedbasuonysalaheldinsoliman
mohamedbasuony
and
salaheldinsoliman
authored
docs(soroban): clarify support status and reorganize docs (#1883)
## Summary This PR improves and reorganizes the Soroban target documentation. - expand `docs/targets/soroban.rst` into a clearer landing page - add dedicated pages for the support matrix, language compatibility, example coverage, and Rust SDK differences - update the main `README.md` to point readers to the Soroban documentation and current support status - add a maintenance note to make support expectations explicit ## Notes - docs only - no compiler or runtime behavior changes - intended to make the current Soroban status easier to understand for contributors and users Signed-off-by: salaheldinsoliman <salaheldin_sameh@aucegypt.edu> Co-authored-by: salaheldinsoliman <salaheldin_sameh@aucegypt.edu>
1 parent 6ce21bc commit 301ee85

7 files changed

Lines changed: 851 additions & 100 deletions

‎MAINTENANCE.MD‎

Lines changed: 307 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,307 @@
1+
# Soroban Target Maintenance Policy
2+
3+
This document defines the maintenance and compatibility expectations for the Soroban target.
4+
5+
## Status
6+
7+
The Soroban target is currently considered **experimental**.
8+
9+
This means:
10+
11+
- the target is actively maintained
12+
- core functionality is expected to work for supported features
13+
- some language features and platform integrations are not supported or may still change
14+
- breaking changes may occur when required by correctness, upstream Soroban changes, or architectural improvements
15+
16+
Experimental does **not** mean unmaintained. It means the support surface is explicitly scoped and evolves with the platform.
17+
18+
---
19+
20+
## Goals
21+
22+
The Soroban backend aims to:
23+
24+
- make Soroban more accessible to Solidity developers
25+
- document all meaningful deviations from `solc` and from EVM behavior
26+
- evolve alongside the Soroban platform in a predictable way
27+
28+
---
29+
30+
## Non-Goals
31+
32+
The Soroban backend does not currently guarantee:
33+
34+
- full Solidity language parity with `solc`
35+
- identical runtime semantics to the EVM
36+
37+
---
38+
39+
## Support Levels
40+
41+
Each Soroban-related feature falls into one of three categories.
42+
43+
### Supported
44+
45+
A feature marked **Supported**:
46+
47+
- is covered by automated tests
48+
- is documented
49+
- is expected to remain stable across patch releases
50+
51+
### Experimental
52+
53+
A feature marked **Experimental**:
54+
55+
- is available for use
56+
- may have incomplete edge-case coverage
57+
- may be removed or redesigned if needed
58+
59+
### Unsupported
60+
61+
A feature marked **Unsupported**:
62+
63+
- is not intended to work on Soroban
64+
- must not silently compile into incorrect behavior
65+
66+
---
67+
68+
## Compatibility Policy
69+
70+
This policy defines maintenance expectations. The detailed compatibility behavior is documented in the published Solang docs.
71+
72+
Soroban compatibility expectations are divided into two scopes:
73+
74+
- Solidity language compatibility
75+
- Solang and Soroban Rust SDK differences
76+
77+
This section does not define guarantees for Soroban protocol-version compatibility or tooling-version compatibility.
78+
79+
The detailed compatibility documentation lives in the published Solang docs:
80+
81+
- [Soroban Solidity Language Compatibility](https://solang.readthedocs.io/en/latest/targets/soroban_language_compatibility.html)
82+
- [Solang and Soroban Rust SDK Differences](https://solang.readthedocs.io/en/latest/targets/soroban_rust_sdk_differences.html)
83+
84+
### Solidity Language Compatibility
85+
86+
Authoritative docs: [Soroban Solidity Language Compatibility](https://solang.readthedocs.io/en/latest/targets/soroban_language_compatibility.html)
87+
88+
Solang aims for source-level Solidity familiarity, not EVM equivalence.
89+
90+
This includes language features and semantics such as:
91+
92+
- types
93+
- structs
94+
- arrays
95+
- mappings
96+
- function behavior
97+
- authentication-related language differences from standard Solidity usage
98+
99+
Examples include differences such as Soroban host-based authorization flows, where authentication is performed through Soroban auth mechanisms rather than typical Solidity or EVM patterns like direct `msg.sender` checks.
100+
101+
Where Soroban differs from normal Solidity or from EVM assumptions, Solang will prefer one of the following:
102+
103+
- document the difference
104+
- emit a warning
105+
- reject the construct
106+
107+
Silent semantic mismatches should be treated as bugs.
108+
109+
### Solang and Soroban Rust SDK Differences
110+
111+
Authoritative docs: [Solang and Soroban Rust SDK Differences](https://solang.readthedocs.io/en/latest/targets/soroban_rust_sdk_differences.html)
112+
113+
Solang also documents where its Soroban implementation differs from common patterns used by the Rust SDK.
114+
115+
This includes differences such as:
116+
117+
- storage layout and key structure for contract state
118+
- representation of arrays and vectors in storage, including `VecObject`-backed layouts
119+
- representation of structs and nested values in storage
120+
- host object and handle conventions needed to interact with Soroban contracts written in Rust
121+
122+
Examples include differences or compatibility requirements around storage representation, such as arrays of native types being stored through `VecObject` handles, and structs or arrays of structs being represented through composite storage keys rather than EVM-style slot packing.
123+
124+
This scope is about documented differences in representation and implementation choices.
125+
It is not a general guarantee of raw storage compatibility.
126+
127+
When Solang uses a different layout or access pattern than a Rust SDK contract would typically use, that difference should be documented clearly.
128+
Undocumented mismatches in documented areas should be treated as bugs.
129+
130+
---
131+
132+
## Release Policy
133+
134+
### Patch Releases
135+
136+
Patch releases may include:
137+
138+
- bug fixes
139+
- diagnostic improvements
140+
- documentation improvements
141+
- non-breaking test and tooling updates
142+
- correctness fixes for clearly incorrect existing behavior
143+
144+
Patch releases should not intentionally introduce new breaking Soroban semantics unless the current behavior is wrong and keeping it would be more harmful.
145+
146+
### Minor Releases
147+
148+
Minor releases may include:
149+
150+
- new Soroban features
151+
- Soroban backend refactors
152+
- changes required by upstream protocol or tooling evolution
153+
- breaking changes, with migration notes
154+
155+
Every Soroban-breaking change in a minor release should include:
156+
157+
- a short description of the change
158+
- the reason for the change
159+
- who is affected
160+
- migration guidance where applicable
161+
162+
---
163+
164+
## Upstream Change Handling
165+
166+
When Soroban platform changes occur, maintainers should classify them as one of:
167+
168+
- no action needed
169+
- tooling-only update
170+
- compiler/runtime behavior update required
171+
- breaking change requiring user migration
172+
173+
Protocol upgrades and upstream breaking changes take priority over new feature work.
174+
175+
---
176+
177+
## Testing Requirements
178+
179+
A Soroban feature should not be considered Supported unless it is covered by tests appropriate to its risk.
180+
181+
The Soroban CI suite should include, where applicable:
182+
183+
- compile-time tests
184+
- negative tests for unsupported constructs
185+
- runtime tests against a local Soroban environment
186+
- regression tests for prior bugs
187+
- integration tests for common contract patterns
188+
189+
Priority test areas include:
190+
191+
- storage behavior
192+
- contract initialization
193+
- authorization/auth-related behavior
194+
- cross-contract calls
195+
- ABI/spec generation and decoding expectations
196+
- integer and data-layout correctness
197+
- failure/revert/error behavior where relevant
198+
199+
Every confirmed Soroban bug should add a regression test when feasible.
200+
201+
---
202+
203+
## Bug Triage Priorities
204+
205+
### P0 — Critical
206+
207+
Examples:
208+
209+
- miscompilation
210+
- security-sensitive incorrect behavior
211+
- incorrect authorization behavior
212+
- incorrect storage behavior
213+
- breakage caused by Soroban protocol/tooling upgrades
214+
215+
These issues should take precedence over feature development.
216+
217+
### P1 — High
218+
219+
Examples:
220+
221+
- valid Soroban-target contracts rejected unexpectedly
222+
- major supported feature broken
223+
- deployment/invocation workflow broken
224+
225+
### P2 — Normal
226+
227+
Examples:
228+
229+
- diagnostics quality
230+
- missing warnings
231+
- documentation gaps
232+
- edge-case issues in experimental areas
233+
234+
---
235+
236+
## Documentation Requirements
237+
238+
Soroban behavior should be documented in a way users can rely on.
239+
240+
At minimum, the project should maintain:
241+
242+
- a Soroban compatibility matrix
243+
- a list of unsupported features
244+
- a list of known differences from `solc` / EVM expectations
245+
- migration notes for breaking changes
246+
- examples for supported Soroban workflows
247+
248+
If a feature is not documented and not tested, it should not be treated as stable.
249+
250+
---
251+
252+
## Deprecation Policy
253+
254+
When support is planned to be removed for:
255+
256+
- a protocol version
257+
- a tooling version
258+
- a Soroban-specific feature shape
259+
- an experimental interface
260+
261+
the project should communicate this in advance whenever feasible through:
262+
263+
- release notes
264+
- migration notes
265+
- warnings in docs and/or compiler diagnostics where appropriate
266+
267+
Immediate removals may still occur if required by correctness or upstream incompatibility.
268+
269+
---
270+
271+
## Definition of Production Readiness
272+
273+
The Soroban target should only be described as production-ready when all of the following are true:
274+
275+
- a compatibility matrix exists and is maintained
276+
- core supported features have stable regression coverage
277+
- at least one full upstream protocol transition has been handled cleanly
278+
- no known critical miscompilation bugs remain open in supported areas
279+
- major behavioral differences are documented
280+
- users have a clear upgrade and migration path
281+
282+
Until then, users should treat the Soroban target as suitable for experimentation, prototyping, evaluation, and controlled pilots.
283+
284+
---
285+
286+
## Maintainer Expectations
287+
288+
The Soroban backend should have:
289+
290+
- at least one named primary maintainer
291+
- at least one backup reviewer familiar with the target
292+
- a release checklist for Soroban-affecting changes
293+
294+
Ownership is required for the policy to be meaningful.
295+
296+
---
297+
298+
## Summary
299+
300+
In short, the Soroban target is maintained with the following principles:
301+
302+
- correctness over feature count
303+
- explicit support levels
304+
- clear compatibility boundaries
305+
- fast reaction to upstream Soroban changes
306+
- no silent incorrect behavior
307+
- documented breaking changes

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,12 @@ stellar contract invoke --network testnet --id CDGUMUXA6IRRVMMKIVQJWLZZONDXBJ4AI
8383
ℹ️ Signing transaction: e0d68ae85bfbe0fceed8bcadd6613e12b3159f27dbf7c18e35e94de2b4a11ee2
8484
```
8585

86+
For the current Soroban support matrix, see the
87+
[`Soroban support matrix`](https://solang.readthedocs.io/en/latest/targets/soroban_support_matrix.html).
88+
For Soroban compatibility details, see the
89+
[`Soroban target docs`](https://solang.readthedocs.io/en/latest/targets/soroban.html).
90+
The repository-level Soroban maintenance policy lives in [`MAINTENANCE.MD`](MAINTENANCE.MD).
91+
8692

8793

8894
## Tentative roadmap

0 commit comments

Comments
 (0)