diff --git a/apps/indexer/README.md b/apps/indexer/README.md index b49c392..8be00e1 100644 --- a/apps/indexer/README.md +++ b/apps/indexer/README.md @@ -6,6 +6,7 @@ Petra Vault uses the No-Code Indexing (NCI) service from [Geomi](https://geomi.d - [Setup Instructions](#setup-instructions) - [Environment Configuration](#environment-configuration) +- [Troubleshooting Processor Imports](#troubleshooting-processor-imports) - [Initial-owner Discovery on Mainnet](#initial-owner-discovery-on-mainnet) ## Setup Instructions @@ -24,7 +25,31 @@ Petra Vault uses the No-Code Indexing (NCI) service from [Geomi](https://geomi.d > **Note**: You should now have two processors: one for mainnet and one for testnet. -### Step 3: Create API Keys +Provisioning can take 5–10 minutes. During that time, Geomi may report a missing +database, missing `processor` / `hasura-api` deployments, and a route JSON error. +Wait for the overall status to become **Running** before using the API. If it +stays in **Provisioning**, see [Troubleshooting Processor Imports](#troubleshooting-processor-imports). + +### Step 3: Expose Tables in Hasura + +For each processor, open its **Console URL** and authenticate with the Hasura admin +secret shown on the processor page. Under **Data**, select the `processordb` +database and `public` schema, then **Track** these tables: + +- `multisig_transactions` +- `multisig_owner_activities` +- `multisig_creation_candidates` (mainnet only) + +Hasura only generates GraphQL fields for [tracked tables](https://hasura.io/docs/2.0/api-reference/metadata-api/table-view/). +If the Explorer shows `no_queries_available` or a query reports a missing field, +check tracking before changing the query. If **Settings** reports inconsistent +metadata for a table that now exists, reload the metadata to refresh Hasura's +schema cache, then track any missing tables and refresh GraphiQL. + +Tracking enables admin-console queries. App API keys also need Hasura select +permissions for their role on the tables they query. + +### Step 4: Create API Keys For **each processor** (mainnet and testnet): @@ -34,7 +59,7 @@ For **each processor** (mainnet and testnet): - **Allowed URLs**: `https://` 3. Click **ADD KEY** -### Step 4: Get Processor Endpoints +### Step 5: Get Processor Endpoints For **each processor** (mainnet and testnet): @@ -65,6 +90,33 @@ NEXT_PUBLIC_MULTISIG_INDEXER_TESTNET_ENDPOINT="https://api.testnet.aptoslabs.com | `NEXT_PUBLIC_MULTISIG_INDEXER_TESTNET_API_KEY` | API key for testnet processor | `AG-...` | | `NEXT_PUBLIC_MULTISIG_INDEXER_TESTNET_ENDPOINT` | GraphQL endpoint for testnet | `https://api.testnet.aptoslabs.com/nocode/v1/api/[id]/v1/graphql` | +## Troubleshooting Processor Imports + +Geomi's visual editor rebuilds column types from event mappings. When legacy +`*Event` account-address metadata and a module event's `$.multisig_account` field +share a column, the last mapping wins. If the legacy mapping comes last, the editor +changes `move_type: address` into `event_metadata: account_address`, even though +the imported YAML declared the correct type. The processor requires a Move type +for event-field mappings and cannot start with that configuration. + +Both YAML files put legacy `*Event` mappings before module events to avoid this +editor bug. Keep this order when importing. Before deploying or saving an edit, +check the generated YAML: the `multisig_account` column in both +`multisig_transactions` and `multisig_owner_activities` must retain: + +```yaml +column_type: + type: move_type + column_type: address +``` + +If the database and API are running but the processor has no status or reports a +missing `processor_status` table, inspect the saved configuration and Geomi's +**Messages** section. Those status messages alone do not identify the cause. +If the two column types above were changed, import the corrected YAML into the +processor editor and verify the generated configuration before applying it. +An editor rebuild can change the types again, so check them on later edits too. + ## Initial-owner Discovery on Mainnet `multisig-mainnet.yaml` adds `multisig_creation_candidates` alongside the existing @@ -111,5 +163,5 @@ to create rows before payload enrichment. This stores a row for every matching fee event, including unrelated transactions with null owners and failed creation calls. Filtering the GraphQL query does not reduce ingestion. Plan ingestion cost and backfill before deployment; the YAML's `starting_version: 0` requests history -from genesis. The promoted config has been checked locally, but has not been -deployed or verified using the mobile API key. +from genesis. Before updating app endpoints, verify candidate indexing and table +permissions using the mobile API key. diff --git a/apps/indexer/multisig-mainnet.yaml b/apps/indexer/multisig-mainnet.yaml index 4dd2ffb..cf276e7 100644 --- a/apps/indexer/multisig-mainnet.yaml +++ b/apps/indexer/multisig-mainnet.yaml @@ -1,7 +1,7 @@ spec_identifier: spec_creator: shepherd@aptoslabs.com spec_name: remapping-processor - spec_version: "0.0.21" + spec_version: '0.0.21' common_config: network: mainnet starting_version: 0 @@ -22,43 +22,51 @@ custom_config: block_height: [] hash: [] events: - # Payload mappings enrich event-created rows; they do not filter ingestion. - 0x1::transaction_fee::FeeStatement: + # Keep legacy *Event mappings first. Geomi's editor uses the last mapping + # to choose a shared column's type; module events must set Move addresses. + 0x1::multisig_account::AddOwnersEvent: event_fields: - $.total_charge_gas_units: - - table: multisig_creation_candidates - column: total_charge_gas_units + $.owners_added: + - table: multisig_owner_activities + column: owners_added event_metadata: sequence_number: [] creation_number: [] - account_address: [] + account_address: + - table: multisig_owner_activities + column: multisig_account event_type: - - table: multisig_creation_candidates - column: fee_event_type + - table: multisig_owner_activities + column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::AddOwners: + 0x1::multisig_account::ExecuteRejectedTransactionEvent: event_fields: - $.multisig_account: - - table: multisig_owner_activities - column: multisig_account - $.owners_added: - - table: multisig_owner_activities - column: owners_added + $.executor: + - table: multisig_transactions + column: executor + $.num_rejections: + - table: multisig_transactions + column: num_rejections + $.sequence_number: + - table: multisig_transactions + column: sequence_number event_metadata: sequence_number: [] creation_number: [] - account_address: [] + account_address: + - table: multisig_transactions + column: multisig_account event_type: - - table: multisig_owner_activities + - table: multisig_transactions column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::AddOwnersEvent: + 0x1::multisig_account::RemoveOwnersEvent: event_fields: - $.owners_added: + $.owners_removed: - table: multisig_owner_activities - column: owners_added + column: owners_removed event_metadata: sequence_number: [] creation_number: [] @@ -70,40 +78,45 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::ExecuteRejectedTransaction: + 0x1::multisig_account::TransactionExecutionFailedEvent: event_fields: $.executor: - table: multisig_transactions column: executor - $.multisig_account: - - table: multisig_transactions - column: multisig_account - $.num_rejections: + $.num_approvals: - table: multisig_transactions - column: num_rejections + column: num_approvals $.sequence_number: - table: multisig_transactions column: sequence_number + $.transaction_payload: + - table: multisig_transactions + column: transaction_payload event_metadata: sequence_number: [] creation_number: [] - account_address: [] + account_address: + - table: multisig_transactions + column: multisig_account event_type: - table: multisig_transactions column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::ExecuteRejectedTransactionEvent: + 0x1::multisig_account::TransactionExecutionSucceededEvent: event_fields: $.executor: - table: multisig_transactions column: executor - $.num_rejections: + $.num_approvals: - table: multisig_transactions - column: num_rejections + column: num_approvals $.sequence_number: - table: multisig_transactions column: sequence_number + $.transaction_payload: + - table: multisig_transactions + column: transaction_payload event_metadata: sequence_number: [] creation_number: [] @@ -115,40 +128,55 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::RemoveOwners: + 0x1::multisig_account::VoteEvent: event_fields: - $.multisig_account: - - table: multisig_owner_activities - column: multisig_account - $.owners_removed: + $.owner: - table: multisig_owner_activities - column: owners_removed + column: owner_vote event_metadata: sequence_number: [] creation_number: [] - account_address: [] + account_address: + - table: multisig_owner_activities + column: multisig_account event_type: - table: multisig_owner_activities column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::RemoveOwnersEvent: + # Payload mappings enrich event-created rows; they do not filter ingestion. + 0x1::transaction_fee::FeeStatement: event_fields: - $.owners_removed: - - table: multisig_owner_activities - column: owners_removed + $.total_charge_gas_units: + - table: multisig_creation_candidates + column: total_charge_gas_units event_metadata: sequence_number: [] creation_number: [] - account_address: + account_address: [] + event_type: + - table: multisig_creation_candidates + column: fee_event_type + event_index: [] + constant_values: [] + 0x1::multisig_account::AddOwners: + event_fields: + $.multisig_account: - table: multisig_owner_activities column: multisig_account + $.owners_added: + - table: multisig_owner_activities + column: owners_added + event_metadata: + sequence_number: [] + creation_number: [] + account_address: [] event_type: - table: multisig_owner_activities column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::TransactionExecutionFailed: + 0x1::multisig_account::ExecuteRejectedTransaction: event_fields: $.executor: - table: multisig_transactions @@ -156,15 +184,12 @@ custom_config: $.multisig_account: - table: multisig_transactions column: multisig_account - $.num_approvals: + $.num_rejections: - table: multisig_transactions - column: num_approvals + column: num_rejections $.sequence_number: - table: multisig_transactions column: sequence_number - $.transaction_payload: - - table: multisig_transactions - column: transaction_payload event_metadata: sequence_number: [] creation_number: [] @@ -174,32 +199,24 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::TransactionExecutionFailedEvent: + 0x1::multisig_account::RemoveOwners: event_fields: - $.executor: - - table: multisig_transactions - column: executor - $.num_approvals: - - table: multisig_transactions - column: num_approvals - $.sequence_number: - - table: multisig_transactions - column: sequence_number - $.transaction_payload: - - table: multisig_transactions - column: transaction_payload + $.multisig_account: + - table: multisig_owner_activities + column: multisig_account + $.owners_removed: + - table: multisig_owner_activities + column: owners_removed event_metadata: sequence_number: [] creation_number: [] - account_address: - - table: multisig_transactions - column: multisig_account + account_address: [] event_type: - - table: multisig_transactions + - table: multisig_owner_activities column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::TransactionExecutionSucceeded: + 0x1::multisig_account::TransactionExecutionFailed: event_fields: $.executor: - table: multisig_transactions @@ -225,11 +242,14 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::TransactionExecutionSucceededEvent: + 0x1::multisig_account::TransactionExecutionSucceeded: event_fields: $.executor: - table: multisig_transactions column: executor + $.multisig_account: + - table: multisig_transactions + column: multisig_account $.num_approvals: - table: multisig_transactions column: num_approvals @@ -242,9 +262,7 @@ custom_config: event_metadata: sequence_number: [] creation_number: [] - account_address: - - table: multisig_transactions - column: multisig_account + account_address: [] event_type: - table: multisig_transactions column: event_type @@ -267,22 +285,6 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::VoteEvent: - event_fields: - $.owner: - - table: multisig_owner_activities - column: owner_vote - event_metadata: - sequence_number: [] - creation_number: [] - account_address: - - table: multisig_owner_activities - column: multisig_account - event_type: - - table: multisig_owner_activities - column: event_type - event_index: [] - constant_values: [] payload: # Geomi's function ABI lookup requires the full address. 0x0000000000000000000000000000000000000000000000000000000000000001::multisig_account::create_with_owners: diff --git a/apps/indexer/multisig-testnet.yaml b/apps/indexer/multisig-testnet.yaml index d956a6a..ac1cc12 100644 --- a/apps/indexer/multisig-testnet.yaml +++ b/apps/indexer/multisig-testnet.yaml @@ -1,7 +1,7 @@ spec_identifier: spec_creator: shepherd@aptoslabs.com spec_name: remapping-processor - spec_version: "0.0.21" + spec_version: '0.0.21' common_config: network: testnet starting_version: 4500665800 @@ -20,28 +20,51 @@ custom_config: block_height: [] hash: [] events: - 0x1::multisig_account::AddOwners: + # Keep legacy *Event mappings first. Geomi's editor uses the last mapping + # to choose a shared column's type; module events must set Move addresses. + 0x1::multisig_account::AddOwnersEvent: event_fields: - $.multisig_account: - - table: multisig_owner_activities - column: multisig_account $.owners_added: - table: multisig_owner_activities column: owners_added event_metadata: sequence_number: [] creation_number: [] - account_address: [] + account_address: + - table: multisig_owner_activities + column: multisig_account event_type: - table: multisig_owner_activities column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::AddOwnersEvent: + 0x1::multisig_account::ExecuteRejectedTransactionEvent: event_fields: - $.owners_added: + $.executor: + - table: multisig_transactions + column: executor + $.num_rejections: + - table: multisig_transactions + column: num_rejections + $.sequence_number: + - table: multisig_transactions + column: sequence_number + event_metadata: + sequence_number: [] + creation_number: [] + account_address: + - table: multisig_transactions + column: multisig_account + event_type: + - table: multisig_transactions + column: event_type + event_index: [] + constant_values: [] + 0x1::multisig_account::RemoveOwnersEvent: + event_fields: + $.owners_removed: - table: multisig_owner_activities - column: owners_added + column: owners_removed event_metadata: sequence_number: [] creation_number: [] @@ -53,40 +76,45 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::ExecuteRejectedTransaction: + 0x1::multisig_account::TransactionExecutionFailedEvent: event_fields: $.executor: - table: multisig_transactions column: executor - $.multisig_account: - - table: multisig_transactions - column: multisig_account - $.num_rejections: + $.num_approvals: - table: multisig_transactions - column: num_rejections + column: num_approvals $.sequence_number: - table: multisig_transactions column: sequence_number + $.transaction_payload: + - table: multisig_transactions + column: transaction_payload event_metadata: sequence_number: [] creation_number: [] - account_address: [] + account_address: + - table: multisig_transactions + column: multisig_account event_type: - table: multisig_transactions column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::ExecuteRejectedTransactionEvent: + 0x1::multisig_account::TransactionExecutionSucceededEvent: event_fields: $.executor: - table: multisig_transactions column: executor - $.num_rejections: + $.num_approvals: - table: multisig_transactions - column: num_rejections + column: num_approvals $.sequence_number: - table: multisig_transactions column: sequence_number + $.transaction_payload: + - table: multisig_transactions + column: transaction_payload event_metadata: sequence_number: [] creation_number: [] @@ -98,40 +126,40 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::RemoveOwners: + 0x1::multisig_account::VoteEvent: event_fields: - $.multisig_account: - - table: multisig_owner_activities - column: multisig_account - $.owners_removed: + $.owner: - table: multisig_owner_activities - column: owners_removed + column: owner_vote event_metadata: sequence_number: [] creation_number: [] - account_address: [] + account_address: + - table: multisig_owner_activities + column: multisig_account event_type: - table: multisig_owner_activities column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::RemoveOwnersEvent: + 0x1::multisig_account::AddOwners: event_fields: - $.owners_removed: + $.multisig_account: - table: multisig_owner_activities - column: owners_removed + column: multisig_account + $.owners_added: + - table: multisig_owner_activities + column: owners_added event_metadata: sequence_number: [] creation_number: [] - account_address: - - table: multisig_owner_activities - column: multisig_account + account_address: [] event_type: - table: multisig_owner_activities column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::TransactionExecutionFailed: + 0x1::multisig_account::ExecuteRejectedTransaction: event_fields: $.executor: - table: multisig_transactions @@ -139,15 +167,12 @@ custom_config: $.multisig_account: - table: multisig_transactions column: multisig_account - $.num_approvals: + $.num_rejections: - table: multisig_transactions - column: num_approvals + column: num_rejections $.sequence_number: - table: multisig_transactions column: sequence_number - $.transaction_payload: - - table: multisig_transactions - column: transaction_payload event_metadata: sequence_number: [] creation_number: [] @@ -157,32 +182,24 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::TransactionExecutionFailedEvent: + 0x1::multisig_account::RemoveOwners: event_fields: - $.executor: - - table: multisig_transactions - column: executor - $.num_approvals: - - table: multisig_transactions - column: num_approvals - $.sequence_number: - - table: multisig_transactions - column: sequence_number - $.transaction_payload: - - table: multisig_transactions - column: transaction_payload + $.multisig_account: + - table: multisig_owner_activities + column: multisig_account + $.owners_removed: + - table: multisig_owner_activities + column: owners_removed event_metadata: sequence_number: [] creation_number: [] - account_address: - - table: multisig_transactions - column: multisig_account + account_address: [] event_type: - - table: multisig_transactions + - table: multisig_owner_activities column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::TransactionExecutionSucceeded: + 0x1::multisig_account::TransactionExecutionFailed: event_fields: $.executor: - table: multisig_transactions @@ -208,11 +225,14 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::TransactionExecutionSucceededEvent: + 0x1::multisig_account::TransactionExecutionSucceeded: event_fields: $.executor: - table: multisig_transactions column: executor + $.multisig_account: + - table: multisig_transactions + column: multisig_account $.num_approvals: - table: multisig_transactions column: num_approvals @@ -225,9 +245,7 @@ custom_config: event_metadata: sequence_number: [] creation_number: [] - account_address: - - table: multisig_transactions - column: multisig_account + account_address: [] event_type: - table: multisig_transactions column: event_type @@ -250,22 +268,6 @@ custom_config: column: event_type event_index: [] constant_values: [] - 0x1::multisig_account::VoteEvent: - event_fields: - $.owner: - - table: multisig_owner_activities - column: owner_vote - event_metadata: - sequence_number: [] - creation_number: [] - account_address: - - table: multisig_owner_activities - column: multisig_account - event_type: - - table: multisig_owner_activities - column: event_type - event_index: [] - constant_values: [] payload: {} db_schema: multisig_transactions: