Extend the issuance venue

If your token does not mint through a plain mint(address,uint256), you do not need a new sale contract. You need one overridden function.

AsseteraIssuanceVenue is the contract Assetera deploys for its own primary offerings. It is MIT licensed and public, so you can inherit from it, change the single line that touches your token, and keep every economic guarantee the base contract makes. This page takes you from an empty directory to a deployed CustomerIssuanceVenue.

The worked example is the common one: a token that requires the investor to be whitelisted before a privileged issuance call may credit them.

A venue is any address the router can call

Primary settlement runs through AsseteraPrimarySales, the Assetera router. The contract it settles against is called the venue, and the router imposes no interface on it whatsoever. It approves the venue an exact amount of settlement currency, calls it with calldata whose selector and hash were signed in advance, and then judges the whole settlement on balances it measured itself.

That is the trust boundary. Everything to the left of the router is Assetera's. Everything from the venue rightwards is yours, and the router does not read your storage, does not call your token and does not believe anything your contract returns.

What it does instead, after your venue has run:

Set up the project

The contracts live in a public repository. The Foundry project is the contracts/ subdirectory, which is why the remapping below reaches into it.

forge init customer-issuance-venue
cd customer-issuance-venue
forge install OpenZeppelin/openzeppelin-contracts@v5.1.0
forge install Assetera-AG/AsseteraEvmContracts@evm-contracts-v8.2.1

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc = "0.8.28"

remappings = [
  "assetera/=lib/AsseteraEvmContracts/contracts/src/",
  "@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/",
]

Three things about that configuration are worth a sentence each.

• solc must be 0.8.28 or later. Every Assetera source file pins pragma solidity 0.8.28.
• The OpenZeppelin remapping is not optional. The Assetera sources import @openzeppelin/contracts/..., and the line above points those imports at the copy in your own project. Version 5.1.0 is the version Assetera builds against.
• Pin the Assetera tag. evm-contracts-v8.2.1 is the current release. Tracking a branch means your sale contract can change under you between a review and a deployment.

The one function you override

Inside the base contract, the entire assumption about how your token issues units is this:

/// The ONE place this contract assumes anything about how an asset token mints.
function _mintAsset(address to, uint256 amount) internal virtual {
    IMintableERC20(address(ASSET_TOKEN)).mint(to, amount);
}

ASSET_TOKEN is your token, fixed at deployment. to is the buyer. amount is the quantity the base contract has already priced, charged for and is about to verify. Nothing else on the purchase path knows what kind of token it is dealing with.

Override it and your token's own call takes its place:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import {AsseteraIssuanceVenue} from "assetera/primary/sale/AsseteraIssuanceVenue.sol";

/// Your token's issuance surface, as your token declares it.
interface ICustomerAssetToken {
    function isWhitelisted(address investor) external view returns (bool);
    function whitelist(address investor) external;
    function subscribeFor(address investor, uint256 amount) external;
}

contract CustomerIssuanceVenue is AsseteraIssuanceVenue {
    constructor(SaleConfig memory config) AsseteraIssuanceVenue(config) {}

    /// @inheritdoc AsseteraIssuanceVenue
    function _mintAsset(address to, uint256 amount) internal override {
        ICustomerAssetToken token = ICustomerAssetToken(address(ASSET_TOKEN));

        // Idempotent on purpose. A buyer's second purchase must not revert because they are
        // already on the register.
        if (!token.isWhitelisted(to)) token.whitelist(to);

        token.subscribeFor(to, amount);
    }
}

That is the whole contract. The cap, the price, the rounding, the measured settlement pull, the measured delivery check, the four roles and all five events are inherited untouched.

Where your override runs

The base purchase function is the only way units are ever created, and only the router may call it. Your override is step six.

Two properties of that order are load bearing. The currency is pulled before your token is touched, so units can never exist against a payment that has not landed. And the delivery is measured, not trusted: the base contract records balanceOf(buyer) before and after your override and reverts AssetDeliveryShortfall if the buyer received less than was quoted.

What your token has to satisfy

Deploy it

Every field of the deployment configuration is named, because four of them are addresses of the same type sitting next to each other and a transposed pair is invisible in a positional call.

CustomerIssuanceVenue venue = new CustomerIssuanceVenue(
  AsseteraIssuanceVenue.SaleConfig({
    // Roles. A multisig for the first, and keep the others separate from it.
    admin:           SAFE,          // roles, the purchase cap, and unpause
    rateSetter:      PRICING_KEY,   // may move the price inside the bounds below, nothing else
    pauser:          OPS_KEY,       // may stop the sale, and may not restart it
    treasurer:       TREASURY,      // may withdraw the proceeds

    // Immutable wiring.
    router:          PRIMARY_SALES, // the ONE address allowed to call purchase
    settlementToken: USDC,          // what the buyer pays in
    assetToken:      YOUR_TOKEN,    // what this venue issues

    // Price of ONE WHOLE asset token, in the settlement token's smallest unit.
    // With 6-decimal USDC, 12_500_000 means 12.50 USDC buys one whole token.
    unitPrice:       12_500_000,
    minUnitPrice:        10_000,    // 0.01 USDC. Must be above zero
    maxUnitPrice: 10_000_000_000,   // 10,000 USDC

    // Per-purchase ceiling, in WHOLE settlement tokens. Zero deploys the venue CLOSED.
    maxSettlementPerPurchaseWholeUnits: 100_000
  })
);

A freshly deployed venue cannot sell yet. Three things still have to happen, and none of them can be done from the venue itself.

Keep the view functions answering

Assetera prices your offering by reading your contract, at the moment a buyer asks for a quote. You inherit all of these from the base contract and they need no work, but an override that changed what any of them reports would put the quote and the fill out of step.

Test it before you deploy

The base contract ships with a Foundry suite, and the repository already contains a worked subclass that overrides _mintAsset for a partitioned token. Both are the fastest way to check your own override against a mock of your token.

forge test --match-contract CustomerIssuanceVenue -vvv

The one test to write first is the delivery assertion, because it is the failure that a mock hides and a real token does not:

function test_PurchaseCreditsTheBuyerSynchronously() public {
    uint256 before = token.balanceOf(buyer);
    vm.prank(ROUTER);
    (uint256 minted,) = venue.purchase(buyer, 125_000_000, 0);
    assertEq(token.balanceOf(buyer) - before, minted);
}

When something reverts

Next