Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stateset.com/llms.txt

Use this file to discover all available pages before exploring further.

​
ssUSD Smart Contracts

StateSet USD (ssUSD) is implemented as a native Cosmos SDK module with CosmWasm smart contract interfaces for advanced functionality.

​
🏗️ Architecture Overview

Native Module

Core ssUSD logic implemented as Cosmos SDK module for maximum performance

CosmWasm Interface

Smart contract layer for programmable features and DeFi integration

​
📋 Contract Addresses

​
Mainnet

ContractAddressDescription
ssUSD Tokenstateset1ssusd...Main token contract
Minterstateset1mint...Issuance controller
Treasurystateset1treasury...Reserve management
Bridgestateset1bridge...Cross-chain bridge

​
Testnet

ContractAddressDescription
ssUSD Tokenstateset1test_ssusd...Test token contract
Faucetstateset1faucet...Test token distribution

​
🔧 Core Interfaces

​
Token Contract

// Query ssUSD balance
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    Balance { address: String },
    TotalSupply {},
    TokenInfo {},
    Allowance { owner: String, spender: String },
}

// Execute token operations
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Transfer {
        recipient: String,
        amount: Uint128,
    },
    TransferFrom {
        owner: String,
        recipient: String,
        amount: Uint128,
    },
    Approve {
        spender: String,
        amount: Uint128,
    },
    IncreaseAllowance {
        spender: String,
        amount: Uint128,
    },
    DecreaseAllowance {
        spender: String,
        amount: Uint128,
    },
}

​
JavaScript Integration

// Initialize contract interface
const ssusdContract = new Contract(
  client,
  'stateset1ssusd...',
  ssUSDContractABI
);

// Query balance
const balance = await ssusdContract.balance({
  address: 'stateset1user...'
});

// Transfer tokens
const tx = await ssusdContract.transfer({
  recipient: 'stateset1recipient...',
  amount: '1000000' // 1 ssUSD (6 decimals)
});

​
💡 Common Patterns

​
Programmatic Transfers

// Batch transfer with memo
async function batchTransfer(transfers) {
  const messages = transfers.map(t => ({
    contractAddress: SSUSD_CONTRACT,
    msg: {
      transfer: {
        recipient: t.recipient,
        amount: (t.amount * 1e6).toString() // Convert to uunits
      }
    }
  }));
  
  const tx = await client.signAndBroadcast(
    senderAddress,
    messages,
    'auto',
    'Batch payment'
  );
  
  return tx;
}

​
Allowance Management

// Approve spending limit for DeFi protocol
async function approveProtocol(protocol, amount) {
  const tx = await ssusdContract.approve({
    spender: protocol,
    amount: (amount * 1e6).toString()
  });
  
  // Monitor spending
  const allowance = await ssusdContract.allowance({
    owner: myAddress,
    spender: protocol
  });
  
  console.log(`Protocol can spend: ${allowance.allowance / 1e6} ssUSD`);
}

​
Event Monitoring

// Subscribe to transfer events
const subscription = await client.subscribeTx({
  "message.action": "/stateset.ssusd.v1.MsgTransfer"
});

subscription.on('data', (tx) => {
  const events = tx.events.filter(e => e.type === 'transfer');
  events.forEach(event => {
    const from = event.attributes.find(a => a.key === 'from').value;
    const to = event.attributes.find(a => a.key === 'to').value;
    const amount = event.attributes.find(a => a.key === 'amount').value;
    
    console.log(`Transfer: ${from} → ${to}: ${amount}`);
  });
});

​
🔐 Security Features

​
Multi-Signature Support

// Create multi-sig transfer
const multiSigMsg = {
  transfer: {
    recipient: 'stateset1recipient...',
    amount: '1000000000' // 1000 ssUSD
  }
};

// Requires 2 of 3 signatures
const signatures = await Promise.all([
  signer1.sign(multiSigMsg),
  signer2.sign(multiSigMsg)
]);

const tx = await client.broadcastMultisig(
  multiSigAddress,
  multiSigMsg,
  signatures
);

​
Rate Limiting

