Safe API Cheatsheet

The safe API is a small set of on-chain operations whose semantics close a vulnerability class: the obvious hand-written expansion is wrong in a way real contracts have paid for, and the named operation removes the mistake. Three conventions hold throughout:

• Fail-fast is primary. A lookup that must succeed is xOrFail(message); the Option form exists only where the caller branches.
• Predicates plus require. Checks return Boolean and you write require(check, message). There are no requireX wrappers.
• Safety in semantics, not naming. findContinuingOutputOrFail compares the whole address; onlyBurnsUnder refuses an empty mint. The name says what is checked, and the body checks it.

Already in the library

The nineteen operations

Grouped by receiver. The last column is the hand-written line the operation replaces.

List, SortedMap, AssocMap

Credential

Value

TxOut

TxInfo

TxOutRef

Math

The fail-fast form of every lookup

Reach for the OrFail form whenever the validator cannot continue without the value. Each one takes a message, so the failure names the check.

Vocabulary. singleton builds a one-element collection (List.singleton(a), SortedMap.singleton(k, v)). singleOrFail extracts the only element of a size-one collection. findUniqueOrFail finds the one element that satisfies a predicate among many, and keeps scanning to prove there is no second. .head after filter is the anti-idiom for both.

Deprecated members

Deprecated members still compile and delegate to their replacement. The design-pattern callback change in the last row is different: it is in place, with no deprecated overload.

Worked example: the vesting validator

scalus-examples/jvm/src/main/scala/scalus/examples/vesting/VestingValidator.scala, the spend branch before and after migration. Five operations do the work of nine lines of scaffolding, and every check that used to be implicit now fails with its own message.

Before

val ownInput = txInfo.findOwnInputOrFail(txOutRef).resolved
val contractAddress = ownInput.address
 
require(
  txInfo.findOwnInputsByCredential(contractAddress.credential).length === BigInt(1),
  MultipleVestingInputs
)
 
val contractOutputs = txInfo.findOwnOutputsByCredential(contractAddress.credential)
val txEarliestTime = txInfo.getValidityStartTime   // 0 when the range has no lower bound
// ...
require(contractOutputs.length === BigInt(1), NotExactlyOneContractOutput)
val contractOutput = contractOutputs.head
require(contractOutput.address === ownInput.address, ContinuingAddressMismatch)
require(
  contractOutput.value === ownInput.value - Value.lovelace(requestedAmount),
  ContinuingValueMismatch
)
require(contractOutput.datum === OutputDatum.OutputDatum(vestingDatum), InvalidDatum)

After

val ownInputInfo = txInfo.findInputOrFail(txOutRef)
val ownInput = ownInputInfo.resolved
val ownCredential = ownInput.address.credential
 
// One own input per transaction: one pass, fails on a second match (DS-1).
txInfo.inputs.findUniqueOrFail(
  _.resolved.address.credential === ownCredential,
  MultipleVestingInputs
)
 
val txEarliestTime = txInfo.validFromOrFail(NoValidityLowerBound)   // fails, never 0 (TI-1)
// ...
// The unique output at the exact own input address, staking credential included (AU-4).
val contractOutput =
    txInfo.findContinuingOutputOrFail(ownInputInfo, NotExactlyOneContractOutput)
require(
  contractOutput.value === ownInput.value - Value.lovelace(requestedAmount),
  ContinuingValueMismatch
)
require(contractOutput.hasInlineDatum(vestingDatum), InvalidDatum)

The vesting formula in the same file uses the rounding operation: vestingDatum.initialAmount * elapsed divFloor vestingDatum.duration.

See Also

• Common Vulnerabilities – The classes these operations close
• Datum Validation – Whole-datum equality and lazy decoding
• Design Patterns – State-thread NFTs, indexers and other structural defences