Prerequisites & Basics

Dependencies, commonly used URLs, contract addresses and useful methods

Prerequisites

Before executing scripts, ensure you have Stellar SDK installed:

  • Python 3.7+: The script is written in Python and requires Python version 3.7 or higher.

  • Stellar SDK: Install via pip:

pip install stellar-sdk

Constants

Below are some API endpoints and contract addresses that will be used in other code examples.

For Mainnet

# The contract ID of the Aquarius AMM contract
router_contract_id = "CBQDHNBFBZYE4MKPWBSJOPIYLW4SFSXAXUTSXJN76GNKYVYPCKWC6QUK"
# Soroban RPC server address
soroban_rpc_server = "https://mainnet.sorobanrpc.com"
# Horizon server address
horizon_server = "https://horizon.stellar.org"
# Aquarius backend API URL
base_api = "https://amm-api.aqua.network/api/external/v1"

For Testnet

# The contract ID of the Aquarius AMM contract
# This updates quarterly, due to testnet reset. 
# Address updated on December 2024.
router_contract_id = "CDGX6Q3ZZIDSX2N3SHBORWUIEG2ZZEBAAMYARAXTT7M5L6IXKNJMT3GB"
# Soroban RPC server address
soroban_rpc_server = "https://soroban-testnet.stellar.org:443"
# Horizon server address
horizon_server = "https://horizon-testnet.stellar.org"
# Aquarius backend API URL
base_api = "https://amm-api-testnet.aqua.network/api/external/v1"

Helper Functions

Common utility methods that will be used in other code examples.

Get Asset Contract Id

To interact with any Soroban assets, you need their smart contract address.

This code snippet demonstrates how to retrieve the contract address of an asset on the Stellar network. The code uses the PUBLIC network by default, but you can switch to the desired network (e.g. TESTNET).

from stellar_sdk import Asset, Network

# Create the native asset
asset = Asset.native()
# Or create a custom asset
# asset = Asset("AQUA", "GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA")

# Retrieve the contract ID for the PUBLIC network
contract_id = asset.contract_id(Network.PUBLIC_NETWORK_PASSPHRASE)

print(contract_id)
# Example output:
# "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA"

Get Pool Contract ID and Pool Hash

To interact with an Aquarius pool (e.g. make deposits or direct swaps), you need the address of the pool contract.

One option to find the pool address is to refer to the pool page on Aquarius website, please see below:

Example of pool contract address, click to copy.

In order to receive this information programmatically, please refer to detailed description in the "Get Pools Info" section.

Order Tokens IDs

Most of the time, if an array of token IDs needs to be passed as arguments in a contract call, they should be sorted.

def order_token_ids(tokens: List[xdr.SCVal]) -> List[xdr.SCVal]:
   """
   Orders token IDs based on their contract ID to maintain consistency.

   Args:
       tokens (List[xdr.SCVal]): List of token addresses as SCVal objects.

   Returns:
       List[xdr.SCVal]: Ordered list of token SCVal objects.
   """
   return sorted(tokens, key=lambda token: int(token.address.contract_id.hash.hex(), 16))

Data Conversion Utilities

Here are methods and code snippets for converting data between basic types and ScVal (Smart Contract Value).

from stellar_sdk import Address, scval

# ================
# Basic => ScVal
# ================

# Contract Id To ScVal
contract_id = "C..."
contract_id_scval = scval.to_address(contract_id)

# Array To ScVal
scval.to_vec([contract_id_scv, contract_id_scv])

# Public Key To ScVal
public_key = "G..."
public_key_scval = scval.to_address(public_key)

# Number To Uint32 ScVal
number_u32_scval = scval.to_uint32(1_000_000)


# Number To Uint128 ScVal
number_u128_scval = scval.to_uint128(1_000_000)

# Hash To ScVal 
pool_hash = "a1b2...."
pool_hash_scval = scval.to_bytes(bytes.fromhex(pool_hash))

# ================
#  ScVal => Basic
# ================

def u128_to_int(value: UInt128Parts) -> int:
   """
   Converts UInt128Parts from Stellar's XDR to a Python integer.

   Args:
       value (UInt128Parts): UInt128Parts object from Stellar SDK.

   Returns:
       int: Corresponding Python integer.
   """
   return int(value.hi.uint64 << 64) + value.lo.uint64

Last updated