Document ToXdr and FromXdr traits

[leighmcculloch]

What

Added documentation to the ToXdr and FromXdr traits explaining the two-step serialization process: values are first converted to a Val, then serialized to XDR in their ScVal form. Added Errors and Panics sections to FromXdr and from_xdr, doc examples on both traits, and doc comments on the to_xdr, from_xdr methods and the Error associated type.

Why

FromXdr::from_xdr panics if the provided bytes are not valid XDR for an ScVal, but returns an error if the Val cannot be converted into the target type. This distinction was undocumented. The panic originates from the host side, making it non-obvious even when reading the implementation.

Close #1766

[Copilot]

Pull request overview

Improves the Soroban SDK’s XDR conversion API documentation by expanding the rustdoc for ToXdr and FromXdr, clarifying how values are serialized/deserialized via Val/ScVal and what error/panic behavior to expect.

Changes:

• Clarified ToXdr semantics (conversion to Val then serialization as ScVal XDR) and added a short usage example.
• Clarified FromXdr semantics (deserialize ScVal XDR to Val, then convert) and documented error/panic behavior with an example.

[mootz12]

Approving - but it might be worth exploring having from_xdr surface the env::Error thrown by deserialize_from_bytes instead of unwrap_infallible(). I don't really have a use case in mind here, but this might make it simpler to take in raw XDR in contracts.

Leaving as an extra comment to get your thoughts.

[leighmcculloch]

it might be worth exploring having from_xdr surface the env::Error thrown by deserialize_from_bytes instead of unwrap_infallible()

Yeah, but that's a protocol change, so not going to do that here. Take that to a GitHub Discussion to pursue.