Doğrulanabilir mekânsal kayıtlarla geliştirme rehberi.

Ağ bağlantısı

Canister bağlantısını doğru ağ adresiyle kurun.

Ana ağ çağrıları için VITE_IC_HOST=https://icp-api.io kullanın. Yerel replica adresi http://127.0.0.1:4943 olur; canister kimliklerini scripts/write_frontend_local_env.sh ile üretin. Uzak bağlantılarda SDK içindeki IC kök anahtarı korunur. Replica kök anahtarını yalnız yerel geliştirme ortamında alın.

VITE_IC_HOST=https://icp-api.io

./scripts/write_frontend_local_env.sh

Kredi ve kanıt işlemleri

Yarım kalan işlemi aynı istekle sonuçlandırın

Zaman aşımı işlemin başarısız olduğunu kanıtlamaz. Aynı kullanıcı kimliğini, hedef canister’ı, istek kimliğini ve içeriği koruyun. 3 Eylül tarihli 2060dce sürüm adayında işlem günlüğü, aynı isteğin tekrarı ve yükseltme sonrası kurtarma yerel kabul testini geçmiştir. Zorunlu CI sonuçları, onaylı dağıtım ve canlı ortamdan geri okuma ayrı kabul koşullarıdır.

Mekânsal kanıt kontrolü

Kanıt dosyasını paylaşmadan önce kontrol edin.

Haritadan indirdiğiniz veri seti anlık görüntüsünü veya kayıt kanıtını DApp içindeki Check Evidence ekranında açın. UTF-8 JSON dosyaları 10 MiB sınırına kadar tarayıcı sekmesinde incelenir; dosya içeriği yüklenmez ve hesap bağlantısı gerekmez.

1. Tek veri setini dışa aktarınHaritada veri setini seçin ve Export snapshot JSON düğmesiyle dosyayı indirin. Canlı veri setlerinde v2 paketi, her sınırlı sayfanın ham JSON içeriğini ve checksum değerini birlikte korur.
2. Dosyayı seçinCheck Evidence ekranında indirdiğiniz dosyayı açın. Paket özeti ve canlı anlık görüntünün her sayfası kontrol edilir; sayfa sırası, veri seti bilgileri ve kayıt sayıları eşleşmelidir.
3. Sonucu kaynakla karşılaştırınEşleşme, içeriğin dosyada sunulan özetlerle tutarlı olduğunu gösterir. Gönderenin kimliğini, kanıt makbuzunu veya canister üzerindeki güncel durumu doğrulamaz. Dosyanın tam SHA-256 değerini güvenilir teslim kaydıyla karşılaştırın.

Ana ağ referansları

Canister kimliklerini karşılaştırın.

Ana ağ bağlantısını bu canister kimlikleriyle kontrol edin. Dağıtım sonrasında kimlikler değişirse güncel adresleri terminode.io üzerindeki geliştirici dokümanından alın.

dfx canister call trmg_ledger icrc1_name '()' --network ic
dfx canister call trmg_ledger icrc1_symbol '()' --network ic
dfx canister call spatial get_system_metrics '()' --network ic
dfx canister call oracle_gateway get_system_metrics '()' --network ic

Mekânsal veri hazırlığı

İlk katmanı incelemeye hazır hale getirin.

Geçmişi veya kabul edilmiş sınırı sonradan kanıtlanması gereken tek bir katman seçin. EPSG:4326 koordinatlarını, sabit kaynak kimliklerini ve güvenli üstveri alanlarını aktarım öncesinde belirleyin.

1. Tek katman seçinHizmet bölgesi, çalışma sınırı, kesinti alanı, varlık koridoru veya hasar alanıyla başlayın.
2. Geometriyi doğrulayınGeoJSON veya WKB kullanın. Poligonları kontrol edin, koordinatları EPSG:4326 biçiminde tutun ve herkese açık üstveriden hassas kişisel bilgileri çıkarın.
3. Üstveriyi tanımlayınKaynak, inceleme durumu, değişiklik nedeni, sorumlu rol, kanıt referansı ve aktarım grubu gibi gerekli işletim bilgilerini koruyun.
4. Sınırlı gruplarla aktarınBir veri seti oluşturup az sayıda kayıt ekleyin. Ardından bir kaydı güncelleyerek sürüm geçmişini ve denetim izini inceleyin.
5. Kanıtı dışa aktarınPilot kaydın anlık görüntüsünü, checksum değerini, sürümlerini, kanıt makbuzunu ve denetim olaylarını birlikte arşivleyin.

Başlamadan önce

TermiNode kullanmak için ne gerekli?

Başarılı entegrasyon geniş bir platform taşımasıyla değil, dar ve net bir spatial proof hedefiyle başlar. Günlük GIS düzenleme, routing, search, dashboard ve private case data mevcut araçlarda kalabilir; TermiNode kabul edilmiş spatial record için version history, audit evidence ve portable proof katmanı sağlar.

Tekrar kullanılabilir değerlendirme kontratı

Domain paketi seçin, ardından sample veriyi onaylı müşteri kaydıyla değiştirin

TermiNode saha kabulü, hizmet bölgeleri, altyapı veya sigorta kanıtı ve lojistik veya uyum bölgeleri için aynı proof-layer akışını kullanır. Her paket iki EPSG:4326 Polygon örneği, güvenli meta veri alanları, alıcı rolleri, kanıt sorusu, demo sırası, kanıt çıktıları ve ölçülebilir pilot kriterleri içerir. Add Data sayfasındaki seçici paket adını ve GeoJSON örneğini forma yükler; bu adım canister’a veri yazmaz.

1. Operasyon kaydını seçinReview, dispute, handoff veya compliance sonucu olan tek boundary tipini belirleyin.
2. Örnek kontratı doğrulayınAdd Data içinde domain paketini seçin, örnek veriyi forma yükleyin ve dry-run doğrulamasını çalıştırın. Bu aşamada canister’a yazma işlemi yapılmaz.
3. Müşteri kaynağını eşleyinSample source_system, source_layer, source_feature_id, source_revision ve evidence referanslarını onaylı değerlerle değiştirin.
4. Kabul kuralını belirleyinReviewer ve approver rollerini isimlendirin; kararı tek bir exact feature version’a bağlayın.
5. Evidence ile kapatınBounded snapshot, acceptance report, manifest ve ölçülmüş müşteri kararını birlikte arşivleyin.

source_system=<onayli-kaynak>
source_layer=<kalici-layer>
source_feature_id=<kalici-id>
source_revision=<iyimser-revizyon>
external_reference=<guvenli-referans>
asset_boundary_id=<kalici-boundary>
evidence_hash=sha256:<ozet>
reviewed_at=<ISO-8601>
reviewed_by_role=<rol>
review_status=<durum>
change_reason=<neden>

# personal_data, private_notes, raw_attachment, access_token
# ve customer_secret TermiNode metadata alanına yazılmaz.

Doğrulanmış kayıt paterni

İçerik kimlik bilgisini mekânsal kanıta bağlayın

Bir iş ortağı uygulaması kayıt bütünlüğünü içerik kimlik bilgileriyle kanıtlıyorsa TermiNode eksik mekânsal bağlamı ekler: kayıt hangi özellik, çokgen, bölge veya varlık sınırıyla ilişkilidir?

Quickstart

Sample layer’dan evidence package’a gidiş

Bir uygulama için TermiNode uygun mu diye test ederken bu sırayı kullan. Risk düşük kalır, değer hızlı görünür ve teknik alıcının inceleyebileceği kanıt paketi oluşur.

1. Canlı DApp’i açterminode.io adresinden başla; Landing, Map, Add Data, Docs, Pilot ve Readiness sayfalarını incele.
2. Dry-run import çalıştırAdd Data içinde küçük bir GeoJSON sample yükle; accepted/rejected count, CRS uyarısı, metadata riskleri ve tahmini write-credit ihtiyacını kontrol et.
3. Map evidence inceleMap sayfasında sample layer seç, feature aç, audit trail, version bilgisi, proof receipt ve export butonlarını incele.
4. Bounded read test etCandid veya TypeScript actor ile dataset listesi ve bbox-scoped GeoJSON page oku; tüm dünyayı değil yalnız gereken viewport’u iste.
5. Export ve arşivleSnapshot JSON, feature evidence JSON, proof receipt ve checksum evidence dosyalarını pilot kaydına veya procurement dosyasına ekle.
6. Gerekirse agent review ekleClaude/agent workflow dataset, audit, version, metrics veya partner evidence context okusun istiyorsan MCP server’ı local çalıştır.

Write path

Bir uygulama spatial record’u nasıl yazmalı?

Draft editing çoğu zaman mevcut uygulamada kalmalıdır. TermiNode, ekip kabul edilmiş geometry ve evidence history bilgisinin bağımsız incelenebilir olmasını istediğinde kullanılmalıdır.

1. Geometry bilgisini kendi uygulamanda veya Add Data dry-run ile doğrula.
2. TermiNode dataset oluştur veya mevcut dataset seç.
3. Sadece onaylanmış feature ve güvenli metadata yaz.
4. Kabul edilen geometri değişirse feature update yap.
5. Feature versions ve audit events oku.
6. Snapshot ve proof receipt export ederek review dosyasına ekle.

{
  "source_app": "your-system-name",
  "external_reference": "CASE-OR-ASSET-123",
  "feature_id": "ZONE-0426-A",
  "asset_boundary_id": "BOUNDARY-77",
  "proof_receipt_id": "YOUR-PROOF-REF",
  "evidence_hash": "sha256:...",
  "recorded_at": "2026-07-07T09:00:00Z",
  "review_status": "approved"
}

Import onboarding

GIS layer yazılmadan önce workspace hazırlığı

TermiNode en iyi sonucu, pilot ekip veriyi yazmadan önce çalışma alanını net hazırladığında üretir: dataset sahibi kim, import yetkilisi kim, hangi kayıt kanıt değeri taşıyor, hangi metadata public olabilir ve export paketini kim saklar? Bu yaklaşım ürünü GIS-first tutar ve import adımını kontrollü bir spatial accountability workflow haline taşır.

// Sponsor önce top_up_write_credits_idempotent çağrısında aynı istek kimliğini ve tutarı koruyarak yazma kredisi yükler.
await spatial.configure_workspace_sponsorship(
  workspaceId, sponsorPrincipal, 500_000_000n, 100_000_000n, [expiresAtNs]
);
await spatial.fund_workspace_credits(workspaceId, 300_000_000n);

// Importer kimliği TRMG veya kişisel write credit tutmadan yazar.
await spatial.add_feature(datasetId, h3Cells, polygonWkb, safeMetadata);

const usage = await spatial.get_workspace_sponsored_usage(
  workspaceId, importerPrincipal
);
const usagePage = await spatial.list_workspace_sponsored_usage_page(
  workspaceId, 0n, 50n
);

await spatial.set_workspace_sponsorship_active(workspaceId, false);
await spatial.return_unused_workspace_credits(workspaceId, unusedAmount);

Artımlı senkronizasyon

Tekrarlanan GIS teslimlerini güvenli ve idempotent hâle getirin

Zamanlanmış bir QGIS çıktısı, PostGIS işi veya varlık kayıt sistemi her çalıştığında yeni bir özellik oluşturmamalıdır. TermiNode; source_system, source_layer ve source_feature_id alanlarını tek bir özellik ile bağlar, kabul edilmiş kaynak revizyonunu ve payload hash bilgisini saklar. İlk upsert bağlantıyı oluşturur. Sonraki değişiklikler expected_current_revision ile iyimser eşzamanlılık kontrolünden geçer.

import {
  buildFeatureSyncInput,
  syncFeatureBatch,
  listFeatureSyncStatesPage,
} from '@/lib/terminode-integration';

const entries = sourceRows.map((row) => buildFeatureSyncInput({
  sourceSystem: 'qgis',
  sourceLayer: 'asset-boundaries',
  sourceFeatureId: row.id,
  sourceRevision: row.revision,
  expectedCurrentRevision: row.acceptedRevision,
  mode: 'upsert',
  coveredCells: row.h3Hints.join(','),
  wkbHex: row.wkbHex,
  metadata: JSON.stringify(row.safeMetadata),
}));

