thruput-xdr 0.63.0

---
# The number of u32 arguments to a syscall.
# (The riscv32 syscall ABI passes each argument slot in a 32-bit register.
# The native mock entrypoint in test_ffi keeps u64 slots so it can carry host
# pointers, but value slots are still validated against the 32-bit constraint.)
# Syscalls that need fewer than this many arguments pad the argument list
# with arbitrary values (in the SDK, this defaults to 0, although that
# condition is not enforced.)
# The syscall itself is an `ecall` taking 8 register arguments (a0..a7). The
# first argument is the syscall number.
syscall_input_count: 7
# A set of mappings for common types between the SDK (rust) and the syscall
# implementation (cpp).
# All types passed in or out of a syscall must be trivially copyable and
# FFI-safe.
# Syscall arguments are either spans of bytes, (aliases of) integral types,
# or repr(C) types.
# primitive_type: true means that the type can be passed by value as a single
# 32-bit argument slot to the syscall. Such a type MUST be at most 32 bits
# wide; wider types (e.g. BlockHeight, a 64-bit value) are passed by reference
# (as an offset into contract memory) instead. The uint64_t and int64_t
# mappings below carry the flag but are only used as outputs, which are always
# passed by reference; using one as an input would fail that width check.
# rust_uses_as_ptr: true means that the SDK passes the type by calling
# .as_ptr() on it.
type_mappings:
  - base_name: "uint32_t"  # The cpp name, which is used in this spec
    rust_name: "u32"
    rust_uses_as_ptr: false
    primitive_type: true
  - base_name: "int32_t"
    rust_name: "i32"
    rust_uses_as_ptr: false
    primitive_type: true
  - base_name: "uint64_t"
    rust_name: "u64"
    rust_uses_as_ptr: false
    primitive_type: true
  - base_name: "int64_t"
    rust_name: "i64"
    rust_uses_as_ptr: false
    primitive_type: true
  - base_name: "int128_t"
    rust_name: "i128"
    rust_uses_as_ptr: false
  - base_name: "uint128_t"
    rust_name: "u128"
    rust_uses_as_ptr: false
  - base_name: "bool"
    rust_name: "bool"
    rust_uses_as_ptr: false
    primitive_type: true
  - base_name: "generated::AuthClaim"
    rust_name: "AuthClaim"
    rust_uses_as_ptr: false
  - base_name: "Weight"
    rust_name: "u32"
    rust_uses_as_ptr: false
    primitive_type: true
  - base_name: "Topic"
    rust_name: "[u8; 32]"
    rust_uses_as_ptr: false
  - base_name: "StorageDeltaFlagSet"
    rust_name: "StorageDeltaFlagSet"
    rust_uses_as_ptr: false
    primitive_type: true
  - base_name: "BlockHeight"
    rust_name: "BlockHeight"
    rust_uses_as_ptr: false
    # NOT primitive_type: BlockHeight is a 64-bit value (typedef hyper), which
    # does not fit in a single 32-bit syscall argument slot. It is therefore
    # passed by reference (as an offset into contract memory), not by value.
    newtype: true
  - base_name: "TimePoint"
    rust_name: "TimePoint"
    rust_uses_as_ptr: false
    # NOT primitive_type, for the same reason as BlockHeight above: TimePoint
    # is a 64-bit value (typedef unsigned hyper), so it is passed by reference
    # rather than in a 32-bit argument slot.
    newtype: true
  - base_name: "TransactionStatistic"
    rust_name: "TransactionStatistic"
    rust_uses_as_ptr: false
    primitive_type: true
    dot_zero_type: true
  - base_name: "CopyableInvokeInputs"
    rust_name: "CopyableInvokeInputs"
    rust_uses_as_ptr: false
  - base_name: "CopyableInvokeOutputs"
    rust_name: "CopyableInvokeOutputs"
    rust_uses_as_ptr: false
