Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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.
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.
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.
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.
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.


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.




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 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 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 Yield Reference
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.
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.
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.
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 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

The premium has thinned. Large onchain credit products now yield 4% to 5%. On 31 August the 30-year Treasury paid 5.25%.

┌──────────────────────┐
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.
Full enumeration in Roles and permissions.
You
Deposit, request redemption, collect your own redemption
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.
Asset owners (borrowers). Companies that own the underlying assets, such as a data center, a mine or a gold vault, and borrow against them.
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.
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.
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.
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.
Subscription. Eligible institutional investors subscribe to the credit from whitelisted addresses.
Issuance and distribution. At origination, all tokens for the credit are minted within the issuance cap and distributed to the subscribers.
Holding and transfer. Holders keep the tokens or transfer them to other whitelisted addresses.
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.
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.
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
—
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.

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
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.
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
0x884B12aAf42a586932bba1ce5E1D475AF49EBCc7
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.
requestRedeem(uint256)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.
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.
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.
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.
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
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.
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.
Three things per vault:
The chain and the vault contract address.
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.
The vault ABI. Ask us for it, or pull the verified ABI from the explorer.
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.
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]
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.
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.
The vault lends 1,000,000 USDC to a trading team under a credit facility.
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.
If the price rises 10%, the spot leg gains 50,000 and the short loses 50,000. The position's value is unchanged.
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.
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.
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:
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.
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.
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.
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.
Define the data. The fields to be attested are set by TownSquare's townRWA schema.
Sign. TownSquare signs the data with its attesting address.
Store onchain. The attestation is recorded through EAS on Base, Robinhood Chain or Monad.
Verify. Anyone can check the signature against TownSquare's attesting address and read the data.
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.
Reference. A later attestation, such as a revaluation, can reference the earlier one to show how the record has developed.
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.
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.
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.
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.
Depositing is standard ERC-4626 and works as you would expect. Approve the vault, then deposit.
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.
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.
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.
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.
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.

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
cast call <manager> "minSharesInVaultToken(address)(uint256)" <vault> --rpc-url <rpc>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 $RPCWho 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)
The investor connects its whitelisted wallet to the app.
It reviews the credit's offering documents and subscription terms.
It submits a subscription and pays the subscription amount as the terms require.
At origination, its townRWA tokens are minted and delivered to its wallet.
Offchain (by agreement)
The investor reviews the offering documents and signs the subscription agreement.
It pays the subscription amount as the agreement requires.
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.
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 youSteps 3 and 6 depend on offchain actors. Everything else you control yourself.
The protocol is three upgradeable contracts, each with one job.
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.
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:
The strategy's performance is not visible onchain. The vault has no view of the trading book. What you see is the reported result.
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.
There are two fees in the protocol. Only one is charged to you directly.
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
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.

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
On each profit report
# 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>description: Operational runbook for the OPERATOR_ROLE holder deploying capital and funding redemptions.
OPERATOR_ROLE holds three functions on the Manager:
execute(targets[], data[])
Deploy capital to whitelisted destinations
transferToVault(token, amount)
Return capital so redemptions can be paid
redeemFor(vault, user)
false reverts with AccessControlUnauthorizedAccount.
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:
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.
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.
Description: Operational runbook for the REBALANCER_ROLE holder reporting each epoch's realised P&L.
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.
YIELD=<yield proxy>
VAULT=<vault proxy>
RPC=<rpc url>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.
amount <= totalAssets() * maxYieldPercentage / 10_000. Default maxYieldPercentage is 50 = 0.5% of recognised assets.
feeAmount <= amount * maxFeePercentage / 10_000. Default 5000 = 50% of amount — not of total realised P&L.
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%:
A successful call means the guards pass. It does not validate that your figures are economically correct — only that they are accepted.
Confirm the DistributeYield event carries the figures you intended.
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:
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.
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.
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.
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.
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.

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
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
amount
trxns[proofHash] unseen
Redemption backlog
# 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> $MANAGERcast call $MANAGER "execute(address[],bytes[])(bytes[])" \
"[<target1>,<target2>]" "[<data1>,<data2>]" \
--from <operator> --rpc-url $RPCcast 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 $RPCMANAGER=<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 $RPCcast call $MANAGER "whitelistedAddresses(address)(bool)" <target> --rpc-url $RPCcast logs --address $MANAGER "WhitelistUpdated(address,address,bool)" \
--from-block <deployment block> --rpc-url $RPCcast 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 $PKcast send $MANAGER "redeemFor(address,address)" $VAULT <user> \
--rpc-url $RPC --private-key $PKcast call $YIELD "lastDistributionTime()(uint256)" --rpc-url $RPC
cast call $YIELD "minDistributionInterval()(uint256)" --rpc-url $RPC
cast block latest -f timestamp --rpc-url $RPCcast call $VAULT "totalAssets()(uint256)" --rpc-url $RPC
cast call $YIELD "maxYieldPercentage()(uint256)" --rpc-url $RPCcast call $YIELD "maxFeePercentage()(uint256)" --rpc-url $RPCcast call $YIELD "distributeYield(uint256,uint256,uint256,bool)" \
<amount> <feeAmount> <nonce> <isProfit> \
--from <rebalancer> --rpc-url $RPCcast send $YIELD "distributeYield(uint256,uint256,uint256,bool)" \
<amount> <feeAmount> <nonce> <isProfit> \
--rpc-url $RPC --private-key $PKcast 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 treasuryPeriodic, 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.
Functions available to you as a depositor, plus the standard ERC-4626 surface and where it deviates.
deposit(uint256 assets, address receiver) → uint256 sharesStandard. 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 assetsStandard. Mints an exact share count, pulling however many assets that requires.
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.
On the Yield contract:
Listed so you know they exist and who controls them:
Withdrawing is two steps with a mandatory waiting period between them.
Three things happen immediately:
Your shares are burned. They are gone from your balance right away.
Your payout is calculated and locked in, at the current share price, net of the exit fee.
The cooldown timer starts.
Check whether your request has matured:
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

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
Exit fee, 1e18 = 1%
previewWithdraw / previewRedeem
distributeYield
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.
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 $PKcast call <vault> "canExecuteRedeem(address)(bool)" <you> --rpc-url <rpc>cast call <vault> "getRedeemRequest(address)(uint256,uint256,uint256,bool)" <you> \
--rpc-url <rpc>
# returns: shares, assets, timestamp, existscast send <vault> "redeem(uint256,address,address)" <shares> <you> <you> \
--rpc-url <rpc> --private-key $PKcast 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 $PKisProfit
Direction of the report
What is checked before anything is booked
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
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.
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.
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
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)All contracts use custom errors. If your wallet shows a raw selector, decode it:
cast 4byte <selector>InvalidMinShares
Deposit below the minimum share threshold
Deposit more
InvalidDeposit
Zero amount, zero shares, or zero receiver
Check your inputs
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
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.
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.
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.
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.
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.
getRedeemRequestThe 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 ← unchangedcast 4byte <selector>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.
Trade and supply chains
Subscription, redemption and settlement frameworks
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.
Base URL
https://vault-indexer.townesquare.xyzAuthentication
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
BigIntrather thanNumber.
A vault is identified by its chain and its contract address. Filters accept three formats:
Always qualify with a chain if the same address is deployed on more than one network, which is common.
Supported chains
To list all vaults:
This is the endpoint you will use most. Filter it to your vault and choose a status.
Query parameters
What each status means
openis not the same asclaimable. Useopenfor the full outstanding liability of your vault, andclaimablefor what is due right now.
Requests against a Base vault that are ready to settle:
sharesandassetsuse different decimals.assetsis denominated in the underlying token, so always divide byvault.assetDecimals— not byvault.decimals— when displaying a withdrawal amount.
assetsis 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.
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 /redemptionsvault
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_VAULTGET /statscurl -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=100400
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"
}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
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.
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.
An attester submits an attestation to the EAS contract under a TownSquare schema.
EAS sees the resolver named in the schema and calls the resolver's attest function.
The resolver checks that the caller is the EAS contract, then checks whether the attester holds ATTESTER_ROLE.
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.
InvalidAttestationRole
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)
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.
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 (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:
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.
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.
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.
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.
Cannot: change the whitelist, grant roles, upgrade, pause, set parameters, or report yield.
REBALANCER_ROLE, on Yield only.
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).
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.
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.
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.
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>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
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.
Role constants:
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.
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.
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.
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:
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_ROLEcontrols where the money is.REBALANCER_ROLEcontrols what the books say it is worth.ADMIN_ROLEdecides the rules.DEFAULT_ADMIN_ROLEdecides the code.
Compromise analysis:
Known weaknesses in the current separation:
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.
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.
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.
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.
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.
treasuryDebtDebt 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
distributeYield(uint256 amount, uint256 feeAmount, uint256 nonce, bool isProfit) — Yield.sol:171-281setManager
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)