tcUSD

tcUSD (Taco USD) is an 18-decimal ERC-20 token with EIP-2612 permit support. Timu contracts can use it as shared settlement collateral for price markets when a deployment enables that path.

The current TcUSDCollateralMinterV24 lets you mint tcUSD by depositing a governance-configured asset as over-collateralized backing. The minter records your collateral and debt separately for each backing asset.

Availability

Contract support does not guarantee that the current app exposes a complete tcUSD minting flow. Networks, token and minter addresses, enabled backing assets, oracles, caps, and pause state are deployment-dependent.

Before transacting, confirm the active deployment manifest or product configuration and read the current onchain settings. A token or minter address alone does not prove that the minter is active or that a backing asset can mint new tcUSD.

Two contract layers

• TcUSD is the token and issuance-authority layer. Only an active authorized minter can create tcUSD. Active and frozen minters can burn tcUSD held by the minter contract for repayment and recovery.
• TcUSDCollateralMinterV24 is the collateral and debt layer. It holds backing assets, values them through configured USD oracles, mints debt, accepts repayment, and handles liquidation and bad debt.

One tcUSD token can authorize multiple minter contracts during a migration. Each minter keeps its own debt book and risk settings.

Borrow and repay

You interact directly with the active TcUSDCollateralMinterV24 unless the current product provides a supported wrapper.

Every risk-taking call carries explicit guards that you set when you sign. maxDebtAfter bounds the debt you accept after a mint, minHealthFactorAfter bounds the health of a withdrawal, expectedOracleDigest pins the exact oracle reading the transaction must observe, and deadline rejects stale submissions. A changed oracle digest, an expired deadline, or a breached bound reverts the call instead of executing at unexpected terms.

depositAndMint combines a deposit and a mint in one call and takes both sets of parameters. A failed mint also reverts the deposit.

repayFor(account, collateral, amount) lets a third party supply tcUSD to repay someone else's recorded debt. The payer receives no collateral claim and no compensation; the borrower's collateral stays in the minter. Like repay, it never reads an oracle and is available in every configured mode.

Approve the backing token to TcUSDCollateralMinterV24 before depositing. Approve tcUSD to the same minter before repaying. TcUSD.permit can set a tcUSD allowance through an EIP-2612 signature, but the caller still needs to submit the permit and repayment calls through a supported transaction flow.

Each (account, collateral) debt book is independent. Collateral deposited under one asset does not support debt under another asset, and the minter does not net health across backing assets.

Lifecycle modes and the depeg gate

Each backing asset has a lifecycle mode in its backing config:

• ACTIVE allows new minting against that asset.
• REDUCE_ONLY and FROZEN block new minting. Risk-reducing paths remain available: you can add collateral, repay, make a health-safe withdrawal, or be liquidated.
• RETIRED also blocks new deposits. Repayment, liquidation, and bad-debt coverage remain available, but you cannot add backing to a retired asset.

The minter can also bind a shared depeg monitor. While the bound monitor reports an open depeg incident:

• New minting reverts.
• Withdrawing collateral that still secures outstanding debt reverts, because removing backing while debt remains is new risk. Once your recorded debt for that asset is zero, a withdrawal no longer passes through the depeg gate, but it still requires a valid oracle reading.
• Accepting a pending config proposal that introduces a new config, loosens risk terms, or swaps the pinned oracle identity reverts. Pure tightening, such as a higher mode or a lower cap, stays available.

Minting also stays paused after insolvency is observed. resumeMinting is owner-only and reverts while any recorded bad debt remains or while a bound depeg monitor still reports an open incident.

Health and issuance limits

The minter converts collateral into a USD value using the configured oracle and the token's decimals. The oracle must return the collateral's USD price scaled to 1e18. Debt uses 18-decimal tcUSD/USD units.

