Deploy and Operate an Aspens Market Stack

This guide shows you how to deploy and configure your own Aspens Market Stack (AMS). Follow these steps to set up a crosschain trading infrastructure that enables trading between blockchains.

1. Set Up Infrastructure

Check Prerequisites

Before beginning, ensure you have:

Docker and Docker Compose installed
Domain name for your AMS instance
Access to blockchain node endpoints (RPC URLs) for each chain you'll support
Private key for the AMS deployer wallet (will control the AMS configuration)

Prepare the Environment

# Create a dedicated directory for your AMS deployment
mkdir -p ~/aspens-stack
cd ~/aspens-stack
 
# Clone the Aspens Market Stack repository
git clone https://github.com/aspensprotocol/markets-stack.git .
 
# Create configuration directories
mkdir -p config data logs

2. Deploy Smart Contracts

Before deploying the stack, you need to deploy the smart contracts that will power your Aspens Market Stack instance. The deployment process involves deploying a ContractFactory on each supported chain and then creating an AppInstance through the TEE (Trusted Execution Environment).

Contract Deployment Flow

Deployment Steps

Deploy ContractFactory
- Deploy the ContractFactory smart contract on each chain you plan to support
- Keep track of the deployed addresses for each chain
Configure AppStack in TEE
- Define your AppStack configuration in the TEE
- Add base and quote chains using the gRPC interface
- Create an instance through the TEE
Create AppInstance
- The TEE will interact with the ContractFactory to create your AppInstance
- The AppInstance will be deployed at a new address on each chain
- Your AppStack will be set as the owner of these instances
Post-Deployment Setup
- Add tokens to each chain through the gRPC interface
- Create markets for the token pairs you want to support
- Configure market parameters and fees

Security Considerations

Ensure the TEE is properly configured and secured
Keep private keys for contract deployment secure
Verify contract addresses and ownership after deployment
Monitor contract events for any unexpected behavior

3. Deploy the Stack

Install the Aspens Admin CLI

The Aspens Market Stack is configured using the aspens-admin CLI tool. First, install it:

# Clone the SDK repository
git clone https://github.com/aspensprotocol/sdk.git
cd sdk
 
# Build the admin CLI
cargo build --release --bin aspens-admin
 
# Copy to your path (optional)
cp target/release/aspens-admin /usr/local/bin/

Configure Environment

Create a .env file with your configuration:

# Stack URL (your AMS gRPC endpoint)
ASPENS_MARKET_STACK_URL=http://localhost:50051
 
# Admin private key (hex string without 0x prefix)
# This wallet will be the admin for your AMS instance
ADMIN_PRIVKEY=your_admin_private_key_here

Initialize Admin

For a fresh stack, initialize the first admin:

aspens-admin init-admin --address 0xYourAdminAddress

This returns a JWT token. Save it to your .env file:

ASPENS_JWT=your_jwt_token_here

For subsequent sessions, authenticate with:

aspens-admin login

Add Base Chain

Add your base chain (e.g., Base Sepolia):

aspens-admin set-chain \
  --architecture EVM \
  --canonical-name "Base Sepolia" \
  --network base-sepolia \
  --chain-id 84532 \
  --instance-signer-address 0xYourInstanceSignerAddress \
  --rpc-url "https://your-base-sepolia-rpc-endpoint" \
  --factory-address 0xYourContractFactoryAddress \
  --permit2-address 0x000000000022D473030F116dDEE9F6B43aC78BA3 \
  --explorer-url "https://sepolia.basescan.org"

Add Quote Chain

Add your quote chain (e.g., OP Sepolia):

aspens-admin set-chain \
  --architecture EVM \
  --canonical-name "OP Sepolia" \
  --network op-sepolia \
  --chain-id 11155420 \
  --instance-signer-address 0xYourInstanceSignerAddress \
  --rpc-url "https://your-op-sepolia-endpoint" \
  --factory-address 0xYourContractFactoryAddress \
  --permit2-address 0x000000000022D473030F116dDEE9F6B43aC78BA3 \
  --explorer-url "https://sepolia-optimism.etherscan.io"

Add Tokens to Base Chain

Add the tokens you want to support on the base chain:

# Add USDC on Base Sepolia
aspens-admin set-token \
  --network base-sepolia \
  --name "USD Coin" \
  --symbol USDC \
  --address 0xYourUsdcAddress \
  --decimals 6

Add Tokens to Quote Chain

Add the corresponding tokens on the quote chain:

# Add USDT on OP Sepolia
aspens-admin set-token \
  --network op-sepolia \
  --name "Tether USD" \
  --symbol USDT \
  --address 0xYourUsdtAddress \
  --decimals 6

Deploy Trade Contracts

Deploy trade contracts on each chain:

# Deploy on Base Sepolia
aspens-admin deploy-contract base-sepolia --fees 100
 
# Deploy on OP Sepolia
aspens-admin deploy-contract op-sepolia --fees 100

The --fees parameter specifies the fee in basis points (100 = 1%).

Create Markets

Create markets for the token pairs you want to support:

