Skip to content

Commit 12ac6eb

Browse files
atticusofspartaatticusofsparta
committed
chore(adr): add adr for reassign evolve
1 parent 59b4298 commit 12ac6eb

File tree

2 files changed

+202
-0
lines changed

2 files changed

+202
-0
lines changed

‎docs/madr/1-reassign-evolve.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Reassign ANT to Evolve Implementation Kickoff on the ArNS Portal
2+
3+
- Status: Proposed
4+
- Approvers: [Ariel], [Dylan], [Atticus], [Phil], [David]
5+
- Date: [2025-01-30]
6+
- Authors: [Atticus]
7+
8+
## Context and Problem Statement
9+
10+
Currently to evolve the ANT we use AOS `Eval` - this introduces the problem of
11+
evaluating what the current version of the code is. If we maintain a variable in
12+
the state of the process containing a version number, that tells us only what
13+
that version number is. At any point the user - owner - of the ANT may `Eval`
14+
new code into the process resulting in changes to the process that may not
15+
reflect what we expect the version number we assigned to reflect. To overcome
16+
this we dryrun interactions on APIs and analyze the results to see if the APIs
17+
perform as expected - this is very inefficient as dry run calls to CU's are
18+
expensive in networking client side, as well as for the CU.
19+
20+
And so it is proposed to leverage the `Reassign-Name` handler in conjunction
21+
with `_boot` to fork the process state to a whole new ANT, assign that new ANT
22+
as the registered ANT to the specified ArNS name in the registry, and using the
23+
module ID of the process to identify process version and capabilities, and
24+
solely the module ID.
25+
26+
## Decision Drivers
27+
28+
- Improve the performance of ANT loading client side.
29+
- Ensure the upgrade process is more robust by using immutable module IDs.
30+
- Reduce computational load on CU infra.
31+
- Mitigate risks associated with reassigning ANT state and ARNS records.
32+
33+
## Considered Options
34+
35+
1. **Current Approach (Baseline)**
36+
- Multiple dry runs per ANT.
37+
- ETH compatibility checked via handler analysis.
38+
- Upgrade involves loading Lua code.
39+
2. **Optimized Approach (Proposed Change)**
40+
- Use the module ID to evaluate process version.
41+
- Upgrade via spawning a new ANT and reassigning ARNS records.
42+
43+
## Decision Outcome
44+
45+
### Chosen Option: Optimized Approach
46+
47+
The optimized approach reduces computational overhead and improves caching for
48+
better performance. It also shifts to a more robust upgrade mechanism using
49+
immutable module IDs rather than version detection heuristics. We can do this
50+
now that we compile and publish our own WASM binaries, rather than using an AOS
51+
binary and loading our code into it.
52+
53+
### Positive Consequences
54+
55+
- **Performance Improvement:** Reducing dry runs significantly speeds up ANT
56+
loading.
57+
- **Immutable Module Versioning:** Eliminates issues with heuristic version
58+
analysis.
59+
- **Reduced CU Load:** Fewer computations per ANT.
60+
61+
### Negative Consequences
62+
63+
- **Complicates Memory Usage on ANT Registry:** More ANTs means more state in
64+
the ANT registry, which currently doesn't have a cleanup process.
65+
- **Potential Integration Issues:** Existing integrations relying on fixed ANT
66+
IDs may break.
67+
- **State Limitations:** Large ANT states (e.g., >2000 undernames) may fail to
68+
bootstrap on spawn, meaning we need to understand the limitations there and
69+
decide what amounts we wish to support.
70+
71+
## Pros and Cons of the Options
72+
73+
### Current Approach
74+
75+
- `+` Already implemented and functional.
76+
- `+` Ensures ETH compatibility via handler checks.
77+
- `-` Multiple dry runs increase computational cost.
78+
- `-` Upgrade process relies on mutable version checks.
79+
80+
### Optimized Approach (Chosen)
81+
82+
- `+` 3x faster ANT loading.
83+
- `+` Reduces CU consumption.
84+
- `+` Enables robust versioning.
85+
- `-` Introduces new risks related to state migration and memory management.
86+
87+
## Links
88+
89+
- [Ariel]: https://github.com/arielmelendez
90+
- [David]: https://github.com/djwhitt
91+
- [Dylan]: https://github.com/dtfiedler
92+
- [Atticus]: https://github.com/atticusofsparta
93+
- [Phil]: https://github.com/vilenarios
94+
95+
## Notes
96+
97+
- Further analysis is required for large ANT states.
98+
- Records
99+
- Controllers
100+
- Consider preemptive PRs for integration updates.
101+
- for example permaweb deploy
102+
- Implement observation tools to track stale ANTs in the ANT registry
103+
- Fastest solution is probably adding a `prune` handler to the ANT registry
104+
that consumes process IDs and removes them, then use a cron job in gh
105+
actions to pull the ArNS records and decide which ANT ids to prune

‎docs/madr/template.md

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# [short title of solved problem and solution]
2+
3+
- Status: [proposed | rejected | accepted | deprecated | superseded by
4+
[ADR-5](5-example.md)]
5+
- Approvers: [list everyone involved in the decision]
6+
- Date: [YYYY-MM-DD]
7+
- Authors: [list of authors]
8+
9+
## Context and Problem Statement
10+
11+
[Describe the context and the problem that needs to be solved, capturing the
12+
background and why this decision is necessary.]
13+
14+
## Decision Drivers
15+
16+
[Identify key factors that influence the decision, such as
17+
requirements, constraints, and other considerations.]
18+
19+
- [driver 1]
20+
- [driver 2]
21+
- [driver 3]
22+
23+
## Considered Options
24+
25+
[List the options that were considered to address the problem, providing a brief
26+
overview of each.]
27+
28+
- [option 1]
29+
- [option 2]
30+
- [option 3]
31+
32+
## Decision Outcome
33+
34+
[Describe the decision that was made, including why it was chosen over the
35+
other options.]
36+
37+
### Positive Consequences
38+
39+
[Highlight the benefits and positive outcomes expected from this decision.]
40+
41+
- [consequence 1]
42+
- [consequence 2]
43+
44+
### Negative Consequences
45+
46+
[Identify any drawbacks or negative outcomes that might result from this decision.]
47+
48+
- [consequence 1]
49+
- [consequence 2]
50+
51+
## Pros and Cons of the Options
52+
53+
[Compare the pros and cons of each considered option.]
54+
55+
### [option 1]
56+
57+
- `+` [pro 1]
58+
- `+` [pro 2]
59+
- `-` [con 1]
60+
- `-` [con 2]
61+
62+
### [option 2]
63+
64+
- `+` [pro 1]
65+
- `+` [pro 2]
66+
- `-` [con 1]
67+
- `-` [con 2]
68+
69+
### [option 3]
70+
71+
- `+` [pro 1]
72+
- `+` [pro 2]
73+
- `-` [con 1]
74+
- `-` [con 2]
75+
76+
## Links
77+
78+
[Include any relevant links to documents, discussions, or other resources that
79+
provide additional context or background information.]
80+
81+
- [link 1](url)
82+
- [link 2](url)
83+
84+
## Related Decisions
85+
86+
[List any related ADRs or decisions that are connected to this one.]
87+
88+
- [ADR-1](1-example.md) - [Title of ADR-1]
89+
- [ADR-2](2-example.md) - [Title of ADR-2]
90+
91+
## Notes
92+
93+
[Include any additional notes or comments that are relevant to the decision.]
94+
95+
---
96+
97+
[ADR Template]: https://adr.github.io/

0 commit comments

Comments
 (0)