• collateralFactorBps determines the initial borrowing limit: maxDebt = collateralValue × collateralFactorBps / 10,000.
• liquidationThresholdBps determines when liquidation starts. An account is liquidatable only when debt > liquidationDebt, where liquidationDebt = collateralValue × liquidationThresholdBps / 10,000.
• liquidationIncentiveBps increases the collateral paid to a liquidator. Configuration validation bounds the incentive and requires the account to remain fully liquidatable at the configured threshold.

Use getAccountHealth(account, collateral) to read collateral value, maximum debt, liquidation debt, current debt, the account's healthFactorWad, initial-health status, and liquidatability.

New issuance must fit all three capacity limits:

• The backing asset's mintCap in backingConfig limits active debt plus recorded bad debt associated with that asset.
• globalDebtCeiling limits the minter's aggregate active debt plus recorded bad debt across all backing assets. It defaults to zero, so issuance starts fail-closed.
• TcUSD.minterMintCap(minter) limits that authorized minter's tracked net issuance at the token layer.

Lowering a cap or debt ceiling below current usage blocks further issuance but does not block repayment, collateral top-ups, health-safe withdrawals, liquidation, or bad-debt coverage.

These contracts do not accrue borrowing interest. Recorded debt changes through minting, repayment, liquidation, and bad-debt coverage.

Oracle checks

The minter does not trust a bare nonzero getPrice() response. For every price-dependent action it reads the configured backing oracle through a bound read that checks:

• The oracle adapter is bound to this exact collateral token as its base token and quotes USD.
• The adapter's source identity, including source id, config hash, and runtime code hash, matches the identity pinned when the backing config was scheduled.
• The oracle status is LIVE, the sequencer is reported healthy, and the price is nonzero and internally consistent with the risk snapshot.
• The observation is inside its validity window. Transactions carrying expectedOracleDigest also require that expected digest to match the current result; health reads do not take that transaction guard.

Binding failures can return BackingConfigInvalid; invalid normalized prices return OraclePriceUnavailable, while transaction digest mismatches return OracleDigestMismatch. Adapter failures can propagate their own errors. Deposits, repayment, repayment for another account, and bad-debt coverage never read an oracle.

Liquidation and bad debt

Liquidation is permissionless. A liquidator approves tcUSD to the minter and calls liquidate with a TcUsdLiquidationRequestV24:

• account and collateral identify the borrower's debt book.
• maxDebtToRepay is a maximum. The minter repays at most this amount and at most the outstanding debt.
• minCollateralSeized and maxBadDebtCreated bound the seizure and any bad debt the liquidation would create.
• expectedOracleDigest and deadline pin the oracle reading and the expiry.

The call returns a receipt with the debt repaid, collateral seized, bad debt created, and the resulting account and system state.

The minter burns the tcUSD actually used for repayment and transfers the calculated backing collateral, including the configured incentive, to the liquidator. The actual burn and seizure are capped by the remaining debt and collateral.

If a price gap makes the debt larger than the amount supported by the remaining collateral:

1. Any successful liquidation that observes the shortfall pauses new minting immediately.
2. A partial liquidation can leave the shortfall as active borrower debt.
3. When the remaining collateral is exhausted, the minter closes that borrower debt and records the uncovered amount in badDebtByCollateral and totalBadDebt.

The minter can pay a configured subsidy to successful liquidators, subject to its reserve, a daily budget, and a per-borrower budget. The subsidy is deployment-dependent and may be zero or paused; failed eligibility, reserve, or budget checks skip the subsidy. An actual subsidy transfer failure still reverts the liquidation.

Anyone holding existing tcUSD can approve the minter and call coverBadDebt(collateral, amount). The call burns that tcUSD and reduces the recorded bad debt and aggregate debt. It is not a claim for compensation and does not mint replacement backing.

Covering all bad debt does not resume issuance automatically. systemRiskStatus() reports aggregate debt, bad debt, the debt ceiling, global-ceiling capacity, pause state, and whether the onchain bad-debt and depeg conditions permit a resume. Its remainingMintCapacity field reflects only globalDebtCeiling; the collateral and token-level caps can reduce actual capacity further. Governance must still assess the live collateral and oracle state before calling resumeMinting.

Timelock-governed configuration

Backing config and global debt ceiling changes follow a two-step proposal flow on TcUSDCollateralMinterV24:

• scheduleBackingConfig(collateral, config) records a pending config and its eta. acceptBackingConfig(collateral) applies it after the delay.
• scheduleGlobalDebtCeiling(newCeiling) and acceptGlobalDebtCeiling() follow the same pattern.

The delay is the CONFIG_DELAY set when the minter was deployed. It is a deployment parameter, not a fixed one-day constant.

The fixed one-day MINTER_AUTHORIZATION_DELAY applies to TcUSD minter authorization and scheduled minter-cap changes at the token layer. The collateral minter's proposal delay is separate.

The owner or the emergency guardian can tighten immediately without a proposal: downgradeBackingMode moves a backing asset to a stricter mode, and pauseMinting pauses issuance. These actions are one-way; reversing them requires the owner.

Bounded minter authorization

TcUSD separates new issuance from recovery burns:

• Governance calls scheduleMinter with a per-minter cap. Scheduling grants no authority.
• After the fixed one-day MINTER_AUTHORIZATION_DELAY, governance calls activateMinter. Activation rechecks the minter's runtime code hash, tcUSD binding, and debt-reporting interface.
• Governance or the emergency guardian can call freezeMinter immediately. A frozen minter cannot mint, but it remains a burner so its existing book can accept repayment, liquidate accounts, and cover bad debt.
• Governance can remove a frozen minter only after its reported debt and bad debt are zero and its tracked net issuance is zero. Reactivation requires a new delayed authorization.

The emergency guardian can reduce issuance risk immediately, including pausing collateral minting, freezing an active token minter, and cancelling a pending new minter or cap increase. It cannot activate a minter, resume collateral minting, increase the global debt ceiling, or rotate guardian authority.

The token's minter authorization and the collateral minter's mintingPaused flag are separate gates. New issuance requires both to allow it.

Using tcUSD in price markets

A pvpAMM pool settles tcUSD as an ERC-20 collateral token. When the deployment binds it to shared depeg monitoring, an open incident can also block new pool positions, liquidity additions, and other new-risk operations. Each pool still settles in one collateral token, even though the tcUSD minting layer can accept several backing assets.

The two solvency domains are independent:

• Locking borrowed tcUSD in a price position, LP lot, or margin account does not reduce your TcUSDCollateralMinterV24 debt.
• If your backing asset falls, the minter can liquidate that backing collateral without touching tcUSD already held by a pool.
• Closing a pool position can return tcUSD, but the payout does not repay your minter debt automatically. You must repay separately.
• The pool does not read your minter health, and the minter does not use your pool position or LP value as backing.

When the deployment supports Cross trading, one tcUSD margin account can group positions across supported pools whose collateral token is the same tcUSD address. See Position modes and margin accounts.

What to check before signing

• Confirm the current TcUSD and TcUSDCollateralMinterV24 addresses from the active deployment source.
• Check TcUSD.minterStatus(minter), minterMintCap(minter), and minterNetIssued(minter).
• Check backingConfig(collateral), including mode, oracle, collateral factor, liquidation threshold, incentive, and mint cap. Check pendingBackingConfig(collateral) for scheduled changes.
• Check systemRiskStatus() for global-ceiling capacity, bad debt, and minting pause, then check the other two issuance caps separately.
• Check your collateralOf(account, collateral), debtOf(account, collateral), and getAccountHealth(account, collateral) result, including healthFactorWad, with a usable oracle price.
• Verify the correct token allowance for the action.

Read next

• pvpAMM overview
• Position modes and margin accounts
• Oracle and contract risks