# Create USDC/USDT market
aspens-admin set-market \
  --base-network base-sepolia \
  --quote-network op-sepolia \
  --base-symbol USDC \
  --quote-symbol USDT \
  --base-address 0xYourUsdcAddress \
  --quote-address 0xYourUsdtAddress \
  --base-decimals 6 \
  --quote-decimals 6 \
  --pair-decimals 6

Verify Configuration

After completing the configuration, verify that everything is set up correctly:

# Check connection and server status
aspens-admin status
 
# Get server version
aspens-admin version

Start the Stack

Once configuration is complete, start the stack services:

# Start all services
docker-compose up -d
 
# Verify services are running
docker-compose ps

You should see the following services running:

arborter (core service)
journal (trade log database)
frontend (UI service)

4. Configure Blockchain Networks

The blockchain networks were already configured in Step 3 using the aspens-admin set-chain command. This section provides additional details about chain configuration.

Chain Configuration Parameters

When adding chains with aspens-admin set-chain, you need to provide:

Parameter	Description
`--architecture`	Chain type: `EVM` or `Hedera`
`--canonical-name`	Human-readable chain name (e.g., "Base Sepolia")
`--network`	Network identifier used in commands (e.g., "base-sepolia")
`--chain-id`	The chain's numeric ID
`--instance-signer-address`	Address of the TEE instance signer
`--rpc-url`	RPC endpoint for the chain
`--factory-address`	Deployed ContractFactory address
`--permit2-address`	Permit2 contract address
`--explorer-url`	(Optional) Block explorer URL

Example: Add Additional Chains

# Add Ethereum Mainnet
aspens-admin set-chain \
  --architecture EVM \
  --canonical-name "Ethereum" \
  --network ethereum \
  --chain-id 1 \
  --instance-signer-address 0xYourInstanceSignerAddress \
  --rpc-url "https://your-ethereum-rpc-endpoint" \
  --factory-address 0xYourContractFactoryAddress \
  --permit2-address 0x000000000022D473030F116dDEE9F6B43aC78BA3 \
  --explorer-url "https://etherscan.io"
 
# Add Arbitrum
aspens-admin set-chain \
  --architecture EVM \
  --canonical-name "Arbitrum One" \
  --network arbitrum \
  --chain-id 42161 \
  --instance-signer-address 0xYourInstanceSignerAddress \
  --rpc-url "https://your-arbitrum-endpoint" \
  --factory-address 0xYourContractFactoryAddress \
  --permit2-address 0x000000000022D473030F116dDEE9F6B43aC78BA3 \
  --explorer-url "https://arbiscan.io"

Delete a Chain

To remove a chain from your configuration:

aspens-admin delete-chain base-sepolia

5. Configure Tokens

After configuring blockchain networks, add the tokens that will be tradable on your AMS.

Token Configuration Parameters

When adding tokens with aspens-admin set-token, you need to provide:

Parameter	Description
`--network`	Network identifier (must match a configured chain)
`--name`	Human-readable token name
`--symbol`	Token symbol (e.g., "USDC")
`--address`	Token contract address
`--decimals`	Token decimal places
`--token-id`	(Optional) Token ID for Hedera tokens

Example: Add Tokens

# Add USDT on Ethereum
aspens-admin set-token \
  --network ethereum \
  --name "Tether USD" \
  --symbol USDT \
  --address 0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  --decimals 6
 
# Add USDC on Arbitrum
aspens-admin set-token \
  --network arbitrum \
  --name "USD Coin" \
  --symbol USDC \
  --address 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 \
  --decimals 6
 
# Add WETH on Ethereum
aspens-admin set-token \
  --network ethereum \
  --name "Wrapped Ether" \
  --symbol WETH \
  --address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
  --decimals 18

Delete a Token

To remove a token from a chain:

aspens-admin delete-token --network ethereum --symbol USDT

6. Create Markets

Now that you have configured the networks and tokens, create markets for trading these tokens across chains.

Market Configuration Parameters

When creating markets with aspens-admin set-market, you need to provide:

Parameter	Description
`--base-network`	Network for the base token
`--quote-network`	Network for the quote token
`--base-symbol`	Base token symbol
`--quote-symbol`	Quote token symbol
`--base-address`	Base token contract address
`--quote-address`	Quote token contract address
`--base-decimals`	Base token decimal places
`--quote-decimals`	Quote token decimal places
`--pair-decimals`	Decimal precision for the trading pair

Example: Create Markets

# Create USDT/USDC crosschain market
aspens-admin set-market \
  --base-network ethereum \
  --quote-network arbitrum \
  --base-symbol USDT \
  --quote-symbol USDC \
  --base-address 0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  --quote-address 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 \
  --base-decimals 6 \
  --quote-decimals 6 \
  --pair-decimals 6

Delete a Market

To remove a market:

aspens-admin delete-market USDT/USDC

Verify Configuration

Check your configuration at any time:

# Check connection status
aspens-admin status
 
# Get server version and info
aspens-admin version

7. Implement Security and Monitoring

Set Up Monitoring

Configure monitoring to keep track of your AMS performance and security:

# Install monitoring stack (if not included in your docker-compose)
docker-compose -f monitoring-stack.yaml up -d
 
