Dutch Proposal

1. Summary

PWNSimpleLoanDutchAuctionProposal.sol defines the Dutch Auction Proposal type for Simple Loan and implements functions to make an on-chain proposal and accept proposals.

The Dutch Auction Proposal creates a dutch auction with user pre-defined collateral, loan duration and interest. Credit amount drops (or goes up, if proposal is an offer) from user defined minimum and maximum for the auction duration from auction start. Interest can be either accruing or fixed.

2. Important links

550KB

PWNSimpleLoanDutchAuctionProposal.json

3. Contract details

PWNSimpleLoanDutchAuctionProposal.sol is written in Solidity version 0.8.16

Features

Provides acceptProposal function and makeProposal for on-chain proposals
Defines the Proposal struct

Inherited contracts, implemented Interfaces and ERCs

PWNSimpleLoanProposal

Functions

acceptProposal

Overview

A function to accept a proposal.

This function takes five arguments supplied by the caller:

addressacceptor - Address of a proposal acceptor
uint256refinancingLoanId - Refinancing loan ID
bytes32 calldataproposalData - Encoded proposal struct
bytes32[] calldataproposalInclusionProof - Multiproposal inclusion proof. Empty if single proposal
bytes calldatasignature - Signature of a proposal

Implementation

function acceptProposal(
    address acceptor,
    uint256 refinancingLoanId,
    bytes calldata proposalData,
    bytes32[] calldata proposalInclusionProof,
    bytes calldata signature
) override external returns (bytes32 proposalHash, PWNSimpleLoan.Terms memory loanTerms) {
    // Decode proposal data
    (Proposal memory proposal, ProposalValues memory proposalValues) = decodeProposalData(proposalData);

    // Make proposal hash
    proposalHash = _getProposalHash(PROPOSAL_TYPEHASH, abi.encode(proposal));

    // Calculate current credit amount
    uint256 creditAmount = getCreditAmount(proposal, block.timestamp);

    // Check acceptor values
    if (proposal.isOffer) {
        if (
            creditAmount < proposalValues.intendedCreditAmount ||
            proposalValues.intendedCreditAmount + proposalValues.slippage < creditAmount
        ) {
            revert InvalidCreditAmount({
                auctionCreditAmount: creditAmount,
                intendedCreditAmount: proposalValues.intendedCreditAmount,
                slippage: proposalValues.slippage
            });
        }
    } else {
        if (
            creditAmount > proposalValues.intendedCreditAmount ||
            proposalValues.intendedCreditAmount - proposalValues.slippage > creditAmount
        ) {
            revert InvalidCreditAmount({
                auctionCreditAmount: creditAmount,
                intendedCreditAmount: proposalValues.intendedCreditAmount,
                slippage: proposalValues.slippage
            });
        }
    }

    // Try to accept proposal
    _acceptProposal(
        acceptor,
        refinancingLoanId,
        proposalHash,
        proposalInclusionProof,
        signature,
        ProposalBase({
            collateralAddress: proposal.collateralAddress,
            collateralId: proposal.collateralId,
            checkCollateralStateFingerprint: proposal.checkCollateralStateFingerprint,
            collateralStateFingerprint: proposal.collateralStateFingerprint,
            creditAmount: creditAmount,
            availableCreditLimit: proposal.availableCreditLimit,
            expiration: proposal.auctionStart + proposal.auctionDuration + 1 minutes,
            allowedAcceptor: proposal.allowedAcceptor,
            proposer: proposal.proposer,
            isOffer: proposal.isOffer,
            refinancingLoanId: proposal.refinancingLoanId,
            nonceSpace: proposal.nonceSpace,
            nonce: proposal.nonce,
            loanContract: proposal.loanContract
        })
    );

    // Create loan terms object
    loanTerms = PWNSimpleLoan.Terms({
        lender: proposal.isOffer ? proposal.proposer : acceptor,
        borrower: proposal.isOffer ? acceptor : proposal.proposer,
        duration: proposal.duration,
        collateral: MultiToken.Asset({
            category: proposal.collateralCategory,
            assetAddress: proposal.collateralAddress,
            id: proposal.collateralId,
            amount: proposal.collateralAmount
        }),
        credit: MultiToken.ERC20({
            assetAddress: proposal.creditAddress,
            amount: creditAmount
        }),
        fixedInterestAmount: proposal.fixedInterestAmount,
        accruingInterestAPR: proposal.accruingInterestAPR,
        lenderSpecHash: proposal.isOffer ? proposal.proposerSpecHash : bytes32(0),
        borrowerSpecHash: proposal.isOffer ? bytes32(0) : proposal.proposerSpecHash
    });
}

makeProposal

Overview

Function to create an on-chain proposal. Marks the hash of the supplied proposal as proposed.

This function takes one argument supplied by the caller:

Proposal calldataproposal - Proposal struct containing all needed proposal data

Implementation