const report = await syncFeatureBatch(spatial, datasetId, entries);
const bindings = await listFeatureSyncStatesPage(spatial, datasetId, 0n, 100n);
archiveSyncEvidence(report.report_checksum, report.entries, bindings);

Kesin sürüm kararı

Bir mekânsal sürümü kabul edin, geçmişi yeniden yazmayın

Güncel geometri ile kabul edilmiş geometri aynı kavram değildir. Mekânsal kabul akışı Draft, Submitted, Reviewed, Accepted, Rejected ve Superseded kararlarını tek bir özellik ve sürüm çifti üzerinde tutar. Üç ayrı principal ile rol kontrolleri, checksum çıktısı, otomatik supersession ve upgrade sonrası kalıcılık yerel canister kabul testini geçmiştir. Kontrollü production sürümü ve readback kanıtı henüz açıktır.

const draft = await spatial.create_spatial_acceptance_draft(
  featureId, versionId,
  {
    note: 'Kesin sürüm incelemesine hazırlandı',
    acceptance_reference: [],
    evidence_hash: [],
    proof_receipt_id: [],
  }
);

await spatial.transition_spatial_acceptance(
  featureId, versionId, { Submitted: null }, submittedInput
);
// Reviewer principal { Reviewed: null } kaydeder.
// Ayrı Approver principal { Accepted: null } kaydeder.

const selected = await spatial.get_spatial_acceptance(featureId, versionId);
const current = await spatial.get_current_spatial_acceptance(featureId);
const history = await spatial.list_feature_acceptances_page(featureId, 0n, 20n);
const [reportJson, checksum] = await spatial
  .export_spatial_acceptance_report_with_checksum(featureId, versionId);

// Paketi paylaşmadan önce SHA-256(reportJson) değerini yeniden hesaplayın.

NETWORK=local RUN_UPGRADE=1 DFX_CALL_TIMEOUT_SECONDS=120 \
  ./scripts/check_spatial_acceptance_workflow_smoke.sh

# Üç principal, iptal edilen rol reddi, v1 supersession,
# v2 güncel kabul, checksum ve ikinci upgrade kontrol edilir.

Doğrulama ve tekrar deneme

Demo smoke, connected smoke, QGIS/ETL smoke ve retry kontrolleri

TermiNode deterministik demo doğrulaması ile canlı canister doğrulamasını birbirinden ayırır. DApp dokümanı mock GIS verisiyle sample gateway smoke, ayarlı ICP aktörleriyle connected canister smoke, fetch-style request handling kanıtlayan HTTP adapter smoke ve public REST gateway yayına alınmadan önce CRS84 metadata, safe handoff fields, private-field exclusion, bbox validation ve geo+json packaging kontrol eden QGIS/ETL adapter smoke çalıştırabilir. Map export, ledger approval, oracle proof, governance action, operatör methodları ve external-router convenience sayfası da aynı operasyonel güvenilirlik standardıyla görünür durum ve retry yönlendirmesi sunar.

İmzalı kayıt kabulü

İş ortağı isteğini kısa ömürlü HMAC ve tek kullanımlık değerle doğrulayın

Gateway v1.8, iş ortağı sunucusundan gelen güvenli referansları kuyruğa almadan önce API anahtarını, veri seti kapsamını, gövde özetini, zaman damgasını, tek kullanımlık istek değerinin daha önce kullanılıp kullanılmadığını ve yinelenen teslim anahtarını birlikte denetler. Korumalı durum dosyası; iş durumunu, süreli iş sahipliğini, sınırlandırılmış yeniden denemeyi, başarısız iş kaydını ve geçiş geçmişini yeniden başlatma sonrasında korur. Her durum dosyasını yalnız bir ağ geçidi süreci açabilir; bu kilit dağıtık kuyruk değildir ve eski kilidin kaldırılması operatör doğrulaması gerektirir. Ayrı imzalı bildirim çalışanı, tamamlanan veya başarısız iş sonucunu onaylı sunucuya ham kanıt verisi taşımadan iletir. Mekânsal eşitleme, bildirim ve kimlik bilgisi doğrulama varsayılan olarak kapalıdır. Yerel kabul; tek kurum destekli yazıyı, indekslenmiş makbuz geri okumasını ve canister yazısını yinelemeyen imzalı bildirimi doğrular.

