Skip to main content

Goldsky

Onchain shareholder register for transfer agents

Talk to our team

What is an onchain shareholder register?

An onchain shareholder register, also called a tokenized shareholder register, is a transfer agent’s official list of who owns a tokenized fund or stock, kept in step with every transfer of the token.

Transfer agents run it because the chain records wallets and balances while the legal record of ownership names investors, and the two have to agree every time shares move.

Goldsky decodes each mint, burn and transfer of the token, streams it into your database and keeps each holder’s balance there; your team books the official register.

You can keep an onchain shareholder register two ways: stream every transfer into your own database with Turbo Pipelines, or have a subgraph on Goldsky Subgraphs keep each holder’s balance and serve it over GraphQL.

Who keeps an onchain shareholder register?

Transfer agents, tokenization platforms and asset managers that issue a fund or stock as a token and keep its legal register of holders.

How an onchain shareholder register stays current

The diagram follows one holding from the investor’s identity check to its entry in the official register, and shows who does each step. Your setup may differ.

Your business, step 1: KYC/KYB providerVerify the investorWallet linked to a checked identity
Blockchains, step 2: Shares change handsA fund or stock token moves wallets
Goldsky, steps 3–4: TurboDecode every transferMints, burns and transfers, in your database
Your business, step 7: Book the official registerYour records name each holder
Goldsky, steps 5–6: TurboKeep each holder’s balanceCredits and debits summed per holder
  • Goldsky
  • Your provider

Ways to keep an onchain shareholder register

A stream lands every transfer in your database and keeps each holder’s balance there, beside the register; the subgraph keeps each holder’s balance through mappings you write and serves it over GraphQL.

Usual setupOption 1: Stream to your database
Best for
A register in your own database, on one chain or several
Products
Turbo
What you run
The destination: your database, queue or bucket, or a Postgres database Goldsky hosts
What you write
Pipeline YAML and SQL; TypeScript transforms when needed
Where your data lives
In your own database or systems
How results reach you
Pushed to you
Option 2: Hosted holder index
Best for
One chain per token, queried by holder from an API
Products
Subgraphs
What you run
Nothing; Goldsky runs indexing, storage and the API
What you write
A schema and mapping handlers, or a no-code or low-code config for simple contracts
Where your data lives
Hosted by Goldsky
How results reach you
You query; changes are pushed

Option 1: Keep an onchain shareholder register by streaming transfers

A pipeline decodes every mint, burn and transfer of the token, writes it to the database your register runs on and keeps each holder’s balance there. Your team books those balances to the register.

When to stream transfers into your register database

The register already runs on your own database, or the token is issued on more than one chain, and you want every transfer next to the records you book from.

What you’ll need

  • Goldsky Turbo
  • An identity verification provider
  • The token’s contract address and ABI on each chain it’s issued on
  • A database for the transfer rows and balances
  • Your register system of record

  1. Verify the investor

    A security can only be registered to an investor the issuer has checked, so each wallet is linked to a verified identity before it can hold shares.

    Your identity verification provider checks the investor, and the wallet they’ll use is recorded against that identity, often in an identity registry the token itself checks. A wallet that holds shares with no verified investor behind it is a holder the register can’t name.

  2. Record each change of ownership on the chain

    Every issue, redemption and transfer of the token is recorded on the chain, which is where the register reads ownership changes from.

    A mint creates new shares in a wallet, a burn removes them, and a transfer moves them between wallets. For a short time the newest blocks can still be rewritten (a reorg), so a move seen once isn’t settled yet.

  3. Decode every transfer of the token

    Handled by Goldsky Turbo

    The chain stores each event as encoded data, so it has to be decoded into readable fields: who sent, who received and how much.

    Every mint, burn and transfer has to be decoded with the token’s contract definition (its ABI). For a permissioned token, the events that link a wallet to an identity matter too, or the register sees addresses and can’t name the investors behind them.

    In Turbo Pipelines, a SQL transform decodes raw logs with _gs_log_decode and the token’s ABI. For an ERC-3643 token, decode identity events such as IdentityRegistered in the same pipeline, so each holder links to a verified identity.

    Decode event logs in SQL (opens in a new tab)

  4. Land every transfer in your database

    Handled by Goldsky Turbo

    The register needs each holder’s balance, and every transfer changes two balances: the sender’s goes down and the recipient’s goes up.

    Write each transfer as a credit to the recipient and a debit from the sender, each with its own ID, so two identical transfers aren’t merged into one. Mints have no sender and burns have no recipient, so skipping the empty address keeps them from adjusting a holder that doesn’t exist.

    Goldsky’s Turbo Pipelines can emit a credit row and a debit row for every transfer, with -in and -out added to the id and the debit’s amount negative, and write them to a database table with a primary_key.

    Build a holder registry (opens in a new tab)

  5. Correct the rows after a reorg

    Handled by Goldsky Turbo

    When the chain replaces its newest blocks, a transfer you recorded can disappear or change.

    The rows have to follow the chain, removing or updating any transfer the reorg undid. If they don’t, the register shows shares in a wallet that never received them.

    Reorg corrections pass through the pipeline as deletes and updates, and a database sink with a primary_key applies them to the same rows. A repeated delivery after a restart overwrites the row it already wrote.

    How reorgs reach your database (opens in a new tab)

  6. Keep each holder’s balance current

    Handled by Goldsky Turbo

    The register books balances, so the transfer rows have to be added up per holder.

    Each credit and debit has to change its holder’s balance as it arrives, and a transfer a reorg removes has to come back out. Holders who sold everything keep a balance of zero, so the register leaves them out.

    The same pipeline can also write the rows to Turbo Pipelines’ postgres_aggregate sink, which keeps running totals in a Postgres database: group by holder and token with sum on the amount, and a trigger updates each balance as rows land and subtracts a row a reorg deletes, provided the rows keep the _gs_op column.

    Keep running totals in your database (opens in a new tab)

  7. Book the official register

    The register is the legal record of ownership, so it names investors, and the onchain balances have to be carried into it.

    Each wallet’s balance is booked against the verified investor it belongs to, and any wallet with tokens but no matching investor, or the reverse, is a break someone has to explain. Because the balances sit in your own records, checking the register against them is a query your team can run whenever it needs to.

What to know about streaming transfers into your register

  • Goldsky runs the pipeline and keeps the balances; you own the database and the register you book from it.
  • Each holder’s balance is kept per holder and token as rows arrive, and corrected when a reorg removes a transfer.
  • The pipeline’s SQL decides what each row holds, so the table’s columns are yours to choose.
  • Tables with a primary key take reorg corrections as updates and deletes, so the rows follow the chain without extra code.
  • Adding a chain means adding a source to the pipeline, and the rows keep the same columns.

Option 2: Keep an onchain shareholder register with a hosted index

You write a schema and mappings that keep a balance for each holder, and Goldsky indexes the token and serves the holders at a GraphQL endpoint. Your register queries it by holder.

When to use a hosted holder index

The token is on one EVM chain and you’d rather query balances by holder from an API than keep transfer rows in your own database.

What you’ll need

  • Goldsky Subgraphs
  • An identity verification provider
  • The token’s contract address and the network it runs on
  • A code repository for the schema and mappings
  • Your register system of record

  1. Verify the investor

    A security can only be registered to an investor the issuer has checked, so each wallet is linked to a verified identity before it can hold shares.

    Your identity verification provider checks the investor, and the wallet they’ll use is recorded against that identity, often in an identity registry the token itself checks. A wallet that holds shares with no verified investor behind it is a holder the register can’t name.

  2. Record each change of ownership on the chain

    Every issue, redemption and transfer of the token is recorded on the chain, which is where the register reads ownership changes from.

    A mint creates new shares in a wallet, a burn removes them, and a transfer moves them between wallets. For a short time the newest blocks can still be rewritten (a reorg), so a move seen once isn’t settled yet.

  3. Define the holder records

    A hosted index has to know which contract events change a holding and how to turn each one into a record you can look up by holder.

    You write a schema with a holder record and its balance, and mapping code that adds to the recipient and subtracts from the sender on every transfer. A field left out can’t be queried later without changing the index and building it again from the start.

  4. Keep each holder’s balance in the index

    Handled by Goldsky Subgraphs

    Your systems need each holder’s current balance without adding up the token’s history every time they ask.

    Indexing has to start from the block where the token was deployed, or early holders are missing with no warning. From there, every mint, burn and transfer updates the holders it touches.

    Goldsky Subgraphs runs your mapping code from the start block onward and keeps the holder records current as new blocks arrive. You deploy it with goldsky subgraph deploy, and an existing subgraph deploys unchanged.

    Deploy a subgraph to Goldsky (opens in a new tab)

  5. Roll back holdings undone by a reorg

    Handled by Goldsky Subgraphs

    When the chain replaces its newest blocks, a transfer the index already counted can disappear.

    The index has to drop the changes those blocks made, so each holder’s balance goes back to what it was. If it doesn’t, the register can show shares in a wallet that never received them.

    Subgraphs stores every version of a record with a block_range showing the blocks it’s valid for, and rows are removed only when a reorg rolls them back. Webhooks on the record carry the same block_range, so your systems can tell a rollback from an ordinary change.

    How record versions track reorgs (opens in a new tab)

  6. Query holders by investor wallet

    Handled by Goldsky Subgraphs

    Your register, statements and support tools read positions by querying the index for a holder or a token.

    The index responds at one web address while it keeps indexing. Holder data isn’t public, so that address should require a key on every request.

    Every subgraph gets a GraphQL endpoint in Subgraphs. Turn on the private endpoint and turn off the public one, and each request then needs an API token in the Authorization header.

    Set up a private endpoint (opens in a new tab)

  7. Book the official register

    The register is the legal record of ownership, so it names investors, and the onchain balances have to be carried into it.

    Each wallet’s balance is booked against the verified investor it belongs to, and any wallet with tokens but no matching investor, or the reverse, is a break someone has to explain. Because the balances sit in your own records, checking the register against them is a query your team can run whenever it needs to.

What to know about keeping holders in a hosted index

  • Goldsky runs the index and its endpoint; your systems pull balances when they need them.
  • The mapping code you write keeps the balances, so a change to what’s stored means a new version that indexes again.
  • Each index follows one chain, so a token on several chains needs one per chain and your own step to combine them.
  • Reorgs are rolled back inside the index, so queries return balances that follow the chain.

What you control

Your team
  • Book the official register
Your providers
  • KYC/KYB provider

Questions and answers

What is a tokenized shareholder register?

A tokenized shareholder register is the official record of who owns a security that is issued as a token on a blockchain. The chain shows which wallets hold the token and how many units each holds. The transfer agent links each wallet to a verified investor and keeps the legal register, updating it whenever the token is minted, burned or transferred, so the register and the chain show the same holders.

Can a transfer agent keep its official records on a blockchain?

Under rule changes the SEC proposed in September 2026, which are a proposal and not yet final, a registered transfer agent could use a blockchain or other distributed ledger as its master securityholder file, or part of it, but would not have to. The proposal asks how such records should link wallet addresses and balances onchain with holder names and addresses kept offchain, so that each token transfer is matched by a transfer in the master file, and how to treat a ledger the transfer agent doesn’t exclusively control.

Security and deployment

  • SOC 2 Type IIIndependently audited security controls.
  • Dedicated infrastructureSingle-tenant options for production workloads.
  • Data residencyCloud, on-premises or co-located.

More use cases that keep a holder register

Use cases built the same way

Keep an onchain shareholder register with Goldsky

We’ll map it to your systems and show you what Goldsky runs, so your team builds the product, not the pipelines underneath it.

Talk to our team

© Endless Sky Inc. All rights reserved.

PrivacyTermsSecurity

System status