Surety Insurance Policy

contracts/products/surety_insurance_policy.trea models a seguro garantia (performance bond / garantia contratual) — a specialization sitting between std.profile.GuaranteeLifecycle and the insurance templates in insurance_parametric.trea. The insurer (seguradora) underwrites the policyholder's (tomador) obligation toward the beneficiary/insured (segurado), in exchange for a premium and a reserve/capacity it constitutes for the guaranteed limit. Unlike SuretyAgreement (a pure fiança with collateral-in-escrow), this contract is accounted through the insurance posting lines (post(insurance.*_lines(...))), and after indemnification it creates an explicit right of subrogation against the policyholder, tracked separately from the original guaranteed obligation.

SuretyInsurancePolicy -> one admin, one insurer, one policyholder, one beneficiary

Lifecycle

initialize -> underwrite -> issue -> activate -> claim -> approve_claim -> indemnify -> recover_subrogation (repeatable, partial allowed)
                                         \-> endorse (while Active)
                                         \-> suspend -> reinstate (while Active/Suspended)
                                         \-> renew (extends expiry_date, while Active)
                                \-> claim -> reject_claim -> claim (again, while Active)
                                \-> expire (after expiry_date, from Active or Suspended)
        initialize|underwrite|issue|activate -> cancel (before any claim)

States (PolicyState enum):

• Quoted — policy initialized, not yet underwritten
• Underwritten — underwriting authorization recorded (admin or insurer)
• Issued — insurer constituted the reserve/capacity for guaranteed_limit
• Active — policyholder paid the premium; claims allowed
• Suspended — administratively suspended (e.g. premium delinquency)
• Claimed — beneficiary or admin filed a claim within validity
• Approved — admin approved the claim after analysis
• Indemnified — insurer paid the claim; a subrogation right against the

policyholder exists

• Expired — expiry_date elapsed with no active claim
• Cancelled — admin cancelled before any claim was filed

Underwriting, Issuance, And Activation

underwrite() (admin or insurer) represents the external underwriting authorization — the tx signature is the on-chain proof of approval, the same identity-based pattern ParametricInsurance uses for its oracle. Only after underwriting can issue() (insurer or admin) constitute the reserve via post(insurance.reserve_lines(token_id, insurer, guaranteed_limit)), and only after issuance can the policyholder activate() the policy by paying the premium via post(insurance.premium_lines(token_id, policyholder, insurer, premium_amount)).

Claim, Decision, And Indemnification

claim(amount) may only be called by the beneficiary or admin, only while the policy is Active, only before expiry_date, and only for an amount up to guaranteed_limit. The admin then decides:

• approve_claim() — moves the claim to Approved, enabling indemnification.
• reject_claim(reason) — requires a non-empty reason, returns the policy

to Active so a corrected claim can be filed again within validity.

indemnify() (admin or insurer) requires claim_amount not to exceed the reserve currently locked. It pays claim_amount to the beneficiary via post(insurance.payout_lines(token_id, insurer, beneficiary, claim_amount)), decreases reserve_locked by that amount, and — distinct from a plain insurance payout — creates the subrogation right by setting subrogation_balance = claim_amount. A claim smaller than guaranteed_limit results in partial indemnification, visible via available_limit() (guaranteed_limit - indemnified_amount).

Subrogation

Once Indemnified, the policyholder can call recover_subrogation(amount) any number of times, each time paying up to the remaining subrogation_balance to the insurer. Partial recovery is explicit: subrogation_balance decreases and subrogation_recovered accumulates the total paid back, so the outstanding exposure is always visible via subrogation_balance_view(). Only the policyholder may call recover_subrogation; attempting to recover more than subrogation_balance is rejected with amount_exceeds_subrogation_balance.

The subrogation credit is tracked independently of guaranteed_limit and claim_amount — it never reduces or confuses the original guaranteed obligation, only the insurer's later right against the policyholder.

Suspension, Reinstatement, And Renewal

• suspend() — admin-only, only from Active. Blocks new claims until

reinstated.

• reinstate() — admin-only, only from Suspended, only before

expiry_date. Returns the policy to Active.

• renew(new_expiry) — admin-only, only from Active, requires

new_expiry to extend the current expiry_date.

Expiration And Cancellation

• expire() — admin-only, only from Active or Suspended, only after

expiry_date.

• cancel() — admin-only, only from Quoted, Underwritten, Issued, or

Active (i.e. before any claim was filed).

Neither path touches subrogation_balance: by construction it is only nonzero after indemnify(), which transitions to Indemnified, a state neither function accepts.

Receipts

The contract emits SuretyInsuranceReceipt(policy_ref, insurer, policyholder, beneficiary, action, kind, state, amount, token) on every lifecycle step, alongside more specific events (PolicyQuoted, PolicyUnderwritten, PolicyIssued, PolicyActivated, PolicyEndorsed, PolicySuspended, PolicyReinstated, PolicyRenewed, PolicyClaimed, ClaimApproved, ClaimRejected, ClaimIndemnified, SubrogationCreated, SubrogationRecovered, PolicyExpired, PolicyCancelled).

Product Boundary

The contract governs the policy's economic and lifecycle rules: premium collection, reserve/capacity constitution, claim validation, decision, indemnification, and the subrogation balance between insurer and policyholder. It does not perform underwriting/rating analysis, judicial collection, or off-chain enforcement of the subrogation debt, and it does not store full policy documents or PII — only the policy_ref and document_hash reference and amounts. Claim adjudication beyond approve/reject (e.g. partial settlement negotiation) is left to the admin role and off-chain process.