Skip to content

Commit 007362c

Browse files
SIGNIAINDEXSIGNIAINDEX
authored
Create faq.md
1 parent ca64a8a commit 007362c

1 file changed

Lines changed: 297 additions & 0 deletions

File tree

‎docs/faq.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
2+
# FAQ
3+
4+
This FAQ answers common questions about SIGNIA: what it is, what it is not, and how to use it correctly in production settings.
5+
6+
---
7+
8+
## 1) What is SIGNIA?
9+
10+
SIGNIA is a structure-level on-chain compilation system. It converts real-world, already-formed artifacts (repos, specs, schemas, workflows, configs) into **canonical, verifiable, composable structural representations**.
11+
12+
SIGNIA focuses on structure, not execution. It produces deterministic bundles (schema/manifest/proof) that can be verified locally and optionally anchored on Solana.
13+
14+
---
15+
16+
## 2) What problem does SIGNIA solve?
17+
18+
SIGNIA provides a stable structural anchor for artifacts that otherwise drift over time.
19+
20+
It solves:
21+
- “Which exact interface contract did we rely on?”
22+
- “What configuration graph was approved at that point in time?”
23+
- “Can we verify the published structure independently?”
24+
- “Can we reference this structure on-chain by hash?”
25+
26+
---
27+
28+
## 3) Is SIGNIA a smart contract framework?
29+
30+
No.
31+
32+
SIGNIA does not execute application logic, deploy code as programs, or provide a runtime.
33+
It compiles structure into a verifiable form and optionally registers identifiers on-chain.
34+
35+
---
36+
37+
## 4) Does SIGNIA store content on-chain?
38+
39+
No.
40+
41+
The on-chain registry stores minimal identifiers (schema hash, optional manifest hash/proof root, and minimal metadata). It does not store full schemas or arbitrary content.
42+
43+
Schemas and bundles are distributed off-chain, while the chain provides an anchor and a stable handle.
44+
45+
---
46+
47+
## 5) What does “structure-level” mean?
48+
49+
It means SIGNIA models:
50+
- entities (modules, endpoints, fields)
51+
- relationships (dependencies, references)
52+
- types and constraints
53+
- invariants required for verification
54+
55+
It does not model:
56+
- runtime behavior
57+
- execution semantics
58+
- operational outcomes
59+
60+
---
61+
62+
## 6) What outputs do I get from SIGNIA?
63+
64+
A deterministic bundle containing:
65+
- `schema.json`: canonical structural schema (versioned)
66+
- `manifest.json`: compilation context and integrity links
67+
- `proof.json`: cryptographic verification material (e.g., Merkle root)
68+
69+
Optionally, the schema hash can be registered on Solana.
70+
71+
---
72+
73+
## 7) How does verification work?
74+
75+
Verification checks:
76+
- `schema.json` canonical bytes match the schema hash
77+
- `manifest.json` references match schema hash and proof root
78+
- `proof.json` root matches the leaf set and deterministic ordering rules
79+
- all versions and domains match expected specifications
80+
81+
Verification does not require trust in the compiler runner; any party can recompute and verify.
82+
83+
---
84+
85+
## 8) What guarantees does SIGNIA provide?
86+
87+
The primary guarantees are:
88+
- determinism: same input → same output
89+
- canonical encoding: stable bytes for hashing
90+
- verifiable integrity: hashes and proofs bind outputs
91+
- composability: schemas can be referenced and combined by hash
92+
93+
SIGNIA does not guarantee the real-world “truthfulness” of an input. It guarantees reproducibility and integrity of the compilation.
94+
95+
---
96+
97+
## 9) Can I compile a GitHub repository?
98+
99+
Yes, if you use a repo plugin and provide an immutable reference (commit SHA recommended).
100+
For determinism, avoid floating refs like `main` without pinning.
101+
102+
A correct compilation input is something like:
103+
- repo URL + commit SHA
104+
- or a tarball with a stable checksum
105+
106+
---
107+
108+
## 10) Can I compile private repositories?
109+
110+
Yes, but it requires careful handling:
111+
- access must be explicit (tokens/credentials)
112+
- inputs must remain pinned and reproducible
113+
- secrets must never be stored in bundles
114+
- verification must be possible by authorized parties
115+
116+
For public registries, prefer public inputs or publish only hashes while distributing bundles privately.
117+
118+
---
119+
120+
## 11) Does SIGNIA require Solana?
121+
122+
No.
123+
124+
SIGNIA can be used fully off-chain:
125+
- compile
126+
- verify
127+
- store and distribute bundles
128+
129+
Solana is used as an optional registry to anchor schema identifiers and enable on-chain referencing.
130+
131+
---
132+
133+
## 12) Why Solana for the registry?
134+
135+
Solana offers:
136+
- low-latency, low-cost transactions
137+
- a mature program model for registries
138+
- broad ecosystem integration potential
139+
140+
However, the architecture keeps the registry minimal so the system remains portable conceptually.
141+
142+
---
143+
144+
## 13) How does SIGNIA handle schema evolution?
145+
146+
SIGNIA treats evolution as a relationship between immutable schema hashes.
147+
148+
Evolution can be expressed via:
149+
- version links (supersedes, compatible_with, forks_from)
150+
- explicit compatibility metadata in manifests
151+
- separate registry records per schema hash
152+
153+
A new schema version is a new hash. Links define the relationship.
154+
155+
---
156+
157+
## 14) Can outputs be indexed and searched?
158+
159+
Yes, but indexing is off-chain.
160+
161+
The registry is not a full-text search engine. It provides stable identifiers.
162+
A separate indexing service (optional) can:
163+
- ingest bundles
164+
- build search indexes
165+
- support rich queries over entities/edges
166+
167+
---
168+
169+
## 15) Is SIGNIA an oracle?
170+
171+
Not in the typical price/data oracle sense.
172+
173+
SIGNIA provides a verifiable structural representation. It can be used as a building block for oracle-like systems that need to reference immutable interface or rule structure.
174+
175+
---
176+
177+
## 16) How do plugins affect determinism?
178+
179+
Plugins must be deterministic by contract.
180+
181+
A plugin must:
182+
- normalize inputs consistently
183+
- avoid environment-dependent behavior
184+
- avoid unpinned network calls
185+
- define ordering and identity rules explicitly
186+
- produce IR that can be canonicalized deterministically
187+
188+
Plugins should be versioned and their version recorded in the manifest.
189+
190+
---
191+
192+
## 17) What about AI in SIGNIA?
193+
194+
AI can be used in a controlled, deterministic way, for example:
195+
- classification into known categories
196+
- mapping to predefined structural types
197+
- extracting structured fields when the output is fully normalized
198+
199+
If AI introduces nondeterminism, it must be confined to **non-hashed metadata domains** or replaced by deterministic rules.
200+
201+
Determinism is the primary constraint.
202+
203+
---
204+
205+
## 18) Can I trust bundles produced by someone else?
206+
207+
You should not trust them blindly. You should verify.
208+
209+
The verification model is designed so:
210+
- anyone can recompute hashes
211+
- proofs bind schema and manifest
212+
- mismatches are detectable
213+
214+
This is the intended trust posture.
215+
216+
---
217+
218+
## 19) What are common pitfalls?
219+
220+
- Using unpinned inputs (floating branches, mutable URLs)
221+
- Allowing network access without content addressing
222+
- Including timestamps or random IDs in hashed domains
223+
- Relying on filesystem iteration order
224+
- Mixing hashed and non-hashed metadata without clear boundaries
225+
226+
---
227+
228+
## 20) Is there a token?
229+
230+
No.
231+
232+
There is currently **no token issued**.
233+
234+
If you see token claims, treat them as unrelated to the SIGNIA repository unless explicitly documented in official releases and channels.
235+
236+
---
237+
238+
## 21) How do I contribute?
239+
240+
Open a PR with:
241+
- a clear summary
242+
- tests for determinism or compatibility
243+
- documentation updates where required
244+
245+
Start with:
246+
- documentation improvements
247+
- new plugin adapters
248+
- better fixtures and verification coverage
249+
250+
---
251+
252+
## 22) Where do I start if I want to integrate SIGNIA?
253+
254+
Start off-chain:
255+
1. Compile an artifact and generate a bundle.
256+
2. Verify the bundle locally.
257+
3. Integrate by consuming the schema hash and bundle format in your system.
258+
4. Optionally register the schema hash on Solana for on-chain referencing.
259+
260+
---
261+
262+
## 23) What is the expected stability policy?
263+
264+
SIGNIA aims to keep stable:
265+
- bundle contracts (schema/manifest/proof) once published
266+
- hash domains and canonical encoding rules
267+
- registry instruction semantics
268+
269+
Anything that changes those must be versioned and documented.
270+
271+
---
272+
273+
## 24) How do I report security issues?
274+
275+
Please do not open public issues for sensitive vulnerabilities.
276+
277+
Use the security policy in `SECURITY.md` to report vulnerabilities responsibly.
278+
279+
---
280+
281+
## 25) Where can I see examples?
282+
283+
Check:
284+
- `examples/` for runnable inputs and expected outputs
285+
- `docs/` for formal specifications
286+
- CI workflows for the expected build and verification commands
287+
288+
---
289+
290+
## Quick link index
291+
292+
- Overview: `docs/overview.md`
293+
- Architecture: `docs/architecture.md`
294+
- Glossary: `docs/glossary.md`
295+
- CLI: `docs/cli/usage.md`
296+
- Determinism: `docs/data-model/determinism-rules.md`
297+
- On-chain registry: `docs/onchain/registry-program.md`

0 commit comments

Comments
 (0)