Only this pageAll pages
Powered by GitBook
1 of 54

TownSquare: RWA origination & curation, powering private credits

Introduction

Loading...

Private Credits - the "holy grail" of RWA

Loading...

Loading...

Loading...

Loading...

townRWA Private Credits

Loading...

Loading...

Loading...

Technicals & Mechanisms

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Third party dashboards

Loading...

Institutional Strategy Credit Vault

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

veTOWN governance

Loading...

Loading...

Roadmap

Loading...

Security

Loading...

Resources

Loading...

Loading...

Originating Private Corporate Asset Credits

TownSquare originates private credit against corporate assets: a data center and its leases, a battery storage site, a mine, a vault of gold, a producing energy field.

This page covers three things. Why originating this kind of credit is harder to copy than issuing a tokenized money market fund. How an asset is audited before it is tokenized. And how publicly rated credits differ from private corporate credits, including why many of the latter will never carry a public rating.

Why corporate credit has a moat and a money market fund does not

A money market fund is defined by what it is allowed to hold. A US government fund must keep at least 99.5% of its assets in cash, government securities and repurchase agreements backed by them (17 CFR 270.2a-7), with an average maturity of 60 days or less (ICI). Every issuer buys the same instruments, in the same market, under the same rule.

The product has almost no room to differ. In the third quarter of 2026 tokenized money market funds yielded between 3.22% and 3.59% (Rock'n'Block, citing Dune). Issuers compete on fees, brand and distribution, and those advantages belong to whoever is already largest. Nothing in the portfolio is proprietary, so a new entrant can reproduce it in a day.

Corporate private credit reverses each of those conditions.

  • The asset has to be found. No market offers a loan against a particular data center or mine for sale. The loan exists only after someone has built a relationship with the company, understood the asset and agreed terms. Deal flow arrives one company at a time.

  • The information is private. Underwriting rests on contracts, site reports and financial records that the borrower shares in confidence. A competitor cannot read them, so it cannot price the same loan.

  • Judgment is specific to the sector. Valuing contracted lease income from a data center, the reserves of a mine and bullion in a vault are three different crafts. Each takes time to learn, and none of it carries over from buying Treasury bills.

  • The work compounds. Every audited asset adds to the data, benchmarks and relationships used on the next one. Borrowers return to the originator that closed their last deal, and liquidity providers follow a record of loans that performed.

These barriers are also costs. Corporate credit is slower to originate, cannot be scaled by buying more of the same thing, and carries real default risk. That is the trade. A money market fund is easy to launch and easy to copy. A corporate origination pipeline is hard to build and hard to displace.

No corporate asset is tokenized until it has passed our audit. The audit answers three questions in order, and each answer limits the next.

  1. Valuation: what is the asset worth? The starting point is evidence, not the borrower's own figure. That means proof that the asset exists and who owns it, any claims already secured against it, the contracts that produce its income, and independent appraisals or comparable sales where they exist. The valuation is set on what can be verified.

  2. Loanable amount: how much can be lent against it? Never the full value. The loanable amount is the valuation less a margin for how far that value could fall and how long the asset would take to sell if the borrower defaulted. A vault of gold and a half-built energy site support very different proportions.

  3. Issuance cap: how much credit may ever be issued? The cap is a hard ceiling on tokenized credit against the asset. It keeps the amount outstanding inside what the audit supports, however much demand there is for the token.

Only when all three are fixed does the asset move to tokenization and on to our collateralization partners. The audit process is proprietary, and its findings are specific to each asset. What every case shares is the order: verify, value, size, cap, and only then issue.

The two kinds of credit differ less in quality than in who does the assessing and who gets to see it. A publicly rated credit carries an agency's opinion, published for any investor to read. A private corporate credit is assessed by the lender that originates it, and S&P Global describes private credit markets as largely unrated ().

  • Who it is built for. A publicly rated bond is sold to many investors who never meet the borrower, and the rating lets them buy and trade it without doing their own diligence. A private corporate credit is arranged directly with the company and usually held to maturity by a small group of lenders.

  • Who assesses it, and who pays. For a rated credit, an agency applies its published criteria, and the issuer pays for the rating and for keeping it current. That is economical for a large bond issue. For a private credit, the originator does the underwriting itself, one deal at a time.

  • What the borrower discloses. A public rating keeps a company's finances and contracts in front of the market. In a private credit that information goes to the lender in confidence, which is a main reason companies choose it.

These differences are why many corporate asset credits will never receive a public rating. The loan is too small or too specific to justify the cost, the company does not want the disclosure, no public market needs the grade, or the asset is too new for agency criteria. None of those is a verdict on quality.

Some credits sit in between. Agencies also issue private letter ratings, whose disclosure is limited by contract to a named group of investors (), and confidential credit estimates on unrated borrowers (). Neither is public, and neither is available for every asset.

Unrated therefore means not assessed in public. It does not mean not assessed. The work an agency does for a public bond still has to be done by someone, and for the assets we originate the audit does it.

The audit is not a rating from a regulated agency, and it is not a guarantee. It reduces the risk of lending against an asset that was misdescribed or overvalued. It does not remove the risk that a borrower defaults, or that an asset loses value after the loan is made. TownSquare originates and audits. It does not manage assets on anyone's behalf.

  • : definition of a government money market fund.

  • : maturity limit.

  • (29 October 2026): tokenized money market fund yields, from Dune.

  • and : unrated private credit and credit estimates.

From Stocks, Money Market Funds, to Private Credits

The order in which assets arrive onchain is not random, and it repays a close reading.

Stablecoins came first and became the money. Then, within about two years, two very different real-world assets followed: shares in public companies and shares in money market funds. One brought millions of small holders. The other brought the largest asset managers in the world.

Belowthose two steps, asks what each one actually changed, and follows the pattern to where it points next.

Tokenized stocks began in mid-2025 as a crypto-native experiment. Backed's xStocks, Robinhood's stock tokens for European users and Ondo Global Markets launched within months of each other, and at the end of that June the whole category was worth about $2 million ().

Seventeen months later it is a $3.9 billion market and the most widely held real-world asset onchain. RWA.xyz counted $3.89 billion across 4.61 million holders on 5 November 2026, with $23.9 billion changing hands in a month ().

The crypto-native issuers still lead, but in 2026 the core of the US market moved in beside them. In March the SEC approved Nasdaq's plan to let Russell 1000 stocks and major index ETFs trade as tokens on its main order book. In June ICE, the parent of the NYSE, formed a joint venture with OKX covering more than 60 US-listed stocks. DTCC's tokenization service went live on 28 October. Securitize listed on the NYSE and tokenized its own shares, now the largest single stock token at $208.6 million. Galaxy and Forward Industries issued SEC-registered shares directly on Solana through Superstate.

