Surety Agreement

contracts/products/surety_agreement.trea models a fiança contratual ou financeira — distinct from a seguro garantia (parametric/insurance-style guarantee). The fiador (surety) assumes the obligation owed to the beneficiary/credor on behalf of the debtor (afiançado). After the fiador pays a claim, a right of regress (direito de regresso) against the debtor is created and tracked on-chain, recoverable partially or in full.

SuretyAgreement -> one admin, one surety, one debtor, one beneficiary

The colateral-in-escrow mechanics reuse the technique from std.profile.GuaranteeLifecycle (issue locks collateral in the contract vault; payment releases it to the beneficiary; excess returns to the surety), but the state machine and storage are specific to fiança: a regress_balance is created on payment and decreases independently as the debtor recovers it.

Lifecycle

initialize -> issue -> accept -> claim -> pay_claim -> recover_regress (repeatable, partial allowed)
                          \-> amend (while Active)
                 \-> claim -> reject_claim -> claim (again, while Active)
                 \-> expire (after expiry_date)
        issue -> cancel (before acceptance)
                 \-> release (while Active, by mutual agreement)

States (SuretyState enum):

• Drafted — agreement initialized, collateral not yet locked
• Issued — surety locked collateral_amount in the contract escrow
• Active — debtor, beneficiary, or admin accepted the terms; claims allowed
• Claimed — beneficiary or admin filed a claim within validity
• Paid — surety paid the claim; a regress right against the debtor exists
• Expired — expiry_date elapsed with no active claim; collateral returned
• Cancelled — admin cancelled before acceptance; collateral returned
• Released — released by mutual agreement while Active; collateral returned

Claim And Payment

claim(amount) may only be called by the beneficiary or admin, only while the agreement is Active, only before expiry_date, and only for an amount up to obligation_amount. The admin can reject_claim() to contest it and return the agreement to Active (still within validity), allowing a corrected claim to be filed again.

pay_claim() (callable by admin or surety) requires the claimed amount not to exceed the collateral currently locked in escrow. It pays claim_amount to the beneficiary, returns any excess collateral to the surety, and — unlike GuaranteeLifecycle.honor() — does not stop there: it creates the regress right by setting regress_balance = claim_amount.

Right Of Regress

Once Paid, the debtor can call recover_regress(amount) any number of times, each time paying up to the remaining regress_balance to the surety. Partial recovery is explicit: regress_balance decreases and regress_recovered accumulates the total paid back, so the outstanding exposure of the debtor to the surety is always visible via regress_balance_view().

Only the debtor may call recover_regress; attempting to recover more than regress_balance is rejected with amount_exceeds_regress_balance.

Expiration, Cancellation, And Release

• expire() — admin-only, only from Active, only after expiry_date.

Returns any remaining locked collateral to the surety.

• cancel() — admin-only, only from Issued (before acceptance). Returns

locked collateral to the surety.

• release() — admin-only, only from Active, for consensual early

termination with no claim filed. Returns locked collateral to the surety.

None of these three paths touch regress_balance: by construction it is only nonzero after pay_claim(), which transitions to Paid, a state none of these three functions accept.

Receipts

The contract emits SuretyReceipt(surety_ref, surety, debtor, beneficiary, action, kind, state, amount, token) on every lifecycle step, alongside more specific events (SuretyIssued, SuretyAccepted, SuretyAmended, SuretyClaimed, SuretyClaimRejected, ClaimPaid, RegressCreated, RegressRecovered, SuretyExpired, SuretyCancelled, SuretyReleased).

Product Boundary

The contract governs the fiança's economic and lifecycle rules: collateral custody, claim validation, payment, and the regress balance between surety and debtor. It does not perform judicial collection, credit analysis, or off-chain enforcement of the regress debt, and it does not store full contract documents or PII — only the surety_ref reference and amounts. Claim adjudication beyond accept/reject (e.g. partial dispute resolution mechanics) is left to the admin role and off-chain process.