function makeProposal(Proposal calldata proposal) external returns (bytes32 proposalHash) {
    proposalHash = getProposalHash(proposal);
    _makeProposal(proposalHash, proposal.proposer);
    emit ProposalMade(proposalHash, proposal.proposer, proposal);
}

View Functions

getProposalHash

Overview

This function returns supplied proposals hash according to EIP-712.

This function takes one argument supplied by the caller:

Proposal calldataproposal - Proposal struct to be hashed

Implementation

function getProposalHash(Proposal calldata proposal) public view returns (bytes32) {
    return _getProposalHash(PROPOSAL_TYPEHASH, abi.encode(proposal));
}

encodeProposalData

Overview

Function to encode a proposal struct and proposal values.

This function takes two arguments supplied by the caller:

Proposal memoryproposal - Proposal struct to be encoded
ProposalValues memoryproposalValues - ProposalValues struct to be encoded

Implementation

function encodeProposalData(
    Proposal memory proposal,
    ProposalValues memory proposalValues
) external pure returns (bytes memory) {
    return abi.encode(proposal, proposalValues);
}

decodeProposalData

Overview

Function to decode an encoded proposal struct and proposal values.

This function takes one argument supplied by the caller:

bytes memoryproposalData - Encoded proposal and proposal values structs

Implementation

function decodeProposalData(bytes memory proposalData) public pure returns (Proposal memory, ProposalValues memory) {
    return abi.decode(proposalData, (Proposal, ProposalValues));
}

getCreditAmount

Overview

Function to compute credit amount for an auction in a specific timestamp.

This function takes two arguments supplied by the caller:

Proposal memoryproposal - Proposal struct containing all proposal data
uint256timestamp - Timestamp to calculate auction credit amount for

Implementation

function getCreditAmount(Proposal memory proposal, uint256 timestamp) public pure returns (uint256) {
    // Check proposal
    if (proposal.auctionDuration < 1 minutes) {
        revert InvalidAuctionDuration({
            current: proposal.auctionDuration,
            limit: 1 minutes
        });
    }
    if (proposal.auctionDuration % 1 minutes > 0) {
        revert AuctionDurationNotInFullMinutes({
            current: proposal.auctionDuration
        });
    }
    if (proposal.maxCreditAmount <= proposal.minCreditAmount) {
        revert InvalidCreditAmountRange({
            minCreditAmount: proposal.minCreditAmount,
            maxCreditAmount: proposal.maxCreditAmount
        });
    }

    // Check auction is in progress
    if (timestamp < proposal.auctionStart) {
        revert AuctionNotInProgress({
            currentTimestamp: timestamp,
            auctionStart: proposal.auctionStart
        });
    }
    if (proposal.auctionStart + proposal.auctionDuration + 1 minutes <= timestamp) {
        revert Expired({
            current: timestamp,
            expiration: proposal.auctionStart + proposal.auctionDuration + 1 minutes
        });
    }

    // Note: Auction duration is increased by 1 minute to have
    // `maxCreditAmount` value in the last minutes of the auction.

    uint256 creditAmountDelta = Math.mulDiv(
        proposal.maxCreditAmount - proposal.minCreditAmount, // Max credit amount difference
        (timestamp - proposal.auctionStart) / 1 minutes, // Time passed since auction start
        proposal.auctionDuration / 1 minutes // Auction duration
    );

    // Note: Request auction is decreasing credit amount (dutch auction).
    // Offer auction is increasing credit amount (reverse dutch auction).

    // Return credit amount
    return proposal.isOffer
        ? proposal.minCreditAmount + creditAmountDelta
        : proposal.maxCreditAmount - creditAmountDelta;
}

Events

The PWN Simple Loan Dutch Auction Proposal contract defines one event and five errors.

event ProposalMade(bytes32 indexed proposalHash, address indexed proposer, Proposal proposal);

ProposalMade

ProposalMade event is emitted when an on-chain proposal is made.

This event has three parameters:

bytes32 indexedproposalHash - Hash of the proposed proposal
address indexedproposer - Address of the proposer
Proposalproposal - The proposal made

`Errors`

error InvalidAuctionDuration(uint256 current, uint256 limit);
error AuctionDurationNotInFullMinutes(uint256 current);
error InvalidCreditAmountRange(uint256 minCreditAmount, uint256 maxCreditAmount);
error InvalidCreditAmount(uint256 auctionCreditAmount, uint256 intendedCreditAmount, uint256 slippage);
error AuctionNotInProgress(uint256 currentTimestamp, uint256 auctionStart);

InvalidAuctionDuration

InvalidAuctionDuration error is thrown when auction duration is less than min auction duration.

This error has two parameters:

uint256current - Provided duration
uint256limit - Minimal duration (1 minute)

AuctionDurationNotInFullMinutes

AuctionDurationNotInFullMinutes error is thrown when auction duration is not in full minutes.

This error has two parameters:

uint256current - Supplied duration

