hashgraph / hashgraph/asset-tokenization-studio
Whitelist-mode security tokens block the issuer's own address from minting — undocumented
- Dominant language
- TypeScript
- Stars
- 33
- Forks
- 28
- Avg merge
- 15h 36m
- Merged PRs (30d)
- 8
Description
### Summary
Deploying an Equity (or Bond) with `isWhiteList: true`, then immediately
calling `Security.issue` / the diamond's `mint()` to the admin/deployer
account that just created the token, reverts with
`AccountIsBlocked(address)`.
### Why this is surprising
In whitelist mode, *every* holder — including the issuer itself — must be
explicitly added via `addToControlList` before it can receive tokens.
This isn't mentioned in the SDK README's "Minting" or "Deploy a new
Equity" use-case sections, and it's an easy first-mint failure for anyone
following the docs literally: deploy an Equity, try to mint to yourself
to seed initial supply, get a cryptic custom-error revert with no
matching guidance in the docs.
We only found the cause by decoding the raw revert selector
(`AccountIsBlocked(address)`) against the contracts' own `error`
declarations in `packages/ats/contracts/contracts/infrastructure/errors/ICommonErrors.sol`.
### Suggested fix
Add a note to the "Minting" use-case section (and/or the "Deploy a new
Equity"/"Deploy a new Bond" sections) along the lines of: *"If the asset
was deployed with `isWhiteList: true`, the recipient — including the
issuer, if minting to itself — must first be added via
`Security.addToControlList` (requires the Control List Role)."*
### What we did instead
Called `addToControlList` for the admin address immediately after
deployment, before the first mint. Full writeup:
https://github.com/fabian4819/Stratus-Finance/blob/main/docs/phase-0-findings.md
### Environment
- `@hashgraph/asset-tokenization-contracts` v8.0.0
Contributor guide
Research direction
Start in the SDK README's "Minting" and deployment use-case sections, and review packages/ats/contracts/contracts/infrastructure/errors/ICommonErrors.sol for the AccountIsBlocked(address) error. Document that whitelist-mode assets require Security.addToControlList for every recipient, including the issuer, before minting; done means the affected sections explain the required step and role.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- solidity, typescript
- Domain
- blockchain, documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100