Skip to main content
The issuer-signed flow lets the controller approve the record with a signature, and your platform carries it. Trusset checks the signature and the controller’s role on chain when the record is saved. The controller’s wallet never becomes a wallet of your instance, so it gets none of your instance’s platform roles and no approval power over your other clients’ tokens.
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:
It commits to the token, the chain, the carrying instance, the exact content, the record version and the time. Replayed into another instance it fails, because the instance is in the message. After any change to the record it fails with 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 to signer, 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: true replaces 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.

Cost

Two calls per save, the approval request and the save, each one credit within the write limit of 10 requests per minute per API key. Verification costs one signature recovery and one multicall for a wallet, and two more chain reads for a contract wallet.