Build Soroban contract auth entry builder with simulation pre-check

[Kingsman-99]

Description

Building SorobanAuthorizationEntry objects for complex multi-party Soroban invocations requires correctly assembling nested auth trees and pre-populating signatures, which is error-prone and under-documented. This issue adds a ContractAuthBuilder that constructs valid auth entries from a high-level AuthSpec descriptor, runs a simulation to validate the entry before submission, and returns the fully signed SorobanAuthorizedInvocation ready for the transaction envelope.

Technical Context

• New file: src/auth/ContractAuthBuilder.ts; types: AuthSpec, AuthEntry, AuthBuildResult in src/types/auth.ts
• AuthSpec: { contractId: string; functionName: string; args: xdr.ScVal[]; signers: SignerSpec[] } where SignerSpec is { keypair?: Keypair; publicKey: string; weight: number }
• The builder uses SorobanRpc.Server.simulateTransaction() to obtain the sorobanData and the pre-authorized entries, then merges them with the provided signers
• If simulation returns error, the builder throws AuthSimulationError with the diagnostic events from the simulation response
• ContractAuthBuilder.build(spec, networkPassphrase): Promise<AuthBuildResult> is the primary API; AuthBuildResult includes the entry XDR and simulation cost

Acceptance Criteria

• build() produces a valid SorobanAuthorizationEntry that can be included in a transaction envelope and accepted by the Soroban sandbox without auth errors
• When simulation returns an error, AuthSimulationError is thrown with the full diagnostic event list attached
• Multi-signer specs where the total weight meets the threshold produce an entry with all signer signatures included
• The builder correctly handles nested invocations (contract A calling contract B) by recursively building auth entries for each callee
• Integration tests run against a local Soroban sandbox with a deployed test contract
• All CI checks (npm test, npm run build, ESLint) pass and the branch has no merge conflicts

---

[willowgray071-cpu]

@willowgray071-cpu has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

i can get this done, kindly assign to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @willowgray071-cpu to this issue.

[drips-wave]

Congratulations, @willowgray071-cpu! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @willowgray071-cpu: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @willowgray071-cpu as part of the Stellar Wave Program's 7th Wave 🥳

😎 @willowgray071-cpu: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.