cd gateway-server
npm run build
# TERMINODE_PARTNER_API_KEY değerini onaylı gizli anahtar yöneticisinden yükleyin.
eval "$(node scripts/sign-partner-request.mjs \
  --body ./partner-recording.json \
  --idempotency-key partner:CAST-DEMO-001 \
  --format env)"

curl --request POST "$GATEWAY_URL/v1/partner-evidence/recordings" \
  --header "Authorization: Bearer $TERMINODE_PARTNER_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $TERMINODE_REQUEST_IDEMPOTENCY_KEY" \
  --header "X-Terminode-Timestamp: $TERMINODE_REQUEST_TIMESTAMP" \
  --header "X-Terminode-Nonce: $TERMINODE_REQUEST_NONCE" \
  --header "X-Terminode-Signature: $TERMINODE_REQUEST_SIGNATURE" \
  --data-binary @partner-recording.json

# Beklenen: HTTP 202, awaiting_anchor, canisterWritePerformed=false

curl --request POST \
  --header "Authorization: Bearer $TERMINODE_OPERATOR_API_KEY" \
  "$GATEWAY_URL/v1/partner-evidence/jobs/<job-id>/replay"

# Yalnız dead_letter -> awaiting_anchor geçişine izin verir.
# Önce dış hatanın nedeni giderilmelidir.

# İmza girdisi LF satır ayırıcılarıyla hazırlanır.
terminode-partner-callback-v1
<zaman-damgası>
<teslim-kimliği>
<tam-gövde-sha256>

# Eski zaman damgasını reddedin, HMAC değerini sabit süreli karşılaştırın ve
# her teslim kimliğini yalnız bir kez işleyin. Kalıcı kabulden sonra 2xx dönün.

cd gateway-server
npm run smoke:partner-callback

# Alıcı düzeltildikten sonra yalnız bildirim teslimini yeniden açın.
curl --request POST \
  --header "Authorization: Bearer $TERMINODE_OPERATOR_API_KEY" \
  "$GATEWAY_URL/v1/partner-evidence/jobs/<job-id>/callback/replay"

# Aynı teslim kimliği korunur; canister yazımı tekrarlanmaz.

Yönetilen teslim

Erişimi kesintisiz devredin, müşteriye bağımsız doğrulanabilir arşiv verin

Yönetilen Gateway v1.8, özellik sürümlerinin yanında güncel ve geçmiş kesin sürüm kabul kararlarını salt okunur olarak sunar. Kanıt rolü, veri seti anlık görüntüsünü ve canister tarafından üretilen kabul raporunu kendi SHA-256 değeriyle indirebilir.

cd gateway-server
npm run smoke:key-rotation
npm run smoke:offboarding

cd ..
python3 scripts/check_snapshot_restore_rehearsal.py --self-test
DFX_IDENTITY=default NETWORK=local DRY_RUN=0 \
  RESTORE_REHEARSAL_CONFIRM=local-snapshot-restore \
  SOURCE_DATASET_ID=1 ./scripts/check_snapshot_restore_rehearsal.py

TERMINODE_GATEWAY_API_KEY='<evidence-key>' \
  node scripts/export-customer-offboarding.mjs \
  --base-url https://gateway.example/v1 \
  --dataset-id 42 \
  --output-dir ../operator-private/offboarding/customer-42-<timestamp>

npm run verify:offboarding -- \
  ../operator-private/offboarding/customer-42-<timestamp>

Ölçülebilir pilot kapanışı

Pilot sonucunu iki dilli ve checksum destekli bir kayda dönüştürün

Pilot evidence aracı Türkçe ve İngilizce iş tanımı, gizlilik eki, owner matrix, teknik kanıt index’i, önce/sonra süreç metrikleri, müşteri kabul notu ve WP1-WP6 fon eşlemesi üretir. Çalışma dosyaları git tarafından yok sayılan operator-private alanında kalır; paylaşılabilir pakette müşteri takma adı kullanılır.

