Auth

Helper for signing Soroban authorization entries.

Supports legacy ADDRESS credentials (Protocol 20+), ADDRESS_V2 credentials (Protocol 27+), and ADDRESS_WITH_DELEGATES credentials (Protocol 27+) with recursive delegate trees.

Preimage selection

The hash preimage type is determined by the credential arm:

• ADDRESS ->ENVELOPE_TYPE_SOROBAN_AUTHORIZATION (legacy; not address-bound)

• ADDRESS_V2 and ADDRESS_WITH_DELEGATES ->ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS

For ADDRESS_WITH_DELEGATES, the address in the preimage is always the top-level credential address, never a delegate address. All signers in the tree (top-level and every delegate at any depth) sign the same hash.

Signature write-back

Signing appends a new {public_key, signature} map element to the node's existing signature vector. A void signature becomes a one-element vector. Existing non-void signatures are never overwritten. Append order is call order; callers are responsible for supplying signatures in ascending public-key order where the host requires it (G-address, medium threshold multi-sig). Calling authorizeEntry twice with the same key on the same node appends a duplicate the host will reject.

Expiration

An entry stores one signature expiration ledger, and every signature on it, top-level and delegate, commits to that value. authorizeEntry stamps validUntilLedgerSeq before hashing. When any node already carries a signature (neither void nor an empty vector; see carriesSignature), including the node being signed, validUntilLedgerSeq must equal the stored expiration; otherwise authorizeEntry throws.

Protocol gating

Emitting ADDRESS_V2 or ADDRESS_WITH_DELEGATES on a network below Protocol 27 invalidates the transaction. authorizeInvocation builds ADDRESS_V2 credentials by default; pass authV2 = false for the legacy ADDRESS arm, required on networks below Protocol 27. ADDRESS_WITH_DELEGATES credentials are built via attachDelegates.