Whitelabel DevKit
Up-to-date for Alpha v2.5, live through at least August 2023
The TC Trading Bot is presently in Alpha v2.5. We are working diligently to get Beta completed sometime in Q3 2023. These docs will guide you on how to interact with the TC Trading Bot at the Web3, blockchain-level with examples given in Solidity.
We would be honoured if you chose to integrate our service into your DeFi project. Please do drop us a line if you integrate! We would happily promote your integration: [email protected]
From a top-level view, funds are moved in the following order:
Frontend.sol -> BotPool.sol -> BotTrader.sol
Funds being withdrawn are moved directly from the smart contract to the depositor. Balances in the TC Trading Bot cannot be transferred to any other address. Withdrawals can only be sent back to the depositing address.
TC tokens are moved from the BotPool contract back to the address that deposited them.
USDC tokens – which is the only
cash token used during Alpha v2.5 – are directly deposited to and withdrawn from the BotTrader contract when there is no active trade. During an active trade, USDC deposited will be held as a Pending Deposit in the BotPool contract. In all cases, USDC can only ever be moved back (withdrawn) to the address that deposited.
Live Frontend contract deployed on-chain:
https://snowtrace.io/address/0x04134e403e6d14775a9ed1f012d9ed28bb95eadb
The
IFrontend.sol file linked below must be used to cast an address to an IFrontend interface object in order to then call a function on the Frontend contract.IERC20.sol is also required in order to approve() on the cash token contract before submitting a deposit() transaction to the Frontend contract. You may skip this step if you grant the BotPool contract sufficient allowance by some other mechanism. The IERC20.sol file is linked at the end of this section.deposit()transaction (pending if there's an active trade)withdraw()transaction (standard, pending if there's an active trade)withdrawAll()transaction (standard, pending if there's an active trade)
import "./IERC20.sol";
import "./IFrontend.sol";
IERC20 constant usdc = IERC20(0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E);
IFrontend constant tcFrontend = IFrontend(0x04134e403e6d14775a9ed1f012d9ed28bb95eadb);
address constant tcBotPool = 0x04134e403E6d14775A9eD1f012d9ed28bB95EadB; // Alpha v2.5
function tcDeposit(uint amountUSDC) external {
// the `cash` token must be approved first --> `transferFrom()`
usdc.approve(botPool, amountUSDC);
// 0 is the `amountTC` which is not required during Alpha v2.5
tcFrontend.deposit(tcBotPool, 0, amountUSDC);
}
function tcWithdraw(uint amountUSDC) external {
// 0 is the `amountTC` which is not required during Alpha v2.5
tcFrontend.withdraw(tcBotPool, 0, amountUSDC);
}
function tcWithdrawAll() external {
// false is the `onlyCash` option
// false will request TC and TCC tokens to be withdrawn as well
tcFrontend.withdrawAll(tcBotPool, false);
}
Solidity Interface (
IERC20.sol):
https://github.com/tripleconfirmation/tc-core/blob/main/contracts/interfaces/IERC20.solSolidity Interface (
IFrontend.sol):
https://github.com/tripleconfirmation/tc-core/blob/main/contracts/interfaces/IFrontend.solSolidity contract full source code (
Frontend.sol):
https://github.com/tripleconfirmation/tc-core/blob/main/contracts/Frontend.solThe above code deposits and withdraws 0 TC. Please note that while this will work during our Alpha v2.5 testing phase, Beta will require TC tokens.
If you'd like to check your balance, you'll need a bit more code. Please note that checking your balance during a trade will return a best guess estimate using Chainlink's quoted USD prices for the
asset token. BotTrader either holds asset tokens (in a Long position) or owes them as debt (in a Short position) which is subtracted from its cash token holdings to arrive at the final balance.There's two methods by which you may check your current balance. To include this functionality, add your preferred function call to the Solidity example code above:
- 2.
/** 1. Go directly to the BotTrader contract
* Function: https://github.com/tripleconfirmation/tc-core/blob/main/contracts/BotTrader.sol#L266
* Download IBotTrader.sol: https://github.com/tripleconfirmation/tc-core/blob/main/contracts/interfaces/IBotTrader.sol
* @dev The BotTrader address will change when TC moves into Beta.
*/
import "./IBotTrader.sol";
IBotTrader constant tcBotTrader = IBotTrader(0xFDF8e89573D0d1b660745c5ea7d200d298377607);
function tcBalanceCheckBotTrader() external view returns (uint balance) {
// @dev Balance request of the outside `msg.sender` wallet or `address(this)` smart contract wallet?
balance = tcBotTrader.getBalanceOf(msg.sender | address(this));
}
/** 2. Pull the relevant field out of the `getUser()` function return
* Function: https://github.com/tripleconfirmation/tc-core/blob/main/contracts/Frontend.sol#L151
*/
function tcBalanceCheckGetUser() external view returns (uint balance) {
balance = tcFrontend.getUser(tcBotPool).cash.balance;
}
The
deposit() function will transferFrom() the depositor the amountCash registered in BotPool's cash tokens. These tokens will only be successfully transferred if they are accepted into the TC Trading Bot. The deposit() function will revert if the depositor's internal balance did not increase. The deposit() function requires sufficient allowance to transferFrom() the depositor. An approve() transaction must be executed on the USDC token contract first:
https://github.com/centrehq/centre-tokens/blob/master/contracts/v1/FiatTokenV1.sol#L226Scenario: The BotTrader contract has an active trade and a depositor has a Pending Withdrawal of 10 USDC. If the depositor submits a
deposit()of 3 USDC, then no USDC will be transferred. Instead, their Pending Withdrawal will be amended to 7 USDC.Note that USDC is the only
cash token used during Alpha v2.5. The USDC deposited will be held temporarily in the BotPool contract if the BotTrader contract has an active trade. Otherwise, USDC will be deposited directly into the BotTrader contract if it has no active trade ("holding cash").Deposits made during an active trade will be accepted on the active trade's exit. Until then, the USDC tokens will be held in the BotPool contract as a Pending Deposit.
The minimum deposit, and balance, during Alpha v2.5 is 1 USDC. Balances that fall below 1 USDC on trade exit will be withdrawn to the depositor.
function deposit(address botPool, uint amountTC, uint amountCash)
The
depositWithPermit function only offers execution of gasless EIP-2612 Permits for depositing TC tokens. Unless you really nerd out on that kind of stuff, this is not relevant for Alpha v2.5 (current version).function depositWithPermit(
address botPool,
uint amountTC,
uint amountCash,
uint tcToApprove,
uint deadline,
uint8 v,
bytes32 r,
bytes32 s
)
The
withdraw() function executes a withdrawal immediately if the BotTrader contract has no active trade or submits a Pending Withdrawal if the BotTrader contract has an active trade. In the case of a Pending Withdrawal, the withdrawal will be processed on trade exit at the same time as Pending Deposits. A depositor may not concurrently have a Pending Withdrawal and Pending Deposit as they are exclusive to each other.Scenario: The BotTrader contract has an active trade and a depositor has a Pending Deposit of 10 USDC. If the depositor requests a
withdraw()of 3 USDC, then they will instantly receive 3 USDC and have their Pending Deposit amended to 7 USDC.If there is an active trade, the amount you request to
withdraw() may put your balance below the 1 USDC required minimum balance by the time the trade exits. In such a scenario, your request will instead be processed by withdrawAll() and your full balance will be returned.Since these withdrawals occur only when the BotTrader contract has settled its trade into
cash tokens, there is no slippage and no additional on-chain fees.function withdraw(address botPool, uint amountTC, uint amountCash)
The
withdrawNow() function immediately withdraws the given TC and cash tokens with an optional swapCallData field submitted to 0x's smart contracts. To obtain the swapCallData, an 0x API call must be made in Web2 for subsequent submission into Web3. Since submitting an 0x API call is complicated and requires unique authorisation using an API token, please contact us for further guidance if you desire to implement immediate withdrawals: [email protected]Full withdrawals must be submitted using either the
withdrawAll() or withdrawAllNow() function. The standard withdraw() and withdrawNow() functions only allow for partial withdrawals.Generally speaking up to 90% of your balance can be partially withdrawn. Keep in mind that 1 USDC is the required minimum balance.
This is an irreversible transaction which instantly reduces your balance in the TC Trading Bot and settles your requested portion of the Trading Bot's position into
cash tokens. High slippage may occur due to on-chain swapping!If there is an active trade, on-chain slippage could consume a large portion of your balance! Our frontend at https://app.tripleconfirmation.com verifies slippage and reports an estimate before transaction submission whereas no such functionality exists directly on the blockchain, contract-to-contract.
function withdrawNow(
address botPool,
uint amountTC,
uint amountCash,
bytes calldata swapCallData
)
The
withdrawAll() function will withdraw your entire position. This will execute immediately if there is no active trade or setup a Pending Withdrawal for your full balance if an active trade exists.After submitting a
withdrawAll() request, new withdraw() requests – which withdraw only part of your balance – will be denied (revert with a reason string). To learn how to cancel your withdrawAll() request, see Cancel Pending Transfers.Since these withdrawals occur only when the BotTrader contract has settled its trade into
cash tokens, there is no slippage and no additional on-chain fees.function withdrawAll(address botPool, bool onlyCash)
The
withdrawAllNow() function will withdraw your entire position immediately. This will execute regardless of active trade status. In the case of no active trade existing, this operates the same way as the standard withdrawAll() function.If there is an active trade, the optional
swapCallData field executes the required swap via 0x's smart contracts. To obtain the swapCallData, an 0x API call must be made in Web2 for subsequent submission into Web3. Since submitting an 0x API call is complicated and requires unique authorisation using an API token, please contact us for further guidance if you desire to implement immediate withdrawals: [email protected]This is an irreversible transaction which eliminates your entire balance in the TC Trading Bot and settles your entire portion of the Trading Bot's position. High slippage may occur due to on-chain swapping!
If there is an active trade, on-chain slippage could consume a large portion of your balance! Our frontend at https://app.tripleconfirmation.com verifies slippage and reports an estimate before transaction submission whereas no such functionality exists directly on the blockchain, contract-to-contract.
function withdrawAllNow(
address botPool,
bool onlyCash,
bytes calldata swapCallData
)
You may cancel your
withdrawAll() request and all other Pending transfers of cash tokens by executing the cancelPendingTransfers() function on the Frontend contract. Executing this function will immediately cancel all Pending Deposits and Pending Withdrawals including a pending withdrawAll() request.function tcCancelPendingTransfers() external {
// instantly cancels all pending deposits and pending withdrawals
tcFrontend.cancelPendingTransfers(tcBotPool);
}
Live BotPool contract deployed on-chain:
https://snowtrace.io/address/0xedbd9afdde1c5e98203049e1990ea6e57e239054
While most of the same functions exist in BotPool.sol as exist in Frontend.sol, we highly advised you to use Frontend.sol. The
deposit() function in particular requires a Permit in BotPool.sol. For ease-of-use and overall compatibility, our Frontend.sol contract submits an empty Permit to BotPool's deposit() function, allowing you to forget about that quirk.The BotPool contract has had some of its function headers removed in order to protect our young project and novel intellectual property. We open-source as much as possible. Sadly some would steal our system and copy our project in-full. Until we gain a first-mover advantage and securely establish ourselves we'll have to redact some parts of our code. You can still seamlessly interact with the on-chain TC Trading Bot through the Frontend contract which is 100% open-source.
Live BotTrader contract deployed on-chain:
https://snowtrace.io/address/0xfdf8e89573d0d1b660745c5ea7d200d298377607
Most of the functions in the BotTrader contract are privileged exclusively to its parent BotPool contract. The only exceptions are the entry and exit functions which can be executed by a team-managed trading wallet. This trading wallet can only submit entry and exit transactions without the authorisation to run any other state-altering functions. The trading wallet submits transactions when the TC Trading Bot strategy fires a signal.
Last modified 2mo ago