Package org.stellar.sdk

Class Auth

java.lang.Object
org.stellar.sdk.Auth
public class Auth extends Object
This class contains helper methods to sign SorobanAuthorizationEntry.
See Also:

  • Constructor Details

    • Auth

      public Auth()

  • Method Details

    • authorizeEntry

      public static SorobanAuthorizationEntry authorizeEntry(String entry, KeyPair signer, Long validUntilLedgerSeq, Network network)
      Actually authorizes an existing authorization entry using the given the credentials and expiration details, returning a signed copy.

      This "fills out" the authorization entry with a signature, indicating to the InvokeHostFunctionOperation it's attached to that:

      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.
      Parameters:
      entry - a base64 encoded unsigned Soroban authorization entry
      signer - a KeyPair which should correspond to the address in the `entry`
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      network - the network is incorporated into the signature
      Returns:
      a signed Soroban authorization entry

    • authorizeEntry

      public static SorobanAuthorizationEntry authorizeEntry(String entry, KeyPair signer, Long validUntilLedgerSeq, Network network, @Nullable String forAddress)
      Actually authorizes an existing authorization entry using the given the credentials and expiration details, returning a signed copy.

      This "fills out" the authorization entry with a signature, indicating to the InvokeHostFunctionOperation it's attached to that:

      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.
      Parameters:
      entry - a base64 encoded unsigned Soroban authorization entry
      signer - a KeyPair which should correspond to the address in the `entry`
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      network - the network is incorporated into the signature
      forAddress - which credential node the signature should be written to, see authorizeEntry(SorobanAuthorizationEntry, Signer, Long, Network, String)
      Returns:
      a signed Soroban authorization entry

    • authorizeEntry

      public static SorobanAuthorizationEntry authorizeEntry(SorobanAuthorizationEntry entry, KeyPair signer, Long validUntilLedgerSeq, Network network)
      Actually authorizes an existing authorization entry using the given the credentials and expiration details, returning a signed copy.

      This "fills out" the authorization entry with a signature, indicating to the InvokeHostFunctionOperation it's attached to that:

      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.
      Parameters:
      entry - an unsigned Soroban authorization entry
      signer - a KeyPair which should correspond to the address in the `entry`
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      network - the network is incorporated into the signature
      Returns:
      a signed Soroban authorization entry

    • authorizeEntry

      public static SorobanAuthorizationEntry authorizeEntry(SorobanAuthorizationEntry entry, KeyPair signer, Long validUntilLedgerSeq, Network network, @Nullable String forAddress)
      Actually authorizes an existing authorization entry using the given the credentials and expiration details, returning a signed copy.

      This "fills out" the authorization entry with a signature, indicating to the InvokeHostFunctionOperation it's attached to that:

      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.
      Parameters:
      entry - an unsigned Soroban authorization entry
      signer - a KeyPair which should correspond to the address in the `entry`
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      network - the network is incorporated into the signature
      forAddress - which credential node the signature should be written to, see authorizeEntry(SorobanAuthorizationEntry, Signer, Long, Network, String)
      Returns:
      a signed Soroban authorization entry

    • authorizeEntry

      public static SorobanAuthorizationEntry authorizeEntry(String entry, Auth.Signer signer, Long validUntilLedgerSeq, Network network)
      Actually authorizes an existing authorization entry using the given the credentials and expiration details, returning a signed copy.

      This "fills out" the authorization entry with a signature, indicating to the InvokeHostFunctionOperation it's attached to that:

      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.
      Parameters:
      entry - a base64 encoded unsigned Soroban authorization entry
      signer - a Auth.Signer that takes the authorization preimage (a HashIDPreimage) and returns the signature SCVal the account at the entry's address expects
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      network - the network is incorporated into the signature
      Returns:
      a signed Soroban authorization entry

    • authorizeEntry

      public static SorobanAuthorizationEntry authorizeEntry(String entry, Auth.Signer signer, Long validUntilLedgerSeq, Network network, @Nullable String forAddress)
      Actually authorizes an existing authorization entry using the given the credentials and expiration details, returning a signed copy.

      This "fills out" the authorization entry with a signature, indicating to the InvokeHostFunctionOperation it's attached to that:

      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.
      Parameters:
      entry - a base64 encoded unsigned Soroban authorization entry
      signer - a Auth.Signer that takes the authorization preimage (a HashIDPreimage) and returns the signature SCVal the account at the entry's address expects
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      network - the network is incorporated into the signature
      forAddress - which credential node the signature should be written to, see authorizeEntry(SorobanAuthorizationEntry, Signer, Long, Network, String)
      Returns:
      a signed Soroban authorization entry

    • authorizeEntry

      public static SorobanAuthorizationEntry authorizeEntry(SorobanAuthorizationEntry entry, Auth.Signer signer, Long validUntilLedgerSeq, Network network)
      Actually authorizes an existing authorization entry using the given the credentials and expiration details, returning a signed copy.

      This "fills out" the authorization entry with a signature, indicating to the InvokeHostFunctionOperation it's attached to that:

      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.
      Parameters:
      entry - an unsigned Soroban authorization entry
      signer - a Auth.Signer that takes the authorization preimage (a HashIDPreimage) and returns the signature SCVal the account at the entry's address expects
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      network - the network is incorporated into the signature
      Returns:
      a signed Soroban authorization entry

    • authorizeEntry

      public static SorobanAuthorizationEntry authorizeEntry(SorobanAuthorizationEntry entry, Auth.Signer signer, Long validUntilLedgerSeq, Network network, @Nullable String forAddress)
      Actually authorizes an existing authorization entry using the given the credentials and expiration details, returning a signed copy.

      This "fills out" the authorization entry with a signature, indicating to the InvokeHostFunctionOperation it's attached to that:

      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.

      All address-based credential types are supported: SOROBAN_CREDENTIALS_ADDRESS, SOROBAN_CREDENTIALS_ADDRESS_V2, and SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES. The signature payload differs per type, see buildAuthorizationEntryPreimage(SorobanAuthorizationEntry, long, Network). Source-account credentials are returned unchanged (they are covered by the transaction envelope signature).

      Parameters:
      entry - an unsigned Soroban authorization entry
      signer - a Auth.Signer that takes the authorization preimage (a HashIDPreimage) and returns the signature SCVal the account at the entry's address expects
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      network - the network is incorporated into the signature
      forAddress - which credential node the signature should be written to. Only relevant for SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES, where a single entry can be signed by the top-level account and/or any of its (possibly nested) delegates. Per CAP-71-01 every one of these signers signs the same payload (bound to the top-level address), so the signature produced here is written to whichever node(s) carry forAddress. Because that shared payload commits to validUntilLedgerSeq, every signer of one entry must use the same value — signing with a different value invalidates the signatures collected so far. When null, the signature is written to the top-level credentials, which preserves the behavior for SOROBAN_CREDENTIALS_ADDRESS / SOROBAN_CREDENTIALS_ADDRESS_V2 and for accounts whose signing key differs from the credential address (e.g. multisig).
      Returns:
      a signed Soroban authorization entry

    • authorizeInvocation

      public static SorobanAuthorizationEntry authorizeInvocation(KeyPair signer, Long validUntilLedgerSeq, SorobanAuthorizedInvocation invocation, Network network)
      This builds an entry from scratch, allowing you to express authorization as a function of:
      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.

      This is in contrast to authorizeEntry(java.lang.String, org.stellar.sdk.KeyPair, java.lang.Long, org.stellar.sdk.Network), which signs an existing entry "in place".

      The returned entry uses legacy SOROBAN_CREDENTIALS_ADDRESS credentials, which are valid on every network. To opt in to the address-bound SOROBAN_CREDENTIALS_ADDRESS_V2 credentials (CAP-71-02, requires a protocol 27 network), use authorizeInvocation(KeyPair, Long, SorobanAuthorizedInvocation, Network, SorobanCredentialsType). The default will flip to V2 once protocol 28 makes it mandatory.

      Parameters:
      signer - a KeyPair used to sign the entry
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      invocation - invocation the invocation tree that we're authorizing (likely, this comes from transaction simulation)
      network - the network is incorporated into the signature
      Returns:
      a signed Soroban authorization entry

    • authorizeInvocation

      public static SorobanAuthorizationEntry authorizeInvocation(KeyPair signer, Long validUntilLedgerSeq, SorobanAuthorizedInvocation invocation, Network network, SorobanCredentialsType credentialsType)
      This builds an entry from scratch, allowing you to express authorization as a function of:
      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.

      This is in contrast to authorizeEntry(java.lang.String, org.stellar.sdk.KeyPair, java.lang.Long, org.stellar.sdk.Network), which signs an existing entry "in place".

      Parameters:
      signer - a KeyPair used to sign the entry
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      invocation - invocation the invocation tree that we're authorizing (likely, this comes from transaction simulation)
      network - the network is incorporated into the signature
      credentialsType - the credential type for the new entry, either the legacy SOROBAN_CREDENTIALS_ADDRESS (the default of the shorter overloads, valid on every network) or the address-bound SOROBAN_CREDENTIALS_ADDRESS_V2 (CAP-71-02, requires a protocol 27 network). To build a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES entry, use buildWithDelegatesEntry(SorobanAuthorizationEntry, long, List, SCVal) instead
      Returns:
      a signed Soroban authorization entry

    • authorizeInvocation

      public static SorobanAuthorizationEntry authorizeInvocation(Auth.Signer signer, String address, Long validUntilLedgerSeq, SorobanAuthorizedInvocation invocation, Network network)
      This builds an entry from scratch, allowing you to express authorization as a function of:
      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.

      This is in contrast to authorizeEntry(java.lang.String, org.stellar.sdk.KeyPair, java.lang.Long, org.stellar.sdk.Network), which signs an existing entry "in place".

      The returned entry uses legacy SOROBAN_CREDENTIALS_ADDRESS credentials, which are valid on every network. To opt in to the address-bound SOROBAN_CREDENTIALS_ADDRESS_V2 credentials (CAP-71-02, requires a protocol 27 network), use authorizeInvocation(Signer, String, Long, SorobanAuthorizedInvocation, Network, SorobanCredentialsType). The default will flip to V2 once protocol 28 makes it mandatory.

      Parameters:
      signer - a Auth.Signer that takes the authorization preimage (a HashIDPreimage) and returns the signature SCVal the account at the entry's address expects
      address - the address being authorized — a classic G... account or a C... contract address (the typical custom-account case)
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      invocation - invocation the invocation tree that we're authorizing (likely, this comes from transaction simulation)
      network - the network is incorporated into the signature
      Returns:
      a signed Soroban authorization entry

    • authorizeInvocation

      public static SorobanAuthorizationEntry authorizeInvocation(Auth.Signer signer, String address, Long validUntilLedgerSeq, SorobanAuthorizedInvocation invocation, Network network, SorobanCredentialsType credentialsType)
      This builds an entry from scratch, allowing you to express authorization as a function of:
      • a particular identity (i.e. signing KeyPair or Auth.Signer)
      • approving the execution of an invocation tree (i.e. a simulation-acquired SorobanAuthorizedInvocation or otherwise built)
      • on a particular network (uniquely identified by its passphrase, see Network)
      • until a particular ledger sequence is reached.

      This is in contrast to authorizeEntry(java.lang.String, org.stellar.sdk.KeyPair, java.lang.Long, org.stellar.sdk.Network), which signs an existing entry "in place".

      Parameters:
      signer - a Auth.Signer that takes the authorization preimage (a HashIDPreimage) and returns the signature SCVal the account at the entry's address expects
      address - the address being authorized — a classic G... account or a C... contract address (the typical custom-account case)
      validUntilLedgerSeq - the (exclusive) future ledger sequence number until which this authorization entry should be valid (if `currentLedgerSeq==validUntil`, this is expired)
      invocation - invocation the invocation tree that we're authorizing (likely, this comes from transaction simulation)
      network - the network is incorporated into the signature
      credentialsType - the credential type for the new entry, either the legacy SOROBAN_CREDENTIALS_ADDRESS (the default of the shorter overloads, valid on every network) or the address-bound SOROBAN_CREDENTIALS_ADDRESS_V2 (CAP-71-02, requires a protocol 27 network). To build a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES entry, use buildWithDelegatesEntry(SorobanAuthorizationEntry, long, List, SCVal) instead
      Returns:
      a signed Soroban authorization entry

    • getAddressCredentials

      @Nullable public static SorobanAddressCredentials getAddressCredentials(SorobanCredentials credentials)
      Extracts the SorobanAddressCredentials from any address-based Soroban credential, regardless of which credential type variant is used.

      This unifies access across SOROBAN_CREDENTIALS_ADDRESS, SOROBAN_CREDENTIALS_ADDRESS_V2 (which carries identical fields but binds the address into the signature payload, CAP-71-02), and SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES (which wraps the same address credentials alongside a set of delegate signatures, CAP-71-01).

      Parameters:
      credentials - the credentials to inspect
      Returns:
      the inner address credentials, or null for source-account credentials (which carry no address payload)

    • authorizationPayloadHash

      public static byte[] authorizationPayloadHash(HashIDPreimage preimage)
      Returns the 32-byte payload that account contracts receive in __check_auth: the SHA-256 hash of the authorization preimage's XDR bytes.

      Use this inside a custom Auth.Signer to obtain the exact bytes the host asks the account contract to verify, then return whatever signature SCVal the contract expects. It is the same payload the KeyPair signing path signs.

      Parameters:
      preimage - the Soroban authorization preimage, see buildAuthorizationEntryPreimage(SorobanAuthorizationEntry, long, Network)
      Returns:
      the SHA-256 hash of the preimage XDR bytes

    • defaultAccountSignatureScVal

      public static SCVal defaultAccountSignatureScVal(byte[] publicKey, byte[] signature)
      Builds the signature SCVal shape expected by the default Stellar Account contract: Vec<Map{public_key: Bytes, signature: Bytes}>.

      This is the building block for ed25519 Auth.Signer implementations that sign elsewhere (a hardware module or remote signing service) yet target a classic G... account — the same shape the KeyPair signing path produces. Use this byte[] overload when you already hold the raw public key (e.g. from an HSM); use defaultAccountSignatureScVal(String, byte[]) to pass a G... address instead.

      Parameters:
      publicKey - the raw 32-byte ed25519 public key that produced signature
      signature - the 64-byte ed25519 signature over authorizationPayloadHash(HashIDPreimage)
      Returns:
      the default Stellar Account signature value
      See Also:

    • defaultAccountSignatureScVal

      public static SCVal defaultAccountSignatureScVal(String accountId, byte[] signature)
      Builds the default Stellar Account signature SCVal from a classic G... account address — a convenience wrapper over defaultAccountSignatureScVal(byte[], byte[]) that decodes accountId to its raw ed25519 public key.
      Parameters:
      accountId - the G... account whose ed25519 public key produced signature
      signature - the 64-byte ed25519 signature over authorizationPayloadHash(HashIDPreimage)
      Returns:
      the default Stellar Account signature value

    • buildAuthorizationEntryPreimage

      public static HashIDPreimage buildAuthorizationEntryPreimage(SorobanAuthorizationEntry entry, long validUntilLedgerSeq, Network network)
      Builds the HashIDPreimage whose hash a signer must sign to authorize entry. This is the low-level signature payload used by authorizeEntry(java.lang.String, org.stellar.sdk.KeyPair, java.lang.Long, org.stellar.sdk.Network), exposed for callers that drive signing themselves — most notably for SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES, where the client (not simulation) decides which delegates sign and how.

      For SOROBAN_CREDENTIALS_ADDRESS this is the legacy, non-address-bound ENVELOPE_TYPE_SOROBAN_AUTHORIZATION preimage. For SOROBAN_CREDENTIALS_ADDRESS_V2 and SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES it is the address-bound ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS preimage (CAP-71). For the delegates variant this single payload — bound to the top-level address — is what the top-level account and every (nested) delegate each sign.

      To get the raw bytes to sign, hash the XDR: Util.hash(preimage.toXdrByteArray()).

      Parameters:
      entry - the authorization entry to build the payload for
      validUntilLedgerSeq - the expiration ledger committed into the payload (must match the signatureExpirationLedger on the credentials you submit)
      network - the network whose id is mixed into the payload
      Returns:
      the preimage to hash and sign
      Throws:
      IllegalArgumentException - if entry carries source-account or otherwise non-address credentials

    • buildWithDelegatesEntry

      public static SorobanAuthorizationEntry buildWithDelegatesEntry(SorobanAuthorizationEntry entry, long validUntilLedgerSeq, List<Auth.DelegateSignature> delegates, @Nullable SCVal signature)
      Builds a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES authorization entry (CAP-71-01) by wrapping the address credentials of an existing SOROBAN_CREDENTIALS_ADDRESS or SOROBAN_CREDENTIALS_ADDRESS_V2 entry (e.g. one returned by simulation) together with a caller-provided set of delegate signers.

      Simulation never emits the delegates variant on its own — which accounts use delegated authentication is account-specific policy known only to the client (much like a multisig policy). This helper just assembles the wrapper XDR; you supply the delegate tree (addresses and, optionally, signatures). To produce the signatures, build the shared payload with buildAuthorizationEntryPreimage(SorobanAuthorizationEntry, long, Network) on the returned entry and sign it, or fill each node afterwards with authorizeEntry(SorobanAuthorizationEntry, Signer, Long, Network, String) (passing the signer's address as forAddress and the same validUntilLedgerSeq as given here — the shared payload commits to it).

      Which delegates must actually sign is decided by the top-level account contract: per CAP-71-01 the host verifies a listed delegate only when the account's __check_auth consumes it, so a delegate left with its void placeholder is valid as long as the account's policy does not require it.

      Each delegates list (the top-level set and every nestedDelegates) is sorted by address in ascending order, and duplicate addresses within a list are rejected, as the protocol requires (CAP-71-01) — otherwise the host rejects the entry.

      Parameters:
      entry - an existing SOROBAN_CREDENTIALS_ADDRESS or SOROBAN_CREDENTIALS_ADDRESS_V2 entry whose address credentials should be wrapped
      validUntilLedgerSeq - the expiration ledger sequence stored on the top-level credentials
      delegates - the delegate signers to attach
      signature - the top-level account's signature, or null for an SCV_VOID placeholder, which is valid for accounts that authorize purely via delegated signers
      Returns:
      a new SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES authorization entry
      Throws:
      IllegalArgumentException - if entry does not carry ADDRESS / ADDRESS_V2 credentials, or if any delegates list contains a duplicate address