What can be assessed. Agencies rate from long default histories and standard templates, which suits established issuers and asset classes. Newer assets such as AI compute, robotics fleets and grid-scale storage have short histories, and a single mine or vault does not fit a corporate template. Private underwriting can take each asset on its own evidence.

  • What the result looks like. A rating is a letter grade on a public scale, comparable across thousands of issuers. A private assessment is a set of terms specific to one deal. In our case those terms are a valuation, a loanable amount and an issuance cap.

  • NAIC Capital Markets Bureau, private credit and private letter ratings: how private letter ratings are disclosed.

    How an asset is audited

    Publicly rated credits vs private corporate credits

    What the audit is not

    Sources

    S&P Global
    NAIC
    S&P Global
    17 CFR 270.2a-7
    Investment Company Institute, summary of money market fund regulatory requirements
    Rock'n'Block, "Private Credit RWA Explained"
    S&P Global, "Private lending: time to adjust the sails"
    "Private debt"
    What stocks proved is distribution. A saver in Jakarta or Lagos can now hold a fraction of a US share in a wallet, trade it at any hour and pledge it as collateral. The three largest issuers do not serve US users at all; the demand is from people the traditional brokerage system served poorly.

    What stocks did not prove is that the chain makes the asset itself better. The New York market already settles in a day, costs almost nothing to trade and is open to anyone with a brokerage account. Most stock tokens are wrappers that carry no vote, and 16 US companies, Goldman Sachs and Microsoft among them, have objected to third parties tokenizing their shares. Tokenization gave equities longer hours and a wider audience. It did not fix anything that was broken.

    The second step came from the opposite direction. Franklin Templeton had already put a US-registered money market fund onchain, but the category took off once BlackRock entered in 2024. By 16 October 2026 RWA.xyz tracked $14.68 billion of tokenized Treasuries and money market funds across 86,753 holders (Pixel Web Solutions).

    Stocks were built by crypto firms and adopted by Wall Street afterwards. Here Wall Street issued the product itself.

    The names are the point. BlackRock launched BUIDL in March 2024. J.P. Morgan followed with MONY in December 2025 and a registered fund, JLTXX, in May 2026; seeded with $100 million, it held $738 million five months later. These are not pilots run from an innovation lab. They are share classes of real funds, sold to real clients.

    The use case that carried them is collateral. A trader who posts stablecoins as margin earns nothing; one who posts fund tokens earns the Treasury yield and keeps the margin. Binance, Bybit and OKX now accept tokenized fund shares this way, CFTC staff confirmed in December 2025 that tokenized money market funds can serve as derivatives collateral, and the GENIUS Act lets stablecoin issuers hold registered government money market funds in tokenized form as reserves.

    Money market funds gave onchain finance its cash layer. They also show the ceiling of wrapping a liquid asset. The category yields the risk-free rate, 3.36% on average in October, and nothing more. It shrinks when rates fall or a few large holders leave: BUIDL has 106 holders and lost 17.6% of its value in 30 days. Treasury bills were already the most liquid instrument on earth. Once capital has a safe place to sit onchain, the next question is what it can buy.

    Set side by side, the two steps did the same thing. Each took an asset that was already liquid, standardized and cheap to reach, and gave it a new wrapper. Stocks gained longer hours and a wider audience. Fund shares gained the ability to move as collateral. Both gains are real, and in neither case did the underlying asset get any better.

    The steps also point in a direction. Stocks offered access. Money market funds offered a safe yield. Each asked the ledger to do a little more than the last, and each drew a more serious class of institution.

    Follow that line one step further and it does not land on another liquid asset in a new wrapper. It lands on the one large market where the wrapper is the smaller part of the benefit: private credit. Counting loans still held on issuers' own platforms, it is already the largest pool of real-world assets onchain, and it has the highest share of its underlying market tokenized.

    This is the sense in which private credit is the holy grail of onchain real-world assets. Stocks and funds were the approach. Private credit is what they were approaching.

    Private credit is the natural next step because it joins the yield that onchain capital now wants with the inefficiencies a ledger can remove. Five things point the same way.

    The pull is yield. In Treasuries the market sets the result and every holder gets the same one. Tokenized money market funds paid 3.22% to 3.59% in the third quarter; tokenized credit paid 3.32% to 13.84% (Rock'n'Block, citing Dune). With more than $300 billion of stablecoins outstanding and a cash layer that pays the risk-free rate at best, the capital already onchain is looking for a spread. Credit is the asset class built to pay one.

    The fit is friction. Stocks and Treasury bills were standardized and liquid before anyone tokenized them. Private loans are the reverse. Money is locked until maturity, funds often ask for $5 million to $10 million to enter, and positions are revalued once a quarter by model. A token attacks each of these: transfers between approved wallets settle in minutes, positions split into small units, interest is paid by program to whoever holds the token, and ownership is visible in real time.

    The new property is collateral. A share in a private credit fund has never been something you could borrow against on a Tuesday afternoon. Onchain it is. Of the $2.11 billion of tokenized assets pledged in lending protocols at the end of August, 76% was credit, against $68 million of money market funds. About a fifth of all tokenized credit is already working as collateral. The asset decentralized finance actually uses is not tokenized cash. It is tokenized credit.

    The room to grow is nearly all of it. Global private credit is a market of roughly $2 trillion, and about 0.4% of it is tokenized. That share is already higher than for money market funds (about 0.2% of the $7.98 trillion in US funds) or equities (0.002% of a $157.8 trillion global market). The category where tokenization changes the product is the one where it has penetrated furthest, and it has barely started.

    The difficulty is the moat. A tokenized stock or Treasury fund starts from an asset anyone can buy. The issuer purchases the share or the bill in a public market, places it with a custodian and mints a token against it. A competitor can do the same the next morning, which is why the same share is now issued as a token by several rival platforms. Private credit cannot be bought off a screen. Every loan has to be sourced, company by company and asset by asset, then diligenced, valued and structured before there is anything to tokenize. The assets are illiquid, and most are unknown outside a small circle of lenders. This makes private credit harder to reach by design, and that is a large part of why it is the grail. Wrapping equities is a product anyone can launch. An origination pipeline is slow, relationship-heavy work that does not copy, and whoever builds one holds something a wrapper never gives its issuer: a moat.

    Seen this way the sequence is not a list of unrelated products. It is the order in which any financial system is built: first money, then a safe asset to hold it in, then lending. Stablecoins were the money. Money market funds became the safe asset. Stocks brought the audience. Credit is what all of it was for.

    Onchain credit holds $8.17 billion in tokens that can move between wallets and a further $37.88 billion recorded on issuers' own platforms, per RWA.xyz on 16 October 2026 (Rock'n'Block).

    The names are serious ones. Apollo's ACRED, issued through Securitize, is a feeder into its diversified credit fund and passed $100 million in 2025 (Markets Media). Hamilton Lane tokenized its senior credit fund the same way. Janus Henderson's AAA CLO fund runs on Centrifuge and held $909.7 million at the end of August. Coinbase Asset Management launched a credit fund with a tokenized share class on Superstate in July. Figure has $23.9 billion of home equity lines recorded on its own chain.

    Look at what these products hold, though, and what they pay.

    The first generation repeated the pattern of the first two steps. It took the part of credit that was easiest to tokenize: feeder funds into vehicles that already existed and AAA tranches that already carry a public rating. It reused the rails built for the cash layer, with Securitize, Centrifuge and Superstate each carrying a credit product beside a Treasury one. And it produced yields close to a Treasury bill, because the assets are close to one.

    That was the right place to start, and it proved that institutions will hold credit onchain. But it is distribution of credit that someone else had already originated and packaged. The core of private credit is something different: loans against real assets that carry no public rating, found and underwritten one at a time. Very little of that is onchain. Where it is, as with Figure's loans, it mostly cannot leave the platform it was written on.

    The missing piece is not another wrapper. It is origination.

    • Pintu Academy, "5 Reasons Tokenized Stocks Will Become Key Assets in Crypto" (updated 10 November 2026): tokenized stock value, issuers and US market-structure milestones, from RWA.xyz data of 5 November 2026.

    • Pixel Web Solutions, "Tokenized Money Market Funds in 2026" (24 October 2026): fund-by-fund values from the RWA.xyz Treasury table of 16 October 2026.

    • Rock'n'Block, "Private Credit RWA Explained" (29 October 2026): onchain credit size, yields, platforms and risks, from RWA.xyz, Dune, Allium, Keyrock and LlamaRisk.

    • Investment Company Institute, Money Market Fund Assets (12 November 2026): US money market fund assets of $7.98 trillion.

    • (19 August 2026): global equity market capitalization of $157.8 trillion in 2025.

    • : ACRED assets.

    First, stocks

    CoinGecko
    Pintu Academy

    Then, money market funds

    What the two steps have in common

    Why private credit

    The first generation of onchain credit

    Sources

    SIFMA, 2026 Capital Markets Fact Book key findings
    Markets Media, "Apollo Tokenized Private Credit Fund Reaches $100m"

    Third Party RWA Dashboards

    TownSquare's onchain activity is tracked by independent data platforms. Their dashboards let anyone check townRWA supply, holders and activity without relying on TownSquare's own reporting.

    Token Terminal

    Token Terminal is an onchain data platform that standardizes financial and operating data for blockchains and decentralized applications, so that projects can be compared on consistent metrics. It reads data directly from the chains it covers.

    TownSquare is listed under real-world asset (RWA) issuers. Its page tracks standardized onchain data across the chains TownSquare is deployed on, updated daily, with overview, metrics and financial statement views.

    • TownSquare on Token Terminal Project RWA issuer All networks

    RWA.xyz

    RWA.xyz is an analytics platform for tokenized real-world assets. It aggregates and standardizes data across blockchains, token standards and asset classes, and works directly with issuers, networks and protocols on the accuracy of what it lists.

    The platform page covers TownSquare as a whole: distributed asset value, holders, transfer volume and active addresses, broken down by network. Each asset page covers one townRWA token.

    • Platform All tokens All networks

    • Asset townREIT Real estate

    Figures on these dashboards are calculated by each provider under its own methodology and may differ from each other and from TownSquare's records.

    Asset townAIROBO AI robotics
  • Asset townBATT Energy storage

  • TownSquare platform on RWA.xyz
    townREIT on RWA.xyz
    townAIROBO on RWA.xyz
    townBATT on RWA.xyz

    Reference

    TownSquare Yield Reference

    Overview

    Operations

    The "Holy Grail" of RWA

    The next step: an onchain Apollo

    In traditional finance the firms that lead private credit are not known for distribution. Apollo built its position on origination: finding the borrower, auditing the asset, setting the terms. Everything downstream of that, the funds, the feeders and now the tokens, is packaging. The onchain market built the packaging first.

    At TownSquare we are building the part that comes before it. We call it an onchain Apollo: a decentralized protocol that originates and curates real-world private credit. We do not work with Treasury bills or money market funds, which anyone can already reach through public markets. We work with the credit that has traditionally sat behind private equity firms and stayed closed to almost everyone else.

    The stack has three layers.

    1. Origination and audit. Private credit carries no public grade, so every asset goes through our proprietary audit before anything is tokenized. The audit sets its valuation, the amount that can be lent against it and the cap on issuance.

    2. Collateralization. Curation happens through collateralized borrowing and lending, in the form of onchain private credit, on partner platforms such as Multipli. The same pipeline connects each asset to liquidity providers.

    3. Yield distribution. Yield from the credit reaches liquidity providers through our distribution protocol, either onchain or in an audited offchain environment.

    Our current focus is seven sectors: AI data centers, AI robotics, energy storage infrastructure for AI, real estate, mining, vaulted gold, and oil, gas and energy fields. Each is capital-hungry, tied to a physical asset and financed largely through private channels.

    One distinction matters. The protocol is not an asset manager and does not manage anyone's assets. It audits, originates and connects, and it leaves the lending itself to the collateralization platforms it plugs into. That is the difference between tokenizing a fund and building the pipeline that funds are made from.

    The prize is unclaimed because the hard parts of credit do not move onchain with the token. An honest case for private credit has to carry these with it.

    • A token changes the record, not the borrower. Default risk, collateral value and court recovery all stay in the real world. Moody's makes the same point: tokenized private credit carries the same credit risk as the traditional kind.

    • Liquidity is mostly a promise so far. About $3 billion of permissioned credit products showed little or no transfer between holders over 90 days, and only 7 of 22 credit products traded onchain at all.

    • Runs happen faster. In April 2026 more than $800 million left Maple's pools within 72 hours of a bridge exploit. Onchain private credit fell from $5.85 billion in March to $4.67 billion by the end of August.

    None of this weakens the case. It describes the work. Every item on that list is a failure of something that happens before or around the token: underwriting, valuation, structure, servicing. Those are origination problems, and a better wrapper does not solve them.

    They are also the problems our stack is organized around. An audit that fixes valuation, loanable amount and issuance cap before tokenization is aimed at the first. Collateralized structures on dedicated platforms are aimed at the losses and runs that follow weak security. An audited path for yield is aimed at the gap between what a token says and what a borrower pays. These are design choices, not guarantees. Credit can still default, and the test of any originator, onchain or off, is how its loans perform through a bad year.

    Each step onchain has moved toward assets where the ledger matters more. Tokenized stocks, at $3.9 billion, gave real-world assets an audience of millions. Tokenized money market funds, at $14.7 billion, gave them BlackRock, J.P. Morgan and Franklin Templeton, and a cash layer that works as collateral. Both were necessary. Neither was the destination, because neither asset needed fixing.

    Private credit does. It is a market of roughly $2 trillion that still runs on bilateral contracts, quarterly marks and multi-million-dollar minimums, and it pays the one thing that capital already onchain cannot get from a Treasury bill. Its first onchain generation, led by names like Apollo, Hamilton Lane and Janus Henderson, showed that the demand and the rails are real. It also showed what is still missing.

    The grail is not a tokenized share of someone else's credit fund. It is credit that is originated, audited and curated for the chain from the start, against data centers, energy, real estate and commodities. That work is done deal by deal, on assets no screen quotes, which is what makes it hard to reach and hard to copy. That is what we mean by an onchain Apollo, and it is what TownSquare is building. Stocks proved that people would come. Money market funds proved that institutions would come. Private credit, originated onchain, is what gives them a reason to stay.

    TownSquare - the "onchain Apollo" for AI and real economies

    TownSquare is building an "onchain Apollo" - a decentralized RWA origination and curation protocol, powering private credits. Different from the protocols and platforms focusing on T-bills, money market funds that are easily accessible via public markets, TownSquare originates and curates private credits that are traditionally more closed and accessible via private equity firms. At its core, the stack provides asset audit, origination, and an integration pipeline that directly connects with RWA collateralization platforms for LP sourcing. The protocol does not manage assets as an asset manager.

    Currently TownSquare primarliy focuses on assets in the following sectors:

    • AI data centers;

    • AI robotics;

    • (AI) energy storage infrastructure;

    • Real estate;

    • Mining;

    • Vaulted gold;

    • Oil, gas and energy fields.

    The stack solves longstanding accessibility issues in private credits via onchain RWA solutions:

    • RWA origination & audit: private credits that are non-publicly graded are passed via audits for valuation, loanable amounts, issuance cap, etc. via oour proprietary audit process, before tokenization.

    • RWA collateralization: the curation process is achieved done via a collateralized borrow/lend via RWA collateralization partners, in the form of onchain private credit, partnered with RWA collateralization platforms such as Multipli.

    • RWA yield distribution: RWA yield from private credit is distributed to LP via TownSquare's yield distribution protocol onchain or in an offchain audited environment.

    • Tokenized Private Assets, originated by TownSquare: assets from AI data centers, real estate, mining, renewable energy, gold vaults, tokenized onchain, via townMINE, townAIDC, townREIT, townGOLD etc.

    • Tokenized Credit Yield: Collateralized RWA and yield generated from LP lending, distributed to LP.

    • Institution-backed strategies and private yields: trading strategies, private credit yields, proprietary yield sources are made accessible to retail on chains including BNBChain, Base, Monad and other performant chains.

    • Battle-tested curated yield vaults

    : yield vaults on TownSquare can be customized for private credit lending-based, trading-based, and proprietary strategies, managed by institutional curators.

    Key functionalities

    The track record is short and mixed. Maple lost more than $50 million of lenders' money in 2022 before rebuilding around overcollateralized loans. Goldfinch voted to wind down in June 2026. One tokenized note returned -15.1% over the past year.
  • The premium has thinned. Large onchain credit products now yield 4% to 5%. On 31 August the 30-year Treasury paid 5.25%.

  • Why a grail and not yet a trophy

    Getting the grail

    Architecture

    Contract Relationships

                        ┌──────────────────────┐
       user ──deposit──▶│    townSqToken       │──safeTransferFrom──▶ Manager
       user ──request──▶│  (ERC4626, UUPS)     │                      (holds all assets)
       user ──withdraw─▶│                      │◀──transferToVault────┘
                        └──────────┬───────────┘
                                   │ reads manager.treasury()
                                   │ reads manager.yield()
                                   │ reads manager.maxRedeemCap()
                                   │ reads manager.minSharesInVaultToken()
                                   ▼
                        ┌──────────────────────┐
                        │      Manager         │──call()──▶ whitelisted DeFi protocols
                        │       (UUPS)         │
                        └──────────▲───────────┘
                                   │ manageAssetAndShares()
                        ┌──────────┴───────────┐
       rebalancer ─────▶│       Yield          │──transferInRewards()──▶ townSqToken
                        │       (UUPS)         │
                        └──────────────────────┘

    All three core contracts sit behind townSqProxy (ERC1967 + UUPS). All three contracts are UUPS-upgradeable behind ERC-1967 proxies. The addresses you interact with are the proxies, and they do not change when the implementation is upgraded.

    Who can do what

    Full enumeration in Roles and permissions.

    Actor
    Can
    Cannot

    You

    Deposit, request redemption, collect your own redemption

    Key townRWA Workflow

    townRWA turns a corporate asset into a credit token. TownSquare is the originator and issuer: it audits the credit and mints the tokens at origination. Downstream, aggregation layers may allow townRWA tokens to be minted into stable-pegged instruments for distribution in DeFi. Multipli, with rwaUSDi, is one example.

    1. Asset owners (borrowers). Companies that own the underlying assets, such as a data center, a mine or a gold vault, and borrow against them.

    2. TownSquare (originator and issuer, upstream). TownSquare sources the asset, audits it, sets its valuation, loanable amount and issuance cap, originates the credit and issues the townRWA tokens. We are the upstream partner to the aggregation layers below.

    3. Institutional subscribers. Institutional investors and professional investors outside the United States, on whitelisted KYC or KYB'ed addresses. They subscribe to a credit and receive its tokens at origination.

    4. Aggregation layers (downstream). Downstream partners that may allow townRWA tokens to be minted into a stable-pegged distribution instrument for DeFi. Multipli is one such partner, and its instrument is rwaUSDi. Each aggregation layer applies its own eligibility checks and risk parameters.

    • Origination and audit (TownSquare). Every asset is audited before issuance. The audit sets the terms that bound the credit.

    • Issuance at origination (TownSquare). All townRWA tokens for a credit are minted when the credit is originated and are distributed to its institutional subscribers. No townRWA is minted afterwards.

    • Transfer control (TownSquare). Tokens are priced onchain at $100 and move only between whitelisted addresses.

    • Yield distribution (TownSquare). Yield from the underlying credit is distributed to token holders onchain or in an audited offchain environment.

    Protection against default is underwritten by the asset itself. The underlying asset is assigned to the lender, which secures the future cash flows if the borrower defaults.

    This ties the protection to something the audit has already verified and valued. It does not remove risk: what is recovered in a default depends on the value of the asset at that time and on enforcing the assignment.

    1. Origination and audit. TownSquare sources the asset and audits it. The audit sets the valuation, loanable amount and issuance cap, and the asset is assigned to the lender as security.

    2. Subscription. Eligible institutional investors subscribe to the credit from whitelisted addresses.

    3. Issuance and distribution. At origination, all tokens for the credit are minted within the issuance cap and distributed to the subscribers.

    4. Holding and transfer. Holders keep the tokens or transfer them to other whitelisted addresses.

    Schemas

    Every TownSquare attestation follows a schema. This page explains what a schema is in the Ethereum Attestation Service (EAS), how TownSquare's townRWA schema is registered, and the principles behind its design.

    A schema is the fixed structure of an attestation's data: which fields it contains and what type each one is. Because every townRWA attestation uses the same schema, attestations about different assets, on different chains, are consistent, readable and can be checked the same way.

    The schema decides what TownSquare can attest to and how that information is laid out. It does not change from one attestation to the next.

    Schemas are registered in the EAS schema registry contract on each chain. Each registration creates a record with these fields:

    • UID. The unique identifier of the schema. It is derived from the schema definition, its resolver and whether it allows revocation, so the same definition registered on another chain has the same UID.

    Yield Vault

    Stratety-backed vault is a yield-bearing vault built on ERC4646. You deposit an underlying asset and receive townSquare shares. The yield is produced by a trading strategy operated offchain, and profit or loss is reported back to the vault periodically. Your shares gain (or lose) value as those reports land; the number of shares you hold does not change.

    Profit arrives gradually, not all at once. When a profit is reported, it is released into the share price linearly over the vesting period rather than instantly. This stops someone from depositing just before a report and capturing yield they were not exposed to. Practically: a reported profit raises your position's value smoothly over the following days.

    Standard ERC-4626. Approve the vault, then deposit.

    • There is no deposit fee. Entering the vault is free; the fee is charged only on exit.

    Contract Suite

    Each townRWA token is deployed as a TownToken contract on each network it is live on. Token is the contract address of the token. Implementation is the address of the contract that holds its logic.

    Anything else

    Operator

    Deploy capital to whitelisted addresses, fund the vault, settle a user's request

    Change the allowlist, report yield, change parameters

    Rebalancer

    Report each epoch's profit or loss

    Move any asset

    Admin (timelock, 48h)

    Set the allowlist, fees, cooldown, caps; pause and unpause; emergency-recover assets

    —

    Guardian

    Pause the vault, remove whitelist entries — instantly

    Unpause, add to the allowlist, change parameters

    Governance (root admin) (timelock, 48h)

    Upgrade all contracts, grant and revoke every role

    —

    The Admin role can both whitelist a destination and extract assets from the vault, and both go through a 48-hour timelock — delayed and public, but not prevented. Deposit sizing should account for this. See Governance and the timelock.

  • Aggregation (downstream partners). An aggregation layer may allow townRWA tokens to be minted into a stable-pegged instrument for use in DeFi, for example rwaUSDi on Multipli. This happens downstream of issuance and does not create new townRWA.

  • Yield. Yield is distributed on the token's own schedule: daily, weekly, quarterly or at maturity.

  • Aggregation (where available). A downstream aggregation layer, such as Multipli, may allow townRWA tokens to be minted into a stable-pegged instrument, such as rwaUSDi, which can then be distributed in DeFi.

  • Repayment. The borrower repays the credit on its terms, which is how the credit comes to an end.

  • Core components

    Default protection

    Lifecycle

    Schema number.
    A sequence number assigned by the registry on that chain. It is not a unique identifier.
  • Creator. The address that registered the schema.

  • Transaction. The transaction that registered it.

  • Resolver. An optional contract that can add rules when attestations are made with the schema.

  • Revocable. Whether attestations made with the schema can be revoked.

  • Schema. The field names and types, ABI-encoded.

  • Attestation count. How many attestations have been made with it.

    • Chain: Base

    • Schema number: #1985

    • UID: 0x7cc8b06611ab8b545b5e2c29e9f3bd0367b80cf0c309aca2fefa22b4e7983c01

    • Used by: townRWA attestations made by TownSquare's attesting address, 0xAb3965E78286dF2DFcA627E8CD249cFa9aEA7f36

    The full record, including the field definitions and the current attestation count, can be viewed on the EAS explorer at the link above.

    TownSquare designs its schemas to the same principles EAS recommends:

    • Simple. Only the fields needed to identify an asset and its attested evidence.

    • Descriptive. Each field has one clear purpose and a clear name.

    • No redundancy. Each piece of information is recorded once.

    • Extendable. New townRWA sectors and tokens can use the schema without breaking existing attestations.

    • Efficient. Field types are chosen to keep the cost of attesting low on every chain.

    EAS attestations can reference one another by UID. This lets townRWA records be built in layers instead of repeating the same details in every attestation.

    • Asset record. An attestation identifies the asset and the token issued against it.

    • Valuation record. An attestation records a valuation report and references the asset record's UID, without repeating the asset details.

    • Revaluation. A later valuation references the earlier one, so the history of an asset's valuations can be followed from one attestation to the next.

    A schema's name and description do not need to be written into the schema itself. In EAS they can be added as separate attestations that reference the schema's UID. That keeps the schema lean, and lets the name, description and examples of use be updated without changing the schema or the attestations made with it.

    EAS encourages schemas with wider use to be developed in the open. A common schema for attesting real-world asset evidence would let attestations from different issuers be read and compared in the same way. TownSquare's townRWA schema is a step in that direction.

    Schema

    What a schema is

    How a schema is registered

    The townRWA schema

    Design principles

    Composability

    Naming and describing a schema

    Toward a shared standard

    Monad

    0x805710d7A631C03C5cC246DA55985Fef0919Fa59

    0x04D416b26194ea5F23921a0B29DF67690A9044BF

    Network

    Token (TownToken)

    Implementation

    Base

    0xB2C1C97274B7FAA1aD544A17163FDC1C6a29EfCB

    0x9e3bb4dE2Fb2369e9B4197e6B669b01121749cA8

    Robinhood Chain

    0x8967227480445eb5F249c167d8f9aF4D1D5539F2

    0x63dE20d7588Fe50434f45dC47a71017a4588B2ec

    Network

    Token (TownToken)

    Implementation

    Base

    0xdADEbb81A35F62938c20232597cE351F62a32E5A

    0xCa0258eF62D768823bF50767DC9c837a898e6412

    Robinhood Chain

    0x210cc08eb503dfD1d35430cB71b74e635eBf640C

    0x1D483a555FBffc253033bf4b1a9d13653E90ea8A

    Only use addresses published on this page or in official TownSquare channels.

    Attestation (Base): 0xd395d1b7cdfba754437e07adb83a20a5d2c2d648dd8baa77dbfb4095ac9520d7

    Network

    Token (TownToken)

    Implementation

    Base

    0xd58d35857A202d041c3Cf943e07dB1e151bc4D58

    0xBcE58c5838406e00A12ccB5c59e6CF90F345A5a2

    Robinhood Chain

    0xf7B1A92916C84A95e18C309C04eEd807975D5863

    townREIT

    0x884B12aAf42a586932bba1ce5E1D475AF49EBCc7

    townBATT

    townAIROBO

    There is a minimum deposit size, expressed in shares (minSharesInVaultToken). Very small deposits revert.

  • Your assets do not stay in the vault. They are forwarded immediately to the Manager contract, which deploys them to the strategy. This matters for withdrawal — see below.

  • This is the part that differs from a normal vault. Withdrawal is a two-step process with a waiting period, and you cannot skip it.

    What happens the moment you call this:

    • Your shares are burned immediately.

    • The asset amount you will receive is calculated and locked in now, at the current share price, net of the exit fee.

    • A cooldown timer starts.

    Rules that will trip you up

    • Your amount is fixed at request time. Once you request, you are no longer exposed to the share price. If a profit is reported during your cooldown you do not receive it. If a loss is reported you are not affected. Requesting is an exit from the strategy, not a queued sale.

    • One request at a time. requestRedeem reverts if you already have a pending request. You cannot add to it, and there is no cancel function — once requested, you are committed to that amount.

    • You must call withdraw/redeem yourself. The vault requires the caller to be the owner of the request. Approving another address does not let it withdraw for you — this intentionally breaks the standard ERC-4626 allowance flow.

    • The amount must match exactly. redeem(shares) requires shares to equal your request's stored share count exactly; withdraw(assets) requires an exact asset match. Partial collection is not supported. Read your request and pass the stored value back.

    • There may be a cap on the size of a single request (maxRedeemCap). If your position exceeds it, exit across multiple requests, one after another.

    Fees

    You pay one fee as a depositor: the exit fee, charged when you request a redemption. It is capped at 1% and is deducted from the amount you are quoted.

    There is no deposit fee and no ongoing management fee.

    Depositing

    Withdrawing

    Step 1 — request

    Step 2 — collect, after the cooldown

    requestRedeem(uint256)

    Audits & Underwriting

    Every townRWA credit is audited and underwritten by TownSquare before any token is issued. This page holds the audit requirement list for each townRWA token.

    How the lists are used

    • One list per token. Each sector has its own audit requirements, because each kind of asset is verified and valued on different evidence.

    • What a list contains. The documents and evidence an asset owner must provide, and the checks TownSquare performs on them.

    • What the audit produces. Three terms for every asset: a valuation, a loanable amount and an issuance cap. No credit is originated until all three are set.

    • Who the lists are for. Asset owners preparing an application, and investors who want to see what stands behind a token.


    TownSquare AI Robotics Token. Covers credit to AI robotics companies.

    Audit requirement list:

    TownSquare AI Data Center Token. Covers credit to AI data centers and affiliated activities.

    Audit requirement list:

    TownSquare Energy Storage Infrastructure Token. Covers credit to energy and power infrastructure companies.

    Audit requirement list:

    TownSquare Mine Token. Covers credit to mines and mining corporations.

    Audit requirement list:

    TownSquare Real Estate Investment Token. Covers credit backed by real estate.

    Audit requirement list:

    TownSquare Gold. Covers credit backed by gold vaults.

    Audit requirement list:

    Due diligence lists for the other townRWA tokens will be released later.


    Underwriting turns the audit into the terms of a credit. The framework is the same for every sector. The specific terms are set per asset in its own documents.

    1. Authorization. The asset owner signs a letter of authority. It permits TownSquare to structure the transaction, to issue a townRWA token against the asset, to use the owner's reports and information for due diligence and disclosure, and to approach the valuer or report preparer. It does not commit either party to the transaction.

    2. Information and audit. The owner provides the items on the audit requirement list for its sector. Items are prioritized, and the most critical are reviewed first.

    3. Independent valuation. A third-party valuation report establishes the value of the asset. TownSquare takes a conservative collateral value from it.

    Each technical audit and underwriting report prepared by TownSquare addresses the items set out in this Schedule. The Schedule lists item names only. The content under each item is specific to the asset and is confidential. Items in Part 4 are adapted to the sector of the asset.

    PART 1. SCOPE AND BASIS OF ASSESSMENT

    1.1 Source Material

    1.2 Limitations

    1.3 Conventions: (a) Currency; (b) Measurement; (c) Interest Rates; (d) Market Yield Reference

    1.4 Mandate and Letter of Authority: (a) Scope of Authority; (b) Retention of Title; (c) Use of Information; (d) Third Parties; (e) Provision of Information; (f) Owner Confirmation; (g) Binding Effect; (h) Governing Law

    PART 2. THE ASSET

    2.1 Location

    2.2 Description and Authorised Use

    PART 3. TITLE AND LEGAL STANDING

    3.1 Tenure

    3.2 Ownership and Assembly

    3.3 Registered Encumbrances

    PART 4. INCOME AUDIT

    4.1 Occupancy Schedule

    4.2 Income Reconciliation

    4.3 Discrepancies between Schedule and Register

    4.4 Contract Expiry and Income Security

    4.5 Benchmarking

    PART 5. VALUATION REVIEW

    5.1 External Valuation: (a) Purpose and Reliance; (b) Currency of Valuation; (c) Inspection; (d) Independence; (e) Method Disclosure

    5.2 Implied Metrics

    5.3 Comparison Approach

    5.4 Income Approach

    5.5 Probabilistic Valuation

    5.6 Reconciliation: (a) Adopted Collateral Range; (b) Conservative Collateral Value

    PART 6. CAPITAL STRUCTURE

    6.1 Senior Debt

    6.2 Debt Service Cover

    PART 7. ISSUANCE STRUCTURE AND TERMS

    7.1 Borrower

    7.2 Collateral and Security Package

    7.3 Additional Security: (a) Assignment of Income; (b) Guarantee

    7.4 Token Terms: (a) Issuer; (b) Backing; (c) Unit and Pricing; (d) Maximum Issuance; (e) Minting; (f) Transfer Restriction; (g) Redemption

    7.5 Issuance Caps and Minimum Cover

    7.6 Yield

    7.7 Re-attestation

    7.8 Reconciliation with Indicative Terms

    PART 8. YIELD CAPACITY

    8.1 Capacity of the Asset to Fund Yield

    8.2 Yield Position

    PART 9. TOKENISATION STRUCTURE AND REGULATION

    9.1 Structural Options

    9.2 Regulatory Position

    PART 10. RISK DISCLOSURE

    10.1 Valuation Risk

    10.2 Income Risk

    10.3 Capital Structure and Credit Risk

    10.4 Legal and Title Risk

    10.5 Liquidity and Enforcement Risk

    10.6 Structural and Regulatory Risk

    PART 11. CONDITIONS PRECEDENT AND MONITORING

    11.1 Conditions Precedent

    11.2 Ongoing Covenants: (a) Senior Debt Ceiling; (b) Income Reporting; (c) Revaluation; (d) Issuance Freeze; (e) Interest Rate Trigger; (f) Disclosure

    What are townRWA Private Credits

    townRWA private credits are yield-bearing credit tokens issued through TownSquare. Each token represents private credit facilities in one sector of the real economy.

    TownSquare currently offers real economy RWA private credit facilities* primarly focused on AI data centers and AI robotics, plus high-value assets from real estate, mining, vaulted gold, oil fields, gas fields etc.:

    • townAIROBO (TownSquare AI Robotics Token): yield-bearing credit token from AI robotics companies, variable yield.

    • townAIDC (TownSquare AI Data Center Token): yield-bearing credit token from from AI data centers and affiliated activities, variable yield.

    • townBATT (TownSquare Energy Storage Infrastructure Token): yield-bearing credit token from from energy and power infrastructure companies, variable yield.

    • townMINE (TownSquare Mine Token): yield-bearing credit token from mines and mining corporations, variable yield.

    • townREIT (TownSquare Real Estate Investment Token): yield-bearing credit token from real estate, variable yield.

    • townGOLD (TownSquare Gold): yield-bearing credit token from gold vaults, variable yield.

    • townOIL (TownSquare Gas): yield-bearing credit token from oil and gas fields, variable yield.

    • Yield-bearing. Each token passes on yield from the credit facilities behind it.

    • Variable yield. The rate is not fixed. It follows what the underlying credits pay.

    • One sector per token. A token holds credit from its own sector only.

    • Audited before issuance. Every asset goes through TownSquare's audit, which sets its valuation, loanable amount and issuance cap, before any token is issued against it.

    One representative asset per token, and the path it takes to become an onchain credit.

    • Asset: an AI data center with offtake agreements with big-tech corporations for its compute capacity.

    • Origination: the operator applies for credit against the facility. The audit reviews the offtake agreements and the counterparties behind them, the power supply, and the hardware. Valuation rests on the contracted income. Once the loanable amount and issuance cap are set, the credit is tokenized and launched as townAIDC, and offtake payments fund the yield.

    • Asset: an AI robotics company with a deployed robot fleet under robots-as-a-service contracts with manufacturers and logistics operators.

    • Origination: the company applies for credit against the fleet and its contracts. The audit reviews the service contracts, fleet utilization and hardware depreciation. Valuation rests on contracted service revenue and the resale value of the robots. The credit is then tokenized and launched as townAIROBO, and service fees fund the yield.

    • Asset: a grid-scale battery storage or electricity generation site with a long-term capacity contract with a utility or a data center operator.

    • Origination: the developer applies for credit against the site. The audit reviews the grid connection, the capacity contract, and battery degradation and warranties. Valuation rests on contracted capacity revenue. The credit is then tokenized and launched as townBATT, and capacity payments fund the yield.

    • Asset: a producing mine with a certified reserve report and an offtake agreement with a metals trader.

    • Origination: the mining company applies for credit against the mine. The audit reviews the reserve report, permits and licences, and the offtake agreement. Valuation rests on reserves and contracted sales at conservative commodity prices. The credit is then tokenized and launched as townMINE, and offtake proceeds fund the yield.

    • Asset: a commercial property, such as a logistics warehouse, fully let to corporate tenants on long leases.

    • Origination: the owner applies for credit against the property. The audit reviews the independent appraisal, the leases and tenants, and the title and any existing liens. Valuation rests on the appraisal and rental income. The credit is then tokenized and launched as townREIT, and rent funds the yield.

    • Asset: allocated gold bars of recognized refinery standard, held in an insured and independently audited vault.

    • Origination: the bullion owner applies for credit against the bars. The audit verifies bar count, weight and purity, and the custody and insurance arrangements. Valuation follows the gold price. The credit is then tokenized and launched as townGOLD, and interest paid by the borrower funds the yield.

    • Asset: a producing oil and gas field with independently certified proved reserves and sales contracts for its output.

    • Origination: the field operator applies for credit against the field. The audit reviews the reserve certification, the production record and decline rate, and operating permits. Valuation rests on proved producing reserves at conservative prices. The credit is then tokenized and launched as townOIL, and production revenue funds the yield.

    • Audit reports and attestation are available for each asset. Each audit is prepared by an experienced audit firm and attested by an onchain risk assessor, on a quarterly basis.

    • Onchain attestation: each townRWA token is attested on TownSquare's .

    *Investor eligibility: KYC/KYB investors from outside the Republic of Korea and the United States of American are eligible to invest upon approval.

    Indexing

    Running your own indexer

    If you would rather index the vault contracts yourself, this section covers what to listen for and the traps worth knowing about before you start.

    What you need

    Three things per vault:

    1. The chain and the vault contract address.

    2. The block the vault was deployed at. Get this from the block explorer rather than guessing. Starting a few million blocks early only costs you a longer backfill, but starting even one block late means you miss requests and can never settle them correctly.

    3. The vault ABI. Ask us for it, or pull the verified ABI from the explorer.

    Events to index

    Event
    What it means

    RedemptionRequested and Withdraw are the two you cannot skip. The rest are optional depending on what you are building.

    When CooldownPeriodUpdated fires, the new period applies to requests that are already open, not just to new ones. A request created last week can become claimable earlier or later than the date you first calculated.

    On that event, recompute claimableAt for every open request in that vault as requestedAt + newPeriod. If you store a claimable date and never revisit it, your queue will drift away from what the contract actually allows.

    When an operator settles on a user's behalf, the contract emits Withdraw first and WithdrawalExecuted second. By the time the second event arrives, the request is already closed.

    So do not treat WithdrawalExecuted as the completion. Treat it as a flag on a row you have already closed, and match it using the transaction hash plus the user address. If you look for an open request, you will find nothing, because Withdraw closed it a moment earlier.

    pause() calls the internal _pause(), which emits Paused, and then the vault emits Paused again. You get two identical logs in one transaction.

    Keep that handler idempotent. Setting a boolean is safe. Incrementing a counter is not.

    Institution Credit Loans for Strategy Yield (coming soon)

    A strategy credit vault lends stablecoins such as USDC and USDT to institutional trading teams. The teams deploy the capital in delta-neutral strategies and pay the vault interest out of the trading yield. For lenders, the result is a credit exposure to a trading team and its strategy, not a directional bet on crypto prices.

    [embed: node/bc683cf1-8b8b]

    What delta-neutral means

    A position is delta-neutral when its value does not change as the price of the underlying asset moves. The usual way to get there is to hold the asset and short it in equal size at the same time. A price rise gains on one leg and loses the same on the other.

    With price risk taken out, what is left is the spread between the two legs, and that spread is the source of yield.

    Where the yield comes from

    • Funding rates. Perpetual futures have no expiry. To keep their price close to spot, longs and shorts pay each other a periodic funding rate. When the market is net long, shorts receive it. A team that holds spot and shorts the perpetual collects that funding.

    • Basis. Dated futures often trade above spot. A team that buys spot and sells the future locks in that difference, which it earns as the two prices converge at expiry.

    • Arbitrage. The same asset can trade at different prices or funding rates on different venues. Buying where it is cheap and selling where it is dear captures the gap.

    • Market making. Quoting both sides of a market earns the spread between bid and ask, with inventory hedged back to neutral.

    1. The vault lends 1,000,000 USDC to a trading team under a credit facility.

    2. The team buys 500,000 USDC of an asset on the spot market and shorts 500,000 USDC of the same asset in perpetual futures, using the rest as margin.

    3. If the price rises 10%, the spot leg gains 50,000 and the short loses 50,000. The position's value is unchanged.

    4. While funding is positive, the short leg receives funding payments. That income, less costs, is the trading yield.

    • Credit facility. The team borrows under agreed terms: amount, interest, duration and conditions for repayment.

    • Collateral and custody. Assets are often held with an independent custodian and mirrored to trading venues, so that collateral does not sit on an exchange.

    • Limits. Facilities set limits on leverage, venues, assets and the size of any single position, together with a maximum drawdown.

    • Monitoring. Positions, collateral and exposure are reported to the lender on a regular basis.

    • Funding turns negative. When the market is net short, the short leg pays funding instead of receiving it, and yield falls or turns negative.

    • Venue and counterparty risk. A failure at an exchange, custodian or broker can freeze or lose the assets held there.

    • Execution and liquidation risk. A sharp move can liquidate one leg before the other is adjusted, breaking the hedge.

    • Operational risk. Errors in systems, keys or processes can cause loss.

    Delta-neutral strategies reduce exposure to price direction. They do not remove credit, counterparty or operational risk, and yields vary with market conditions.

    Attestation

    TownSquare attests the evidence behind townRWA tokens using the Ethereum Attestation Service (EAS) stack. This page explains what an attestation is, why TownSquare uses one, and how to check it.

    All townRWA attestations are made from one address, on every chain where townRWA is attested:

    0xAb3965E78286dF2DFcA627E8CD249cFa9aEA7f36

    • Chains: Base, Robinhood Chain and Monad

    • Tokens: all townRWA tokens, not only townREIT

    An attestation about a townRWA asset that comes from any other address is not a TownSquare attestation.

    An attestation is a digital signature on structured data: a claim one party makes about something, signed so that anyone can confirm who made it and that it has not been changed.

    Project Roadmap

    • Nov 2025: mainnet launch of the TownSquare money market on Monad

    • Q1 2026: Pre-Series A round closed

    • Q2 2026: TOWN token deployed on Base, BNB Chain and Monad with Chainlink CCIP token pools; veTOWN vote-escrow development completed

    • Jul 2026:

    Github

    TownSquare stack repos:

    RedemptionRequested

    A user has queued a withdrawal. Create your row here.

    Withdraw

    The withdrawal settled. Close the row.

    WithdrawalExecuted

    The settlement was operator driven, not user driven.

    CooldownPeriodUpdated

    The cooldown changed. Read the note below, this one is not simple.

    FeeSet, ManagerUpdated, Paused, Unpaused

    Vault configuration changed.

    Cooldown changes are retroactive

    Withdraw and WithdrawalExecuted land in the same transaction

    Pause emits twice

    The team pays the vault interest on the facility from that yield, and the vault distributes it to lenders.

    Diligence. Teams are assessed on track record, risk controls, operations and the legal entity that borrows.

    Borrower risk. The vault's claim is on the trading team. If the team fails or breaches its limits, recovery depends on the collateral and the legal terms of the facility.

    A simple example

    How the credit is structured

    Risks

    What every token has in common

    Example assets and how each is originated

    townAIDC

    townAIROBO

    townBATT

    townMINE

    townREIT

    townGOLD

    townOIL

    Audit & Onchain Verification

    verification page
    https://github.com/TowneSquare
    Technical audit.
    A technical audit report covers the physical and operating condition of the asset, with site access for the auditor where needed.
  • Title and existing debt. Ownership is verified, registered encumbrances are searched, and existing loans are reviewed for consent rights, negative pledges and change-of-control terms. Any required consent from an existing lender is obtained.

  • Sizing. The loanable amount is set from the conservative collateral value less any senior debt. The issuance cap follows from it.

  • Security and asset assignment. The credit is secured on the asset. The security package may include a legal charge or pledge over the asset, a charge over shares in the entity that holds it, an assignment of the income it produces, and a guarantee. The security is registered so that it can be enforced.

  • Legal structure. The borrower, any asset-holding vehicle and the issuer are defined, and legal opinions confirm the structure and the enforceability of the security.

  • Conditions precedent. Issuance takes place only once the agreed conditions are met, such as a current valuation, legal opinions and required approvals.

  • Ongoing reporting. After issuance, the owner reports on the asset at agreed intervals, and the valuation is refreshed periodically.

  • Audit requirement lists

    townAIROBO

    townAIDC

    townBATT

    townMINE

    townREIT

    townGOLD

    Lists to be released

    Underwriting framework

    Schedule 1: Items of the Technical Audit and Underwriting Report

    Townsquare_US_Machine_Learning_Robotics_Audit_Tokenization_Data.pdf
    PDF · 539KB
    Open
    Townsquare_US_Hardware_Robotics_Audit_Tokenization_Data.pdf
    PDF · 539KB
    Open
    Townsquare_Japan_AI_Data_Centre_Audit_Tokenisation_Data.pdf
    PDF · 724KB
    Open
    Townsquare_US_Bitcoin_Farming_Data_Centers_Audit_Tokenization_Data.pdf
    PDF · 542KB
    Open
    Townsquare_US_Hardware_Battery_Company_Audit_Tokenization_Data.pdf
    PDF · 544KB
    Open
    Townsquare_US_Battery_Company_Audit_Tokenization_Data.pdf
    PDF · 548KB
    Open
    Townsquare_Mine_Audit_Tokenisation_Data.pdf
    PDF · 558KB
    Open
    Townsquare_HK_Real_Estate_Audit_Tokenisation_Data.pdf
    PDF · 567KB
    Open
    Townsquare_US_Real_Estate_Audit_Tokenisation_Data.pdf
    PDF · 563KB
    Open
    Townsquare_Gold_Vault_Audit_Tokenisation_Data.pdf
    PDF · 523KB
    Open

    Audits

    TownSquare is going through periodic audits and has gone thru 2 audits in Q3 2025.

    • Q3 2025 audits: https://github.com/TowneSquare/audit-reports-2025Q3

    Further audits will be published here.

    For townRWA, the attester is TownSquare and the claim is about an underlying asset, such as its valuation report. The attestation is signed with TownSquare's attesting address and recorded onchain through EAS.

    • Trust without access. Investors cannot inspect a data center, a mine or a vault themselves. An attestation gives them a signed, public record of what TownSquare has stated about the asset, and when.

    • Credibility rests on the attester. An attestation is only as strong as the party behind it. A TownSquare attestation stands on the audit and underwriting described in Audits & Underwriting and on the independent valuation behind each asset.

    • Anyone can check it. The attester address, the time and the data are public, so verification does not depend on TownSquare's own reporting.

    • Verifying. Recording the valuation report of the asset behind a townRWA token.

    • Certifying. Recording that an asset has completed TownSquare's audit before its token was issued.

    • Recording. Adding later events, such as a revaluation, to the asset's onchain history.

    • Proving. Showing, at any later date, what was attested about an asset and when.

    • Unique ID. Each attestation has its own identifier (UID), a hash of the whole attestation.

    • Status. When it was created, whether it expires, and whether it has been revoked.

    • Schema. The structure its data follows. TownSquare uses its own schema for townRWA attestations.

    • Who is involved. The address that made it, and any recipient.

    • Decoded data. The contents, decoded according to the schema so that anyone can read them.

    • References. Links to other attestations, so a new valuation can point to the one before it.

    1. Define the data. The fields to be attested are set by TownSquare's townRWA schema.

    2. Sign. TownSquare signs the data with its attesting address.

    3. Store onchain. The attestation is recorded through EAS on Base, Robinhood Chain or Monad.

    4. Verify. Anyone can check the signature against TownSquare's attesting address and read the data.

    5. Lifecycle. An attestation cannot be edited. If information changes, it is either revoked, where the schema allows it, or superseded by a new attestation. Either way the full history stays onchain.

    6. Reference. A later attestation, such as a revaluation, can reference the earlier one to show how the record has developed.

    • Attestation: 0xd395d1b7cdfba754437e07adb83a20a5d2c2d648dd8baa77dbfb4095ac9520d7

    • Chain: Base

    • Created: 26 October 2026

    • Attester: 0xAb3965E78286dF2DFcA627E8CD249cFa9aEA7f36

    • Schema: #1985 on Base EAS

    • Expiration: never

    • Revocable: no. Any update will be made as a new attestation.

    • TownSquare verification portal: verification.townsq.xyz

    • EAS explorer on Base: base.easscan.org

    When verifying, check that the attester address is 0xAb3965E78286dF2DFcA627E8CD249cFa9aEA7f36, on whichever of the three chains the attestation was made.

    TownSquare's attesting address

    What an attestation is

    Why it matters for townRWA

    What TownSquare uses attestations for

    What every attestation shows

    How a TownSquare attestation is made

    Live example: townREIT

    Where to verify

    Sonar public sale completed
    • Launch of tokenized RWA credits from key sectors totaling over $400M AUM:

      • townREIT (real estate)

      • townAIROBO (AI robotics)

      • townBATT (energy storage)

      • Fortune 100 company credits expansion, named are under strict confidentiality.

    • Launch of TradFi-familiar assets, including townMINE (mining), townGOLD (vaulted gold), townOIL (oil and gas fields)

    • Launch of townAIDC (AI data centers)

    • DeFi lending market & DEX support for townRWA

    • Licensing procurement and regulatory sandbox

    • Banking partnership

    • Institutional Trading Strategy Backed Credit Vaults

    • RWA Subscription Vaults

    • Overall AUM: $1B by early to mid 2027

    Timelines are targets and may change.

    Completed

    Q4 2026 (current)

    Q1 2027

    Q2 2027

    Ongoing

    Target

    Risks

    Risks and trust assumptions

    This page is deliberately direct. Every item below is drawn from the protocol's own technical documentation (docs/KNOWN_ISSUES.md, docs/INVARIANTS.md) and from the contract code. None of it is hypothetical.

    Counterparty risk

    Your funds are not held onchain.

    Deposits are forwarded to the Manager contract and then transferred to an offchain trading counterparty. What the vault holds is an accounting record of what you are owed — not the assets themselves.

    Once capital leaves via execute(), onchain enforcement ends. Recovery depends on the counterparty honouring an offchain agreement.

    Enforced by code: deposits reach only the Manager; capital can only go to addresses governance has whitelisted; every whitelist change and every deployment emits an event, so the destination set is publicly auditable.

    Not enforced by code: which addresses get whitelisted, how much leaves, when it returns, and whether any reserve is kept back.

    Unverifiable yield reporting

    The share price is set entirely by an offchain engine's reports. There is no oracle, and the vault has no view of the strategy's actual balances.

    From the code's own comment:

    Nothing onchain can verify this: the vault has no view of strategy balances, so the split is trusted input from the offchain engine.

    What bounds it: by default at most 0.5% of vault assets per report, at most one report roughly every 22 hours, strict epoch sequencing, duplicate rejection.

    What does not bound it: the truth of the figure. And the caps are per-report, not cumulative — sustained reporting at the limit compounds. At the default rate, roughly 5.5% per week could be reported in either direction indefinitely.

    Both the magnitude cap and the interval are governance-adjustable, and the interval has no enforced minimum.

    The guardian (instantly) or the admin (through the timelock) can pause the vault. Pause blocks withdraw, redeem, and redeemFor as well as deposits — so a pause makes matured redemptions temporarily uncollectable. Unpausing is admin-only, so it always takes at least 48 hours.

    Most vaults deliberately keep the exit path open while pausing entry. This one does not. The protocol documents this as an accepted risk on the basis that pause is a short-lived emergency measure.

    All three contracts are UUPS-upgradeable. Upgrade authority (DEFAULT_ADMIN_ROLE) is held by a TimelockController with a 48-hour delay, so an upgrade must be scheduled publicly and wait 48 hours before it can execute.

    Watch CallScheduled on the timelock. See Governance and the timelock.

    ADMIN_ROLE is also held by the timelock, so each of these now takes 48 hours and is visible in advance — but each is still possible:

    • Whitelist any destination address, after which the operator can deploy capital to it immediately

    • Call emergencyRecover to transfer any token out of the vault

    • Set the minimum reporting interval as low as 1 second, effectively removing the rate limit

    • Repoint the Manager address, changing which contract controls vault accounting

    Two actions are deliberately not delayed. The Safe holds GUARDIAN_ROLE, which can pause() the vault and remove whitelist entries instantly. It cannot unpause, add to the whitelist, or change anything else.

    These are intentional, but they will surprise you if you assume standard ERC-4626:

    • No cancel. A redemption request cannot be undone or amended.

    • Amount frozen at request. You forgo profit and are insulated from loss during cooldown.

    • One request at a time. Large positions must be exited sequentially.

    • Self-collection only. Allowance-based withdrawal is disabled; no other address can withdraw for you, ever.

    Guides

    Depositing

    Depositing is standard ERC-4626 and works as you would expect. Approve the vault, then deposit.

    Steps

    1

    Approve the vault

    cast send <asset> "approve(address,uint256)" <vault> <amount> \
      --rpc-url <rpc> --private-key $PK
    2

    Deposit

    cast send <vault> "deposit(uint256,address)" <amount> <you> \
      --rpc-url <rpc> --private-key $PK

    Returns the number of shares minted. Alternatively, mint(shares, receiver) if you want an exact share count and are willing to let the asset amount vary.

    3

    Confirm

    cast call <vault> "balanceOf(address)(uint256)" <you> --rpc-url <rpc>

    What to know

    There is no deposit fee. Entry is free. The only fee you pay as a depositor is the exit fee on redemption. There is also no ongoing management fee.

    Your assets leave the vault immediately. The deposit is forwarded to the Manager contract in the same transaction. This is by design, and it is why withdrawal requires a cooldown — see Withdrawing.

    There is a minimum deposit size. It is expressed in shares, not assets. Deposits below it revert with InvalidMinShares.

    You start earning from the next report. Yield is credited through periodic reports, and profit vests over several days. A deposit made shortly before a report will not capture the full epoch's yield — this is deliberate, and it protects existing depositors from being diluted. See The share price.

    Error
    Cause

    Tracking Your Position

    Everything below is readable onchain without permission. Set these first:

    The assets value is what you will receive — fixed at request time and unaffected by anything that happens afterwards.

    Cooldown elapsed is necessary but not sufficient. The vault must also hold enough assets.

    Comparing profit() against loss() gives you the strategy's reported lifetime performance. A stalled epoch() or a lastDistributionTime() far in the past means reporting has stopped.

    Primer on Yield Assets & Liquidity Incentive

    Vote escrow is a way of deciding where a protocol's incentives go. Holders lock a token for a period of time and receive voting power in return. They then use that power to direct rewards to the pools that should receive them.

    The model was built to attract stablecoin liquidity, then adapted for trading liquidity on decentralized exchanges. The same logic now applies to real-world asset (RWA) credit and institutional vaults.

    • Lock for voting power. Holders lock the token for a chosen period. A longer lock gives more voting power.

    • Power decays. Voting power declines as the lock approaches its end, unless the holder extends it.

    Logo

    Official asset materials:

    Change the treasury, redirecting all fee accrual

  • Unpause the vault

  • maxWithdraw / maxRedeem over-report. They are not overridden.

  • An operator can settle your request before the cooldown ends via redeemFor. It can only pay you your locked amount, but it can end your position early.

  • Withdrawals can be paused

    Upgradeability, behind a 48-hour timelock

    Broad admin powers

    Pause fast, resume slow. The guardian can pause instantly, but lifting a pause takes a 48-hour timelock proposal — and a pause blocks withdrawals. A pause placed while a governance change is pending would stop depositors from using the 48-hour window to exit.

    Design behaviours that are not bugs

    https://www.townsq.xyz/brandkit

    Locked, not traded. The escrowed position cannot be sold or transferred while it is locked.

  • Vote on incentives. Each period, holders vote on how new token emissions are split between pools, vaults or deposits, called gauges.

  • The effect is to give the most say to those committed for longest, and to turn the protocol's emissions into something third parties compete for.

    Curve introduced vote escrow with its CRV token in August 2020.

    • veCRV. Holders lock CRV for up to four years. One CRV locked for four years gives one veCRV; locked for one year, it gives 0.25 veCRV.

    • Boost. Liquidity providers who hold veCRV earn up to 2.5 times more CRV on their pools.

    • Gauge votes. veCRV holders vote on gauge weights that decide where weekly CRV emissions flow.

    Stablecoin issuers needed deep Curve pools to hold their pegs. The emissions a pool received depended on the votes it attracted, so control of votes became valuable in its own right.

    In 2022 Solidly combined vote escrow with the (3,3) game theory of OlympusDAO. It failed within months, but Velodrome on Optimism refined the design and made it work.

    • Liquidity providers earn emissions. Providers are paid in newly emitted tokens, according to the share of votes their pool receives.

    • Weekly epochs. Votes are cast and rewards distributed in weekly cycles.

    Aerodrome launched on Base on 28 August 2023 as a fork of Velodrome V2, with veAERO as its escrowed token. It became the main venue for trading liquidity on Base. Projects launching a token there pay incentives to veAERO voters to direct emissions to their pools.

    The design closes the loop. Liquidity holders are incentivized to direct emissions to pools where they have liquidity.

    What vote escrow does is allocate incentives through a market in which committed holders decide which assets get incentivized . Nothing in that limits it to swap pools. The same mechanism can direct incentives to RWA credit and institutional vaults.

    • RWA yield. Emissions directed to an RWA vault are paid on top of the credit yield, raising the total return for depositors in that vault.

    • Onchain RWA liquidity. RWA tokens, and stable instruments built on them, need liquidity to be useful in DeFi. Votes can direct incentives to the pools and markets where that liquidity sits.

    • Institutional vault incentives. Trading vaults run by institutional curators compete for deposits. Votes can direct incentives to the vaults that holders favor.

    • Governance of allocation. Holders decide, period by period, which assets and vaults receive incentives. The question moves from "which pool gets emissions" to "which credit or vault gets emissions".

    The parties who need emission incentives change too. In a DEX they are token projects that want trading depth. Here they are asset originators, borrowers and vault curators that want capital. These are the parties are would be receiving incentives.

    • Votes direct incentives, not credit approval. Only assets that have passed audit and underwriting, and vaults that meet set standards, can be eligible to receive votes. Voting decides where incentives go among approved options. It does not decide what is lent to.

    • Eligibility rules still apply. Where a vault holds restricted assets, such as townRWA tokens available only to whitelisted investors, incentives reach only the participants allowed to hold them.

    • Short-term vote chasing. In ve(3,3) exchanges, large voters have sometimes directed emissions to pools that pay the highest incentives rather than the most useful ones. RWA vote markets need limits on how far votes can shift incentives toward any single asset or vault.

    The pages that follow describe how the TOWN token and locked TOWN apply this model.

    How vote escrow works

    Curve: stablecoin liquidity

    ve(3,3): Solidly, Velodrome and Aerodrome

    From exchange liquidity to RWA

    What has to be different for RWA

    InvalidMinShares

    Deposit is below the minimum share threshold

    InvalidDeposit

    Zero amount, zero shares, or zero receiver address

    EnforcedPause

    The vault is paused

    ERC-20 revert

    Insufficient approval or balance

    Sizing a large position. If maxRedeemCap is non-zero, you can only redeem up to that amount per request, and you can only have one request pending at a time. A position larger than the cap must be exited sequentially — cooldown, collect, request again. Factor that into how long a full exit would take.

    Errors you might hit

    cast call <manager> "minSharesInVaultToken(address)(uint256)" <vault> --rpc-url <rpc>
    Event
    Contract
    Why you care

    DistributeYield

    Yield

    An epoch's result was reported

    TreasuryDebtAccrued

    Yield

    A loss exceeded what the treasury could absorb

    RedemptionRequested

    Vault

    Your request was recorded, with the locked amount

    Withdraw / WithdrawalExecuted

    Vault

    A redemption was paid

    FeeSet, CooldownPeriodUpdated

    Vault

    Your terms changed

    Paused / Unpaused

    Vault

    Two things you cannot track by event:

    • transferToVault emits no event. Redemption funding — the step your withdrawal depends on — is only visible as a plain ERC-20 Transfer to the vault.

    • AssetsWithdrawn is declared but never emitted. Do not build monitoring against it.

    VAULT=<vault proxy>
    MANAGER=<manager proxy>
    YIELD=<yield proxy>
    ASSET=<underlying token>
    ME=<your address>
    RPC=<rpc url>
    # Shares held
    cast call $VAULT "balanceOf(address)(uint256)" $ME --rpc-url $RPC
    
    # Current value, gross
    cast call $VAULT "convertToAssets(uint256)(uint256)" <shares> --rpc-url $RPC
    
    # What you would actually be quoted, net of the exit fee
    cast call $VAULT "previewRedeem(uint256)(uint256)" <shares> --rpc-url $RPC
    # shares, assets, timestamp, exists
    cast call $VAULT "getRedeemRequest(address)(uint256,uint256,uint256,bool)" $ME --rpc-url $RPC
    
    # Has the cooldown elapsed?
    cast call $VAULT "canExecuteRedeem(address)(bool)" $ME --rpc-url $RPC
    # Owed to everyone with a pending request
    cast call $VAULT "totalRequestedAmount()(uint256)" --rpc-url $RPC
    
    # Actually held by the vault
    cast call $ASSET "balanceOf(address)(uint256)" $VAULT --rpc-url $RPC
    # Recognised assets (excludes profit still vesting)
    cast call $VAULT "totalAssets()(uint256)" --rpc-url $RPC
    
    # Profit reported but not yet in the share price
    cast call $VAULT "getUnvestedAmount()(uint256)" --rpc-url $RPC
    
    # Total shares outstanding
    cast call $VAULT "totalSupply()(uint256)" --rpc-url $RPC
    
    # Share price
    cast call $VAULT "exchangeRate()(uint256)" --rpc-url $RPC
    
    # Paused? Blocks both deposits and withdrawals
    cast call $VAULT "paused()(bool)" --rpc-url $RPC
    # Current epoch number — increments once per report
    cast call $YIELD "epoch()(uint256)" --rpc-url $RPC
    
    # When the last report landed
    cast call $YIELD "lastDistributionTime()(uint256)" --rpc-url $RPC
    
    # Cumulative reported profit and loss
    cast call $YIELD "profit()(uint256)" --rpc-url $RPC
    cast call $YIELD "loss()(uint256)" --rpc-url $RPC
    
    # Unabsorbed loss the treasury owes
    cast call $YIELD "treasuryDebt()(uint256)" --rpc-url $RPC
    # Every yield report — this is what moves the share price
    cast logs --address $YIELD "DistributeYield(address,address,address,uint256,uint256,bool)" \
      --rpc-url $RPC
    
    # Where capital is allowed to go
    cast logs --address $MANAGER "WhitelistUpdated(address,address,bool)" --rpc-url $RPC
    
    # Capital deployment, with full calldata
    cast logs --address $MANAGER "BatchExecuted(address,address[],bytes[])" --rpc-url $RPC

    Tracking your position

    Your position

    Your pending redemption

    Is your withdrawal actually payable?

    This is the most useful health check available to a depositor. If the vault's balance is persistently below totalRequestedAmount(), redemptions are not being funded promptly. Tracking this over time tells you more about operational health than the share price does.

    Vault-wide state

    Yield reporting history

    Events worth watching

    Upgraded, RoleGranted, and WhitelistUpdated take effect immediately — there is no timelock, so watching them is reactive, not preventative.

    Monitoring gaps

    Subscription & Redemption

    Eligibility and KYC/KYB

    • Who can invest. Institutional investors and professional investors outside the United States.

    • KYC. Individuals investing as professional investors verify their identity and address.

    • KYB. Entities verify their registration, directors, authorized signatories and beneficial owners.

    • Screening and status. Investors are screened against sanctions lists, and their status as institutional or professional investors is confirmed.

    • Whitelisting. Once approved, the investor's wallet address is whitelisted. Only whitelisted addresses can receive, hold or transfer townRWA.

    KYC/KYB is completed once per investor, whichever route it then uses.

    Subscription and redemption can take place on either of two routes. Each credit's subscription terms state which routes are open.

    • Onchain, through the TownSquare townRWA app. The investor subscribes, follows its position and requests redemption from its whitelisted wallet.

    • Offchain, by agreement. The investor signs a subscription agreement and subscribes and redeems through documents and payment instructions. This is how institutional private credit funds such as those of Apollo and Blackstone are subscribed and redeemed.

    On both routes the tokens are the same, and they are held at the investor's whitelisted address.

    Onchain (townRWA app)

    1. The investor connects its whitelisted wallet to the app.

    2. It reviews the credit's offering documents and subscription terms.

    3. It submits a subscription and pays the subscription amount as the terms require.

    4. At origination, its townRWA tokens are minted and delivered to its wallet.

    Offchain (by agreement)

    1. The investor reviews the offering documents and signs the subscription agreement.

    2. It pays the subscription amount as the agreement requires.

    3. At origination, its townRWA tokens are minted and delivered to its whitelisted address.

    On either route, all tokens for a credit are minted at origination. A subscription is filled only within the credit's issuance cap.


    Private credit is repaid by the borrower over time and cannot be sold instantly, so redemption follows the terms of each credit. Depending on the case, the terms may provide for:

    • Redemption at maturity. Holders are repaid when the borrower repays the credit.

    • Periodic redemption windows. Redemption on set dates, such as monthly or quarterly, with a notice period.

    • Limits per window. A cap on how much can be redeemed in one window, with any excess carried to the next. Apollo Debt Solutions, for example, limits repurchases to 5% of shares each quarter.

    • Early redemption. Redemption before maturity, where permitted, may carry a cost. Apollo Debt Solutions repurchases shares held for less than a year at 98% of net asset value.

    Requests are made on the investor's route: through the app from its whitelisted wallet, or by written notice under its subscription agreement.


    Yield comes from what the borrower pays under the credit. How it reaches investors is set in each credit's terms.

    • Frequency. Daily, weekly, quarterly or at maturity.

    • Route. Onchain, to the investor's whitelisted wallet through the townRWA app, or offchain, by payment under the subscription agreement.

    • Share. Each investor receives yield in proportion to the tokens it holds.

    • Rate. Yield is variable and follows what the underlying credit pays.

    • Routes open for subscription and redemption

    • Minimum subscription and subscription period

    • Yield basis and distribution frequency

    • Distribution route and currency

    • Maturity of the credit

    Investors should read the subscription terms of each credit before subscribing. They differ from one credit to the next.

    How it Works

    How it works

    The lifecycle of a deposit

    1. You deposit           USDC ──▶ Vault ──▶ Manager
                                      (mints you shares)
    
    2. Capital is deployed   Manager ──▶ offchain trading strategy
                                         (via whitelisted addresses)
    
    3. Results are reported  offchain engine ──▶ Yield ──▶ Vault
                                                  (share price moves)
    
    4. You request an exit   requestRedeem() — shares burned, amount locked
    
    5. Cooldown elapses      (1 day by default)
    
    6. Capital returns       Manager ──▶ Vault
                                         (operator-triggered)
    
    7. You collect           redeem() ──▶ USDC to you

    Steps 3 and 6 depend on offchain actors. Everything else you control yourself.

    The three contracts

    The protocol is three upgradeable contracts, each with one job.

    Vault (townSqToken)

    The ERC-4626 token you interact with. It mints and burns shares, tracks redemption requests, and maintains the accounting that determines the share price. It deliberately does not hold assets — deposits pass straight through to the Manager.

    Because of this, totalAssets() is a bookkeeping number (virtualAssets minus profit that has not vested yet), not a balance you can verify by looking at the vault's token holdings.

    Manager

    Custodies every deposited asset and deploys capital into the strategy. Two flows matter to you:

    • Out: an operator calls execute() to send capital to whitelisted destinations. This is how funds reach the offchain trading book.

    • In: an operator calls transferToVault() to push assets back so redemptions can be paid.

    The Manager also enforces an allowlist — capital can only be sent to addresses that governance has explicitly whitelisted.

    Receives the offchain engine's profit and loss reports and applies them to the vault. It handles profit vesting, loss application, and the treasury's performance fee.

    Not from onchain lending or liquidity provision. Capital is transferred to an offchain trading counterparty, and returns are generated by that counterparty's trading activity.

    This has two consequences worth being explicit about:

    1. The strategy's performance is not visible onchain. The vault has no view of the trading book. What you see is the reported result.

    2. Recovering capital depends on the counterparty performing. Once assets leave via execute(), the enforcement is contractual and offchain, not onchain.

    An offchain engine calls distributeYield(amount, feeAmount, nonce, isProfit) once per epoch — at most roughly once every 22 hours by default.

    • amount is the shareholders' slice.

    • feeAmount is the treasury's slice, on top of amount, not carved out of it.

    • isProfit sets the direction.

    On profit: amount is released into the share price linearly over the vesting period (7 days by default), rather than all at once. This prevents someone from depositing just before a report and capturing yield they were not exposed to.

    On loss: the loss applies immediately, with no vesting. Profit that has not vested yet absorbs the loss first — if the loss is smaller than the unvested buffer, the share price does not move at all.

    Each report is bounded: by default no more than 0.5% of vault assets per epoch, and epochs must be at least ~22 hours apart. Both limits are governance-adjustable.

    Fees

    There are two fees in the protocol. Only one is charged to you directly.

    Fee
    Who pays
    When
    Cap

    Origination, Onchain Attestation & Reserve Transparency

    This page follows a credit from the moment it is offered to investors to the moment yield reaches them. Some steps happen offchain, where investors are identified and money moves under contract. Others happen onchain, where the token and the evidence behind it can be checked by anyone.

    A credit is offered only after the asset has passed audit and underwriting.

    • What is offered. Financing against one audited asset. Its valuation, loanable amount and issuance cap are already set, together with the yield terms, the distribution period and the security over the asset.

    • Who it is offered to. Institutional investors and professional investors outside the United States.

    Deposits and withdrawals halted or resumed

    WhitelistUpdated

    Manager

    A new destination for capital was authorised

    Upgraded

    all three

    Contract code was replaced

    RoleGranted / RoleRevoked

    all three

    Privileged access changed hands

  • Redemption windows, notice periods and limits

  • Any cost of early redemption

  • Two routes

    Subscription

    Redemption

    Yield distribution

    What each credit's subscription terms set

    Yield

    Where the yield comes from

    This is the single most important structural fact about the protocol. See Risks and trust assumptions.

    How results reach you

    Where it happens. Offchain, through offering documents. Nothing is onchain at this stage.

    • Identity checks. Individuals complete KYC and entities complete KYB. Eligibility as an institutional or professional investor is confirmed at the same time.

    • Whitelisting. An investor who passes has a wallet address whitelisted. Only whitelisted addresses can receive or hold townRWA.

    • Subscription. The investor subscribes for an amount of the credit under the offering terms.

    • Outcome. A closed list of subscribers, each with a subscribed amount and a whitelisted address. This list is the input to issuance.

    A townRWA token is a share that represents a claim on the credit asset.

    • Minted once. All tokens for a credit are minted at origination, within the issuance cap. No more are minted for that credit afterwards.

    • Priced at $100. Each token is priced onchain at $100.

    • Distributed to subscribers. Tokens go to the whitelisted addresses of the subscribers, in proportion to what each subscribed.

    • Restricted transfers. After issuance a token can move only between whitelisted addresses.

    • What is now public. The supply of the token and the balances of its holding addresses are visible onchain.

    TownSquare attests the valuation report of the underlying asset onchain, using the Ethereum Attestation Service (EAS). This is what ties the token to the evidence behind it.

    How an EAS attestation works

    • Schema. The structure of the statement is registered once in the EAS schema registry. Every attestation of that kind follows it.

    • Attester. The attestation is made from a known address. Anyone can see which address made it.

    • Unique ID and time. Each attestation has its own identifier and is timestamped by the chain.

    • Revocation and expiry. An attestation can be given an expiry time and can be revoked by its attester. Both are visible onchain.

    • References. An attestation can point to an earlier one, which lets a new valuation be linked to the one it replaces.

    Where it lives

    • Chains. EAS runs on Ethereum and on other networks including Base, where it is built into the chain (EAS documentation, EAS CLI). TownSquare attestations are made on Ethereum, Base and other supported chains.

    • Verification portal. Attestations are presented at verification.townsq.xyz, where they can be looked up and checked against the chain.

    What it proves, and what it does not

    • It proves that the attesting address made this statement about this valuation report at this time, and that the statement has not since been revoked or changed.

    • It does not prove that the valuation is right. That rests on the audit and underwriting behind the report.

    • Among holders. townRWA transfers directly between whitelisted addresses.

    • Through aggregation layers. Downstream aggregation layers may allow townRWA to be minted into a stable-pegged instrument for use in DeFi. Multipli, with rwaUSDi, is one example.

    • Wrapped version. A future mechanism could allow a wrapped version of townRWA to be used permissionlessly in lending and borrowing markets and on decentralized exchanges.

    • Role of the attestation. Because the valuation attestation is onchain, a downstream protocol can read it when deciding whether and on what terms to accept the token.

    • Source. The borrower pays under the terms of the credit.

    • Schedule. Yield is distributed on the token's own period: daily, weekly, quarterly or at maturity.

    • Allocation. Each holder's share follows its token balance.

    • Where it happens. Distribution is carried out offchain, in an audited environment.

    • Onchain, by anyone: the supply of each townRWA token, the balances of holding addresses, and transfers between them.

    • Onchain, through EAS: the attestation of the asset's valuation report, the address that made it, when it was made, and whether it has been revoked or replaced.

    • On the verification portal: the same attestations, presented for lookup.

    • Offchain, not public: investor identities, subscription documents and yield payments.

    • Frequency: depending on the subscription and distribution terms, attestation window can vary based on the audit interval of each asset.

    Taken together, a holder can compare the tokens in issue with the attested valuation of the asset that stands behind them.

    • Ethereum Attestation Service documentation: schemas, attestations, revocation and referencing.

    • EAS SDK: fields carried by an attestation.

    • EAS CLI: supported chains.

    1. Offering audited asset credit financing (offchain)

    2. Investor KYC/KYB and subscription (offchain)

    3. Issuing townRWA to investors (onchain)

    4. Asset valuation report attestation (onchain)

    5. DeFi liquidity for townRWA (onchain)

    6. Yield distribution (offchain)

    Reserve transparency: what can be verified

    Sources

    50% of profit by default; governance can raise

    There is no deposit fee and no management fee. Entry is free, and holding costs nothing.

    Charged when you call requestRedeem. It is deducted from the amount you are quoted, so the figure stored in your request is already net of it.

    The fee is not burned. It is minted to the treasury as shares.

    This design keeps the share price neutral: your shares are burned in full, but only the net asset amount is removed from the vault. Without the offsetting mint, the difference would silently raise the share price for everyone who stayed. Minting the fee to the treasury instead makes it an explicit claim rather than an implicit subsidy.

    Taken from reported profit before the remainder reaches the share price. You are not billed for it — it reduces the yield you receive rather than being deducted from your principal.

    The fee is paid to the treasury in shares, priced so that they are worth exactly the fee amount once vesting completes — the treasury is paid on the same schedule as depositors, not ahead of them.

    The performance fee is not one-directional. When a loss is reported, the treasury's shares are burned to absorb its proportional share of it.

    If the treasury does not hold enough shares to cover its portion, the shortfall is recorded as treasuryDebt, and future performance fees are redirected to depositors until it is repaid. The treasury earns nothing new while it owes.

    A non-zero treasuryDebt means depositors are currently receiving 100% of reported profit.

    You deposit 10,000 USDC and receive shares. Over time, 1,000 USDC of profit is reported at a 50% performance fee — meaning amount = 1000 to shareholders and feeAmount = 500 to the treasury, as two separate slices of realised P&L.

    Your deposit

    10,000 USDC

    Profit credited to shareholders

    +1,000 USDC (vesting over 7 days)

    Your position after vesting

    ~11,000 USDC

    Exit fee at 1% on redemption

    −110 USDC

    You receive

    ~10,890 USDC

    The treasury separately holds shares worth ~500 USDC plus your 110 USDC exit fee.

    Fees can change without notice — there is no timelock. Before depositing:

    Watch FeeSet on the vault and MaxFeePercentage on the Yield contract for changes.

    Exit fee

    You

    On requestRedeem

    1% — hard-coded, cannot be raised

    Performance fee

    Taken from yield

    Fees

    On each profit report

    The exit fee

    The 1% cap is enforced in the contract, not by policy. setFee reverts on any value above it. This is one of the few parameters governance genuinely cannot raise beyond its stated bound.

    Where it goes

    The performance fee

    This cap is adjustable up to 100%. The contract only checks that the value is at most 10_000 basis points, so governance can in principle assign all reported profit to the treasury. The change goes through the 48-hour timelock, so it is public before it takes effect. Unlike the exit fee, there is no structural ceiling here.

    The treasury also absorbs losses

    Worked example

    Note that feeAmount is reported on top of amount, not carved out of it. In this example the strategy realised 1,500 USDC in total: 1,000 to depositors, 500 to the treasury.

    Checking current terms

    # Current fee — scaled so that 1e18 = 1%
    cast call <vault> "fee()(uint256)" --rpc-url <rpc>
    
    # What you would actually receive, net of fee
    cast call <vault> "previewRedeem(uint256)(uint256)" <shares> --rpc-url <rpc>
    # Cap, in basis points. 5000 = 50% of profit
    cast call <yield> "maxFeePercentage()(uint256)" --rpc-url <rpc>
    cast call <yield> "treasuryDebt()(uint256)" --rpc-url <rpc>
    cast call <vault> "fee()(uint256)" --rpc-url <rpc>
    cast call <yield> "maxFeePercentage()(uint256)" --rpc-url <rpc>

    Deploying Capital

    description: Operational runbook for the OPERATOR_ROLE holder deploying capital and funding redemptions.

    Deploying capital

    This page covers the highest-privilege operation in the protocol. Manager.execute makes arbitrary calls from the address custodying 100% of deposited assets. Within the whitelist there is no amount cap, no per-destination limit, and no rate limit. Read the whole page before your first call.

    OPERATOR_ROLE holds three functions on the Manager:

    Function
    Purpose

    execute(targets[], data[])

    Deploy capital to whitelisted destinations

    transferToVault(token, amount)

    Return capital so redemptions can be paid

    redeemFor(vault, user)

    1

    false reverts with AccessControlUnauthorizedAccount.

    2

    Check this before building anything else. The whitelist is the only constraint on where capital can go, and an unlisted target reverts the entire batch with NotWhitelisted.

    To see the full authorised set rather than checking one address at a time, read the event history:

    3

    The batch is atomic. One failing call reverts the entire transaction — no partial application. Ordering within a batch is therefore safe for dependent operations (approve then deposit in one batch is fine).

    Reverts bubble up raw. A failing target's revert data is re-thrown verbatim, so what you see is the target's error, not a Manager error. Decode it against the target's ABI, not the Manager's:

    execute cannot send native ETH. It is not payable and passes no value, so every call carries msg.value == 0. Native ETH held by the Manager cannot be moved through this function at all.

    There is no reentrancy guard. execute makes raw calls with no lock. Batching calls to a target that can call back into the Manager has no protection.

    The whitelist cannot include the vault or Yield contract. setWhitelistedAddresses rejects both. This is load-bearing: without it, execute could reach mintVaultToken and updateTotalAssets and forge share supply and vault accounting directly.

    The return leg. This is the function that makes withdrawals actually payable.

    Two rough edges worth knowing:

    • It emits no event. Redemption funding is visible only as a plain ERC-20 Transfer into the vault. Do not build monitoring against a transferToVault event — there isn't one. (AssetsWithdrawn is declared in IManager but never emitted anywhere.)

    • It has no zero-amount check and no NatSpec — the only function in Manager missing both.

    Anyone can also fund the vault with a plain ERC-20 transfer; the operator path is simply the intended one.

    Bounded and safe: it pays only that user, only the amount already locked into their request. It cannot redirect funds or change amounts.

    Requires the vault to be funded, exactly like a user-initiated redemption.

    Guard
    Reverts with

    That is the complete list. Note what is absent: no amount limit, no destination-specific cap, no rate limit, no daily ceiling, no pause check.

    Operational discipline is the actual control here, not the contract. Practical guidance:

    • Simulate every batch, including ones identical to yesterday's.

    • Prefer exact approvals over infinite ones. execute can grant unlimited allowances to whitelisted targets; a compromised or upgradeable target with a standing infinite approval can drain the Manager without any further operator action.

    • Check the redemption backlog before deploying, not after. Deploying capital while matured redemptions sit unfunded strands users who have already given up their shares.

    Reporting Profit and Loss

    Description: Operational runbook for the REBALANCER_ROLE holder reporting each epoch's realised P&L.

    Reporting P&L

    This page is for the operator holding REBALANCER_ROLE. Depositors cannot call any of these functions — see How profit and loss reach your shares for what the reports mean from a user's perspective.

    Reporting P&L is one function call. distributeYield is the only function REBALANCER_ROLE gates anywhere in the protocol:

    distributeYield(uint256 amount, uint256 feeAmount, uint256 nonce, bool isProfit)

    Everything else below is preflight work to compute arguments that will not revert — and to avoid the one class of mistake that cannot be undone.

    Before you start

    YIELD=<yield proxy>
    VAULT=<vault proxy>
    RPC=<rpc url>

    Step by step

    1

    Read the current epoch

    cast call $YIELD "epoch()(uint256)" --rpc-url $RPC

    nonce must equal epoch + 1 exactly. Off by one reverts with InvalidEpoch. There is no way to skip an epoch or backfill a missed one.

    2

    Requires lastDistributionTime + minDistributionInterval <= block.timestamp, else DistributionTooFrequent. Default interval is 79,200s (22 hours).

    The very first report is exempt — the check is skipped while lastDistributionTime == 0.

    3

    amount <= totalAssets() * maxYieldPercentage / 10_000. Default maxYieldPercentage is 50 = 0.5% of recognised assets.

    4

    feeAmount <= amount * maxFeePercentage / 10_000. Default 5000 = 50% of amount — not of total realised P&L.

    5

    This is the step that permanently corrupts vault accounting if you get it wrong.

    feeAmount is additive, not deducted from amount. If the strategy realised 5 USDC and the protocol takes 20%:

    Correct
    Wrong
    6

    A successful call means the guards pass. It does not validate that your figures are economically correct — only that they are accepted.

    7
    8

    Confirm the DistributeYield event carries the figures you intended.

    Guard
    Reverts with
    Default

    proofHash is keyed on (vaultToken, amount, nonce, isProfit) — feeAmount is not part of the replay identity, so the nonce check is what actually prevents a duplicate submission.

    distributeYield writes accounting only. There is not a single underlying-asset transfer in Yield.sol. Reporting a profit does not bring capital back onchain.

    Returning capital is Manager.transferToVault, which requires OPERATOR_ROLE. These are independent systems:

    Function
    Role
    Effect

    Reporting profit while the vault stays unfunded raises the share price without making a single redemption payable.

    There is no reversal path. nonce is strictly sequential, and a bad report can only be offset by an opposing report in a later epoch — itself bounded by the per-epoch cap.

    A materially wrong figure could take many epochs to unwind, and throughout that window requestRedeem keeps freezing quotes at the wrong price. Those quotes are final: users who requested during the error are paid the wrong amount permanently.

    There is no required reporting frequency. The interval is a floor, not a ceiling — nothing obliges a report, and there is no staleness check anywhere.

    If reporting stops, unvested profit finishes vesting and the share price freezes at its last value indefinitely, while deposits and redemption requests keep quoting against it. Onchain this is indistinguishable from a flat-performing strategy.

    The 22-hour default paired with a 7-day vesting period implies daily reporting — each epoch's profit vests across roughly seven subsequent reports, so the schedules overlap and the share price moves smoothly instead of stepping.

    Signal
    Read
    Meaning

    That last row is the one worth alerting on. It is the only onchain signal that separates a healthy vault from one whose books look fine while users cannot exit.

    Bridging AI & Real Economies to Onchain Credit

    TownSquare originates private credit across two groups of assets. The first is the physical build-out of AI: data centers, robotics and the energy infrastructure that powers them. The second is the established real economy: real estate, mining, vaulted gold, and oil, gas and energy fields.

    This page sets out how much financing each group needs, how fast that need is growing, and why originating across both is a stronger position than building around a single type of asset.

    The AI economy: new assets, financed with debt

    AI is being built with borrowed money, and most of what is being built is a physical asset.

    • Data centers. Morgan Stanley estimates about $2.9 trillion of data center and hardware spending through 2028. The largest technology companies can fund about $1.4 trillion of it from cash flow. That leaves a $1.5 trillion gap, and the bank expects private credit to supply about $800 billion of it (Morgan Stanley). It forecasts about $570 billion of AI-related debt in 2026 alone (Marcus Today). Lending against the hardware itself is now routine: CoreWeave closed an $8.5 billion GPU-backed facility this year (USD.AI).

    • Robotics. The market is small today and forecasts for it disagree widely. Research firms put humanoid robots at $2.9 billion to $6.2 billion in 2026, Goldman Sachs sees $38 billion by 2035, and Morgan Stanley sees $5 trillion by 2050 (). What matters for credit is the business model. Robots are increasingly deployed as a service, and humanoid robot-as-a-service revenue is forecast to grow about 42% a year to 2034 (). A fleet that is leased out has to be owned and financed by someone.

    • Energy infrastructure. Compute is limited by power. The IEA expects battery storage investment to pass $100 billion in 2026, up more than 35% in a year (). BloombergNEF forecasts record storage additions of 188 GW, up 45% (), and sees storage installed on site at data centers reaching 6.3 GW in 2027 ().

    These three belong together. A data center cannot run without power, and robots cannot work without the models that data centers train. An originator that can finance all three can follow the AI build-out to wherever the next bottleneck appears.

    The second group is older and far larger. Its financing need comes from a different source: banks pulling back.

    • Real estate. About $875 billion of US commercial and multifamily mortgage debt matures in 2026, roughly 17% of a $5 trillion market, and nearly $2.8 trillion matures through 2028 (). Private lenders are refinancing a growing share of it.

    • Mining. The IEA puts the capital needed for critical mineral mining and refining at about $915 billion between 2026 and 2035 (). PwC notes that mining has no single capital market and that the funding gap is widest at the early stages of a project ().

    • Oil, gas and energy fields. Global upstream investment is expected to reach $546 billion in 2026 (). Bank lenders have retreated from the sector over the past decade, and private credit and securitizations of producing assets are filling the gap ().

    These sectors grow more slowly than AI. But they are deep, their assets have long valuation histories, and the lenders they relied on are withdrawing. That combination is what makes them financeable at scale.

    Some onchain credit projects are built around one asset. USD.AI lends against NVIDIA GPUs, through non-recourse loans secured only by the hardware and its contracted cash flows, and has approved more than $1.2 billion of facilities (, ). Figure built the largest non-bank home equity business in the United States on its own chain, with about $30 billion originated (). Both show that specialized origination works, and depth in one asset is a real strength.

    It is also a single exposure. A focus on AI and real economies together has four advantages over it.

    • No single cycle decides the book. GPU values fall as new chip generations arrive. Home equity lending moves with house prices and interest rates. Resource sectors move with commodity prices. These cycles have different drivers, so a book spread across them is not hostage to any one.

    • Origination does not stop when one sector does. A single-sector originator grows only as fast as its one market borrows. When that market pauses, so does its deal flow. Across seven sectors, capital can go where demand and terms are best at the time.

    • The AI build-out is financed whole. A GPU lender finances the chips. The same campus also needs the building, the power connection and the storage beside it, and each is a separate credit. Covering data centers, robotics and energy infrastructure lets one originator serve the same borrower several times.

    Breadth has a price. Each sector needs its own expertise, and evidence gathered for a mine does not carry over to a data center. This is why our audit sets the same three terms for every asset, a valuation, a loanable amount and an issuance cap, while the evidence behind them is specific to the sector. Specialists are not standing still either: Figure is expanding beyond home equity into other loan types.

    • : $2.9 trillion spend, $1.5 trillion gap, $800 billion from private credit.

    • (October 2026): Morgan Stanley's 2026 AI debt forecast.

    • , and : USD.AI's model, approved facilities and the CoreWeave facility.

    • , and : robotics market estimates.

    Liquidity Design

    Private credit is illiquid by construction. A townRWA token can move between whitelisted wallets in minutes, but the loan behind it cannot be sold in minutes, and no token design changes that.

    Liquidity therefore has to be designed around the asset. This page describes the characteristics of private credit assets that the design starts from.

    • No market price. A private loan is not quoted anywhere. Its value is an estimate, not an observation.

    • Valued by model. The usual method discounts the loan's expected cash flows at a rate that reflects the borrower's credit, or appraises the collateral behind it. Accounting rules class these as Level 3 values, built on inputs that cannot be observed in a market.

    Vaulted gold. Bullion in a vault is the simplest collateral in the set: uniform, liquid and priced every day. It anchors the low-risk end of the range.

    Liquidity providers get a range, not one bet. Vaulted gold, a stabilized property, a producing field and a new data center carry different risks, terms and yields. A single-asset protocol offers one risk profile. A multi-sector pipeline can offer several, each audited to the same standard.

    TaiyangNews on the IEA, TaiyangNews on BloombergNEF and Utility Dive: energy storage investment and deployment.

  • NCPERS: commercial real estate maturities, from the Mortgage Bankers Association.

  • Discovery Alert and PwC Mine 2026: mining capital need.

  • IEA, World Energy Investment 2026 and Akin Gump: upstream investment and the shift from bank lending.

  • Chara Capital, "The infrastructure layer of HELOCs": Figure's originations and expansion.

  • The real economy: large, established and short of lenders

    Why breadth beats a single sector

    Sources

    Cervo
    Polaris Market Research
    TaiyangNews
    TaiyangNews
    Utility Dive
    NCPERS, citing the Mortgage Bankers Association
    Discovery Alert, citing the IEA
    PwC Mine 2026
    IEA World Energy Investment 2026
    Akin Gump
    USD.AI docs
    Business Wire
    Chara Capital
    Morgan Stanley, "How credit markets could finance AI's trillion dollar gap"
    Marcus Today, "Who funds AI debt, and who is stretched"
    USD.AI docs
    GPU financing overview
    Business Wire
    Cervo, humanoid robot market statistics 2026
    MarketsandMarkets
    Polaris Market Research

    Build the calldata

    Each entry in data[] is a complete ABI-encoded call to the matching entry in targets[].

    Amounts are in the token's own decimals — 6 for USDC, not 18. execute performs no validation of any kind on the calldata. A misplaced decimal moves 10¹²× the intended amount, and the only thing standing between that and a loss is whether the destination is willing to send it back.

    4

    Simulate the batch

    This returns each call's return data without sending anything. A successful simulation confirms the guards pass and no target reverts — it does not confirm the amounts are correct.

    Simulate every batch. There is no dry-run mode, no confirmation step, and no way to recall a transfer once it lands.

    5

    Send

    6

    Verify

    BatchExecuted records the complete calldata of every call, so each deployment is publicly auditable after the fact.

    Reconcile deployed capital against reported P&L. BatchExecuted tells you what left; DistributeYield tells you what the strategy claims it earned. Nothing onchain connects the two — see Reporting P&L.

    Settle a user's matured redemption on their behalf

    Caller holds OPERATOR_ROLE

    AccessControlUnauthorizedAccount

    targets.length == data.length

    LengthMismatch

    Every target whitelisted

    NotWhitelisted

    Every call succeeds

    the target's own revert data, bubbled raw

    Before you start

    execute — step by step

    Confirm you hold the role

    Confirm every target is whitelisted

    Whitelisting is ADMIN_ROLE, not yours. If a destination is missing, it must be added by the admin multisig before you can reach it — you cannot self-authorise.

    Behaviour to know before you rely on it

    transferToVault — funding redemptions

    This step is the protocol's withdrawal liveness. The vault holds no liquidity buffer, and _withdraw transfers only from the vault's own balance — it cannot pull from the Manager. A user whose cooldown has elapsed cannot exit until this call is made.

    The protocol's invariant documentation records that "users can always eventually withdraw" does not hold precisely because this step is manual and offchain-triggered.

    redeemFor — settling on a user's behalf

    This path does not check the cooldown. It can settle a request before it has matured — paying the user their locked amount early. It cannot take anything from them, but it does end their position sooner than they planned.

    Every guard on execute

    The trust boundary

    execute is where capital stops being governed by code and starts being governed by an offchain agreement.

    Enforced onchain: only whitelisted addresses can receive capital; only ADMIN can change that list; every deployment emits BatchExecuted with full calldata.

    Not enforced onchain: how much leaves, when it returns, or whether it returns at all.

    4e6

    5e6

    feeAmount

    1e6

    1e6

    Booked

    5 USDC

    6 USDC against 5 real

    The wrong version overstates the vault permanently. Nothing onchain will catch it — the vault has no view of strategy balances.

    DuplicateTransaction

    —

    Interval elapsed

    DistributionTooFrequent

    79,200s

    Caller holds REBALANCER_ROLE

    AccessControlUnauthorizedAccount

    —

    totalRequestedAmount() vs the vault's asset balance

    Whether matured redemptions are actually payable

    amount <= totalAssets * maxYieldPercentage / 10_000

    (no reason string)

    50 bps

    feeAmount <= amount * maxFeePercentage / 10_000

    (no reason string)

    5,000 bps

    nonce == epoch + 1

    InvalidEpoch

    —

    Books

    distributeYield

    Rebalancer

    virtualAssets changes

    Assets

    transferToVault

    Operator

    Real tokens arrive at the vault

    Epoch advanced

    epoch()

    Report was accepted

    Vesting in flight

    getUnvestedAmount()

    Profit not yet in the share price

    Treasury debt

    treasuryDebt()

    A loss exceeded what the treasury could absorb; fees now route to depositors

    Confirm the rate limit has elapsed

    Compute the amount ceiling

    The cap is evaluated against live totalAssets() at execution time, not at the time you read it. A deposit or redemption landing between your read and your transaction shifts the ceiling. Leave headroom on a report near the cap.

    Compute the feeAmount ceiling

    Split the realised P&L into the two arguments

    Simulate before sending

    Send

    Verify it landed as intended

    Every guard, in one place

    The two percentage caps are bare require statements with no message — unlike every other check, which uses a named custom error. Exceeding either cap reverts with no reason string. If a transaction fails with nothing to decode, check the caps first.

    Two things this role does not do

    It does not move any assets

    It cannot correct a mistake

    Simulate every report. A misplaced decimal cannot be undone in one transaction, and the users harmed by it are the ones who exit before you finish unwinding it.

    Cadence

    Note that a new profit report restarts the vesting clock for profit still in flight: vestingAmount becomes new + still-unvested and the timestamp resets. Under continuous daily reporting, profit is perpetually re-spread and never fully vests, so totalAssets() structurally lags virtualAssets. This is inherent to the design.

    Monitoring after each report

    amount

    trxns[proofHash] unseen

    Redemption backlog

    Both values are in underlying asset decimals — 6 for USDC, not 18. Passing an 18-decimal figure books a 10¹²× overstatement. This is the single highest-consequence input error available here.

    # Approve a protocol to pull USDC from the Manager
    cast calldata "approve(address,uint256)" <spender> <amount>
    
    # Transfer USDC to a whitelisted destination
    cast calldata "transfer(address,uint256)" <recipient> <amount>
    
    # Any protocol function
    cast calldata "deposit(uint256,address)" <amount> $MANAGER
    cast call $MANAGER "execute(address[],bytes[])(bytes[])" \
      "[<target1>,<target2>]" "[<data1>,<data2>]" \
      --from <operator> --rpc-url $RPC
    cast send $MANAGER "execute(address[],bytes[])" \
      "[<target1>,<target2>]" "[<data1>,<data2>]" \
      --rpc-url $RPC --private-key $PK
    # Manager's remaining balance
    cast call $ASSET "balanceOf(address)(uint256)" $MANAGER --rpc-url $RPC
    
    # The batch, with full targets and calldata
    cast logs --address $MANAGER "BatchExecuted(address,address[],bytes[])" \
      --from-block latest --rpc-url $RPC
    MANAGER=<manager proxy>
    VAULT=<vault proxy>
    ASSET=<underlying token>
    RPC=<rpc url>
    cast call $MANAGER "hasRole(bytes32,address)(bool)" \
      $(cast keccak "OPERATOR_ROLE") <your address> --rpc-url $RPC
    cast call $MANAGER "whitelistedAddresses(address)(bool)" <target> --rpc-url $RPC
    cast logs --address $MANAGER "WhitelistUpdated(address,address,bool)" \
      --from-block <deployment block> --rpc-url $RPC
    cast 4byte <selector>
    # 1. What is owed to everyone with a matured or pending request
    cast call $VAULT "totalRequestedAmount()(uint256)" --rpc-url $RPC
    
    # 2. What the vault currently holds
    cast call $ASSET "balanceOf(address)(uint256)" $VAULT --rpc-url $RPC
    
    # 3. What the Manager has available to send
    cast call $ASSET "balanceOf(address)(uint256)" $MANAGER --rpc-url $RPC
    
    # 4. Push the shortfall in
    cast send $MANAGER "transferToVault(address,uint256)" $ASSET <amount> \
      --rpc-url $RPC --private-key $PK
    cast send $MANAGER "redeemFor(address,address)" $VAULT <user> \
      --rpc-url $RPC --private-key $PK
    cast call $YIELD "lastDistributionTime()(uint256)" --rpc-url $RPC
    cast call $YIELD "minDistributionInterval()(uint256)" --rpc-url $RPC
    cast block latest -f timestamp --rpc-url $RPC
    cast call $VAULT "totalAssets()(uint256)" --rpc-url $RPC
    cast call $YIELD "maxYieldPercentage()(uint256)" --rpc-url $RPC
    cast call $YIELD "maxFeePercentage()(uint256)" --rpc-url $RPC
    cast call $YIELD "distributeYield(uint256,uint256,uint256,bool)" \
      <amount> <feeAmount> <nonce> <isProfit> \
      --from <rebalancer> --rpc-url $RPC
    cast send $YIELD "distributeYield(uint256,uint256,uint256,bool)" \
      <amount> <feeAmount> <nonce> <isProfit> \
      --rpc-url $RPC --private-key $PK
    cast call $YIELD "epoch()(uint256)" --rpc-url $RPC           # incremented by 1
    cast call $VAULT "totalAssets()(uint256)" --rpc-url $RPC
    cast call $VAULT "getUnvestedAmount()(uint256)" --rpc-url $RPC
    cast call $YIELD "treasuryDebt()(uint256)" --rpc-url $RPC    # non-zero: loss exceeded treasury
    One asset at a time. Each loan has its own borrower, terms and collateral, so each is valued on its own facts. A valuation method for a data center does not price a mine.
  • Periodic, not continuous. Values are updated monthly or quarterly. Between updates the last value stands, so the price moves in steps.

  • What follows. The value of a credit token is an estimate until the loan repays or is sold. Who performs the valuation, and how often, is part of the product.

    • No trading venue. S&P Global describes private credit as largely illiquid and without a secondary market, with managers planning to hold assets to maturity (S&P Global).

    • Transfers are negotiated. A buyer has to repeat the diligence on information that is not public, and loan documents often require consent before a transfer.

    • Selling is slow and costly. A sale takes weeks and usually clears at a discount. A forced sale clears at a larger one.

    • What follows. The normal exit from a private credit is repayment by the borrower, not a sale to someone else.

    Because the asset is rarely sold, liquidity comes from the cash it pays. What it pays depends on its status.

    • Cash-paying. Interest arrives in cash on schedule. This is the performing case.

    • Payment in kind (PIK). Interest is added to the loan balance in place of a cash payment. Income accrues, but no cash arrives. S&P Global estimated that 11.7% of loans held by business development companies were making PIK payments in mid-2024.

    • Non-accrual. Payment is in doubt and the lender stops recognizing interest.

    • Pre-revenue. The asset, such as a site under construction, is not yet producing income. Interest is paid from a reserve or capitalized until it does.

    The repayment profile matters as much. Some loans amortize, returning principal in instalments. Many repay in one amount at maturity, and borrowers may prepay early.

    The cash available to holders in any period is limited to what the assets pay in that period.

    • Fixed term. Loans run for a set number of years. Capital is committed until maturity.

    • Floating rate. More than 90% of private credit loans pay a benchmark rate plus a spread (Alternative Credit Council), so income moves with interest rates.

    • Senior and secured. Lenders typically hold a first claim on the borrower's assets or on a specific asset.

    • Covenants. Because loans are held to maturity, lenders write in financial tests that let them step in early if the borrower weakens (S&P Global).

    • Private information. Terms and borrower financials are confidential, which is why outside buyers cannot price the loan quickly.

    • Large, uneven positions. A portfolio holds a limited number of sizeable loans, so one repayment or one default moves the whole.

    The largest originators lend under the same constraints. Their funds show the standard answer to them.

    • Senior, secured, floating. Apollo Debt Solutions holds about 99% first-lien debt and 96% floating-rate investments across 405 companies (AltsWire). Blackstone Secured Lending holds 96.8% first-lien senior secured loans and 96.3% floating rate, at an average loan-to-value of 51.9% (Blackstone).

    • Held, not traded. Loans stay on the fund's books until they repay.

    • Priced at a periodic valuation. The funds publish a net asset value, and investors subscribe and redeem at that value, not at a market price.

    • Exit is scheduled and capped. Apollo Debt Solutions offers repurchases once a quarter, limited to 5% of shares. In 2026 holders asked to redeem 11.2%, 16.8% and 14.7% of shares in the first three quarters, and the fund honored 5% each time ().

    • Early exit costs more. Shares held for less than a year are repurchased at 98% of net asset value ().

    • Redemptions are paid from cash, not asset sales. New subscriptions, loan repayments and fund borrowing cover them.

    Even the largest originators do not offer instant exit from private credit. They offer scheduled, limited exit at a periodic valuation.

    The characteristics above describe the underlying credit. Some of them do not carry over to the townRWA token.

    Does not apply to the token

    • Bespoke pricing. Each townRWA token is priced onchain at $100. The asset-by-asset valuation described above happens in the audit of the underlying credit, not in the price of the token.

    • Negotiated, slow transfers. A townRWA token transfers onchain directly between holders. There is no bilateral sale process.

    Applies to the token

    • Restricted holders. Transfers are possible only between whitelisted addresses that have passed KYC or KYB.

    • Yield follows cash flow. What a token pays still depends on what the underlying credits pay, and so on their cash flow status.

    • Yield distribution period varies. A townRWA token may distribute yield daily, weekly or quarterly, or, like traditional credit, at maturity.

    For free DeFi distribution

    • A wrapped version for DeFi. A mechanism could allow a wrapped version of townRWA to be used permissionlessly in DeFi, in lending and borrowing markets and for trading on decentralized exchanges.

    • S&P Global, payments in kind within private credit and covenants in private credit: illiquidity, PIK share, hold-to-maturity covenants.

    • Alternative Credit Council, Q1 2026 quarterly update: share of floating-rate loans.

    • Houlihan Lokey, private credit vs public credit valuation: how private loans are valued.

    • Apollo Debt Solutions BDC, 8-K of 22 September 2026, 10-Q for June 2026 and AltsWire: portfolio mix, repurchase cap and 2026 requests.

    • : portfolio mix at 30 June 2026.

    Characteristics of private credit assets

    Bespoke valuation

    Illiquid on the secondary market

    Cash flow status

    Other standard characteristics

    How Apollo and Blackstone handle the same assets

    What does and does not apply to townRWA

    Sources

    Functions Reference

    Function reference

    Functions available to you as a depositor, plus the standard ERC-4626 surface and where it deviates.

    Integrators start here. This vault deviates from ERC-4626 in three ways that will break naive integrations: withdrawal requires a prior request, maxWithdraw/maxRedeem over-report, and allowance-based withdrawal is disabled.

    Entering

    deposit(uint256 assets, address receiver) → uint256 shares

    Standard. Transfers assets from you, mints shares to receiver. Assets are forwarded to the Manager in the same transaction.

    Reverts: InvalidMinShares (below minimum), InvalidDeposit (zero amount/shares/receiver), EnforcedPause.

    mint(uint256 shares, address receiver) → uint256 assets

    Standard. Mints an exact share count, pulling however many assets that requires.

    Exiting

    requestRedeem(uint256 shares)

    Step 1 of withdrawal. Burns your shares immediately, quotes your payout at the current price net of the exit fee, stores it, and starts the cooldown.

    Mints the exit fee to the treasury as shares.

    Reverts: RedemptionRequestAlreadyExists, ZeroAmount, InsufficientShares, InsufficientAssets, MaxRedeemCapExceeded, EnforcedPause.

    Step 2. Pays out your stored request. shares must exactly equal the stored share count. msg.sender must equal owner.

    Reverts: NoRedemptionRequest, CooldownNotFinished, InvalidWithdrawalRequest (inexact amount), NotAuthorized (caller ≠ owner), EnforcedPause, or an ERC-20 transfer revert if the vault is unfunded.

    Same as redeem, but keyed on the stored asset amount instead. Same exact-match and self-only rules.

    Function
    Returns
    Function
    Returns

    On the Yield contract:

    Function
    Returns
    Function
    Standard behaviour
    Here

    Listed so you know they exist and who controls them:

    Function
    Contract
    Restricted to

    Withdrawing

    Withdrawing is two steps with a mandatory waiting period between them.

    Three things happen immediately:

    1. Your shares are burned. They are gone from your balance right away.

    2. Your payout is calculated and locked in, at the current share price, net of the exit fee.

    3. The cooldown timer starts.

    Check whether your request has matured:

    How profit and loss reach your shares

    Callable only by the Rebalancer, on the Yield contract. It is the function that determines what your shares are worth, so it is worth understanding precisely.

    What gets reported

    Parameter
    Meaning
    Apollo, SEC filing
    Apollo, SEC filing
    Blackstone Secured Lending, portfolio

    convertToShares(uint256 assets)

    Shares for a given asset amount

    exchangeRate()

    Current share price

    cooldownPeriod(), vestingPeriod()

    In seconds

    paused()

    Whether deposits and withdrawals are blocked

    asset()

    The underlying token address

    decimals()

    Share decimals — 18, even for a 6-decimal asset

    minDistributionInterval()

    Minimum seconds between reports

    No fee

    Includes the exit fee

    previewDeposit / previewMint

    —

    Unchanged; entry is free

    totalAssets

    Token balance

    Accounting figure; vault holds no assets

    Yield

    Rebalancer

    setFee, setCooldownPeriod, setVestingPeriod

    Vault

    Admin

    pause, unpause, emergencyRecover

    Vault

    Admin

    setWhitelistedAddresses, setTreasury

    Manager

    Admin

    updateTotalAssets, mintVaultToken, burnVaultToken

    Vault

    Manager only

    balanceOf(address)

    Your share balance

    getRedeemRequest(address)

    (shares, assets, timestamp, exists)

    canExecuteRedeem(address)

    Whether the cooldown has elapsed

    previewRedeem(uint256 shares)

    Assets you would be quoted, net of fee

    convertToAssets(uint256 shares)

    Gross value, no fee applied

    totalAssets()

    Recognised assets — excludes profit still vesting

    getUnvestedAmount()

    Profit reported but not yet in the share price

    totalSupply()

    Shares outstanding

    totalRequestedAmount()

    Assets owed to all pending requests

    fee()

    epoch()

    Current epoch number

    lastDistributionTime()

    Timestamp of the last report

    profit(), loss()

    Cumulative reported figures

    treasuryDebt()

    Unabsorbed loss the treasury owes

    maxYieldPercentage(), maxFeePercentage()

    Caps, in basis points

    withdraw / redeem

    Immediate

    Requires a prior requestRedeem and elapsed cooldown

    maxWithdraw / maxRedeem

    Accurate ceiling

    Not overridden — over-reports

    Allowance withdrawal

    Approved spender can withdraw

    Disabled — caller must equal owner

    execute

    Manager

    Operator

    transferToVault

    Manager

    Operator

    redeemFor

    Vault / Manager

    Manager only — pays the user their locked amount, no cooldown check

    Irreversible. There is no cancel function.

    redeem(uint256 shares, address receiver, address owner) → uint256 assets

    withdraw(uint256 assets, address receiver, address owner) → uint256 shares

    Reading your position

    Reading vault state

    Reading yield state

    ERC-4626 deviations

    Do not size a withdrawal from maxWithdraw or maxRedeem. Use getRedeemRequest and pass the stored value back exactly.

    Functions you cannot call

    Exit fee, 1e18 = 1%

    previewWithdraw / previewRedeem

    distributeYield

    Read back your request — you need the exact stored values:

    Then collect, passing the stored share count exactly:

    Or by asset amount instead, again matching exactly:

    From the moment you request, you are out of the strategy. If a profit is reported during your cooldown you do not receive any of it. If a loss is reported you are not affected by it.

    Requesting is an exit, not a queued sale order.

    requestRedeem reverts with RedemptionRequestAlreadyExists if you already have one pending. To exit a position larger than maxRedeemCap, you must go through the full cycle repeatedly: request, wait, collect, request again.

    The vault requires the caller to be the owner of the request. Approving another address does not let it withdraw on your behalf — the standard ERC-4626 allowance flow is intentionally disabled. Calls from anyone else revert with NotAuthorized.

    This means: if you deposit from an address you later lose access to, no other address can recover the position for you.

    redeem(shares) requires shares to equal your request's stored share count exactly. withdraw(assets) requires an exact asset match. Anything else reverts with InvalidWithdrawalRequest.

    Partial collection is not supported. Always read getRedeemRequest and pass the stored value straight back.

    Even after your cooldown ends, collection can fail — because the vault holds no liquidity buffer. The assets to pay you must be pushed back onchain by an operator first.

    You can check whether pending redemptions are currently funded:

    If the balance is below totalRequestedAmount(), not every matured request can be paid right now. The contract cannot force funding — this is an offchain operational step.

    The Manager can call redeemFor to pay out your request, and this path does not check the cooldown. It can only pay you, at the amount already locked in — so it cannot be used to take anything from you — but it can end your position earlier than you planned.

    Error
    Meaning

    RedemptionRequestAlreadyExists

    You already have a pending request

    NoRedemptionRequest

    You called redeem/withdraw without requesting first

    CooldownNotFinished

    The cooldown has not elapsed yet

    InvalidWithdrawalRequest

    The amount does not exactly match your stored request

    NotAuthorized

    cast send <vault> "requestRedeem(uint256)" <shares> \
      --rpc-url <rpc> --private-key $PK
    cast call <vault> "canExecuteRedeem(address)(bool)" <you> --rpc-url <rpc>

    Withdrawing

    Withdrawal does not work the way a standard ERC-4626 vault works. Read this page before you deposit, not after.

    Step 1 — request

    There is no cancel function. Once you request, you are committed to that amount. You cannot undo it, change it, or add to it.

    Step 2 — collect, after the cooldown

    cast call <vault> "getRedeemRequest(address)(uint256,uint256,uint256,bool)" <you> \
      --rpc-url <rpc>
    # returns: shares, assets, timestamp, exists
    cast send <vault> "redeem(uint256,address,address)" <shares> <you> <you> \
      --rpc-url <rpc> --private-key $PK
    cast send <vault> "withdraw(uint256,address,address)" <assets> <you> <you> \
      --rpc-url <rpc> --private-key $PK
    # Total owed to everyone with a pending request
    cast call <vault> "totalRequestedAmount()(uint256)" --rpc-url <rpc>
    
    # What the vault actually holds
    cast call <asset> "balanceOf(address)(uint256)" <vault> --rpc-url <rpc>
    VAULT=<vault>; ASSET=<asset>; ME=<you>; RPC=<rpc>
    
    # 1. See what your shares are worth net of fee
    cast call $VAULT "previewRedeem(uint256)(uint256)" \
      $(cast call $VAULT "balanceOf(address)(uint256)" $ME --rpc-url $RPC) --rpc-url $RPC
    
    # 2. Request the full balance
    SHARES=$(cast call $VAULT "balanceOf(address)(uint256)" $ME --rpc-url $RPC)
    cast send $VAULT "requestRedeem(uint256)" $SHARES --rpc-url $RPC --private-key $PK
    
    # 3. Wait out the cooldown, then check
    cast call $VAULT "canExecuteRedeem(address)(bool)" $ME --rpc-url $RPC
    
    # 4. Read the stored request and collect with the exact value
    cast call $VAULT "getRedeemRequest(address)(uint256,uint256,uint256,bool)" $ME --rpc-url $RPC
    cast send $VAULT "redeem(uint256,address,address)" $SHARES $ME $ME \
      --rpc-url $RPC --private-key $PK

    The rules that catch people out

    Your amount is frozen at request time

    One request at a time

    You must collect it yourself

    The amount must match exactly

    Your redemption may not be payable immediately

    The protocol's own invariant documentation records that "users can always eventually withdraw" does not hold. Withdrawal liveness depends on an offchain actor. See Risks.

    An operator can settle your request early

    Errors you might hit

    Full worked example

    isProfit

    Direction of the report

    What is checked before anything is booked

    Guard
    Effect

    amount <= totalAssets() * maxYieldPercentage / 10_000

    Caps report size — default 50 bps (0.5% of assets)

    feeAmount <= amount * maxFeePercentage / 10_000

    Caps the fee slice — default 5,000 bps (50% of amount)

    nonce == epoch + 1

    Strict sequencing; the primary replay defence

    trxns[proofHash]

    Duplicate rejection, keyed on (vaultToken, amount, nonce, isProfit)

    lastDistributionTime + minDistributionInterval <= block.timestamp

    Rate limit — default 79,200s (~22 hours)

    Note that feeAmount is not part of proofHash, so it does not contribute to the replay identity — the nonce check is what actually prevents a report being submitted twice.

    The accounting the share price is derived from

    Two storage values do all the work:

    totalAssets() is an accounting figure, not a token balance, and is never reconciled against one. Profit is added to virtualAssets immediately but withheld from totalAssets() until it vests — which is what makes the share price rise gradually rather than step.

    On profit

    1

    Outstanding treasury debt is settled first

    If treasuryDebt > 0, up to feeAmount of it is cleared and that portion is redirected to depositors instead of being paid to the treasury. Shareholders receive amount + repaid. The treasury earns nothing new while it owes.

    2

    The shareholders' slice enters the vesting schedule

    transferInRewards(amount + repaid, true) adds the profit to virtualAssets and sets vestingAmount, then stamps lastDistributionTimestamp = block.timestamp.

    From there getUnvestedAmount() decays linearly to zero across vestingPeriod, releasing the profit into totalAssets() as it goes.

    3

    The treasury's fee is minted as shares, split across the schedule

    previewProfitFee(netFee) returns three values:

    • feeShares — priced against the fully vested base (virtualAssets), rounded up, so they are worth exactly netFee once the schedule completes

    amount

    The shareholders' slice of realised P&L

    feeAmount

    The treasury's slice, on top of amount — not carved out of it

    nonce

    distributeYield(uint256 amount, uint256 feeAmount, uint256 nonce, bool isProfit)

    Epoch number; must equal epoch + 1 exactly

    virtualAssets        — every asset the vault believes it is owed
    getUnvestedAmount()  — profit reported but not yet released
    
    totalAssets()        = virtualAssets - getUnvestedAmount()
    share price          = totalAssets() / totalSupply()   (with ERC-4626 virtual-share offset)

    feeAmount being additive rather than deductive is the detail most people get wrong. A report of amount = 1000, feeAmount = 500 means the strategy realised 1,500 in total: 1,000 to depositors, 500 to the treasury. The vault books both.

    Events and Errors

    Events and errors

    Errors you may encounter

    All contracts use custom errors. If your wallet shows a raw selector, decode it:

    cast 4byte <selector>

    Depositing

    Error
    Meaning
    Fix

    InvalidMinShares

    Deposit below the minimum share threshold

    Deposit more

    InvalidDeposit

    Zero amount, zero shares, or zero receiver

    Check your inputs

    Error
    Meaning
    Fix
    Error
    Meaning
    Fix
    Error
    Meaning
    Error
    Meaning
    Event
    Emitted when
    Event
    Contract
    Meaning
    Event
    Contract
    Event
    Contract
    Meaning

    FAQ

    FAQ

    Depositing

    Is there a fee to deposit?

    No. Entry is free, and there is no ongoing management fee. The only fee you pay as a depositor is the exit fee on redemption, capped at 1%.

    Is there a minimum deposit?

    Yes, expressed in shares rather than assets. Read it with minSharesInVaultToken(<vault>) on the Manager. Deposits below it revert with InvalidMinShares.

    Should I time my deposit around a yield report?

    No — there is no advantage. Profit vests linearly over several days precisely so that depositing just before a report earns you almost none of it. You earn roughly in proportion to how long your capital was actually exposed.

    Why did my share balance not increase after a profit was reported?

    Share balances never change on their own. There are no rebases and no auto-compounding transactions — the value of each share rises instead. Check exchangeRate() or previewRedeem, not balanceOf.

    Withdrawing

    How long does a withdrawal take?

    The cooldown is 1 day by default and can be up to 7 days. Read the live value with cooldownPeriod().

    Note that the cooldown is the minimum. Collection also requires the vault to hold enough assets to pay you, which depends on an operator funding it.

    Can I cancel a redemption request?

    No. There is no cancel function. Once you call requestRedeem, your shares are burned and you are committed to that amount.

    I requested a redemption and then a profit was reported. Do I get it?

    No. Your payout was locked in at the moment you requested. You forgo profit reported during your cooldown — and equally, you are insulated from any loss reported during it.

    Requesting is an exit from the strategy, not a queued sale order.

    My cooldown has elapsed but `redeem` reverts. Why?

    Most likely one of:

    1. The vault is unfunded. It holds no liquidity buffer, so assets must be pushed back onchain by an operator before you can collect. Compare totalRequestedAmount() against the vault's actual asset balance.

    2. The amount does not match exactly. redeem

    Can I withdraw part of my request?

    No. Partial collection is not supported — the amount must match the stored request to the wei. Plan the size at request time, not collection time.

    Can someone else withdraw for me?

    No. The vault requires the caller to be the owner of the request, and the standard ERC-4626 allowance flow is deliberately disabled. Approving another address does not help.

    If you lose access to the depositing address, no other address can recover the position.

    Why did `maxWithdraw` tell me I could withdraw more than I can?

    maxWithdraw and maxRedeem are not overridden in this vault and over-report. Ignore them. Use getRedeemRequest and canExecuteRedeem instead.

    This is the most common integration mistake — see Function reference.

    My position is larger than the redemption cap. How do I exit fully?

    Sequentially: request up to the cap, wait out the cooldown, collect, then request again. Only one request can be pending at a time, so a full exit takes multiple cooldown cycles. Factor this in before depositing a large amount — check maxRedeemCap(<vault>).

    Someone redeemed my request before my cooldown ended. Is that normal?

    Yes. The Manager can call redeemFor, and that path does not check the cooldown. It can only pay you, at the amount already locked in, so nothing can be taken from you — but it can end your position earlier than you planned.

    Yield and fees

    Where does the yield come from?

    An offchain trading strategy. Capital is transferred to an offchain counterparty, and returns come from that counterparty's trading activity — not from onchain lending or liquidity provision.

    The vault cannot see the trading book. What you see is the reported result. See Risks.

    Can I verify the reported yield?

    Not directly — that is the core trust assumption. The vault has no view of strategy balances, so profit and loss are figures asserted by an offchain engine.

    What you can verify: the reports themselves are onchain and public. Watch DistributeYield, and compare cumulative profit() against loss() for lifetime reported performance. Each report is capped at 0.5% of vault assets by default, with a minimum ~22 hours between them.

    What happens if the strategy loses money?

    The loss applies to the share price immediately, with no vesting. Profit that has not vested yet absorbs it first — if the loss is smaller than that buffer, the share price does not move at all.

    The treasury also burns its own shares to absorb its proportional share of the loss. If it cannot cover it, the shortfall becomes treasuryDebt, and future performance fees go to depositors until it is repaid.

    What does a non-zero `treasuryDebt` mean?

    That a past loss exceeded what the treasury could absorb, and depositors are currently receiving 100% of reported profit until the debt clears. The treasury earns nothing new while it owes.

    Can the fees change after I deposit?

    Yes, and with no timelock. The exit fee cannot exceed 1% — that ceiling is enforced in the contract. The performance fee cap can be raised to 100% of reported profit.

    Check fee() and maxFeePercentage() before depositing, and watch FeeSet and MaxFeePercentage for changes.

    Risk

    Where are my funds actually held?

    Not in the vault. Deposits are forwarded to the Manager contract immediately and then deployed to an offchain counterparty. The vault holds an accounting record of what you are owed.

    Am I guaranteed to be able to withdraw eventually?

    No. The protocol's own invariant documentation states that "users can always eventually withdraw" does not hold. Withdrawal requires an operator to fund the vault, and an admin pause blocks it entirely. Neither can be forced onchain.

    Can the admin take my funds?

    The admin can call emergencyRecover, which transfers any token out of the vault — including assets already earmarked for pending redemptions. The admin can also whitelist a destination and deploy capital to it in the same block, with no timelock.

    This is why the admin should be a multisig, and why it is worth verifying that yourself with getOwners() and getThreshold(). See Roles.

    Can the contracts change after I deposit?

    Yes. All three are upgradeable, effective immediately, with no timelock. There is no window in which to exit ahead of a change. An upgrade can override every limit described in this documentation, including the 1% fee cap.

    Watch the Upgraded event.

    What is the single biggest risk?

    Counterparty default. Once capital leaves for the offchain strategy, recovery depends on an offchain agreement rather than on code. Everything before that point is verifiable onchain; everything after is not.

    Size your deposit as an allocation to an offchain trading counterparty with an onchain accounting wrapper — not as a self-custodial DeFi position.

    Technical

    Why do my shares have 18 decimals when USDC has 6?

    The vault applies a decimals offset, so shares are always 18 decimals regardless of the underlying asset. Never compare share amounts to asset amounts directly — convert with convertToAssets or convertToShares.

    Is this a standard ERC-4626 vault I can integrate against?

    Not without changes. Three deviations will break a naive integration:

    1. withdraw/redeem require a prior requestRedeem and an elapsed cooldown.

    A transaction reverted with a raw selector. How do I decode it?

    Common ones are listed in Events and errors.

    You are not the owner of the request

    MaxRedeemCapExceeded

    Your request exceeds the per-request cap

    InsufficientShares

    You do not hold the shares you are trying to request

    ERC-20 transfer revert

    The vault is not funded — nothing to pay you with yet

    EnforcedPause

    The vault is paused; withdrawals are blocked

    Above the per-request cap

    Split into several requests

    ZeroAmount

    You passed zero

    —

    You are not the owner of the request

    Only the owner can collect

    ERC-20 transfer revert

    The vault has no assets to pay you

    Wait for the vault to be funded

    Yield

    A loss exceeded what the treasury could absorb

    TreasuryDebtRepaid

    Yield

    Treasury debt settled; profit routed to depositors

    Paused / Unpaused

    Vault

    Vault

    Assets extracted from the vault

    RoleGranted / RoleRevoked

    all three

    Privileged access changed hands

    Upgraded

    all three

    Contract code replaced

    EnforcedPause

    Vault is paused

    Wait for unpause

    RedemptionRequestAlreadyExists

    You already have one pending

    Collect it first

    InsufficientShares

    You do not hold that many shares

    Check balanceOf

    InsufficientAssets

    The quoted payout rounds to zero

    Request more shares

    NoRedemptionRequest

    No request exists for this address

    Call requestRedeem first

    CooldownNotFinished

    Cooldown has not elapsed

    Check canExecuteRedeem

    InvalidWithdrawalRequest

    Amount does not match your request exactly

    Read getRedeemRequest, pass it back verbatim

    NotWhitelisted

    Destination is not on the allowlist (operator-facing)

    OnlyManagerContract / OnlyYieldContract

    Internal call from the wrong contract

    AccessControlUnauthorizedAccount

    Caller lacks the required role

    InvalidEpoch

    Report is out of sequence

    DuplicateTransaction

    This report was already submitted

    DistributionTooFrequent

    Minimum interval has not elapsed

    Deposit

    You deposit

    RedemptionRequested

    Your request is recorded, with the locked amount

    Withdraw

    Your redemption is paid

    WithdrawalExecuted

    A redemption settled via redeemFor

    DistributeYield

    Yield

    An epoch's profit or loss was reported

    TransferRewards

    Vault

    Yield entered the vesting schedule

    LossAbsorbedIntoUnvested

    Vault

    A loss was cancelled against unvested profit

    FeeSet

    Vault

    CooldownPeriodUpdated

    Vault

    VestingPeriodUpdated

    Vault

    MaxRedeemCapSet, MinSharesInVaultTokenSet

    Manager

    MaxYieldPercentageSet, MaxFeePercentage, MinDistributionIntervalSet

    Yield

    WhitelistUpdated

    Manager

    A capital destination was authorised or revoked

    BatchExecuted

    Manager

    Capital deployed, with full targets and calldata

    TreasurySet

    Manager

    Fee destination changed

    Requesting a redemption

    Collecting

    InvalidWithdrawalRequest is the most common error. Partial withdrawal is not supported — the amount must match the stored request to the wei.

    Access control

    Yield reporting

    The two percentage caps on distributeYield are plain require statements with no message. A report rejected for exceeding the per-epoch or fee cap reverts with no reason string — this is a known rough edge, not a malfunction.

    Events

    Your activity

    Things that affect your position

    Things that change your terms

    Governance and control

    Upgraded, RoleGranted, and WhitelistUpdated all take effect immediately — there is no timelock, so monitoring them is reactive rather than preventative.

    MaxRedeemCapExceeded

    NotAuthorized

    TreasuryDebtAccrued

    EmergencyRecovery

    recognisedFee — the most that can enter totalAssets() right now without the mint moving the share price, rounded down

  • vestingFee — the remainder, added to the same vesting schedule as everyone else's profit

  • The treasury is paid in full, but on the same timetable as depositors rather than ahead of them. Pricing the shares against the recognised base instead would hand the treasury extra shares that then capture part of the depositors' profit as it vests.

    On loss

    Losses are applied instantly, with no vesting — the assets are already gone, so withholding the write-down would leave the vault overstating itself while redemptions kept settling against the inflated price.

    1

    Unvested profit absorbs the loss first

    _absorbLossIntoUnvested(amount) cancels the loss against profit that has not vested yet. That profit has been credited to nobody, so destroying it costs no holder anything.

    If the loss fits entirely inside the unvested buffer, the recognised share price does not move at all:

    The surviving profit keeps its original vesting end date — vestingAmount is rescaled against the elapsed fraction and lastDistributionTimestamp is deliberately left untouched, rather than restarting the clock.

    2

    The remainder reduces the share price immediately

    Whatever the buffer could not absorb is subtracted from virtualAssets, and the share price drops in the same transaction.

    3

    The treasury burns its own shares to absorb its slice

    feeAmount worth of treasury shares are burned — the mirror of the fee it earns on profit.

    The burn is clamped to the treasury's actual balance. Treasury shares are ordinary ERC-20 shares it can transfer or redeem at any time, so burning unconditionally would revert the entire loss report whenever the treasury had been swept — leaving the vault priced above its real value while redemptions kept settling.

    4

    Any shortfall becomes treasuryDebt

    If the treasury could not cover its slice, the uncovered portion is written down against depositors now (the assets are gone regardless) and recorded as treasuryDebt rather than being silently socialised. Future performance fees repay it before the treasury is paid again.

    A new profit report restarts the vesting clock for profit already in flight. vestingAmount is set to new + still-unvested, and the timestamp resets — so a previously reported profit that was partway through vesting is re-spread across a fresh full period.

    requires the exact stored share count. Read
    getRedeemRequest
    and pass that value back verbatim.
  • The vault is paused. Pause blocks withdrawals as well as deposits.

  • maxWithdraw/maxRedeem over-report.
  • Allowance-based withdrawal is disabled — caller must equal owner.

  • totalAssets() is also an accounting figure, not a token balance. See Function reference.

    totalAssets = (virtualAssets - amount) - (unvested - absorbed)
                = virtualAssets - unvested        ← unchanged
    cast 4byte <selector>

    How TOWN governance works

    The TOWN token is the governance token of the TownSquare Protocol.

    On a high-level, the Token is designed with the following utilities:

    • Governance voting

      • Incentive voting

        • Emission incentive voting

      • Parameter voting

        • Risk, fee & revenue structure

        • Protocol settings

    Note: TOWN confers no dividend, profit-share, redemption, or revenue rights.


    • Lock for TOWN. Any holder can lock TOWN to receive locked TOWN.

    • Longer locks, more power. The longer the lock, the more voting power the position carries.

    • Delegation. locked TOWN voting power can be delegated to another address, so holders can vote through community delegates.

    Through locked TOWN, holders participate in five principal governance areas:

    1. Sector expansion and asset listings

    Vote to approve supported sectors, subsectors, asset categories and credit markets. Potential sectors include:

    Approval of a sector establishes its eligibility framework. Individual assets and financing opportunities remain subject to the applicable underwriting, verification and investment terms.

    2. Credit financing and risk management

    Vote on the protocol-level frameworks governing financing, with the following sub-aspects:

    3. Fee structures and treasury allocation

    Vote on prospective protocol fee policies and allocation of eligible treasury resources among operations, reserves, security, research, development, integrations, ecosystem grants and incentives.

    4. Incentive emission - voting on ecosystem incentive

    Voters can vote on the gauge (pool, vault, or deposit type) the emission incentives get distributed to, as well as reward budgets, eligible markets, campaign duration and other distribution criteria.

    5. Protocol management and governance settings

    Vote on protocol upgrades, delegated committee mandates, proposal thresholds, voting delegation, quorum, timelocks and bounded emergency powers.

    Governance proposals undergo public discussion and relevant credit and technical assessment, followed by community voting. Executable changes proceed through binding on-chain approval and a timelock; authorized off-chain actions follow the documented governance mandate.

    Governance frameworks allow flexibility for investment-specific subscription terms. Their application remains subject to the applicable terms agreed among the investor, asset owner and auditor. Financing, pricing, collateral, fees, liquidity and settlement arrangements may therefore differ between investments.

    Governance decisions do not automatically amend existing investment agreements. Any change affecting an existing investment must follow the approvals, consent requirements and amendment procedures specified in its governing documents.

    • Votes set the split. locked TOWN holders allocate their votes across pools, vaults, and deposits. Each of the pools, vaults and deposit type (gauge) receives TOWN emissions in proportion to its share of votes.

    • Emissions reach depositors. Depositors in a gauge's pool or vault earn TOWN on top of the yield of the underlying asset.

    • Emission schedule. Emissions come from the vote escrow emission allocation and are released quarterly. All future emissions are subject to governance.

    • Lower fees. RWA borrowers through locked TOWN can reduce interest fees and origination fees, subject to governance approval.

    • Governance rights. Holders vote on risk parameters of community-driven pools, vault listings, additions of new chains, fee parameters, as well as where the emission incentive go to.

    TOWN is deployed on Base, Ethereum, BNB Chain, Xlayer and Monad, and moves between them through Chainlink CCIP token pools, so veTOWN can direct emissions to gauges on more than one chain.


    • Gauges only for approved assets. Only townRWA credits that have passed TownSquare's audit and underwriting, and vaults that meet listing standards, can have a gauge. Votes allocate incentives among approved options; they do not approve credit.

    • Eligibility still applies. Emissions to a townRWA vault reach only depositors eligible to hold townRWA, meaning whitelisted institutional and professional investors outside the United States.

    • Governed emissions. Emission levels and listings remain subject to governance, so allocations can be adjusted if votes concentrate in ways that do not serve the protocol.

    Invoice financing, purchase orders, inventory financing and import/export receivables.

    SME and commercial finance

    Working capital, franchise financing, business expansion and commercial contract receivables.

    Transportation and logistics

    Commercial fleets, shipping, aviation assets, warehousing and logistics receivables.

    Healthcare and life sciences

    Medical equipment, healthcare-provider receivables, clinics, diagnostic facilities and pharmaceutical supply chains.

    Agriculture and food systems

    Agricultural equipment, crop and inventory financing, food processing and agricultural trade receivables.

    Digital infrastructure and telecommunications

    Fiber networks, telecommunications towers, broadband infrastructure and connectivity-service receivables.

    Intellectual property and royalties

    Financing backed by eligible music royalties, licensing income, media contracts and other verifiable contractual receivables.

    General policies for subscription windows, withdrawal notices, redemption cycles and settlement procedures, accommodating each investment’s asset liquidity and agreed terms.

    Sector

    Examples of financing opportunities

    AI

    GPUs, data centers, compute providers, AI-service receivables, robotics, autonomous systems and robotic equipment deployment.

    Consumer credit

    Auto finance, consumer loans, installment-payment receivables and residential mortgage credit.

    Real estate

    Commercial and residential property credit, construction financing, bridge loans and rental-income-backed financing.

    Hard assets and equipment

    Industrial machinery, mining assets, gold-backed credit, equipment leasing and other asset-backed facilities.

    Energy and utilities

    Renewable energy, power generation, battery storage, grid infrastructure and contracted energy receivables.

    Sub-aspect

    Governance scope

    Credit LTV, collateral and pricing parameters

    Initial and maintenance LTV limits, collateral haircuts, advance rates, collateral requirements, reference rates, interest spreads, risk premiums and tenor-based pricing.

    Underwriting methodology

    Risk-grading frameworks, debt-service coverage, leverage limits, stress assumptions, eligibility criteria and required financial evidence.

    Valuation and monitoring

    Valuation methods, approved data sources, appraisal frequency, collateral verification, reporting requirements and responses to unreliable information.

    Financing capacity and concentration

    Financing and issuance caps by market, sector, subsector, borrower group and geography, together with conditions for adjusting exposure.

    Utilization, liquidity and reserves

    Capital deployment ratios, liquid buffers, reserve targets and conditions for expanding financing capacity.

    The mechanism

    Locking

    Governance voting

    Voting and emissions

    What veTOWN holders receive

    Across chains

    Guardrails

    Trade and supply chains

    Subscription, redemption and settlement frameworks

    Vault Manager API

    If you curate a vault on TowneSquare, this API lets you see every redemption request against it, who asked, how much, and whether the cooldown has finished so the withdrawal can be settled.

    Everything here is read-only. Nothing in this API moves funds.

    Before you start

    Base URL

    https://vault-indexer.townesquare.xyz

    Authentication

    Every request needs your API key in the x-api-key header. TowneSquare issues one key per curator, contact the team to get yours.

    curl -H 'x-api-key: YOUR_API_KEY' \
      'https://vault-indexer.townesquare.xyz/vaults'

    Send only the key itself. Keep it server-side: anyone holding it can read your vault data, and a key placed in browser JavaScript is public.

    Response shape

    Every response uses the same envelope:

    {
      "status": "success",
      "data": { },
      "message": "ok"
    }

    On failure, status is "error", data is null, and message explains what went wrong. Always read your results from data.

    All numeric values are returned as strings, not JSON numbers. Token amounts and timestamps exceed the range JavaScript can represent exactly, so parse them with BigInt rather than Number.

    A vault is identified by its chain and its contract address. Filters accept three formats:

    Format
    Example
    Matches

    Always qualify with a chain if the same address is deployed on more than one network, which is common.

    Supported chains

    Chain name
    Chain ID

    To list all vaults:

    This is the endpoint you will use most. Filter it to your vault and choose a status.

    Query parameters

    Parameter
    Description

    What each status means

    Status
    Meaning

    open is not the same as claimable. Use open for the full outstanding liability of your vault, and claimable for what is due right now.

    Requests against a Base vault that are ready to settle:

    Field
    Notes

    shares and assets use different decimals. assets is denominated in the underlying token, so always divide by vault.assetDecimals — not by vault.decimals — when displaying a withdrawal amount.

    assets is fixed when the request is made and never changes afterwards, so it reflects the exchange rate at request time, not today's.

    Everything outstanding against your vault

    Only what is due now

    Still within cooldown

    Sort by secondsUntilClaimable on your side to see what ripens next.

    One wallet's request in your vault

    A wallet's history across every vault and chain

    Your vault's current configuration

    Returns name, symbol, decimals, underlying asset, manager, cooldown period, fee, and whether the vault is paused.

    One row per vault, so you can size the queue without paging through requests.

    Each row carries totalRequests, openRequests, claimableRequests, completedRequests, uniqueUsers, and the matching openAssets, claimableAssets and completedAssets sums. Asset sums are scaled by assetDecimals.

    Use claimableAssets to know how much underlying you need on hand to clear the queue right now, and openAssets for the full outstanding obligation.

    Results cap at limit rows, default 100, maximum 1000. Page with offset:

    Rows are ordered newest request first. count is the number of rows in the current page, not the total — keep paging until a page returns fewer rows than your limit.

    Code
    Meaning

    All errors use the standard envelope:

    Cooldown changes apply retroactively. If the vault's cooldown period is updated, cooldownSeconds and claimableAt are rewritten on every request still open in that vault. A request can become claimable earlier or later than when it was created. Re-read rather than caching claimableAt indefinitely.

    Timestamps are unix seconds, not milliseconds. Multiply by 1000 for JavaScript Date.

    A brand-new vault returns 404 from /vaults/{chainId}/{address} until its first event is indexed. Use /vaults/registry to confirm a vault is configured.

    status is computed when you call. A request that reads cooling now will read claimable once its claimableAt passes, with no on-chain event in between. Poll rather than treating a status as final.

    0xADDRESS

    0x27B1E0…7CFA

    That address on every chain

    chainId:0xADDRESS

    8453:0x27B1E0…7CFA

    That address on one chain

    chainName:0xADDRESS

    base:0x27B1E0…7CFA

    Same, using the chain name

    ethereum

    1

    base

    8453

    arbitrum

    42161

    bsc

    56

    monadMainnet

    curl -H 'x-api-key: YOUR_API_KEY' \
      'https://vault-indexer.townesquare.xyz/vaults/registry'
    GET /redemptions

    vault

    Vault reference. Repeat or comma-separate for several

    chain / chainId

    Narrow to one chain

    user

    Only this wallet's requests

    status

    open, cooling, claimable, or completed

    limit

    1–1000, default 100

    cooling

    Requested, cooldown still running. Not yet withdrawable

    claimable

    Cooldown finished, waiting to be settled – your action queue

    completed

    Already withdrawn

    open

    Everything not yet completed: cooling plus claimable

    curl -H 'x-api-key: YOUR_API_KEY' \
      'https://vault-indexer.townesquare.xyz/redemptions?vault=base:0x27B1E0FC9eeBFcA90d7BDe3958723fa0aB937CFA&status=claimable&limit=50'
    {
      "status": "success",
      "data": {
        "items": [
          {
            "id": "8453-0x27b1e0fc9eebfca90d7bde3958723fa0ab937cfa-0xabc…-14",
            "chainId": 8453,
            "vaultAddress": "0x27b1e0fc9eebfca90d7bde3958723fa0ab937cfa",
            "user": "0xd0b0794a79e57559547cc8eb8a51ed041656dae23",
            "shares": "1000000000000000000",
            "assets": "1024500000",
            "requestedAt": "1757500800",
            "requestedBlock": "49700000",
            "requestedTx": "0xabc…",
            "cooldownSeconds": "604800",
            "claimableAt": "1758105600",
            "completedAt": null,
            "completedBlock": null,
            "completedTx": null,
            "receiver": null,
            "caller": null,
            "fulfilledBy": null,
            "status": "claimable",
            "secondsUntilClaimable": "0",
            "vault": {
              "symbol": "rwaUSD",
              "decimals": 18,
              "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "assetSymbol": "USDC",
              "assetDecimals": 6
            }
          }
        ],
        "limit": 50,
        "offset": 0,
        "count": 1
      },
      "message": "ok"
    }

    id

    Stable identifier, unchanged across chain reorganisations

    user

    Wallet that requested the redemption

    shares

    Vault shares burned. Scaled by vault.decimals

    assets

    Underlying owed. Scaled by vault.assetDecimals

    requestedAt

    /redemptions?vault=base:0xYOUR_VAULT&status=open
    /redemptions?vault=base:0xYOUR_VAULT&status=claimable
    /redemptions?vault=base:0xYOUR_VAULT&status=cooling
    /redemptions?vault=base:0xYOUR_VAULT&user=0xWALLET
    /users/0xWALLET/redemptions
    /vaults/8453/0xYOUR_VAULT
    GET /stats
    curl -H 'x-api-key: YOUR_API_KEY' \
      'https://vault-indexer.townesquare.xyz/stats?vault=base:0xYOUR_VAULT'
    /redemptions?vault=base:0xYOUR_VAULT&status=open&limit=100&offset=100

    400

    Bad parameter — message names the problem

    401

    Missing or invalid x-api-key

    404

    No indexed data for that vault. A deployed vault with no activity yet returns this

    429

    Rate limited. Wait Retry-After seconds

    503

    Service not accepting requests — contact TowneSquare

    {
      "status": "error",
      "data": null,
      "message": "limit must be an integer in 1..1000"
    }

    Identifying your vault

    Pending withdrawals

    Example

    Field reference

    Common queries

    Totals

    Paging through results

    Errors

    Things worth knowing

    143

    xlayer

    196

    robinhood

    4663

    ink

    57073

    pharos

    1672

    offset

    Skip this many rows, default 0

    Unix seconds when the request was made

    cooldownSeconds

    Cooldown applied to this request

    claimableAt

    requestedAt + cooldownSeconds

    completedAt

    null until the withdrawal settles

    receiver

    Where funds went. May differ from user

    fulfilledBy

    self if the user withdrew, operator if settled for them

    status

    Computed per request at the time you call

    secondsUntilClaimable

    Time remaining. 0 unless cooling

    vault

    Metadata needed to format the amounts above

    Resolver

    Resolver

    A schema in the Ethereum Attestation Service (EAS) can name a resolver: a contract that EAS calls every time someone attests or revokes under that schema. If the resolver rejects the request, the whole transaction fails and nothing is recorded.

    TownSquare's resolver makes sure that only TownSquare-approved addresses can attest or revoke under its schemas. Anyone can still read and verify the attestations; only the writing is restricted.

    What it does

    • Allowlisted attesters. An attestation is accepted only if the address making it holds the attester role.

    • Allowlisted revokers. A revocation is accepted only if the attester holds the revoke role. EAS separately requires that only the original attester can revoke, so both conditions must hold.

    • Controlled administration. One admin address grants and removes roles. Handing over the admin role takes two steps and a waiting period.

    • No ETH. The resolver does not accept ETH, so no payment can be attached to an attestation or sent to the contract.

    1. An attester submits an attestation to the EAS contract under a TownSquare schema.

    2. EAS sees the resolver named in the schema and calls the resolver's attest function.

    3. The resolver checks that the caller is the EAS contract, then checks whether the attester holds ATTESTER_ROLE.

    4. If it does, EAS records the attestation. If it does not, EAS reverts with

    Revocations follow the same path through revoke, with the check against REVOKE_ROLE.

    The contract is short. Most of its behavior comes from two audited libraries, pinned to fixed versions:

    • EAS SchemaResolver v1.4.0. The standard base contract for EAS resolvers. It receives calls from EAS and passes each attestation or revocation to the checks TownSquare defines.

    • OpenZeppelin AccessControlDefaultAdminRules v5.7.0. Role-based permissions with extra safeguards around the admin role.

    The contract is written in Solidity 0.8.28.

    The admin does not hold the attester or revoke role automatically. Each must be granted separately.

    The checks look at the attester recorded in the attestation, not at the caller, because the caller is always the EAS contract itself.

    Any call to attest, multiAttest, revoke or multiRevoke from an address other than EAS fails with AccessDenied, so the checks cannot be bypassed by calling the resolver directly.

    Checking roles

    Managing roles

    Admin handover

    • Only approved addresses can write. An attestation under a TownSquare schema from any other address is rejected by EAS before it is recorded.

    • Removing a role stops new attestations. If an attester's role is removed, it can no longer attest. Attestations it already made stay on the chain unless they are revoked.

    • The admin cannot change hands silently. A new admin must be proposed, wait out the delay, and accept the role itself, which leaves time to notice and cancel an unexpected change.

    • Revocation depends on the schema. The revoke role matters only for schemas and attestations marked revocable. The live townREIT attestation, for example, is not revocable.

    InvalidAttestation
    and nothing is recorded.

    Role

    Held by

    What it allows

    DEFAULT_ADMIN_ROLE

    One admin address

    Grant and remove the attester and revoke roles; manage the admin handover

    ATTESTER_ROLE

    Approved attesting addresses

    Make attestations under schemas that use this resolver

    REVOKE_ROLE

    Approved attesting addresses

    Revoke attestations they made, where the schema and attestation allow revocation

    Function

    Visibility

    What it does

    constructor(IEAS eas, address defaultAdmin)

    Runs once at deployment

    Links the resolver to the EAS contract on that chain and sets the first admin. Fixes the admin handover delay at 1 hour. Reverts if the EAS address is zero.

    ATTESTER_ROLE()

    Public, read-only

    Returns the identifier of the attester role.

    REVOKE_ROLE()

    Public, read-only

    Returns the identifier of the revoke role.

    onAttest(attestation, value)

    Internal

    Function

    Who can call

    What it does

    attest(attestation)

    EAS contract only

    Entry point for a single attestation. Passes it to onAttest.

    multiAttest(attestations, values)

    EAS contract only

    Entry point for a batch. Checks each attestation in turn; if any one fails, the whole batch is rejected.

    revoke(attestation)

    EAS contract only

    Entry point for a single revocation. Passes it to onRevoke.

    multiRevoke(attestations, values)

    EAS contract only

    Function

    Who can call

    What it does

    hasRole(role, account)

    Anyone, read-only

    Returns whether an address holds a role.

    getRoleAdmin(role)

    Anyone, read-only

    Returns the role that manages a given role. For the attester and revoke roles this is the admin role.

    DEFAULT_ADMIN_ROLE()

    Anyone, read-only

    Returns the identifier of the admin role.

    supportsInterface(interfaceId)

    Anyone, read-only

    Function

    Who can call

    What it does

    grantRole(role, account)

    Admin

    Gives an address the attester or revoke role. Cannot be used for the admin role.

    revokeRole(role, account)

    Admin

    Removes the attester or revoke role from an address. Cannot be used for the admin role.

    renounceRole(role, account)

    The role holder

    Lets an address give up its own role. The admin can renounce only through the scheduled handover process.

    Function

    Who can call

    What it does

    defaultAdmin()

    Anyone, read-only

    Returns the current admin address.

    owner()

    Anyone, read-only

    Returns the same address as defaultAdmin().

    pendingDefaultAdmin()

    Anyone, read-only

    Returns any proposed new admin and when the handover can complete.

    beginDefaultAdminTransfer(newAdmin)

    How an attestation passes through it

    Building blocks

    Roles

    Functions defined by TownSquare

    Functions inherited from EAS SchemaResolver

    Functions inherited from OpenZeppelin access control

    What this means in practice

    Called for every attestation. Returns true only if attestation.attester holds ATTESTER_ROLE.

    onRevoke(attestation, value)

    Internal

    Called for every revocation. Returns true only if attestation.attester holds REVOKE_ROLE.

    Entry point for a batch of revocations, with the same all-or-nothing rule.

    isPayable()

    Anyone, read-only

    Returns false: the resolver does not accept ETH.

    receive()

    Anyone

    Rejects any ETH sent directly to the contract.

    version()

    Anyone, read-only

    Returns the version of the EAS resolver base, 1.4.0.

    Reports which standard interfaces the contract supports.

    Admin

    Proposes a new admin. The handover can complete only after the delay, currently 1 hour.

    acceptDefaultAdminTransfer()

    Proposed new admin

    Completes the handover once the delay has passed. The new admin must accept it actively.

    cancelDefaultAdminTransfer()

    Admin

    Cancels a proposed handover.

    defaultAdminDelay()

    Anyone, read-only

    Returns the current handover delay.

    pendingDefaultAdminDelay()

    Anyone, read-only

    Returns any scheduled change to the delay and when it takes effect.

    changeDefaultAdminDelay(newDelay)

    Admin

    Schedules a change to the handover delay.

    rollbackDefaultAdminDelay()

    Admin

    Cancels a scheduled delay change.

    defaultAdminDelayIncreaseWait()

    Anyone, read-only

    Returns the maximum wait before a longer delay takes effect: 5 days.

    Roles

    Roles and permissions

    Five privileged roles across three contracts, plus a handful of functions that only the protocol's own contracts can call. This page is the user-facing summary — the complete enumeration with line references lives in docs/ROLES.md in the repository.

    Governance and Admin sit behind a 48-hour timelock. DEFAULT_ADMIN_ROLE and ADMIN_ROLE are held by a TimelockController on all three contracts, so every function in those two sections is scheduled publicly and can only execute 48 hours later. The Safe proposes and executes, and holds GUARDIAN_ROLE for the two actions that stay instant. Operator and Rebalancer are operational and have no delay. See Governance and the timelock.

    Summary

    Role
    Holder
    Can move assets
    Can move share price

    Governance (DEFAULT_ADMIN_ROLE)

    Timelock (48h)

    Yes — via upgrade

    The clean way to hold it in your head:

    Operator controls where the money physically is. Rebalancer controls what the books say it is worth. Admin decides the rules. Governance decides the code. Guardian can only stop things.

    Where each role exists:

    Role
    Vault
    Manager
    Yield

    DEFAULT_ADMIN_ROLE. Upgrade authority over all three contracts, and the admin of every other role. No contract calls _setRoleAdmin, so this one role can grant and revoke all of them.

    Function
    Contracts
    What it does

    An upgrade can replace any contract with arbitrary code, which subsumes every other limit in this documentation — including the hard-coded 1% exit fee cap.

    ADMIN_ROLE. Governance parameters, plus powers over custody and the pause switch.

    Function
    What it does
    Function
    What it does
    Function
    What it does

    GUARDIAN_ROLE, on the vault and the Manager, held by the Safe. It exists because the timelock applies one delay to everything, and two emergency actions cannot wait 48 hours.

    Function
    Contract
    What it does

    It is deliberately asymmetric. It can pause but not unpause, and remove whitelist entries but not add them. It cannot change any parameter, upgrade anything, or grant itself anything. The worst a compromised Guardian achieves is a denial of service that the timelock can undo — it can never create a path for funds to leave.

    OPERATOR_ROLE, on the Manager only. This role holds the keys to the address custodying every deposited asset.

    Function
    What it does

    Cannot: change the whitelist, grant roles, upgrade, pause, set parameters, or report yield.

    REBALANCER_ROLE, on Yield only.

    Function
    What it does

    It sets the share price. There is no oracle — the vault books what it is told, bounded by the per-epoch cap, the minimum interval, strict epoch sequencing, and duplicate rejection. The figures themselves are unverifiable onchain.

    Cannot: move any asset, change the whitelist, grant roles, upgrade, pause, or set parameters. Its entire surface is the accounting.

    These are not roles. Each function checks msg.sender against another protocol contract's address, so no person or key can call them directly — only the contract named. They are listed because the addresses they trust are set by Admin (setManager, setManagerAndYield).

    Function
    On
    Only callable by
    What it does
    Compromised
    Consequence
    Bounded by

    Role holders are onchain state. Do not take them from documentation — read them.

    The contracts use plain AccessControl, not the Enumerable variant, so there is no getRoleMember or getRoleMemberCount. To list every holder of a role, replay its grant history:

    Then check each account with hasRole — a later RoleRevoked may have removed it.

    If a holder is a Safe, getOwners() and getThreshold() give the real signing requirement. The Governance and Admin holder should be the timelock, not the Safe — Governance has the full check. Watch RoleGranted and RoleRevoked for rotations; for anything behind the timelock, a CallScheduled event on the timelock warns 48 hours ahead.

    1. The timelock delays, it does not prevent. Whitelisting, upgrades, and role rotations now take 48 hours and are public, but one Safe is still proposer, executor, canceller and guardian. It can also pause instantly and unpausing takes 48 hours, so a pause can block depositors from exiting during a pending change. See Governance and the timelock.

    2. Admin mixes risk parameters with custody powers. setFee and emergencyRecover sit behind the same role, so parameter management cannot be delegated without also delegating fund extraction. The timelock delays both but does not separate them.

    3. The whitelist setter and the fund mover may be the same key. They must be distinct for the whitelist to function as a control.

    Two parameters are unbounded in the direction that matters — the performance fee can reach 100%, and the reporting interval can be dropped to one second — while having no maximum, so reporting can also stop entirely with no staleness check.

    Yes — via upgrade

    Admin (ADMIN_ROLE)

    Timelock (48h)

    Yes — emergencyRecover, whitelist

    Indirectly, via parameters

    Guardian (GUARDIAN_ROLE)

    Safe (instant)

    No

    No

    Operator (OPERATOR_ROLE)

    Executor

    Yes — execute

    No

    Rebalancer (REBALANCER_ROLE)

    Offchain engine

    No

    Yes — entirely

    DEFAULT_ADMIN_ROLE

    ✓

    ✓

    ✓

    ADMIN_ROLE

    ✓

    ✓

    ✓

    upgradeToAndCall(newImplementation, data)

    all three

    Replaces the contract's code behind its proxy, optionally running a call on the new code in the same transaction.

    grantRole(role, account)

    all three

    Gives account any role on that contract — including DEFAULT_ADMIN_ROLE itself.

    revokeRole(role, account)

    all three

    Removes any role from any account.

    setFee(newFee)

    Sets the exit fee charged on redemption. Reverts above 1% (1e18).

    setCooldownPeriod(newPeriod)

    Sets how long a redemption request must wait before it can be collected. Reverts above 7 days.

    setVestingPeriod(newPeriod)

    Sets how long reported profit takes to reach the share price. Reverts above 30 days. Profit still in flight is re-spread across the new period from now.

    setManager(newManager)

    Repoints the vault at a different Manager contract — which controls minting, burning and asset bookkeeping.

    pause()

    Blocks deposits and withdrawals, including operator-settled redemptions. Shared with the Guardian.

    setWhitelistedAddresses(wallets[], statuses[])

    Adds or removes destinations the Operator may call through execute. Refuses the zero address and the protocol's own contracts, and refuses to run before the vault address is set.

    removeWhitelistedAddresses(wallets[])

    Removal-only version of the above. Shared with the Guardian.

    setTreasury(treasury)

    Changes where performance and exit fees are minted — and whose shares are burned on a loss.

    setManagerAndYield(yield, vault)

    Repoints the Manager at a different Yield contract and vault. (Despite the name, it sets Yield and the vault.) Refuses addresses that are currently whitelisted.

    setMinSharesInVaultToken(vault, minShares)

    Sets the minimum shares a deposit must mint. Must be non-zero.

    setMaxYieldPercentage(bps)

    Caps each report's amount as a share of the vault's recognised assets, in basis points. Must be between 1 and 10,000. Default 50 (0.5%).

    setMaxFeePercentage(bps)

    Caps each report's feeAmount as a share of amount, in basis points. Up to 10,000 (100%). Default 5,000 (50%).

    setMinDistributionInterval(seconds)

    Sets the minimum gap between reports. Must be non-zero; no other floor. Default 79,200s (22 hours).

    setManager(manager)

    Repoints Yield at a different Manager.

    pause()

    Vault

    Halts deposits and withdrawals immediately.

    removeWhitelistedAddresses(wallets[])

    Manager

    Cuts off capital destinations immediately. Can only ever write false.

    execute(targets[], data[])

    Makes arbitrary calls to whitelisted addresses, batched, from the Manager. Within the whitelist there is no amount cap, no per-destination cap, and no rate limit. This is how capital reaches the offchain strategy.

    transferToVault(token, amount)

    Pushes assets from the Manager back into the vault so redemptions can be paid. This is the function your withdrawal depends on. It emits no event.

    redeemFor(vault, user)

    Settles a user's redemption request. Bounded: it can only pay that user, at the amount already locked in. It does not check the cooldown, so it can settle a request early. Blocked while paused.

    distributeYield(amount, feeAmount, nonce, isProfit)

    Reports one epoch's profit or loss. amount goes to shareholders and feeAmount to the treasury, as two separate slices. nonce must be exactly epoch + 1. See How profit and loss reach your shares.

    transferInRewards(amount, profit)

    Vault

    Yield

    Puts profit on the vesting schedule, or applies a loss.

    updateTotalAssets(amount, add)

    Vault

    Manager

    Moves virtualAssets up or down.

    Rebalancer

    Mispriced redemptions; value leaks gradually

    0.5%/epoch, ~22h interval

    Operator

    Assets sent to whitelisted destinations

    The whitelist

    Guardian

    Vault paused, whitelist emptied — a denial of service

    Admin can unpause and re-whitelist, after 48h

    # Does <address> hold ADMIN_ROLE on this proxy?
    cast call <proxy> "hasRole(bytes32,address)(bool)" \
      $(cast keccak "ADMIN_ROLE") <address> --rpc-url <rpc>
    
    # DEFAULT_ADMIN_ROLE is the zero hash, not keccak("DEFAULT_ADMIN_ROLE")
    cast call <proxy> "hasRole(bytes32,address)(bool)" \
      0x0000000000000000000000000000000000000000000000000000000000000000 <address> --rpc-url <rpc>
    cast logs --address <proxy> --from-block <deploy-block> \
      "RoleGranted(bytes32,address,address)" $(cast keccak "OPERATOR_ROLE") --rpc-url <rpc>

    Governance

    renounceRole(role, yourself) is also callable by any role holder, but only to give up a role it holds itself. It is not a power over anyone else.

    Admin

    Vault

    Manager

    Yield

    Admin both sets the whitelist and can extract assets. The whitelist therefore constrains the operator, not the admin.

    Guardian

    Operator

    Rebalancer

    Contract-only functions

    If a role were compromised

    Verifying who holds what

    Known weaknesses in the current separation

    GUARDIAN_ROLE

    ✓

    ✓

    —

    OPERATOR_ROLE

    —

    ✓

    —

    REBALANCER_ROLE

    —

    —

    ✓

    unpause()

    Lifts the pause. Admin only — the Guardian cannot.

    emergencyRecover(token, amount, recipient)

    Transfers any token or ETH held by the vault to any address — including assets earmarked for pending redemptions.

    setMaxRedeemCap(vault, cap)

    Sets the largest amount of assets a single redemption request may be for. 0 removes the cap.

    mintVaultToken(to, shares)

    Vault

    Manager

    Mints shares — and only to the treasury.

    burnVaultToken(from, shares)

    Vault

    Manager

    Burns shares — and only from the treasury.

    redeemFor(user)

    Vault

    Manager

    The vault side of the Operator's redeemFor.

    manageAssetAndShares(to, order)

    Manager

    Yield

    Books the treasury's fee: adjusts assets, then mints or burns treasury shares.

    Admin

    Whitelist any address then extract; 100% fee

    48h public delay — needs the Safe to propose

    Governance

    Total — can grant itself every role, or upgrade

    48h public delay — needs the Safe to propose

    Roles and Permissions

    Roles & Permissions

    Companion to ARCHITECTURE.md, written for auditors and counterparty diligence. This document enumerates every privileged role across the three proxies, every function each role can call, and what each role can and cannot cause to happen.

    Every entry is sourced from the code. Where a capability is operational policy rather than an onchain constraint, it is marked as such.

    Summary

    Role
    Contracts
    Intended holder
    Can move assets
    Can move share price

    Role constants:

    Role
    Value

    All three contracts use OpenZeppelin AccessControlUpgradeable. DEFAULT_ADMIN_ROLE is the admin of every other role, so it can grant and revoke ADMIN_ROLE, OPERATOR_ROLE and REBALANCER_ROLE at will, on any of the three proxies, with no delay.


    Highest privilege. Holds two distinct powers.

    _authorizeUpgrade(address) — TownSqToken.sol:115, Manager.sol:68, Yield.sol:93

    All three contracts are UUPS. DEFAULT_ADMIN_ROLE can replace the implementation of any of them with arbitrary code, after the 48-hour timelock delay and with no upgrade-safety check enforced onchain. This subsumes every other capability in this document: a malicious upgrade can mint shares, rewrite accounting, or transfer custodied assets.

    grantRole / revokeRole on all five roles, across all three proxies. Effective after the 48-hour timelock delay.

    Consequence: DEFAULT_ADMIN_ROLE is the root of trust for the entire protocol. It is held by the timelock, whose only proposer is the Safe — so the Safe's signing threshold, plus 48 hours of public notice, is what stands between the protocol and a hostile upgrade.


    Governance parameters plus two custody-adjacent powers. Note the mix — this role is not separable into "risk only" as currently written.

    Function
    Effect
    Bound

    Two of these are not risk parameters:

    • emergencyRecover can withdraw assets already earmarked for pending redemptions. totalRequestedAmount is not consulted. See KNOWN_ISSUES.md.

    • setManager repoints the address authorised to call updateTotalAssets, mintVaultToken and burnVaultToken. A hostile Manager can forge vault accounting.

    Function
    Line
    Effect
    Bound

    setWhitelistedAddresses is the most consequential ADMIN_ROLE function. The whitelist is the only constraint on where custodied assets can be sent by OPERATOR_ROLE. Additions go through the 48-hour timelock, so a new destination is public 48 hours before capital can reach it.

    The guard at L107 is load-bearing — it prevents whitelisting townSqToken or yield, which would otherwise let OPERATOR_ROLE reach mintVaultToken and updateTotalAssets through execute and forge share supply.

    Function
    Line
    Effect
    Bound

    setMaxFeePercentage accepts up to 10_000 — 100% of reported profit assignable to the treasury, after the 48-hour delay. Unlike the exit fee's hard-coded 1% ceiling, there is no structural bound here.

    setMinDistributionInterval rejects 0 (L117) but accepts 1, so the rate limit protecting against a compromised rebalancer can be reduced to a single second. There is also no maximum interval and no staleness check anywhere: nothing obliges the rebalancer to report at all, and if reporting stops the share price simply freezes at its last value.


    Manager only. Three functions. This role controls where the assets physically are.

    Arbitrary calldata to any whitelisted target, batched, executed from the address custodying 100% of deposited assets. Within the whitelist the operator can:

    • transfer any amount of any asset to any whitelisted address

    • grant unlimited ERC-20 approvals to whitelisted targets

    • call any function with any arguments on any whitelisted contract

    • batch all of the above atomically

    No amount cap, no per-target cap, no rate limit, no reentrancy guard. The whitelist and the L107 guard are the only constraints. This is the function through which capital leaves onchain infrastructure for the offchain trading book.

    Pushes assets from Manager custody into the vault so pending redemptions can settle. The return leg of the flow.

    This function is what makes withdrawal liveness an offchain dependency: per INVARIANTS.md I-22, "users can always eventually withdraw" does not hold. A user past cooldown cannot exit until an operator calls this, or until any address sends a plain ERC-20 transfer to the vault.

    No zero-amount check, no event emitted, no NatSpec — the only function in Manager lacking all three.

    Executes a matured redemption on a user's behalf. Fully bounded: requires an existing request, cooldown elapsed, and pays the quoted amount to that user only (TownSqToken.sol:492-500). Cannot redirect funds or alter amounts. A UX convenience.

    Change the whitelist, grant roles, upgrade, pause, set parameters, set the treasury, report yield, or mint/burn shares.


    Yield only. One function. This role controls what the books say the assets are worth.

    There is no oracle in this system. totalAssets() moves only through deposits, redemptions, and this call. The rebalancer asserts P&L; the vault books it.

    Effects:

    • On profit: amount enters the linear vesting schedule for shareholders; feeAmount is minted to the treasury as shares, split into recognisedFee (credited immediately) and vestingFee (rides the same schedule) so the recognised share price does not step up.

    • On loss: amount is debited instantly with no vesting; treasury shares are burned to absorb feeAmount, clamped to the treasury's actual balance, with any uncovered remainder booked to

    Constraints, in full:

    Guard
    Line
    Effect

    Two notes on these guards:

    • proofHash hashes (vaultToken, amount, nonce, isProfit) — feeAmount is excluded from the replay identity. The nonce check is what actually prevents replay.

    • The two requires at L176-177 carry no message and no custom error, unlike every other check in the file. A distribution rejected by a cap reverts with no reason string.

    Move any asset, change the whitelist, grant roles, upgrade, pause, or set parameters. Its entire surface is the accounting.


    The intended split:

    OPERATOR_ROLE controls where the money is. REBALANCER_ROLE controls what the books say it is worth. ADMIN_ROLE decides the rules. DEFAULT_ADMIN_ROLE decides the code.

    Compromise analysis:

    Compromised role
    Consequence
    Bounded by

    Known weaknesses in the current separation:

    1. The timelock delays, it does not prevent. One Safe is proposer, executor, canceller and guardian. It can pause instantly while unpausing takes 48 hours, so a pause can remove depositors' exit window during a pending change.

    2. ADMIN_ROLE mixes risk parameters with custody powers. setFee and emergencyRecover sit behind the same role, so delegating parameter management is impossible without delegating fund extraction. This is the gap a CURATOR_ROLE would fill.


    Live. The handover batch has executed.

    DEFAULT_ADMIN_ROLE and ADMIN_ROLE moved from the Safe to an OpenZeppelin TimelockController with a 48-hour minDelay, deployed with admin == address(0) so no standing bypass exists. There is no code coupling — no contract imports or stores the timelock address. The vault sees a call from an address holding ADMIN_ROLE and has no idea a delay occurred.

    Upgrades inherit the delay at no cost: _authorizeUpgrade was already onlyRole(DEFAULT_ADMIN_ROLE), so the role move is sufficient.

    GUARDIAN_ROLE = keccak256("GUARDIAN_ROLE"), declared on TownSqToken and Manager. It exists only because TimelockController applies one uniform delay and two actions cannot tolerate it.

    Can
    Cannot

    The asymmetry is the point: a compromised guardian can only cause a denial of service that ADMIN_ROLE can undo. It can never open a path for funds to leave, and it can never lift a halt it caused. Pause-fast/resume-slow is deliberate — pause blocks user withdrawals (K-01), so lifting it should carry the delay and the visibility.

    Role
    Holder
    Delay

    The operational roles are deliberately untouched. A 48-hour delay on execute or distributeYield would break normal operation, and neither can change the rules. script/TimelockRoleChange.s.sol asserts at runtime that its batch never touches either.

    Every privileged action emits. Useful for monitoring and for diligence evidence.

    Event
    Contract
    Signals

    Two monitoring gaps:

    • Manager.transferToVault emits nothing. Redemption funding — the step withdrawal liveness depends on — is observable only via the underlying ERC-20 Transfer.

    • AssetsWithdrawn is declared in IManager but never emitted anywhere in src/. Do not build monitoring against it.

    Note also that Yield's fee-cap event is named MaxFeePercentage, not MaxFeePercentageSet — it breaks the naming convention every other setter event follows.

  • pause blocks the exit path, not just entry (KNOWN_ISSUES.md K-01), so it is a fund-freezing power rather than a purely defensive one.

  • treasuryDebt
    .
  • Debt settlement: outstanding treasuryDebt is repaid out of future feeAmount and routed to shareholders before the treasury earns anything new (L201-207).

  • ADMIN_ROLE and OPERATOR_ROLE may be the same key. The whitelist setter and the fund mover must be distinct for the whitelist to function as a control.
  • setMaxFeePercentage and setMinDistributionInterval are unbounded in the directions that matter (100% fee; a 1-second interval, and no maximum interval or staleness check at all).

  • DEFAULT_ADMIN_ROLE

    all three

    TimelockController (48h)

    Yes (via upgrade, emergencyRecover)

    Yes (via upgrade)

    ADMIN_ROLE

    all three

    TimelockController (48h)

    Yes (emergencyRecover, whitelist)

    Indirectly (parameters)

    GUARDIAN_ROLE

    TownSqToken, Manager

    Safe

    No

    No

    OPERATOR_ROLE

    Manager

    Executor (bot/Safe)

    Yes (execute)

    No

    REBALANCER_ROLE

    Yield

    Offchain yield engine

    No

    Yes (entirely)

    DEFAULT_ADMIN_ROLE

    0x00

    ADMIN_ROLE

    keccak256("ADMIN_ROLE")

    OPERATOR_ROLE

    keccak256("OPERATOR_ROLE")

    REBALANCER_ROLE

    keccak256("REBALANCER_ROLE")

    setFee

    Exit fee charged on redemption

    <= ONE_PERCENT (1%), hard-coded

    setCooldownPeriod

    Delay between request and withdrawal

    <= 7 days, hard-coded

    setVestingPeriod

    Linear profit vesting window

    <= 30 days, hard-coded

    setWhitelistedAddresses

    L100

    The strategy/destination allowlist

    cannot whitelist townSqToken or yield (L107)

    setTreasury

    L75

    Destination for all fee accrual

    non-zero only

    setMaxYieldPercentage

    L122

    Cap on reported P&L per epoch

    1..10_000 bps of totalAssets(); default 50 = 0.5%

    setMaxFeePercentage

    L128

    Performance fee share of profit

    <= 10_000 bps; default 5000 = 50%

    setMinDistributionInterval

    if (!whitelistedAddresses[targets[i]]) revert Errors.NotWhitelisted();
    (bool success, bytes memory result) = targets[i].call(data[i]);

    amount <= totalAssets * maxYieldPercentage / 10_000

    L176

    Default 0.5% of TVL per epoch

    feeAmount <= amount * maxFeePercentage / 10_000

    L177

    Default 50% of profit

    nonce == epoch + 1

    L180

    Strictly sequential; primary replay defence

    REBALANCER_ROLE

    Mispriced redemptions; value leaks gradually

    0.5%/epoch, 22h interval

    OPERATOR_ROLE

    Assets sent to whitelisted destinations

    The whitelist

    GUARDIAN_ROLE

    Vault paused, whitelist emptied — denial of service

    ADMIN_ROLE can undo, after 48h

    pause() (TownSqToken.sol)

    unpause()

    removeWhitelistedAddresses() (Manager.sol)

    setWhitelistedAddresses()

    Any parameter, upgrade, or role grant

    DEFAULT_ADMIN_ROLE

    TimelockController

    48h

    ADMIN_ROLE

    TimelockController

    48h

    GUARDIAN_ROLE

    Safe

    none — pause, whitelist removal only

    WhitelistUpdated

    Manager

    Destination allowlist change

    BatchExecuted

    Manager

    execute call, with full targets and calldata

    TreasurySet

    Manager

    Fee destination change

    DEFAULT_ADMIN_ROLE

    Upgrade authority

    Role administration

    ADMIN_ROLE

    TownSqToken

    Manager

    Yield

    OPERATOR_ROLE

    execute(address[] targets, bytes[] data) — Manager.sol:119-140

    transferToVault(address token, uint256 amount) — Manager.sol:194-196

    redeemFor(address _townSqUSD, address _user) — Manager.sol:147-150

    What OPERATOR_ROLE cannot do

    REBALANCER_ROLE

    distributeYield(uint256 amount, uint256 feeAmount, uint256 nonce, bool isProfit) — Yield.sol:171-281

    What REBALANCER_ROLE cannot do

    Separation of duties

    Timelock model

    What changed

    The fifth role

    Roles now

    Events

    setManager

    Repoints the Manager address

    non-zero only

    pause / unpause

    Halts deposit, withdraw, redeem, redeemFor, requestRedeem. pause is shared with GUARDIAN_ROLE; unpause is admin-only

    none

    emergencyRecover

    Transfers any ERC-20 or native balance out of the vault

    balance only

    setManagerAndYield

    L86

    Repoints Yield and TownSqToken

    non-zero only

    setMaxRedeemCap

    L168

    Max assets per redemption request

    none; 0 == uncapped

    setMinSharesInVaultToken

    L157

    Minimum shares per deposit

    must be non-zero

    removeWhitelistedAddresses

    L152

    Removes allowlist entries

    removal only; shared with GUARDIAN_ROLE

    L116

    Minimum spacing between epochs

    none

    setManager

    L138

    Repoints the Manager address

    —

    trxns[proofHash]

    L182-184

    Duplicate rejection

    lastDistributionTime + minDistributionInterval

    L186-188

    Default 79200s (22h)

    ADMIN_ROLE

    Whitelist any address, then emergencyRecover; 100% fee

    48h public delay; Safe must propose

    DEFAULT_ADMIN_ROLE

    Total; can grant itself every other role or upgrade

    48h public delay; Safe must propose

    OPERATOR_ROLE

    Executor

    none — unchanged

    REBALANCER_ROLE

    Offchain engine

    none — unchanged

    MaxRedeemCapSet, MinSharesInVaultTokenSet

    Manager

    Capacity parameter change

    DistributeYield

    Yield

    Epoch P&L report

    TreasuryDebtAccrued, TreasuryDebtRepaid

    Yield

    Unabsorbed loss / settlement

    MaxYieldPercentageSet, MaxFeePercentage, MinDistributionIntervalSet

    Yield

    Yield parameter change

    FeeSet, CooldownPeriodUpdated, VestingPeriodUpdated

    TownSqToken

    Vault parameter change

    EmergencyRecovery

    TownSqToken

    Asset extraction

    Paused, Unpaused

    TownSqToken

    Pause state (OZ Pausable)

    RoleGranted, RoleRevoked

    all three

    Role rotation (OZ AccessControl)

    Upgraded

    all three

    Implementation change (OZ ERC1967)