Request

The Request contract is the settlement intermediary between the Grunt protocol and bridge facilitators. It manages the full lifecycle of a bridge loan: accepting capital from bridge facilitators, making it available to the Facility, tracking repayment, and distributing proceeds back to the funders.

The Role of the Request

When the Facility needs bridge capital to cover the settlement gap of an async fund, it does not borrow directly from a bridge facilitator. Instead, it pulls funds from a Request contract that has already been pre-funded.

The Request is the contract that:

Accepts capital from one or more bridge facilitators
Issues tokens representing their stake (split into principal and yield components)
Allows the Facility to draw down capital as needed
Tracks repayment as the strategy settles
Enables bridge facilitators to redeem their tokens for proceeds once the bridge loan is repaid

The Dual-Token Model: PT and YT

When a bridge facilitator funds a Request, they receive two types of tokens:

Principal Tokens (PT) — represent the deposited principal. One PT is minted for each unit of capital provided.
Yield Tokens (YT) — represent the expected yield. The number of YT minted depends on the expected return agreed upon at funding time.

For example, if a bridge facilitator provides 1,000,000 USDC with a 10% expected return, they receive 1,000,000 PT and 100,000 YT.

Why Two Tokens?

The dual-token model creates a clean priority structure for repayment:

PT holders are repaid first. If the strategy returns less than the principal, PT holders share the loss proportionally, but they are always first in line. YT holders receive nothing until all principal is covered.
YT holders capture the upside. Any returns above the full principal amount flow to YT holders proportionally.

This separation allows bridge facilitators to price their risk clearly. The PT represents a senior claim, and the YT represents a junior, yield-bearing claim. A single funder typically holds both, but the model also allows them to be held separately — enabling secondary markets or risk tranching if desired.

How Redemption Works

When the Request is repaid and redemptions are enabled, the total assets in the contract are split between PT and YT holders using a simple priority rule:

Step 1: Allocate assets to principal first. If total assets are less than total PT outstanding, all assets go to PT holders and YT holders receive nothing. Each PT redeems for its proportional share of whatever is available.
Step 2: Any assets remaining after covering full principal go to YT holders. Each YT redeems for its proportional share of the surplus.

In concrete terms:

Scenario	Total Assets	What PT Holders Get	What YT Holders Get
Loss	900,000	0.90 per PT	0 per YT
Break-even	1,000,000	1.00 per PT	0 per YT
Modest gain	1,050,000	1.00 per PT	0.50 per YT
Strong gain	1,200,000	1.00 per PT	2.00 per YT

This priority structure means PT holders bear loss only when the strategy loses money, and they are always made whole before any yield is distributed. YT holders take more risk but participate in all the upside.

How Bridge Facilitators Fund a Request

There are two ways capital enters a Request:

RFQ-Style Signed Offers

The primary funding mechanism uses an off-chain offer / on-chain consumption pattern, similar to a Request for Quote (RFQ) workflow:

A bridge facilitator signs an off-chain offer specifying: the amount of capital they are willing to provide, the expected return they want, a nonce for ordering and cancellation, and an expiration timestamp
The Facility (or an authorized consumer) presents this signed offer to the Request contract on-chain
The Request verifies the signature, mints the corresponding PT and YT to the bridge facilitator, and pulls the capital

Offers can be partially consumed — the consumer can take less than the full offered amount, and the PT/YT minting scales proportionally.

Just-in-Time Settlement via Callbacks

When a bridge facilitator’s offer includes a callback flag, the Request does not pull funds immediately. Instead, it first calls back to the bridge facilitator’s contract, notifying it that its offer is being consumed. The bridge facilitator’s contract can then source the funds just in time — for example, by withdrawing from a lending pool or unwinding another position — before the Request pulls the capital.

This callback mechanism means bridge facilitators do not need to park idle capital waiting for consumption. They can keep their funds productive until the exact moment they are needed.

Authorized Minting

As an alternative to signed offers, the Request owner can directly authorize a specific funder to mint a fixed amount of PT and YT. The funder then deposits the corresponding capital and receives their tokens. This method is simpler but requires the owner to coordinate each funding event.

Drawdown and Repayment

Once a Request is funded, the Facility interacts with it through a straightforward drawdown and repayment cycle:

Drawdown — the Facility pulls capital from the Request to use in the strategy (e.g., subscribing to an async fund). The Request can optionally call back to the Facility during the pull, enabling the Facility to execute additional logic with the funds in a single transaction.
Utilization — the capital is deployed according to the strategy. During this period, the Request tracks that funds have been drawn.
Repayment — once the strategy settles and the Facility has established the leveraged position, it repays the Request. Repayment can happen in one or multiple transactions.
Redemption enabled — the Request owner marks the loan as repaid, or a pre-configured repayment deadline passes automatically. At this point, PT and YT holders can redeem their tokens for the underlying assets.

Full Request Lifecycle

sequenceDiagram
    participant BF as Bridge Facilitator
    participant 3F as 3F (off-chain)
    participant Req as Request Contract
    participant Fac as Facility

    BF->>3F: 1. Send signed offer (principal + expected yield)
    3F->>Req: 2. Accept offer on-chain

    BF->>Req: 3. Fund capital
    Req-->>BF: Mint PT + YT

    Fac->>Req: 4. Pull funds (drawdown)

    Note over Fac: Capital is deployed<br/>in the strategy

    Fac->>Req: 5. Repay funds

    Note over Req: 6. Assess and settle repayment<br/>based on actual loan duration,<br/>principal, and expected yield

    BF->>Req: 7. Burn PT + YT
    Req-->>BF: Return principal + yield

Nonce Management

Bridge facilitator offers use sequential nonces to provide flexible lifecycle management:

Each new offer must use a nonce higher than the last consumed or cancelled nonce
A bridge facilitator can soft cancel an offer by simply coordinating off-chain to stop presenting it
A bridge facilitator can hard cancel by setting their nonce on-chain to a value that invalidates all outstanding offers at or below that nonce

This system gives bridge facilitators control over their outstanding commitments without requiring on-chain transactions for every offer update.

Hard Cancel

A bridge facilitator can explicitly invalidate an outstanding offer by advancing their nonce on-chain.

sequenceDiagram
    participant BF as Bridge Facilitator
    participant Req as Request Contract
    participant C as Consumer

    BF->>BF: Sign Offer 1 (nonce=0)
    BF->>Req: setNonce(1)
    Note over Req: Current nonce for BF is now 1

    C->>Req: Consume Offer 1 (nonce=0)
    Req--xC: Reverts — nonce ≤ current nonce

Implicit Cancel via Consumption Order

When multiple offers are outstanding, consuming a higher-nonce offer automatically invalidates all lower-nonce offers from the same bridge facilitator.

sequenceDiagram
    participant BF as Bridge Facilitator
    participant Req as Request Contract
    participant C as Consumer

    BF->>BF: Sign Offer 1 (nonce=0)
    BF->>BF: Sign Offer 2 (nonce=1)

    C->>Req: Consume Offer 2 (nonce=1)
    Req-->>BF: Mint PT + YT for Offer 2
    Note over Req: Current nonce for BF is now 2

    C->>Req: Consume Offer 1 (nonce=0)
    Req--xC: Reverts — nonce ≤ current nonce