Skip to content

docs: add ATS bond issuance page under Solutions Finance Workflows - #810

Merged
mgarbs merged 7 commits into
hashgraph:mainfrom
web3buidlerz:docs/solutions-ats-bond
Nov 4, 2026
Merged

mgarbs merged 7 commits into
hashgraph:mainfrom
web3buidlerz:docs/solutions-ats-bond

Conversation

@web3buidlerz

@web3buidlerz web3buidlerz commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

What this adds

A third Solutions → Finance Workflows page, paired with a scaffold-hbar template that runs on testnet.

Issue a tokenised bond with Asset Tokenization Studio issues an ERC-1400 bond through the ATS v8 testnet factory, approves the investors allowed to hold it with the bond's control list in allowlist mode, and distributes it with issue. The learner deploys no contracts: one factory call creates the bond as a Diamond proxy over the resolver's shared logic.

Section Covers
Overview What a tokenised bond is; factory, resolver and Diamond proxy; ERC-1400; actors and lifecycle
Issue the bond Resolving the bond configuration version, the deployBond structure with roles and allowlist mode, reading the bond back
Approve investors and distribute addToControlList, issue, and an unapproved investor refused with AccountIsBlocked
Hold and transfer with MetaMask ATS bonds are EVM contracts: a wallet investor holds and transfers under the same allowlist
Going to production KYC and ERC-3643, custody for the roles, coupons and maturity

The paired template installs with:

npx create-scaffold-hbar@latest --template web3buidlerz/hedera-finance-templates#templates/ats-bond

Validation

  • mint broken-links — no broken links
  • .github/scripts/check-mdx-compiles.js — page compiles
  • .github/scripts/check-terminology.sh — no retired terms
  • docs.json parses as valid JSON

@mintlify

mintlify Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit fc5b4ed.

Approve preview

@web3buidlerz
web3buidlerz marked this pull request as ready for review October 27, 2026 13:32
@web3buidlerz
web3buidlerz requested review from a team as code owners October 27, 2026 13:32
@web3buidlerz
web3buidlerz marked this pull request as draft October 27, 2026 13:41
@web3buidlerz
web3buidlerz marked this pull request as ready for review October 27, 2026 14:09
Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
The page taught the approach the template has just stopped using, and the reason
it stopped is the part worth teaching.

`simulateContract` returns the new bond's address, and keeping it looks free. But
a CREATE address is computed against the state at simulation time and this
factory is shared by everyone on testnet, so another deployment landing in
between changes it — and an app that trusts the prediction then rejects its own
successful deployment and abandons a bond it has already paid 7.4 HBAR for.

The old text also said the event "only indexes the deployer, so the app takes
the address from the simulation", which draws the wrong conclusion from a true
fact: not being indexed means you cannot filter logs by it, not that it is
unavailable. `bondAddress` is in the event's data, and so is the `bondData` the
bond was created with — which is where the page's start date now comes from.

Three other additions, each a thing the template now does and a reader would
want to know:

- what a failed read shows, and why `Not approved` / `0` is the one fallback a
  compliance desk must never have
- that auto-creating a demo investor's account measures 607,858 gas against a
  plain transfer's 21,000, which is what makes each one cost about 1.1 HBAR
- the decoded refusal appears in `#action-error`, not only in the activity log

Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
Both were mine, and both had grown into walls. Step 3 had five paragraphs, two
of them long enough that the reader loses the thread before the point arrives.

- The getters move into a table. A list of eight method names reads better as
  rows than as a sentence with commas.
- The failed-read behaviour becomes a Note of four sentences instead of a
  paragraph of six. It is a rule, not a discussion, and the callout gives the
  section a visual break where it previously had none.
- Auto-creation and its cost are two short sentences rather than one long one
  with an "it" that could have meant the account or the creation.
- The deployment Warning says the same thing in one paragraph instead of two.

293 words of prose down to 178 in Step 3, 129 to 85 in the Warning; nothing
removed but the repetition.

Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
The template now lives in the Hedera org repo, with every branch pushed and
the name no longer carrying its capital I. The card and the install command
point there rather than at a personal fork.

Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
Signed-off-by: web3buidlerz <seba@buidlerlabs.com>
@web3buidlerz
web3buidlerz force-pushed the docs/solutions-ats-bond branch 2 times, most recently from 0ed6f8c to a973896 Compare October 27, 2026 15:06
@mintlify

mintlify Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
hedera-docs 🟢 Ready View Preview Nov 4, 2026, 4:35 PM

Signed-off-by: Michael Garber <michael.garber@hashgraph.com>

# Conflicts:
#	docs.json
@mgarbs
mgarbs merged commit 43efb18 into hashgraph:main Nov 4, 2026
11 checks passed

* A **factory** creates each bond as a new [Diamond (EIP-2535)](https://eips.ethereum.org/EIPS/eip-2535) proxy. One call to `deployBond` gives you a complete security: roles, control lists, maturity, nominal value, corporate-action support.
* A **Business Logic Resolver** holds the shared, audited logic every bond points to, by configuration and version. Bonds get upgrades without being redeployed.
* Each bond implements **ERC-1400**, the security-token standard: ERC-20 compatible, with issuance controlled by roles and transfers checked against compliance rules.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it ERC-3643 as well?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants