The issuer app keeps its own rule: it offers Start Setup only when a verified wallet of the instance controls the token. A record for a token your instance does not control comes through this flow.
The five steps
1
Import the token
Import Token. Detect Token already answers
instrumentAuthority.holds: false for a token your instance does not control.2
Ask what to sign
Request Instrument Approval with the record body
{ instrument, documents }. It validates the body exactly like the save, writes nothing and returns message, recordVersion and signedAt.3
Have the controller sign
The issuer signs
message with the controlling wallet in your app: personal_sign (EIP-191) for a wallet, or the contract wallet’s own signing flow for a Safe, which Trusset checks through ERC-1271.4
Save
Save Instrument with the same body plus
issuerApproval: { signer, signature, recordVersion, signedAt }. Add takeOver: true when the approval request answered takeOverRequired: true.5
Read it back
Get Instrument shows the record asserted by your instance on the controller’s authority, with the signature kept in its provenance.
TypeScript
What the signature binds
The message the controller signs reads:ISSUER_APPROVAL_STALE. After ten minutes it fails with ISSUER_APPROVAL_EXPIRED. With altered content it fails with ISSUER_SIGNATURE_INVALID.
The content digest
Content digest is keccak256 over the UTF-8 bytes of the canonical JSON of the record content: the instrument, documents and presentation members your body carries, as sent. A body with none of them and takeOver: true signs {"takeOver":true}.
Canonical JSON follows RFC 8785: object keys sorted, no whitespace, strings escaped as JSON.stringify escapes them, which leaves non-ASCII characters as they are. In Python that is json.dumps(content, sort_keys=True, separators=(",", ":"), ensure_ascii=False). The approval request returns the digest anyway, so your platform only has to send the same body twice.
What Trusset checks at the save
The signature recovers tosigner, or the signer contract confirms it through ERC-1271. Then the signer’s role is read on chain: owner(), isAgent(signer) or hasRole(DEFAULT_ADMIN_ROLE, signer). A former owner or a revoked agent is refused with ISSUER_NOT_CONTROLLER, which names the current owner() when the contract answers one. Other AccessControl roles and ONCHAINID management keys do not count as control.
How it behaves around other writers
- Two controllers. An owner and an agent can both sign. The last valid signed save wins, and each one is bound to the version it saw.
- A record another instance asserts. An issuer-signed save with
takeOver: truereplaces it, even while that instance still holds a role, because the controller’s signature is the strongest authority there is. - Release. The asserting instance can release the record without a signature.
- Your own overview. Your instance edits its overview with Update Profile whether or not it controls the token.