# Syscalls MUST be defined in increasing numerical order (by the 'number'
# field)
#
# All contracts can return a SyscallErrorCode::kSyscallErrorCodeFault if
# any of the pointers passed to them are out of contract memory bounds.
#
# Any attempt at making a syscall can return a
# SyscallErrorCode::kSyscallErrorCodeNoSyscall if the syscall number is
# not supported.
#
# Every syscall not marked read_only returns
# SyscallErrorCode::kSyscallErrorCodeInvalidSyscallInput, without effect,
# when called from a read-only frame.
syscalls:
  - name: "SHA256"
    read_only: true
    needs_gas: true
    inputs:
      - name: "buffer"
        span_argument: true
    outputs:
      - name: "hash"
        typename: "SHA256Hash"
    number: 0
    description: >
      Returns the SHA256 hash of the input buffer.
    errors:
  - name: "GetMsgSender"
    read_only: true
    inputs:
    outputs:
      - name: "sender"
        typename: "ContractAddress"
    number: 1
    description: >
      Returns the contract address of the contract that invoked the
      current call frame.
    errors:
      - code: kSyscallErrorCodeIsRootTransaction
        description: >
          The syscall was called from a root transaction.
          There is no caller address in this case.
  - name: "GetCalldataLen"
    read_only: true
    inputs:
    outputs:
      - name: "len"
        typename: "RuntimeMemoryLength"
      - name: "auth_token_count"
        typename: "uint32_t"
    number: 2
    description: >
      Returns the length of the calldata supplied to the invocation
      associated with the current call frame.
      Also returns the number N of auth tokens supplied to the invocation,
      which are the current frame's auth token ids 0..N-1.
    errors:
  - name: "GetCalldata"
    read_only: true
    inputs:
    outputs:
      - name: "buffer"
        span_argument: true
      - name: "written_len"
        typename: "RuntimeMemoryLength"
        primitive_type: true
      - name: "auth_token_count"
        typename: "uint32_t"
    number: 3
    description: >
      Returns the calldata supplied to the invocation associated with
      the current call frame.

      written_len is the full length of the calldata, not the number of bytes
      copied: at most buffer.len() bytes are written, and a written_len
      greater than buffer.len() means the output was truncated.

      Also returns the number N of auth tokens supplied to the invocation.
      Auth token ids are local to each call frame, and the supplied tokens
      are the current frame's ids 0..N-1, in the order the caller listed
      them.
    errors:
  - name: "ConsoleLog"
    needs_context: false
    # Logging is for debugging only.
    # On release builds, this is a no-op.
    # On debug builds, this logs to console.
    read_only: true
    inputs:
      - name: "buffer"
        span_argument: true
    outputs:
    number: 4
    description: >
      Logs the input buffer to the console.
      This is a no-op on release builds or when deployed on-chain.

      This will not cause an error if a contract inadvertently includes
      this syscall in a production contract deployment (if, for example,
      a contract built in debug mode is uploaded), but there is no
      reason to do so.
    errors:
  - name: "Invoke"
    read_only: true
    needs_gas: true
    inputs:
      - name: "address"
        typename: "ContractAddress"
      - name: "calldata"
        span_argument: true
      - name: "owned_auth_token_ids_list"
        span_argument: true
      - name: "inputs"
        typename: "CopyableInvokeInputs"
    outputs:
      - name: "outputs"
        typename: "CopyableInvokeOutputs"
    number: 5
    description: |
      Invokes the specified method of the contract at the specified
      address, with the supplied parameters. Creates a new invocation
      frame, which terminates upon conclusion of the Invoke() syscall.

      The frame will be limited to the minimum of gas_limit units
      of gas and the remaining gas in the current frame.
      The SDK sets the default gas limit as UINT64_MAX, meaning i.e.
      all of the remaining gas in the current frame.
      Any unused gas will be returned to the caller.

      The entrypoint is the entrypoint_id field of inputs, a u64 holding the
      big-endian interpretation of the ContractEntrypointID ([u8; 8]) bytes
      (ContractEntrypointID::into_u64 in the Rust bindings).

      The list of auth tokens is passed as a span, which should be
      interpreted as a [u32] slice.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The invocation was rejected before any child frame ran: the contract
          was not found, the invoke flags were invalid, the calldata is longer
          than kConfigParamMaxCalldataLen, more auth token ids were supplied
          than kConfigParamMaxAuthTokens, or one or more of the supplied auth
          token ids are malformed, duplicated, or not owned by the current
          frame. The syscall is a complete no-op in this case.
      - code: kSyscallErrorCodeReentrance
        description: >
          The invoked address is already on the stack. The invocation is
          rejected before any child frame runs and the syscall is a no-op.
      - code: kSyscallErrorCodeInvokeDepthExceeded
        description: >
          The transaction already holds kConfigParamMaxCrossInvokeDepth
          invocation frames open, so admitting another would exceed the
          network's cross-invoke depth bound. This is a resource limit rather
          than a malformed call -- the same invocation succeeds from a
          shallower frame. The invocation is rejected before any child frame
          runs and the syscall is a no-op.
  - name: "Return"
    read_only: true
    inputs:
      - name: "buffer"
        span_argument: true
      - name: "revert_frame"
        typename: "bool"
        primitive_type: true
      - name: "returned_auth_token_ids"
        span_argument: true
    outputs:
    returns: false
    number: 6
    description: >
      Returns data from the current call frame and optionally marks
      the frame for revert. The return buffer will be available to
      the caller via GetReturnedBuffer. Immediately terminates
      execution of the current invocation.

      The syscall never returns an error. Instead, the frame faults with a
      deterministic error (equivalent to Exit) if the buffer is longer than
      kConfigParamMaxReturnBufferLen, if auth tokens are returned from a
      frame marked for revert, or if the returned auth token id list is
      longer than kConfigParamMaxAuthTokens, malformed, duplicated, or
      names tokens the current frame does not own.
    errors:
  - name: "GetReturnedBuffer"
    read_only: true
    inputs:
    outputs:
      - name: "buffer"
        span_argument: true
      - name: "written_len"
        typename: "RuntimeMemoryLength"
        primitive_type: true
      - name: "returned_auth_token_start"
        typename: "uint32_t"
      - name: "returned_auth_token_count"
        typename: "uint32_t"
    number: 7
    description: >
      Returns the return buffer from the most recent subcall invocation
      that ended with Return, including a Return that marked the frame for
      revert.

      written_len is the full length of the return buffer, not the number
      of bytes copied: at most buffer.len() bytes are written, and a
      written_len greater than buffer.len() means the output was truncated.

      Also returns the auth tokens that subcall returned, as the
      current frame's auth token ids start..start+count-1. The returned
      tokens join the frame under consecutive new ids, in the order the
      subcall listed them.
    errors:
      - code: kSyscallErrorCodeNoReturnBufferAvailable
        description: >
          No return buffer is available. Either the most recent subcall
          faulted (for example by trapping or calling Exit), or there have
          been no subcalls within this call frame.
  - name: "Exit"
    read_only: true
    needs_context: false
    inputs:
    outputs:
    returns: false
    number: 8
    description: >
      Terminates execution of the current call frame immediately.
      The current call frame reverts, returning a deterministic error
      to the caller (with no return buffer available).
      Equivalent to a guest trap.
    errors:
  - name: "GetDeployAddress"
    read_only: true
    inputs:
      - name: "caller_address"
        typename: "ContractAddress"
        optional: true
      - name: "nonce"
        typename: "SHA256Hash"
      - name: "contract_hash"
        typename: "SHA256Hash"
    outputs:
      - name: "to_be_deployed"
        typename: "ContractAddress"
    number: 9
    description: >
      Computes the address that would be deployed for a contract with
      the given deployer address, nonce, and contract hash. This is a
      pure computation and does not actually deploy the contract.
      If caller_address is omitted, the current contract's address is
      used, giving the address DeployContract would use.
    errors:
  - name: "DeployContract"
    inputs:
      - name: "nonce"
        typename: "SHA256Hash"
      - name: "contract_hash"
        typename: "SHA256Hash"
    outputs:
      - name: "deployed_address"
        typename: "ContractAddress"
    number: 10
    description: >
      Deploys a contract with the specified nonce and contract hash to
      a computed address. The contract must be provided in the
      transaction's contracts_to_deploy field.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The requested contract was not available for deployment, or the
          contract is a special precompiled (native) contract that cannot be
          deployed (i.e. the native token contract).

          To deploy a contract, that contract must either already exist on chain
          or must be provided in the transaction's contracts_to_deploy field.
      - code: kSyscallErrorCodeContractAlreadyDeployed
        description: >
          A contract with the same nonce and contract hash has already
          been deployed at the computed address, either in a previous
          block or earlier in this transaction.

          A contract can be deployed multiple times concurrently in the same
          block.  If a contract must be initialized only once, then that
          contract should run some initialization process and
          that initialization should acquire a semaphore.
  - name: "GetSourceTransactionHash"
    read_only: true
    inputs:
    outputs:
      - name: "source_tx_hash"
        typename: "SHA256Hash"
    number: 11
    description: >
      Returns the hash of the transaction that initiated the current
      execution: sha256 of the XDR-encoded Transaction, the same
      TransactionHash that identifies it network-wide.
    errors:
  - name: "VerifySignature"
    needs_context: false
    read_only: true
    inputs:
      - name: "scheme"
        # This is a CryptographicScheme enum, but we pass it in as an
        # int32_t to make sure the generated rust code does not assume
        # that the enum does not get extended with more signature schemes
        typename: "int32_t"
        primitive_type: true
      - name: "signature"
        span_argument: true
      - name: "public_key"
        span_argument: true
      - name: "message"
        span_argument: true
    outputs:  # No outputs: check the error code returned
    number: 12
    description: >
      Verifies a cryptographic signature against a public key and
      message. Returns kSyscallErrorCodeNone if verification succeeds,
      otherwise returns an error.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The signature verification failed, or the input parameters
          are invalid (e.g., incorrect key/signature size for the
          specified scheme, or unsupported scheme).
  - name: "BytestringGetLen"
    read_only: true
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
    outputs:
      - name: "length"
        typename: "RuntimeMemoryLength"
    number: 13
    description: >
      Returns the length of the bytestring stored at the specified key.
    errors:
      - code: kSyscallErrorCodeStorageKeyNotExist
        description: >
          The storage key does not exist in the current transaction's
          view.
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The storage key exists but contains a different type
          (e.g., NNInt instead of bytestring).
  - name: "BytestringGet"
    read_only: true
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
    outputs:
      - name: "bytestring"
        span_argument: true
      - name: "written_len"
        typename: "RuntimeMemoryLength"
    number: 14
    description: >
      Retrieves the bytestring stored at the specified key.

      written_len is the full length of the bytestring, not the number of bytes
      copied: at most bytestring.len() bytes are written, and a written_len
      greater than bytestring.len() means the output was truncated.
    errors:
      - code: kSyscallErrorCodeStorageKeyNotExist
        description: >
          The storage key does not exist or has been deleted.
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The storage key exists but contains a different type
          (e.g., NNInt instead of bytestring).
  - name: "BytestringSet"
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
      - name: "bytestring"
        span_argument: true
    outputs:
    number: 15
    description: >
      Sets the bytestring value at the specified storage key.
      Note that this will overwrite any existing value at that key,
      *even if* that value has a different type.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The bytestring is too long.
  - name: "NonnegativeIntGet"
    read_only: true
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
      - name: "force_load_from_snapshot"
        typename: "bool"
        primitive_type: true
    outputs:
      - name: "current_set"
        typename: "int128_t"
      - name: "current_set_opt"
        typename: "bool"
      - name: "current_add"
        typename: "int128_t"
    number: 16
    description: >
      Retrieves the nonnegative integer value at the specified storage
      key.

      current_set_opt reports whether current_set holds a value; when it is
      false, current_set carries no information and should be ignored.

      If force_load_from_snapshot is true, then current_set_opt is always
      true on success. If the snapshot value is not an NNInt, or the
      previous write on that key was not an NNInt, then the syscall returns
      kSyscallErrorCodeInvalidSyscallInput. If the snapshot value does not
      exist, or has been deleted by the prior write, then it returns
      kSyscallErrorCodeStorageKeyNotExist.

      If force_load_from_snapshot is false, then the prior state of the
      item is ignored unless the prior write on that key is an NNInt write
      (in which case the parameters of that write are returned). If the
      prior write is not an NNInt, or was a deletion, then current_set_opt
      is false and current_add is 0.
    errors:
      - code: kSyscallErrorCodeStorageKeyNotExist
        description: >
          The storage key does not exist or has been deleted.
          Only returned if force_load_from_snapshot is true.
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The storage key exists but contains a different type
          (e.g., bytestring instead of NNInt).
          Only returned if force_load_from_snapshot is true.

  - name: "NonnegativeIntSetAdd"
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
      - name: "set_value"
        typename: "int128_t"
        optional: true
      - name: "add_value"
        typename: "int128_t"
    outputs:
    number: 17
    description: >
      Sets or modifies a nonnegative integer at the specified storage
      key. The set_value (if provided) sets the base value, and
      add_value is added as a delta. The final value must remain
      nonnegative. Will overwrite any value of that key, *even if*
      that value has a different type.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The operation would always result in a negative value
          (i.e. set_add(1, -2)).
  - name: "DeleteObject"
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
    outputs:
    number: 18
    description: >
      Deletes the object at the specified storage key.
    errors:
  - name: "GetCurrentAddress"
    read_only: true
    inputs:
    outputs:
      - name: "address"
        typename: "ContractAddress"
    number: 19
    description: >
      Returns the contract address of the current call frame.
    errors:
  - name: "RetrocausalQueueInsert"
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
      - name: "queue_entry"
        span_argument: true
    outputs:
    number: 20
    description: >
      Inserts an entry into the retrocausal queue at the specified
      storage key. Like any storage write, this replaces a value of
      another type at the key. A queue with no live entries does not exist.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The queue entry is too large, or too many entries are inserted
          in the current transaction.
  - name: "RetrocausalQueueConsume"
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
      - name: "peek"
        typename: "bool"
        primitive_type: true
    outputs:
      - name: "queue_entry"
        span_argument: true
      - name: "written_len"
        typename: "RuntimeMemoryLength"
        primitive_type: true
    number: 21
    description: >
      Consumes (or peeks at) the next entry from the retrocausal queue
      at the specified storage key. If peek is true, the entry is not
      removed from the queue. A read never changes the type of the key;
      a same-block conversion by another transaction is visible only
      from the next block.

      written_len is the full length of the entry, not the number of bytes
      copied: at most queue_entry.len() bytes are written, and a written_len
      greater than queue_entry.len() means the output was truncated.
      A consumed entry is removed even if it was truncated, so size
      queue_entry with RetrocausalQueuePeekLen first.
    errors:
      - code: kSyscallErrorCodeNoRetrocausalQueueEntry
        description: >
          The retrocausal queue is empty and has no entries to consume.
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The storage key exists but contains a different type.
      - code: kSyscallErrorCodeRetrocausalQueueReadLimitReached
        description: >
          The transaction has read the maximum number of concurrent
          retrocausal-queue entries allowed per transaction. Returning this
          does not fail the transaction; a contract may use it as a stop
          condition.
  - name: "GetTransactionStatistics"
    read_only: true
    needs_gas: true
    # Note: Some or all of these statistics
    # might be disabled during release builds
    # and/or during production execution.
    # This is allowed to return nondeterministic
    # information during test configurations
    # (and those stats will be disabled in prod)
    inputs:
      - name: "statistic"
        typename: "TransactionStatistic"
    outputs:
      - name: "result"
        typename: "uint64_t"
    number: 22
    description: >
      Returns a transaction statistic value. Note that statistics may
      be disabled in release builds or production execution, and may
      return nondeterministic values in test configurations.
      Nondeterministic stats will be disabled in production settings.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The requested statistic does not exist or is not available
          in this configuration.
  - name: "ChangePublicKeyRegistration"
    inputs:
      - name: "key_index"
        typename: "uint32_t"
      - name: "key_scheme"
        # This is a CryptographicScheme enum, but we pass it in as an
        # int32_t to make sure the generated rust code does not assume
        # that the enum does not get extended with more signature schemes
        typename: "int32_t"
        optional: true
      - name: "key_bytes"
        span_argument: true
      - name: "key_weight"
        typename: "uint32_t"
        optional: true
    outputs:
    number: 23
    description: >
      Changes the public key registration for the current contract
      address at the specified key index. If key_scheme is None, the
      key is removed. Otherwise, the key is set with the provided
      scheme, bytes, and weight.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The public key registration is invalid, or the input key
          index is out of bounds.
  - name: "LogEvent"
    inputs:
      - name: topic0
        typename: "Topic"
        optional: true
      - name: topic1
        typename: "Topic"
        optional: true
      - name: topic2
        typename: "Topic"
        optional: true
      - name: "data"
        span_argument: true
    outputs:
    number: 24
    description: >
      Logs an event with up to 3 topics and additional data. Constructs a
      TxEmittedEvent where the serialized_event field contains the topics
      prepended to the data: topic0 || topic1 || topic2 || data. The num_topics
      field indicates how many leading 32-byte chunks are topics, enabling
      downstream indexers to efficiently filter events. Events are stored
      in the transaction's event log and accumulated into a per-block
      merkle-patricia trie.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The serialized event (32 bytes per supplied topic plus the data)
          is longer than kMaxEventLength, the transaction has already emitted
          kMaxEventsPerTransaction events, or topics are not supplied in a
          continuous sequence (e.g., topic0 and topic2 provided without
          topic1).
  - name: "GetAuthClaim"
    read_only: true
    inputs:
    outputs:
      - name: "auth_claim"
        typename: "generated::AuthClaim"
    number: 25
    description: >
      Returns the authentication claim associated with the
      current transaction.
    errors:
  - name: "SHA256Update"
    number: 26
    read_only: true
    needs_gas: true
    inputs:
      - name: "index"
        typename: "uint32_t"
        primitive_type: true
      - name: "buffer"
        span_argument: true
      - name: "reset"
        typename: "bool"
        primitive_type: true
    description: >
      Updates the SHA256 hash computation at the specified index with
      the provided buffer. If reset is true, the hash input is reset
      before updating. The buffer must exist if reset is false.
      There is no cumulative byte limit.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: |
          This error will be returned if any of the following
          conditions are met:
          - The queried hash buffer does not exist and reset is false.
          - There are too many active hash buffers.
  - name: "SHA256Finalize"
    number: 27
    read_only: true
    inputs:
      - name: "index"
        typename: "uint32_t"
        primitive_type: true
    outputs:
      - name: "output"
        typename: "SHA256Hash"
    description: >
      Finalizes the SHA256 hash computation at the specified index and
      returns the hash. Removes the hash buffer after finalization.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          Returns an error if the queried hash buffer does not exist.
          For example, if finalize is called twice on the same buffer
          without an intervening reset, then the second call will
          return this error.
  - name: "WriteAddressRequiredWeight"
    inputs:
      - name: "required_weight"
        typename: "Weight"
        syscall_pass_by_value: true
    outputs:
    number: 28
    description: >
      Writes the required weight threshold for the current contract
      address. This is the minimum total weight of signing keys needed
      to authorize a transaction from this address.
  - name: "GetBlockHeight"
    read_only: true
    inputs:
    outputs:
      - name: "result"
        typename: "BlockHeight"
    number: 29
    description: >
      Returns the current block height.
    errors:
  - name: RetrocausalQueuePeekLen
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
    outputs:
      - name: "len"
        typename: "RuntimeMemoryLength"
        primitive_type: true
    number: 30
    description: >
      Returns the byte length of the next entry in the retrocausal queue at
      the specified storage key, without consuming it: the queue_entry
      buffer size RetrocausalQueueConsume needs to read that entry whole.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The storage key exists but contains a different type.
      - code: kSyscallErrorCodeNoRetrocausalQueueEntry
        description: >
          The retrocausal queue is empty and has no entries to peek.
      - code: kSyscallErrorCodeRetrocausalQueueReadLimitReached
        description: >
          The transaction has read the maximum number of concurrent
          retrocausal-queue entries allowed per transaction. Returning this
          does not fail the transaction; a contract may use it as a stop
          condition.
  - name: "MintAuthToken"
    inputs:
      - name: "expiry_height"
        typename: "BlockHeight"
      - name: "serialized_auth_token"
        span_argument: true
    outputs:
      - name: "token_id"
        typename: "uint32_t"
    number: 31
    description: >
      Mints an authentication token for the current contract address.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The serialized authentication token fails to parse as a valid
          AuthToken, expiry height is in the past, or the number of auth
          tokens minted would exceed the maximum for the transaction.
  - name: "ConsumeAuthToken"
    inputs:
      - name: "token_id"
        typename: "uint32_t"
    outputs:
      - name: "auth_payload"
        span_argument: true
      - name: "token_minter"
        typename: "ContractAddress"
      - name: "auth_payload_written_len"
        typename: "RuntimeMemoryLength"
        primitive_type: true
      - name: "unwrapped_token_id_start"
        typename: "uint32_t"
      - name: "unwrapped_token_id_count"
        typename: "uint32_t"
    number: 32
    description: >
      Consumes an authentication token for the current contract address.
      Returns any nested tokens unwrapped by the token.

      auth_payload_written_len is the full length of the token's payload,
      not the number of bytes copied: at most auth_payload.len() bytes are
      written, and a larger value means the payload was truncated. The token
      is consumed either way, so a truncated payload cannot be read again.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The authentication token is not owned by the current contract address,
          or the auth token has expired.
  - name: "SHA256Copy"
    number: 33
    read_only: true
    inputs:
      - name: "src_index"
        typename: "uint32_t"
        primitive_type: true
      - name: "dst_index"
        typename: "uint32_t"
        primitive_type: true
    description: >
      Copies the in-progress SHA256 hash computation at src_index to
      dst_index, replacing any hash computation already at dst_index.
      Both computations can then be extended and finalized
      independently. Copying an index onto itself succeeds and changes
      nothing.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: |
          This error will be returned if any of the following
          conditions are met:
          - The hash computation at src_index does not exist.
          - dst_index does not already hold a hash computation and
            there are too many active hash buffers.
  - name: "GetNetworkHash"
    read_only: true
    inputs:
    outputs:
      - name: "network_hash"
        typename: "NetworkHash"
    number: 34
    description: >
      Returns the hash of the network name, the identifier that separates
      this network's blocks from those of every other network. It is fixed
      for the life of the network, so it is constant across every block and
      every invocation.

      Transaction signatures already commit to this value (the signature
      preimage is `cxs(DomainSeparator("Transaction")) || network_hash ||
      xdr(tx)`). Exposing it to contracts lets a contract bind its own
      off-chain signed messages to this network the same way, so a message
      signed for one network cannot be replayed against a contract at the
      same address on another.
    errors:
  - name: "GetBlockTimepoint"
    read_only: true
    inputs:
    outputs:
      - name: "block_timepoint"
        typename: "TimePoint"
    number: 35
    description: >
      Returns the timepoint of the block currently executing. The value is
      fixed by the coordinator before execution begins and is carried in the
      block's ProposalHeader, so it is part of the block identity and is
      identical for every invocation in the block.

      Like a block height, this is consensus data rather than a trusted
      clock: it is chosen by the proposer within whatever bounds the
      network's validators enforce. Contracts should treat it as
      coarse-grained wall-clock time -- suitable for expiries, vesting
      schedules and deadlines -- and must not rely on it for fine-grained
      ordering or as a source of randomness.
    errors:
  - name: "SetStorageFlags"
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
      - name: "flags"
        typename: "StorageDeltaFlagSet"
    outputs:
    number: 36
    description: >
      Adds flags (a bitwise OR) to the storage flags the current transaction
      requests for the key. Writes never change a key's flags: every change
      the transaction commits on the key carries the flags accumulated here,
      whichever write produced it. ClearStorageFlags removes them.

      A write to the key must be pending in the current call frame's view of
      the transaction: one made earlier in this frame, or inherited from a
      caller or from a successful callee. A pending deletion qualifies; a
      value that exists only in the block snapshot does not. Flags set in a
      frame that aborts are discarded along with that frame's writes.
    errors:
      - code: kSyscallErrorCodeInvalidSyscallInput
        description: >
          The flags are invalid, or no write to the key is pending in the
          current call frame's view of the transaction.
  - name: "GetStorageFlags"
    read_only: true
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
    outputs:
      - name: "flags"
        typename: "StorageDeltaFlagSet"
    number: 37
    description: >
      Returns the storage flags the current transaction requests for the
      key, as visible in the current call frame. A key with no pending write
      has no flags, so it reads as StorageDeltaFlags::None, the same as a
      pending write without flags.
    errors:
  - name: "ClearStorageFlags"
    inputs:
      - name: "key"
        typename: "StorageKeyContractData"
    outputs:
    number: 38
    description: >
      Clears every storage flag the current transaction requests for the key,
      as visible in the current call frame. Does nothing if no write to the
      key is pending, since such a key has no flags. As with SetStorageFlags,
      a clear made in a frame that aborts is discarded with that frame.
    errors: