The Issuance Pipeline

How an investor account becomes an eligible holder, how an asset becomes an accepted offering, what legal shape that offering is given, and how it becomes a transfer-restricted token on Solana. This page is the technical walkthrough of all four, and of the checks that sit between them.

The shape of it

Three pipelines run independently and meet at the token. An account becomes an eligible holder; an asset becomes an accepted offering; the offering becomes a mint whose transfer hook checks holders against the offering's own policy on every transfer. A fourth decision sits across them — what the token legally is — and it has to be settled and frozen before a mint exists, because the mint is configured against the answer.

One principle runs through all of it, and it is worth stating before the detail: the chain enforces the output of a decision, never the decision itself. Every determination — who someone is, whether they are accredited, whether an asset may be offered — is made and recorded off-chain. What reaches the chain is a compact, expiring assertion that the determination was made, and a program that refuses transfers when that assertion is missing, stale, or from an issuer the offering does not trust.

1. Creating an account

An account reaches eligibility through five distinct states, each of which produces a durable record. Nothing is inferred: an account that has cleared KYC but has no accreditation on file is not eligible for anything, and the system will say so rather than guess.

Identity and KYC

Accounts are created either by a company employee in the portal or by the investor through the embeddable widget. Both paths converge on the same records. Authentication is password plus mandatory TOTP: a 12-character minimum, a 30-minute session timeout, and a lockout after ten failed attempts. Until TOTP is enrolled, every authenticated route redirects to enrolment.

Identity verification is delegated to a third-party provider that performs the document scan, the liveness check, and AML and sanctions screening. The platform holds a KycVerification row per check, moving through pending → processing → approved | rejected | needs_review.

Results arrive by webhook. The webhook endpoint verifies an HMAC-SHA256 signature, stores the raw event before interpreting it, and deduplicates on the provider's event id — so a replayed or repeated delivery is a no-op rather than a second state change. A background job then fetches the authoritative decision from the provider's API rather than trusting the payload, applies it to the verification, syncs the account's status, and triggers whatever the new status unlocks.

Accreditation and verification level

Accreditation is recorded separately from identity, per investor per company, because they answer different questions: identity verification confirms who someone is, and says nothing about their income or net worth.

Each certification carries a basis — which Rule 501(a) test is being relied on — and a verification level, which records how the determination was reached rather than what it concluded. The level is the part that governs which offerings the investor can hold:

Anything above self-certification is a claim that someone checked something, so the record is required to name them: a verifier identity and an external reference are mandatory at those levels, and a SHA-256 evidence_hash is computed over the verification record on every save. That hash is the only part of the accreditation that ever reaches the chain, and it exists so an on-chain assertion can be tied back to the off-chain record behind it — and so a record altered afterwards no longer matches what was attested.

The evidence file

A verification level above self-certification is a claim that documents were reviewed, so the documents are held. A documentary certification is created pending and accumulates its file first; approval is the checkpoint, not creation. Each document is an AccreditationEvidence row with its own type, and the types are split along the lines Rule 506(c)(2)(ii) draws rather than lumped into one bucket:

The split is not cosmetic. Reviewing an investor's own statements in-house is reasonable steps; a letter moves the determination to someone licensed and accountable for it, which is why it ranks higher. Approving a certification at letter_credential with no letter in the file is refused, as is approving any documentary level with nothing behind it, and as is a certification where the investor is their own certifier — nobody takes reasonable steps to verify themselves. The review screen lists the gaps before anyone presses approve rather than failing at the press.

Uploads are PDFs or images only, capped at 25 MB, and each is hashed with SHA-256 streamed from the upload itself. The certification's evidence_hash is then a digest over the record fields and the sorted document hashes, so it depends on the set of documents rather than the order they arrived in — and a document swapped, edited, or removed after the fact moves the hash away from the one written on chain. Adding or removing a document recomputes it immediately.

What the offering asks for

The question an investor is asked about their accreditation belongs to the offering, not to the form. Each offering declares which Rule 501(a) bases it accepts and carries a verification floor derived from its safe harbour, and the embeddable widget asks that offering's question — the bases it will actually take, and a self-attestation step only where a self-certified investor could clear it.

Embedded without a specific offering, the criteria are the union across the company's live offerings, so what an investor is told still corresponds to something they could buy. A company with no live offering yet is the one case where nothing has stated a requirement: onboarding proceeds self-certified, and the floor applies later at the offering that has one.

Wallets and the qualified-investor attestation

A wallet is registered by proving control of it: the investor signs a challenge with the wallet's key and the platform verifies the Ed25519 signature against the address. An address that is well-formed base58 but does not decode to a 32-byte public key is rejected at the model level — it could never hold a token or carry an attestation.

Once an account is KYC-approved, accredited, and has a verified primary wallet, the platform writes a qualified-investor attestation to the Solana Attestation Service for that wallet. This is the artifact the transfer hook reads. Its address is a program-derived address of ["attestation", credential, schema, wallet] — note the absence of any mint. One attestation covers every offering; the per-offering decision happens at transfer time.

The payload asserts status and nothing else:

No names, no documents, no evidentiary basis — on-chain data is world-readable, and the reasonable-steps record is an examination artifact that belongs off-chain and stays there. Attestations are capped at one year and re-issued by a daily sweep before they lapse; nothing on-chain initiates a refresh, so an attestation that expires simply stops authorising transfers. Re-issuance is skipped when the assertion has not changed, so the sweep is usually a no-op.

2. Identifying an asset and accepting it

An asset arrives as a project belonging to a company that has already cleared business verification. Two things then have to be true before it can be tokenized: it has to be described in a form machines can read, and it has to be accepted by the compliance pipeline.

Classification

Description follows a two-axis classification, because a first-lien note and an equity stake in the same building are both real estate with inverted risk — neither axis can be inferred from the other:

Where a specific property is identified, the identifier is stored hashed with a per-project salt. An unsalted parcel number is recoverable by enumerating the county register, which would make the on-chain record a pointer to a street address; the salt is generated automatically the moment an identifier is set.

Acceptance criteria

Acceptance runs in three stages, and the same shape is used for the company and for each project. Automated gates run first, an AI pass scores what the gates could not decide, and a human makes any decision that is not clear-cut.

For a company, the gates are:

• didit_approved — business verification came back approved
• ofac_sdn — the entity and every beneficial owner against the OFAC SDN list
• un_eu_sanctions — UN and EU consolidated sanctions
• jurisdiction — the entity's jurisdiction against the excluded-country list
• ubo_completeness — ultimate beneficial owners identified to the required threshold

For a project, the gates are:

• company_standing — the sponsoring company is verified and in good standing (a hard fail)
• financial_terms — target raise, minimum investment, and projected return are present and coherent
• documents — the offering documents the exemption requires are on file
• timeline — open and close dates are present and in a sane order

The ruleset itself is data, not code: a versioned record holding the auto-approve threshold, the hard flags with their regulatory basis and routing action, the weighted soft flags, the excluded jurisdictions, and the scoring guidance. Publishing a new version supersedes the previous one, and every review records the version it was judged under — an examiner asking why a 2026 decision was made gets the rules as they stood that day, not as they stand now.

A hard flag is not a score input. An OFAC match, a sanctioned jurisdiction, a failed business verification, or missing beneficial ownership routes to immediate rejection or counsel review regardless of how favourable everything else looks. Soft flags — entity age, complex ownership structures, unusual terms — carry weights that accumulate into the risk score.

A project that clears review is approved, and an approved project is active once published. Only an active project can be tokenized.

3. Choosing the offering's structure

An approved asset still has one question outstanding, and it is the one that decides what everything downstream means: what does the holder of this token legally own? The answer settles who receives the K-1, whether the holder is a partner, whether §7704 transfer limits have to be enforced, and what happens when someone redeems. It is chosen once per offering — never per tranche, never per investor — and frozen before a mint exists.

The two models

There are exactly two coherent answers, and they are mutually exclusive:

For a direct_member offering the §7704(b) private-transfer safe harbour is recorded as parameters rather than code: a window in days and a cap in basis points on interests transferred within it, defaulting to the statutory 2% over 365 days. Counsel may set an offering tighter, never looser. A spv_wrapper offering must carry no limits at all — the hook zeroes that branch, so storing limits there would be a claim about enforcement with nothing behind it.

One model, every other field

A single model choice implies partner of record, token legal character, K-1 recipient, whether the holder is a partner, the redemption event type, where it is taxable, and whether partner eligibility is enforced. Those fields are still materialised into the stored document rather than re-derived at each call site, so the hook provisioner, the ATS feed, and the tax pipeline read one authoritative record instead of three interpretations of an enum.

The cost of materialising is that a hand-edited document could disagree with its own model, so every save validates the whole object: derived fields against the model, the §7704 limits against the model, the tax form against the model, the vocabularies (accounting cycle, valuation method, funding source), and the redemption timing. The offering form asks only for what a model leaves open and fills the rest in, so no submission can produce a hybrid in the first place — the validation exists for documents that arrive from anywhere else.

Counsel approval, and what it freezes

The structure is editable in the portal right up to sign-off, and never after. Approval is a site-admin action on the offering, recorded with who approved it and when, and it re-validates the structure at the one moment it is still possible to fix. From that point:

