Source Chain Smart Contracts

An overview of source chain smart contracts and the best practice pattern to securely query their data on Creditcoin using the Creditcoin oracle.

Outdated Documentation: This page covers the architecture used for USC V1, which was deprecated on 2026-03-30. For the latest documentation, please visit: usc documentation

What is a Source Chain Smart Contract?

A source chain smart contract is a contract living on a chain such as Ethereum that is supported by the Creditcoin Oracle. Source chain contracts have two main responsibilities:

1. Support any source chain logic required by the Universal DApp.

2. Emit events which can be converted into Creditcoin oracle queries.

Let's focus on these one by one.

Source chain logic

Most logic and data for Universal DApps should live in a DApp contract on the execution chain rather than the source chain. But some minimal logic such as moving assets may need still to occur on the source chain. Try and keep this as small possible, since what makes Creditcoin DApps universal is the fact that most of their business logic is encompassed on the Creditcoin execution chain.

Emitting Events

This is the way by which your source chain will communicate with the execution chain. Imagine that you want a simple DApp which burns ERC20 tokens on Ethereum and mints corresponding ERC20 tokens on Creditcoin. Then you would want your source chain smart contract to emit an event such as TokensBurnedForBridging.

Example Source chain contract

The following is a simple source chain smart contract. The Universal DApp it supports is a cross chain token bridge which burns ERC20 tokens on a source chain such as Sepolia and mints corresponding tokens in a Universal DApp contract on Creditcoin.

The most important part of this contract is the TokensBurnedForBridging event which emitted in the burn() function. This event is picked up by an offchain worker and eventually triggers token minting on Creditcoin.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract TestERC20 is ERC20 {
    address public constant BURN_ADDRESS = address(1); // 0x...01
    
  /// This event is bridged by the Creditcoin Oracle to trigger token minting
  /// @notice Emitted when tokens are burned (sent to the burn address).
  /// @param from The address burning their tokens
  /// @param value The amount of tokens burned
  event TokensBurnedForBridging(address indexed from, uint256 indexed value);
  
  constructor(string memory name_, string memory symbol_) ERC20(name_, symbol_) {
      _mint(msg.sender, 1_000_000 ether);
  }
  
  /// The `TokensBurnedForBridging` event emitted by this call is bridged via the 
  /// Creditcoin Oracle to mint tokens on Creditcoin
  /// @notice "Burn" by transferring tokens to the 0x...01 sink address. 
  function burn(uint256 amount) external returns (bool) {
      _transfer(msg.sender, BURN_ADDRESS, amount);
      emit TokensBurnedForBridging(msg.sender, amount);
      return true;
  }
}

Next Steps

Universal Smart Contracts

Check out this tutorial for an example of how to use the Creditcoin stack to set up a decentralized trustless bridge.