# Configure Prometheus endpoints in monitoring/prometheus.yml
cat > monitoring/prometheus.yml << 'EOF'
global:
  scrape_interval: 15s
 
scrape_configs:
  - job_name: 'aspens-metrics'
    static_configs:
      - targets: ['api-gateway:9090', 'arborter:9090', 'blockchain-watcher:9090']
EOF
 
# Restart monitoring services
docker-compose -f monitoring-stack.yaml restart

Harden Your Security

Improve the security of your AMS:

Configure a firewall to only allow necessary ports:

# Allow SSH, HTTP, HTTPS, and the AMS API port
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 50051/tcp
sudo ufw enable

Set up SSL certificates with Let's Encrypt:

# Install certbot
sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
 
# Generate certificates
sudo certbot --nginx -d your-ams-instance.com -d api.yoursite.com

8. Go Live

Complete Pre-Launch Checklist

Before making your AMS available to users, complete these steps:

Fund Admin Wallet: Ensure the admin wallet has enough native tokens for gas fees on each chain:

# Check your admin wallet address
aspens-admin admin-public-key
 
# Fund this address with native tokens on each chain you've configured
# For Ethereum: at least 0.1 ETH
# For L2s (Arbitrum, Base, etc.): at least 0.01 ETH

Deploy Trade Contracts: Ensure trade contracts are deployed on all configured chains:

# Deploy on each chain (if not already done)
aspens-admin deploy-contract base-sepolia --fees 100
aspens-admin deploy-contract op-sepolia --fees 100

Verify Configuration: Confirm all chains, tokens, and markets are properly configured:

# Check stack status and connectivity
aspens-admin status
 
# Verify server version
aspens-admin version

Test Trading: Use the SDK CLI or REPL to perform test trades:

# Install the trading CLI
cd sdk
cargo build --release --bin aspens-cli
 
# Check balances
./target/release/aspens-cli balance
 
# Test a deposit
./target/release/aspens-cli deposit base-sepolia USDC 100
 
# Test a market order
./target/release/aspens-cli buy-market USDC/USDT 10

Launch Your AMS

After completing all the steps above, prepare for launch:

Update DNS Records: Point your domain to your server's IP address:

your-ams-instance.com.    300    IN    A    your.server.ip.address
api.your-ams-instance.com.    300    IN    A    your.server.ip.address

Announce Launch: Inform users that your AMS is now available for trading.

9. Maintain and Update Your Stack

Perform Regular Maintenance Tasks

Execute these tasks regularly to keep your AMS running smoothly:

Back Up Your Database:

# Daily database backup
docker exec -t postgres pg_dumpall -c -U aspens > ~/aspens-stack/backups/backup_$(date +%Y-%m-%d).sql

Update the Software:

# Pull the latest changes
git pull
 
# Rebuild and restart containers
docker-compose build
docker-compose up -d

Monitor the Logs:

# Check service logs
docker-compose logs -f --tail=100

Troubleshoot Common Issues

If you encounter issues with your AMS, try these steps:

Fix Unresponsive Services:

# Restart the specific service
docker-compose restart service-name
 
# Check logs for errors
docker-compose logs service-name

Resolve Database Connection Issues:

# Check database status
docker exec -t postgres pg_isready -U aspens

Solve Blockchain Synchronization Issues:

# Check blockchain-watcher logs
docker-compose logs blockchain-watcher
 
# Restart the watcher
docker-compose restart blockchain-watcher

10. Enable Application Development

Once your Aspens Market Stack is operational, help developers build applications on top of it.

Create Developer Access

To allow developers to build on your stack:

Provide Documentation to Developers:

Share with developers:

API endpoint information
Links to developer documentation

Access Support and Resources

If you need additional help or have questions:

Documentation: Access documentation at https://docs.aspens.xyz
Support: reach out in Telegram for direct support.
Community: Join our operator discussion at https://github.com/aspensprotocol/feedback/discussions

Table of Contents

1. Set Up Infrastructure

Check Prerequisites

Prepare the Environment

2. Deploy Smart Contracts

Contract Deployment Flow

Deployment Steps

Security Considerations

3. Deploy the Stack

Install the Aspens Admin CLI

Configure Environment

Initialize Admin

Add Base Chain

Add Quote Chain

Add Tokens to Base Chain

Add Tokens to Quote Chain

Deploy Trade Contracts

Create Markets

Verify Configuration

Start the Stack

4. Configure Blockchain Networks

Chain Configuration Parameters

Example: Add Additional Chains

Delete a Chain

5. Configure Tokens

Token Configuration Parameters

Example: Add Tokens

Delete a Token

6. Create Markets

Market Configuration Parameters

Example: Create Markets

Delete a Market

Verify Configuration

7. Implement Security and Monitoring

Set Up Monitoring

Harden Your Security

8. Go Live

Complete Pre-Launch Checklist

Launch Your AMS

9. Maintain and Update Your Stack

Perform Regular Maintenance Tasks

Troubleshoot Common Issues

10. Enable Application Development

Create Developer Access

Access Support and Resources