• The structure cannot be changed — the model refuses the update.
• The approval cannot be withdrawn or re-stamped by someone else.
• The portal renders the structure as a locked summary that submits nothing.
• Tokenization is unblocked; without it the mint is refused.

Irrevocability is the point. Investors from here on subscribe to the legal shape the structure describes — partner or not, K-1 or 1099, partner exit or SPV buyback — and an offering whose legal shape can be revised after subscription has told its investors something that stopped being true.

Redemption terms

The structure also carries the terms that make redemption a scheduled event rather than a request: a notice period in days, an accounting cycle (monthly, quarterly, annual), and a first redemption date. The recurrence itself is not stored — the next date is the first date stepped by the cycle, and a stored list of dates would be a second answer that silently stops being right the year nobody extends it. The notice deadline for a given date is that date minus the notice period.

Two more fields name sources rather than figures. valuation_method — appraisal, third_party_mark, cap_rate, cost_basis — says where the strike price comes from. funding_source — reserve, in_kind, gated — says who pays, where gated means the offering may defer or refuse when neither is available, a term that has to be disclosed up front rather than discovered at the window.

4. Creating the token

Tokenization is a single queued job with an unusual property: most of what it does cannot be undone or amended later, because Token-2022 fixes a mint's extensions at account creation. There is no migration back, so the preconditions are checked before anything is sent.

The mint

The mint is created as a Token-2022 mint carrying five extensions, all initialised before the mint itself, because Token-2022 rejects extension initialisation on an already-initialised mint:

The account is allocated for the fixed extensions and funded for the size the variable-length metadata will grow it to, since the metadata write reallocates the account and would otherwise fail for rent.

Offering configuration

Pointing a mint at the hook program is not configuring it. The program needs two accounts per mint before a single transfer can succeed, and both are written immediately after the mint, in one transaction:

• Offering config — the trust anchor and acceptance policy: which attestation issuer and schema this offering trusts, which investor classes it accepts, the minimum verification level, the US-person rule, jurisdiction constraints, holding caps, seasoning windows, and a halt switch.
• Extra account metas — a declaration of which extra accounts every transfer must carry, so that any client can resolve them without knowing the program's internals. The counterparty's attestation address is declared in terms of accounts already present in the transfer, which is what makes it derivable by third parties.

The policy is derived from the offering itself. The verification floor comes from the exemption — a 506(c) offering demands documentary verification and a 506(b) one does not — and a Reg S tranche sets the US-person rule to exclude. Constraints the platform cannot substantiate are left permissive rather than invented: a rule written here is enforced on every transfer for the life of the token.

What a transfer checks

Token-2022 calls the hook on every transfer of a gated mint. The hook reads the counterparty's attestation and the offering's config, and returns an error — aborting the whole transfer atomically — unless all of the following hold:

1. The attestation's schema version is one this offering supports.
2. Its subject is the counterparty's own wallet.
3. It was issued under the credential and schema this offering pins. Shape is not trust: the owning program, credential, and schema are all verified.
4. Its investor class is one the offering accepts.
5. Its verification level meets the offering's floor.
6. Its jurisdiction and US-person status satisfy the offering's policy.
7. It has not expired and is not revoked — evaluated against the current time on every transfer, never cached.

Each failure returns a distinct error code. The hook writes nothing, emits no event, and makes no cross-program call: it is read-and-validate only, which is what keeps it free of reentrancy surface and cheap enough to run on every transfer.

Issuing to investors

Because every token account is created frozen, holding requires a deliberate act by the platform as freeze authority. That act is gated on the same eligibility as everything else: an account is opened only for a wallet carrying a current attestation, for an offering whose verification floor that investor's accreditation clears. A backstop that opened every account would not be a backstop.

Primary issuance therefore cannot outrun the attestation that authorises the wallet — there would be nothing to open the account on the strength of, and Token-2022 refuses to mint into a frozen account. Distributions follow the same shape in the settlement asset: pro-rata USDC against ownership at the record date, with the recipient's token account created if this is the first time they have held it.

A periodic reconciliation job compares the sum of the off-chain ledger against the on-chain supply for every live token and alerts on any mismatch. The cap table is the platform's source of truth for ownership; the chain is the enforcement layer. They are expected to agree, and the system checks rather than assumes.

Redemption and settlement

Redemption runs the issuance pipeline backwards, with one deliberate asymmetry: the token leg is on-chain and the value leg is not. A redemption recorded against the cap table burns the holder's tokens on Solana and decrements the recorded supply; the money moves off the rail, via the ATS or paying agent.

That asymmetry is a privacy decision, not a convenience. Pairing an on-chain USDC payout with the burn would let anyone divide payout by tokens burned and recover per-token NAV every cycle — a continuous, permissionless price oracle for an illiquid asset whose valuation is supposed to be disclosed to eligible investors on a schedule the issuer controls. What leaks from a burn is the quantity and the fact of redemption, not the value. A redemption reference tying the burn to its off-chain settlement is an opaque id, never an amount.

