Issuance venue

AsseteraIssuanceVenue is one offering's primary sale, deployed one per offering. It does exactly one thing: take settlement currency from the router and mint the asset to the buyer, at a price a compliance officer set. No oracle, no order book, no inventory, no holder list, no currency conversion. It is a swap with a price.

To the router it is just a venue

To AsseteraPrimarySales it is a venue in that router's exact sense of the word: an address in a signed intent that gets approved an exact amount, called with calldata bound by hash and selector, then judged entirely on measured balance deltas. Nothing here is privileged there. The router cannot tell it from a third party's contract.

This contract is MIT licensed and public, so an issuer whose token does not mint through a plain mint(address,uint256) can inherit from it and override one function rather than write a sale contract of their own. See Extend the issuance venue.

Why the issuance path is a separate contract at all

Every field of a settlement intent belongs to the settlement operator, the delivery floor included. A mint module inside the router would therefore hand a compromised settlement key an unpriced mint: name yourself the buyer, set the floor to one wei, mint.

This contract removes that, because the economics are enforced by code rather than by a signature. It mints only what it has just been paid for, measured. The signer cannot mint without paying, whatever they sign.

The units. Read this before you integrate

unitPrice is the price of ONE WHOLE asset token, denominated in the SETTLEMENT token's smallest unit. Nothing else. Not a ratio, not a fixed-point number with a scale of its own, not a price per smallest asset unit.

Worked through with a 6-decimal settlement currency paying for an 18-decimal asset:

So, in both directions:

assetOut     = floor(settlementIn * ASSET_UNIT / unitPrice)
settlementIn = ceil (assetOut     * unitPrice  / ASSET_UNIT)

Both run through 512-bit intermediate arithmetic, so the 1e6 * 1e18 in the middle of a realistic quote is exact rather than merely not-yet-overflowing.

Ask the contract, do not reimplement the arithmetic

function quoteAssetOut(uint256 settlementIn)
  external view returns (uint256 assetOut, uint256 settlementCharged);

function quoteSettlementIn(uint256 assetOut)
  external view returns (uint256);

quoteAssetOut is what an off-chain quote should call to fill in the intent's venueQuoteIn and minAssetOut. Two implementations of the same rounding is how a one-wei disagreement ships, and here it would make every purchase whose price does not divide exactly revert at the delivery floor. Both reverts of purchase that a caller can trigger by arithmetic (ZeroAmount, NothingToMint) are raised by quoteAssetOut too, so an answer you get back is an answer you can act on.

quoteSettlementIn is the inverse, for the "I want N units" side of a front end. Note that feeding its answer back into quoteAssetOut can return slightly more than you asked for, because both directions round in the offering's favour. That is correct, and it is why purchase prices the quantity it derived rather than trusting a quantity it was handed.

Why the price bounds are per offering rather than fixed

The price is a settlement-currency amount, so it is written the way every other settlement-currency amount is written. The bounds MIN_UNIT_PRICE and MAX_UNIT_PRICE are therefore in settlement-currency units too, they are immutable per deployment, and they are supplied at deployment rather than hardcoded.

The reason is the same decimals problem. "One cent" and "ten thousand" are decimal numbers a human means; their raw values depend on a decimals count the contract only learns at deployment. A constant would silently mean a different price on a currency with different decimals, which is the exact class of bug this section exists to prevent. With a 6-decimal currency, a floor of 10_000 reads as one cent and a ceiling of 10_000_000_000 reads as ten thousand.

A zero floor is rejected at deployment: a price of zero divides into any payment an unbounded number of times, and the bounds are the only thing between a fat-fingered repricing and an offering given away.

Rounding, and who it favours

assetOut floors, so the buyer never receives more asset than they paid for. The residue is then not kept either: the venue charges the exact ceiling cost of the quantity it is actually about to mint, which is provably at most the payment offered, and simply does not take the difference.

How large that residue can be depends on the two decimal counts.

Whenever unitPrice < ASSET_UNIT, which is the ordinary case of a low-decimal currency buying a high-decimal asset, the ceiling cost of the floored quantity lands back exactly on the payment offered. The charge equals the offer and the router's refund path never fires.

Reverse the decimals and the residue becomes real, bounded by one smallest settlement unit. The router refunds it to the buyer as it would for any venue that rounds a fill down.

The price is enforced by the contract, not by the signed floor

This is the property the whole arrangement rests on, and it is worth stating on its own.

The venue never consults minAssetOut when deciding what to mint. It consults its own on-chain price. The floor is only ever a floor: a check that the price has not moved against the buyer between the quote and execution.

The consequence is that a settlement authorised with a vacuous delivery floor still fills at the real price. Give the venue a full-sized quote and a floor of one wei, and the buyer receives the full priced quantity anyway, and pays for it in full. There is no field of the settlement intent that turns a payment into less asset than the price says it buys.

The mirror half holds as well: a settlement that pays almost nothing mints almost nothing. The smallest settlement the router's gates will carry is one raw unit of the currency, and it buys exactly one raw unit's worth.

The purchase path

function purchase(address buyer, uint256 settlementIn, uint256 minAssetOut)
  external returns (uint256 assetMinted, uint256 settlementCharged);

The pull comes before the mint, so no asset can exist against a payment that has not landed. The reverse order would be a mint on credit for the duration of one external call, which is exactly the property this contract exists to deny.

Two more things worth knowing:

• The venue does not check who buyer is, and must not. The router asserts the measured delta on the buyer named in four signatures, so calldata that minted elsewhere fails there. Re-deriving the buyer here would mean this contract having an opinion about a router payload it cannot see.
• A fee-on-transfer or deflationary settlement currency cannot be sold in at all. Minting the full quantity against a short payment would put the shortfall in the issuer's proceeds, silently, every purchase. The listing decision is taken at the line that moves the money.

Configuration, roles and levers

Everything that cannot change is fixed at deployment: the router address, both tokens, both decimals counts and the price bounds. Everything that can moves under a role.

The venue also holds no compliance logic, no fee logic and no attestation of its own. All of that belongs to the router, which has already verified four signatures, screened the buyer and taken the fee out of the buyer's debit by the time the venue is called. A second copy of those rules would drift from the first.

Events

IssuanceMinted and the router's PrimarySettled are emitted from the same call, from the two different parties, and join on the transaction hash. They report the same money from two sides, so a discrepancy between them is a reconciliation alarm rather than a normal state.

One subtlety worth reading if you build a cap table:

Errors

Deliberately not built

Next