chore(docs): update readme

ar-io · Jun 25, 2024 · 462de2b · 462de2b
1 parent fd40bb1
commit 462de2b
Showing 1 changed file with 162 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -6,33 +6,175 @@ The implementation of the ar.io network contract is written in lua and deployed
 
 ## Contract Spec
 
-### Arweave Name Service (ArNS)
+### Action Map Handlers Specification
 
-- `BuyRecord` - buy a record
-- `ExtendLease` - extend the lease of a record
-- `IncreaseUndernameLimit` - increase the undername limit of a record
+#### General Structure
 
-### Gateway Registry
+Each handler is identified by an action name and it has required and optional tags for its input. The handlers can be categorized into "read" and "write" operations.
 
-- `JoinNetwork` - join a network
-- `LeaveNetwork` - leave a network
-- `UpdateGatewaySettings` - update a gateway settings
-- `IncreaseOperatorStake`- increase operator stake
-- `DecreaseOperatorStake` - decrease operator stake
-- `DelegateStake` - delegate stake to an existing gateway
-- `DecreaseDelegatedStake` - decrease delegated stake to an existing gateway
+#### Action Map
 
-### Observer Incentive Protocol (OIP)
+```lua
+local ActionMap = {
+    -- reads
+    Info = "Info",
+    State = "State",
+    Transfer = "Transfer",
+    Balance = "Balance",
+    Balances = "Balances",
+    DemandFactor = "Demand-Factor",
+    DemandFactorSettings = "Demand-Factor-Settings",
+    -- EPOCH READ APIS
+    Epochs = "Epochs",
+    Epoch = "Epoch",
+    EpochSettings = "Epoch-Settings",
+    PrescribedObservers = "Epoch-Prescribed-Observers",
+    PrescribedNames = "Epoch-Prescribed-Names",
+    Observations = "Epoch-Observations",
+    Distributions = "Epoch-Distributions",
+    -- NAME REGISTRY READ APIS
+    Record = "Record",
+    Records = "Records",
+    ReservedNames = "Reserved-Names",
+    ReservedName = "Reserved-Name",
+    TokenCost = "Token-Cost",
+    -- GATEWAY REGISTRY READ APIS
+    Gateway = "Gateway",
+    Gateways = "Gateways",
+    GatewayRegistrySettings = "Gateway-Registry-Settings",
+    -- writes
+    CreateVault = "Create-Vault",
+    VaultedTransfer = "Vaulted-Transfer",
+    ExtendVault = "Extend-Vault",
+    IncreaseVault = "Increase-Vault",
+    BuyRecord = "Buy-Record",
+    ExtendLease = "Extend-Lease",
+    IncreaseUndernameLimit = "Increase-Undername-Limit",
+    JoinNetwork = "Join-Network",
+    LeaveNetwork = "Leave-Network",
+    IncreaseOperatorStake = "Increase-Operator-Stake",
+    DecreaseOperatorStake = "Decrease-Operator-Stake",
+    UpdateGatewaySettings = "Update-Gateway-Settings",
+    SaveObservations = "Save-Observations",
+    DelegateStake = "Delegate-Stake",
+    DecreaseDelegateStake = "Decrease-Delegate-Stake",
+}
+```
+
+### Handlers and Their Tags
+
+#### 1. Transfer
+
+- **Required Tags**:
+  - `Recipient`: Valid Arweave address
+  - `Quantity`: Integer greater than 0
+- **Optional Tags**:
+  - `X-*`: Tags beginning with "X-" are forwarded.
+
+#### 2. CreateVault
+
+- **Required Tags**:
+  - `Lock-Length`: Integer greater than 0
+  - `Quantity`: Integer greater than 0
+
+#### 3. VaultedTransfer
+
+- **Required Tags**:
+  - `Recipient`: Valid Arweave address
+  - `Lock-Length`: Integer greater than 0
+  - `Quantity`: Integer greater than 0
+
+#### 4. ExtendVault
+
+- **Required Tags**:
+  - `VaultId`: Valid Arweave address
+  - `ExtendLength`: Integer greater than 0
+
+#### 5. IncreaseVault
+
+- **Required Tags**:
+  - `Vault-Id`: Valid Arweave address
+  - `Quantity`: Integer greater than 0
+
+#### 6. BuyRecord
+
+- **Required Tags**:
+  - `Name`: String
+  - `Purchase-Type`: String
+  - `Process-Id`: Valid Arweave address
+  - `Years`: Integer between 1 and 5
+
+#### 7. ExtendLease
+
+- **Required Tags**:
+  - `Name`: String
+  - `Years`: Integer between 1 and 5
+
+#### 8. IncreaseUndernameLimit
+
+- **Required Tags**:
+  - `Name`: String
+  - `Quantity`: Integer between 1 and 9990
+
+#### 9. TokenCost
+
+- **Required Tags**:
+  - `Intent`: Must be valid registry interaction (e.g., BuyRecord, ExtendLease, IncreaseUndernameLimit)
+- **Optional Tags**:
+  - `Years`: Integer between 1 and 5
+  - `Quantity`: Integer greater than 0
+
+#### 10. JoinNetwork
+
+- **Required Tags**:
+  - `Operator-Stake`: Quantity
+- **Optional Tags**:
+  - `Label`, `Note`, `FQDN`, `Port`, `Protocol`, `Allow-Delegated-Staking`, `Min-Delegated-Stake`, `Delegate-Reward-Share-Ratio`, `Properties`, `Auto-Stake`, `Observer-Address`
+
+#### 11. LeaveNetwork
+
+- **No specific tags required**
+
+#### 12. IncreaseOperatorStake
+
+- **Required Tags**:
+  - `Quantity`: Integer greater than 0
+
+#### 13. DecreaseOperatorStake
+
+- **Required Tags**:
+  - `Quantity`: Integer greater than 0
+
+#### 14. DelegateStake
+
+- **Required Tags**:
+  - `Target`: Valid Arweave address
+  - `Quantity`: Integer greater than 0
+
+#### 15. DecreaseDelegateStake
+
+- **Required Tags**:
+  - `Target`: Valid Arweave address
+  - `Quantity`: Integer greater than 0
+
+#### 16. UpdateGatewaySettings
+
+- **Optional Tags**:
+  - `Label`, `Note`, `FQDN`, `Port`, `Protocol`, `Allow-Delegated-Staking`, `Min-Delegated-Stake`, `Delegate-Reward-Share-Ratio`, `Properties`, `Auto-Stake`, `Observer-Address`
+
+#### 17. SaveObservations
+
+- **Required Tags**:
+  - `Report-Tx-Id`: Valid Arweave address
+  - `Failed-Gateways`: Comma-separated string of valid Arweave addresses
+
+#### 18. EpochSettings, DemandFactorSettings, GatewayRegistrySettings
 
-- `SaveObservations` - save observations for a given epoch
-- `Observations` - get observations for a given Epoch
-- `PrescribedObservers` - get prescribed observers for a given Epoch
-- `PrescribedNames` - get prescribed names for a given Epoch
+- **No specific tags required**
 
-### Epoch
+#### 19. Info, State, Gateways, Gateway, Balances, Balance, DemandFactor, Record, Records, Epoch, Epochs, PrescribedObservers, Observations, PrescribedNames, Distributions, ReservedNames, ReservedName
 
-- `Epoch` - get epoch details
-- `Epochs` - get all epochs
+- **No specific tags required**
 
 ## Developers