Settlement lag is affordable precisely because redemption is gated to a notice period plus an accounting cycle: the wire lands inside a window investors were already told about. Off-chain settlement is also where reporting already lives — value and holder identity sit in the ATS layer, so an on-chain payout would force that layer to reconstruct settlement facts from chain data and reconcile them, without relieving a single off-chain obligation.

Notice, and the window it settles in

A holder gives notice to redeem. The platform computes the date that notice settles — the first redemption date far enough out that the whole notice period still fits before it — and stores it on the notice rather than deriving it later. A holder was told a date; that is a fact about the notice, not a function of the offering's current configuration.

Notice given exactly on a date's deadline makes that date. A day later moves it a full cycle, which for a quarterly offering is three months, so the boundary is the part worth being exact about.

Nothing is on chain while the clock runs. When the date arrives, a daily sweep writes a redemption marker for that wallet — a small account seeded on the mint and the wallet, carrying the quantity the notice authorised and the date it settles. Token-2022 calls the hook identically for every transfer, so without the marker the hook cannot tell a redemption leg from an ordinary transfer, and the two have different rules: an ordinary transfer checks the recipient against the roster, while a redemption moves tokens to the issuer on a date and the recipient is not an eligible holder at all.

A notice can be withdrawn while the clock runs and not after. Once the marker exists the hook holds a standing authorisation, and a cancelled record would say the notice is gone while the chain still says it is not.

The burn, and what ties it to the money

With the window open and the marker standing, the tokens are burned. A burn instruction has no room for anything but a discriminator and an amount, so the reference that ties this burn to the payment discharging it rides alongside it in the same transaction as a memo: ioniqx:rdm:<32 hex>.

The reference is random, and that is the point. Anything derived from the amount, the holder or the offering would let an observer work backwards from a public memo to facts this system keeps off the chain. It means nothing to anyone without the platform's records — which is exactly what a join key between a public ledger and a private one should be.

Two records are written before the transaction is sent, because a burn cannot be undone. The reference is persisted first, so a retry after a lost response reuses it rather than minting a second id for one obligation. Then a start marker, so a later run that finds a start with no finish knows a burn may already be on chain and refuses to send another. The ledger entry and the marker cleanup come after: both are recoverable, and the burn is not.

Settlement, and burned-but-unpaid

The two legs of a redemption cannot be made atomic. The burn commits on Solana, the money moves on a banking rail, and nothing spans both. The gap between them is a real state with a name — burned-but-unpaid — in which the holder has neither the tokens nor the cash. It is recorded as an obligation rather than left as an implication.

Only two of those discharge the obligation, and they discharge it in different currencies. settled means the holder got the money. reinstated means they could not be paid at all and got their position back instead — which is what never strand the holder has to mean when money cannot move. A failed payment returns to settling on another attempt; the failure reason is kept, because the remedy depends on it. Wrong routing details get another try; a closed estate does not.

A daily sweep reports every redemption that has burned and not been paid, because nothing on chain or off it notices on its own and the holder should not be the one who tells you. It resolves nothing: paying and reinstating are both decisions with a person behind them.

The strike itself is entered, not computed. valuation_method on the offering structure names where a NAV comes from; producing the figure is the issuer's job, and it is recorded against the redemption because that is the number the holder was paid on. Withholding is recorded the same way and for the same reason — a foreign partner in a direct_member offering carries a §1446 obligation, and the rate is counsel's to decide rather than this platform's to infer.

Verifying the pipeline end to end

The whole sequence is exercised against a real cluster by a single task, bin/rake devnet:e2e. What makes it worth having is what it refuses to do: it runs the production jobs inline — tokenize, attest, thaw, mint, transfer — rather than reimplementing the chain calls, so a passing run says something about the pipeline an investor goes through rather than about a parallel implementation of it.

• It creates a demo company and offering, and spends devnet SOL.
• It asserts on every step, and stops where a failure happened.
• It ends with a transfer the hook must refuse — a gate that never fires is indistinguishable from a gate that is not there.
• It refuses to run against mainnet, and refuses to run at all without real authority and attester keys — a pass against a simulated mint proves nothing, so the provisioner declines rather than letting it look green.

Investor wallets in a run are keypairs generated in memory. The address is persisted on the InvestorWallet row exactly as a real one would be; the private key is never written anywhere, which is why a run does its transfers inside the same process that created the wallets. The same provisioner backs demo companies, so a demo asset is a real devnet mint rather than a fabricated address.

What lives on-chain, and what does not

Last updated November 10, 2026 · Questions: admin@ioniqx.io