Returns the list of Stacks addresses registered as heirs on the specified vault. The order matches the heirs-data list passed to create-vault or the most recent call to update-heirs. Up to 10 heirs can be registered on a single vault.
Function signature
(define-read-only (get-heir-list (owner principal))
-> (response (list 10 principal) uint)
)
Parameters
The Stacks address of the vault owner whose heir list you want to retrieve. No wallet connection is required.
Return value
Returns (ok (list 10 principal)) — an ordered list of up to 10 Stacks addresses that are registered as heirs. The list is in the same order as it was provided to create-vault or update-heirs.If no vault exists for the specified owner, the contract returns an empty list rather than an error (see behavior note below). Behavior note
Unlike get-vault-status and get-heir-info, get-heir-list does not return ERR-VAULT-NOT-FOUND for an unknown owner. Instead, it uses default-to to return an empty list:
;; From heirloom-vault.clar
(define-read-only (get-heir-list (owner principal))
(ok (default-to (list) (map-get? heir-list owner)))
)
get-vault-status.
Error codes
| Code | Constant | When returned |
|---|
| u103 | ERR-VAULT-NOT-FOUND | Not returned by this function — an unknown owner produces an empty list |
get-heir-list always returns (ok ...). There is no error path. To detect a missing vault, call get-vault-status separately — it will return ERR-VAULT-NOT-FOUND (u103) for an address with no vault.JavaScript example
import { getHeirList } from './lib/contracts';
const result = await getHeirList('SP1VAULTOWNER1ADDRESSXXXXXXXXXXXXXXXXX');
// The list is nested under .value.value in the cvToJSON output
const addresses: string[] = (result?.value?.value ?? []).map(
(item: any) => item?.value
);
console.log(addresses);
// [
// 'SP2HEIR1ADDRESSXXXXXXXXXXXXXXXXXX',
// 'SP3HEIR2ADDRESSXXXXXXXXXXXXXXXXXX',
// ]
Example JSON output from cvToJSON
A vault with two heirs:
{
"success": true,
"value": {
"type": "(ok (list 10 principal))",
"value": [
{ "type": "principal", "value": "SP2HEIR1ADDRESSXXXXXXXXXXXXXXXXXX" },
{ "type": "principal", "value": "SP3HEIR2ADDRESSXXXXXXXXXXXXXXXXXX" }
]
}
}
Combining with get-heir-info to build a full heir table
Call get-heir-list to discover all heir addresses, then call get-heir-info in parallel for each one to retrieve their allocation and claim status:
import { getHeirList, getHeirInfo } from './lib/contracts';
async function getFullHeirTable(ownerAddress: string) {
const listResult = await getHeirList(ownerAddress);
const addresses: string[] = (listResult?.value?.value ?? []).map(
(item: any) => item?.value
);
// Fetch all heir info in parallel
const infoResults = await Promise.all(
addresses.map(addr => getHeirInfo(ownerAddress, addr))
);
return addresses.map((address, i) => {
const fields = infoResults[i]?.value?.value ?? infoResults[i]?.value;
const splitBps = parseInt(fields?.['split-bps']?.value ?? '0');
const hasClaimed = fields?.['has-claimed']?.value === true;
return {
address,
splitBps,
percentage: (splitBps / 100).toFixed(2) + '%',
hasClaimed,
};
});
}
// Example output:
// [
// { address: 'SP2HEIR1...', splitBps: 6000, percentage: '60.00%', hasClaimed: false },
// { address: 'SP3HEIR2...', splitBps: 4000, percentage: '40.00%', hasClaimed: true },
// ]
Use Promise.all when fetching get-heir-info for multiple heirs. Each call is an independent read-only request — there is no benefit to serializing them.
The list returned reflects the state at the last create-vault or update-heirs call. If heirs have been updated, the list shows only the current heir set. Previous heirs that were removed are not included, though their heir-claimed records remain on-chain.