// Contract-level rate limiting
pub fn execute_transfer(
    deps: DepsMut,
    env: Env,
    info: MessageInfo,
    recipient: String,
    amount: Uint128,
) -> Result<Response, ContractError> {
    // Check rate limit
    let daily_limit = DAILY_LIMITS.load(deps.storage, &info.sender)?;
    let current_usage = DAILY_USAGE.load(deps.storage, &info.sender)?;
    
    if current_usage + amount > daily_limit {
        return Err(ContractError::DailyLimitExceeded {});
    }
    
    // Execute transfer
    // ...
}

​
🌉 Cross-Chain Bridge

​
Bridge to Ethereum/Base

// Initiate bridge transfer
const bridgeTx = await bridgeContract.bridgeOut({
  destination_chain: 'ethereum',
  recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f6E321',
  amount: '1000000000', // 1000 ssUSD
  memo: 'Bridge to Ethereum'
});

// Monitor bridge status
const status = await bridgeContract.getBridgeStatus({
  tx_hash: bridgeTx.transactionHash
});

console.log(`Bridge status: ${status.status}`);
console.log(`Ethereum tx: ${status.destination_tx_hash}`);

​
🏭 DeFi Integration

​
Liquidity Pool Integration

// Add liquidity to ssUSD/ATOM pool
const poolContract = new Contract(client, POOL_ADDRESS, poolABI);

const provideLiquidity = await poolContract.provideLiquidity({
  assets: [
    {
      info: { token: { contract_addr: SSUSD_CONTRACT }},
      amount: '1000000000' // 1000 ssUSD
    },
    {
      info: { native_token: { denom: 'uatom' }},
      amount: '50000000' // 50 ATOM
    }
  ],
  slippage_tolerance: '0.01' // 1%
});

​
Yield Farming

// Stake LP tokens
const farmContract = new Contract(client, FARM_ADDRESS, farmABI);

const stake = await farmContract.stake({
  amount: lpTokenAmount
});

// Check rewards
const rewards = await farmContract.pendingRewards({
  address: myAddress
});

console.log(`Pending rewards: ${rewards.amount} STATE`);

​
📝 Contract Deployment

​
Deploy Custom Contract

// Deploy contract that uses ssUSD
const wasmCode = fs.readFileSync('./my_contract.wasm');

const uploadResult = await client.upload(
  senderAddress,
  wasmCode,
  'auto'
);

const instantiateResult = await client.instantiate(
  senderAddress,
  uploadResult.codeId,
  {
    ssusd_contract: SSUSD_CONTRACT,
    admin: senderAddress
  },
  'My ssUSD Contract',
  'auto'
);

console.log(`Contract deployed at: ${instantiateResult.contractAddress}`);

​
🧪 Testing

​
Unit Tests

#[cfg(test)]
mod tests {
    use super::*;
    use cosmwasm_std::testing::{mock_dependencies, mock_env, mock_info};
    
    #[test]
    fn test_transfer() {
        let mut deps = mock_dependencies();
        let env = mock_env();
        
        // Initialize contract
        let msg = InstantiateMsg {
            name: "StateSet USD".to_string(),
            symbol: "ssUSD".to_string(),
            decimals: 6,
        };
        
        let info = mock_info("creator", &[]);
        instantiate(deps.as_mut(), env.clone(), info, msg).unwrap();
        
        // Test transfer
        let transfer_msg = ExecuteMsg::Transfer {
            recipient: "recipient".to_string(),
            amount: Uint128::new(1000000),
        };
        
        let info = mock_info("sender", &[]);
        let res = execute(deps.as_mut(), env, info, transfer_msg).unwrap();
        
        assert_eq!(res.messages.len(), 0);
    }
}

​
Integration Tests

describe('ssUSD Contract', () => {
  let client;
  let ssusdContract;
  
  beforeAll(async () => {
    client = await SigningCosmWasmClient.connect(RPC_ENDPOINT);
    ssusdContract = new Contract(client, SSUSD_CONTRACT, abi);
  });
  
  test('should transfer tokens', async () => {
    const beforeBalance = await ssusdContract.balance({
      address: recipient
    });
    
    await ssusdContract.transfer({
      recipient,
      amount: '1000000'
    });
    
    const afterBalance = await ssusdContract.balance({
      address: recipient
    });
    
    expect(afterBalance.balance).toBe(
      (parseInt(beforeBalance.balance) + 1000000).toString()
    );
  });
});

​
📚 Resources

Contract Source

View contract source code

ABI Reference

Complete ABI documentation

Integration Examples

Sample integrations

Security Audits

Contract audit reports