python3 scripts/pilot_evidence_pack.py init \
  --pilot-id PILOT-2026-001 \
  --customer-alias design-partner-a \
  --title "Spatial Acceptance Pilot"

python3 scripts/pilot_evidence_pack.py add-evidence \
  --pack-dir operator-private/pilot-evidence/PILOT-2026-001 \
  --evidence-id EVIDENCE-SNAPSHOT-001 \
  --kind dataset_snapshot \
  --file /guvenli/yol/dataset-snapshot.json \
  --description "Sınırlandırılmış dataset snapshot"

python3 scripts/pilot_evidence_pack.py finalize \
  --pack-dir operator-private/pilot-evidence/PILOT-2026-001
python3 scripts/pilot_evidence_pack.py verify \
  --pack-dir operator-private/pilot-evidence/PILOT-2026-001 --strict

# Tam sentetik paket geçer; değiştirilmiş doküman reddedilir.
python3 scripts/pilot_evidence_pack.py demo-smoke

Read APIs

Bounded query örnekleri

TermiNode map, agent ve adapterlar için bounded read yaklaşımını tercih eder. Yalnız aktif viewport, dataset, page veya proof record okunur.

dfx canister call spatial list_datasets_page '(0 : nat64, 20 : nat64)' --network ic

dfx canister call spatial query_feature_geojson_bbox_page \
  '(40.90 : float64, 28.80 : float64, 41.12 : float64, 29.20 : float64, opt 1 : opt nat64, 0 : nat64, 100 : nat64)' \
  --network ic

import { Actor, HttpAgent } from '@icp-sdk/core/agent';
import { idlFactory as spatialIdlFactory } from '@/lib/idl/spatial';

const agent = new HttpAgent({ host: 'https://icp-api.io' });
const spatial = Actor.createActor(spatialIdlFactory, {
  agent,
  canisterId: 'ov27b-fiaaa-aaaam-qi6dq-cai',
});

const datasets = await spatial.list_datasets_page(0n, 20n);
const geojson = await spatial.query_feature_geojson_bbox_page(
  40.90, 28.80, 41.12, 29.20, [1n], 0n, 100n
);

Evidence

Audit, proof ve export reçeteleri

Proof-layer workflow kullanışlı olacaksa portable evidence bırakmalıdır. Her pilot için dataset snapshot, checksum, feature history, audit page ve verification receipt birlikte tutulur.

dfx canister call spatial list_feature_versions_page '(7 : nat64, 0 : nat64, 20 : nat64)' --network ic

dfx canister call spatial list_audit_events '(0 : nat64, 50 : nat64)' --network ic

dfx canister call spatial export_dataset_snapshot_with_checksum '(1 : nat64)' --network ic

dfx canister call oracle_gateway verify_coordinates_full '(7 : nat64, 41.0214 : float64, 28.9105 : float64)' --network ic

MCP

Agent-ready read-only entegrasyon

MCP, bir AI agent GIS proof context okumak isterken write, market, custody veya administrative tool almaması gereken durumlarda kullanışlıdır.

{
  "mcpServers": {
    "terminode": {
      "command": "node",
      "args": ["/absolute/path/to/terminode/mcp-server/dist/index.js"],
      "env": {
        "TERMINODE_MCP_REPO_ROOT": "/absolute/path/to/terminode",
        "TERMINODE_MCP_NETWORK": "ic",
        "TERMINODE_MCP_SPATIAL_CANISTER": "ov27b-fiaaa-aaaam-qi6dq-cai",
        "TERMINODE_MCP_ORACLE_GATEWAY_CANISTER": "nfjvh-ziaaa-aaaam-qi6lq-cai",
        "TERMINODE_MCP_GOVERNANCE_CANISTER": "ncitt-uqaaa-aaaam-qi6la-cai",
        "TERMINODE_MCP_TRMG_LEDGER_CANISTER": "os3zv-iqaaa-aaaam-qi6da-cai"
      }
    }
  }
}

Utility boundary

TRMG iletişiminde ürün-first çizgi korunur

TRMG write credit, proof credit ve governance operasyonlarını destekler. Satış, yönetilen alım-satım ortamı, finansal beklenti veya otomatik hak ediş sağlamaz.