InvalidCreditAmountRange

InvalidCreditAmountRange error is thrown when min credit amount is greater than max credit amount.

This error has two parameters:

uint256minCreditAmount
uint256maxCreditAmount

InvalidCreditAmount

InvalidCreditAmount error is thrown when current auction credit amount is not in the range of intended credit amount and slippage.

This error has three parameters:

uint256auctionCreditAmount
uint256intendedCreditAmount
uint256slippage

AuctionNotInProgress

AuctionNotInProgress error is thrown when auction has not started yet or has already ended.

This error has two parameters:

uint256currentTimestamp
uint256auctionStart

`Proposal` struct

Type Name Comment

Type	Name	Comment
	`collateralCategory`	Corresponding collateral category
`address`	`collateralAddress`	Address of a loan collateral
`uint256`	`collateralId`	ID of a collateral. Zero if ERC-20
`uint256`	`minCollateralAmount`	Minimal amount of tokens used as a collateral
`bool`	`checkCollateralStateFingerprint`	Flag to enable check of collaterals state fingerprint (see ERC-5 646)
`bytes32`	`collateralStateFingerprint`	A collateral state fingerprint (see ERC-5 646)
`address`	`creditAddress`	Address of credit asset
`uint256`	`minCreditAmount`	Minimum amount of tokens which are proposed as a loan to a borrower. If `isOffer` is true, auction will start with this amount, otherwise it will end with this amount.
`uint256`	`maxCreditAmount`	Maximum amount of tokens which is proposed as a loan to a borrower. If `isOffer` is true, auction will end with this amount, otherwise it will start with this amount.
`uint256`	`availableCreditLimit`	Maximum credit limit of credit asset
`uint256`	`fixedInterestAmount`	Fixed interest amount in credit tokens. It is the minimum amount of interest which has to be paid by a borrower
`uint24`	`accruingInterestAPR`	Accruing interest APR with 2 decimals
`uint32`	`duration`	Loan duration in seconds
`uint40`	`auctionStart`	Auction start timestamp in seconds
`uint40`	`auctionDuration`	Auction duration in seconds
`address`	`allowedAcceptor`	Allowed acceptor address. Zero address if propsal can be accepted by any account
`address`	`proposer`	Proposer address
`bytes32`	`proposerSpecHash`	Hash of a proposer specific data, which must be provided during a loan creation
`bool`	`isOffer`	Flag to determine if a proposal is an offer or loan request
`uint256`	`refinancingLoanId`	ID of a loan to be refinanced. Zero if creating a new loan.
`uint256`	`nonceSpace`	Nonce space of the proposal
`uint256`	`nonce`	Nonce of the proposal
`address`	`loanContract`	Loan type contract

collateralCategory

Corresponding collateral category

address

collateralAddress

Address of a loan collateral

uint256

collateralId

ID of a collateral. Zero if ERC-20

uint256

minCollateralAmount

Minimal amount of tokens used as a collateral

bool

checkCollateralStateFingerprint

Flag to enable check of collaterals state fingerprint (see ERC-5 646)

bytes32

collateralStateFingerprint

A collateral state fingerprint (see ERC-5 646)

address

creditAddress

Address of credit asset

uint256

minCreditAmount

Minimum amount of tokens which are proposed as a loan to a borrower. If isOffer is true, auction will start with this amount, otherwise it will end with this amount.

uint256

maxCreditAmount

Maximum amount of tokens which is proposed as a loan to a borrower. If isOffer is true, auction will end with this amount, otherwise it will start with this amount.

uint256

availableCreditLimit

Maximum credit limit of credit asset

uint256

fixedInterestAmount

Fixed interest amount in credit tokens. It is the minimum amount of interest which has to be paid by a borrower

uint24

accruingInterestAPR

Accruing interest APR with 2 decimals

uint32

duration

Loan duration in seconds

uint40

auctionStart

Auction start timestamp in seconds

uint40

auctionDuration

Auction duration in seconds

address

allowedAcceptor

Allowed acceptor address. Zero address if propsal can be accepted by any account

address

proposer

Proposer address

bytes32

proposerSpecHash

Hash of a proposer specific data, which must be provided during a loan creation

bool

isOffer

Flag to determine if a proposal is an offer or loan request

uint256

refinancingLoanId

ID of a loan to be refinanced. Zero if creating a new loan.

uint256

nonceSpace

Nonce space of the proposal

uint256

nonce

Nonce of the proposal

address

loanContract

Loan type contract

PreviousFungible Proposal NextPWN LOAN

Last updated 1 month ago

1. Summary

2. Important links

3. Contract details

Features

Inherited contracts, implemented Interfaces and ERCs

Functions

Overview

Implementation

Overview

Implementation

View Functions

Overview

Implementation

Overview

Implementation

Overview

Implementation

Overview

Implementation

Events

Errors

Proposal struct

`Errors`

`Proposal` struct