Add PIPs prpoposal and state management proposal

Signed-off-by: Antonio Navarro Perez <antnavper@gmail.com>

3 files changed, 141 insertions, 0 deletions

diff --git a/docs/proposals/PIP-000.md b/docs/proposals/PIP-000.md
new file mode 100644
index 0000000..35dea1d
--- /dev/null
+++ b/docs/proposals/PIP-000.md
@@ -0,0 +1,35 @@
+# PIP Template
+
+| Field | Value |
+| --- | --- |
+| ENIP | 0 |
+| Title | PIP Template |
+| Author | Antonio Navarro |
+| Status | Draft |
+| Created | 2024-01-15 |
+| Updated | 2024-01-15 |
+| Target version | optional |
+
+## Abstract
+
+A short description of the technical issue being addressed.
+
+## Rationale
+
+Proposal motivation.
+
+## Specification
+
+Technical specification of the changes proposed.
+
+## Alternatives
+
+How the issue is currently solved or can be solved if this change is not accepted?
+
+## Impact
+
+How this change would impact parscan functionality: backward compatibility will break, performance improvements or issues, corner cases and so on.
+
+## References
+
+Links to additional documentation describing related features or other kind of related information.
diff --git a/docs/proposals/PIP-001.md b/docs/proposals/PIP-001.md
new file mode 100644
index 0000000..c916a07
--- /dev/null
+++ b/docs/proposals/PIP-001.md
@@ -0,0 +1,94 @@
+# Fetch and Restore VM State Interfaces
+
+| Field | Value |
+| --- | --- |
+| ENIP | 1 |
+| Title | Fetch and Restore VM State Interfaces |
+| Author | Antonio Navarro |
+| Status | Draft |
+| Created | 2024-01-15 |
+| Updated | 2024-01-15 |
+
+## Abstract
+
+This proposal introduces interfaces for saving and restoring the state of a parscan VM, a crucial feature for a variety of use cases.
+We aim to provide a detailed description of these interfaces, focusing on their integration into the VM.
+This will enable functionalities like snapshotting the VM state and tracking new and removed operations from the stack, offering greater control and flexibility in VM management.
+
+## Rationale
+
+There is an essential need to efficiently store and manage the state of VMs.
+Different scenarios might require either a complete copy of the current state or an understanding of the changes made, facilitating storage in various formats like Merkle Trees, CRDTs, or others.
+This functionality is critical for ensuring data consistency, enabling state recovery, and supporting complex computing tasks that require VM state manipulation.
+
+## Specification
+
+### Snapshotting
+
+The snapshot interface aims to simplify the process of serializing and deserializing VM states.
+It includes:
+
+```go
+
+// SnapshotValue is a serializable, simpler representation of *reflect.Value
+type SnapshotValue struct {
+    Kind  Kind
+    Value *any
+}
+
+// Snapshot contains all needed data to continue previously halted VM execution.
+type Snapshot struct {
+    FramePointer, InstructionPointer int64
+    InstructionCounter               int64
+    Values                           []*SnapshotValue
+}
+
+// Snapshotter will be implemented by the VM to make it possible to get and load Snapshots into it. This interface might not really be needed, only the methods on the VM.
+type Snapshotter interface {
+    // Take halts VM execution and generates a *Snapshot from it.
+    Take(context.Context) (*Snapshot, error)
+
+    // Load halts VM execution and load the provided *Snapshot to it.
+    Load(context.Context, *Snapshot) error
+}
+
+```
+
+This interface halts execution to ensure consistency during state capture and restoration.
+Note: VM version compatibility is critical as any changes to generated OP codes might impact state execution.
+
+### Possible solution: OP Step Parser
+
+The OP Step Parser will allow tracking changes on the VM stack, communicating these changes to an external entity.
+This entity, in conjunction with the Snapshotter, will determine the data segments that require updating.
+
+```go
+
+// Implementation details to be added.
+
+```
+
+### Possible solution: track changes made on memory internally on the VM
+
+To maintain optimum VM performance, an alternative is to track memory changes internally within the VM, incorporating these into the Snapshot output.
+
+```go
+
+// Implementation details to be added.
+
+```
+
+
+## Alternatives
+
+While no other alternatives were identified, a thorough review was conducted to ensure the proposed solutions are the most effective and efficient for the intended purpose.
+
+## Impact
+
+The implementation of these interfaces is expected to marginally affect VM performance.
+However, precise benchmarking is needed to quantify the impact.
+The anticipated benefits in terms of improved state management and recovery capabilities are significant and are expected to outweigh the performance costs.
+
+## References
+
+[Actual GnoVM implementation](https://github.com/gnolang/gno).
diff --git a/docs/proposals/README.md b/docs/proposals/README.md
new file mode 100644
index 0000000..a4f3517
--- /dev/null
+++ b/docs/proposals/README.md
@@ -0,0 +1,12 @@
+# Parscan Improvement Proposals
+
+## Introduction
+
+This is the index of Parscan Improvement Proposals, known as PIPs.
+
+## All Proposals by Number
+
+| Number | Status   | Title                                                                |
+| ------ | -------- |----------------------------------------------------------------------|
+| 0      | Draft    | [PIP Template](PIP-000.md)                                           |
+| 1      | Draft    | [Fetch and Restore VM State Interfaces](PIP-001.md)            |