The Situs Protocol supports funding for place-based regeneration, conservation, and restoration, emphasizing a deep 'sense of place' and placemaking. It offers customizable 'member accounts'—like alex.tokyo, alex.ganges, and alex.nyc—that allow individuals to connect with specific locations. These community-owned and governed accounts are utilized by local organizations for memberships and include features for voting and other benefits. Additionally, each account can handle transactions with any Ethereum-based asset, supporting local initiatives. The protocol aims to deepen connections to places and bridge the gap between mere physical space and meaningful place.
Contracts to create a top-level domain (TLD) such as .basin
sequenceDiagram
participant deployer as Deployer
participant basinMetadataStore as SitusMetadataStore
participant basinForbiddenTLDs as SitusForbiddenTLDs
participant basinResolverNonUpgradable as SitusResolverNonUpgradable
participant basinTLDFactory as SitusTLDFactory
participant basinMetadata3 as SitusMetadata3
participant basinTLD as SitusTLD
deployer ->>+ basinMetadataStore: Instantiate
deployer ->>+ basinForbiddenTLDs: Instantiate
deployer ->>+ basinResolverNonUpgradable: Instantiate
deployer ->>+ basinTLDFactory: Instantiate (with SitusForbiddenTLDs and SitusMetadataStore)
basinForbiddenTLDs ->>+ basinTLDFactory: addFactoryAddress
basinResolverNonUpgradable ->>+ basinTLDFactory: addFactoryAddress
deployer ->>+ basinTLDFactory: ownerCreateTld (non-custom metadata)
deployer ->>+ basinMetadata3: Instantiate
deployer ->>+ basinTLD: Instantiate (with SitusTLDFactory and BasinMetadata3)
sequenceDiagram
participant O as TLD Owner
participant A as Admin
participant F as SitusTLDFactory
participant S as SitusTLD
participant T as ForbiddenTLDs
Note over A, F: Admin Operations
A->>+F: changePrice(newPrice)
A->>+F: changeRoyalty(newRoyalty)
A->>+F: changeMetadataAddress(newAddress)
A->>+F: ownerCreateTld(_name, _symbol, _tldOwner, _domainPrice, _buyingEnabled)
A->>F: toggleBuyingTlds()
Note over O, T: TLD Creation by TLD Owner
O->>+F: createTld(_name, _symbol, _tldOwner, _domainPrice, _buyingEnabled)
F->>F: Verify buying is enabled
F->>F: Check payment
F->>F: _createTld (internal function call)
F->>F: Validate TLD name
F->>+T: Check if TLD is forbidden
F->>S: Create new TLD
F->>T: Add new TLD to forbidden list
sequenceDiagram
participant U as User
participant O as TLD Owner
participant T as SitusTLD
participant M as SitusMetadataStore
Note over O, M: TLD Operations by TLD Owner
O->>M: Change Metadata Description
O->>T: Toggle Buying
O->>T: Change Max Length for Domain Name
O->>T: Change Domain Price
O->>T: Change Referral Fee
O->>T: Freeze Metadata
O->>T: Change Royalty Amount
Note over U, T: Domain Creation by User
U->>T: Mint Domain
U->>T: Edit Domain Data
U->>T: Edit Default Domain
U->>T: Transfer Domain
U->>T: Burn Domain
If buying is disabled, owner, but not users can mint.
cp .env.sample .envadd PRIVATE_KEY (default) or MNEMONIC. Never share your PRIMARY_KEY or MNEMONIC with anyone (or check into a repo).
add BASESCAN_API_KEY
npm installnpm run buildnpm run testnpm run lintnpm run fmtDeploy to in-process instance of Hardhat Network, results will be lost.
npm run protocol:deployandverify hardhatStart local network
npx hardhat nodeStart a new terminal and execute:
npm run protocol:deployandverify localhostExecute:
npm run customtld:deployandverify localhostMake sure .env has PRIMARY_KEY (or MNEMONIC) and BASESCAN_API_KEY values filled in.
If ignition/deployments/chain-84532 does not exist, run this command.
Update parameters under SitusProtocolModule in ignition/parameters.json.
Start a new terminal and execute:
npm run protocol:deployandverify baseTestnetIf ignition/deployments/chain-84532 does exist, run this command.
Update parameters under SitusProtocolModule in ignition/parameters.json.
Start a new terminal and execute:
npm run protocol:resetdeployandverify baseTestnetVerify SitusTLD and BasinTLD separately since they were created by the factory using the following steps:
Update deployer, and tldAddressSitus and tldAddressBasin using the values in deployed_addresses.json for the network in ignition/modules/archive/verify/manualTldVerification.js.
Update factoryAddress and metadataAddress using the values in deployed_addresses.json for the network in ignition/modules/archive/verify/argumentsSitus.js and ignition/modules/archive/verify/argumentsBasin.js
npx hardhat run ignition/modules/archive/verify/manualTldVerification.js --network base // (or baseTestnet)update custom TLD parameters under SitusTLD in ignition/parameters.json.
Execute:
npm run customtld:deployandverify baseTestnet- Name Sepolia
- Network Name Base Sepolia
- RPC Endpoint https://sepolia.base.org
- Chain ID 84532
- Currency Symbol ETH
- Block Explorer https://sepolia-explorer.base.org
- Reference module in tests
- Deploy to Base Mainnet
- Point Frontend to Base Mainnet
- Adapted from the Flexi contracts in punk-contracts repo by @tempe-techie and @johnson86tw and offered under same LICENSE
Punk Domains allow anyone to either create a top-level domain (TLD) such as .wagmi or a normal domain such as techie.wagmi. In addition, users can add some other data to their domain:
- description
- redirect URL (useful together with the Punk Domains browser extension)
- profile picture (an address and token ID of an NFT)
Verifying TLD contracts generated through the factory is a bit tricky, but there is a way around the issue. See scripts/temp/deployTld.js for instructions.
- Flatten the code (
npx hardhat flatten <path-to-contract>.sol >> <flat-contract-name>.sol). - Delete all instances of SPDX Licences except one.
- Go to Etherscan and select single file verification.
- Turn on optimizations.
- Select 0.8.4 for compiler (do not delete other pragma solidity lines in the file, even if they are for a different Solidity version).
- Generate the ABI-encoded constructor arguments using this online tool: https://abi.hashex.org/. Make sure you generate all arguments needed in the TLD constructor, including the Factory address.
- Submit for verification and hope for the best :)
Most audit tools will require you to flatten the contracts. This means that all contracts that are defined under the imports will actually be imported into one .sol file, so all code is in one place.
First create a new folder called flattened:
mkdir flattenedTo flatten a contract, run this command:
npx hardhat flatten <path-to-contract> >> flattened/<flat-contract-name>.solYou may also need to give all contracts in the flattened file the same Solidity version. And you may need to delete all SPDX lines except the very first one.
Use Docker:
sudo docker pull mythril/mythGo to the flattened folder and run this command:
sudo docker run -v $(pwd):/tmp mythril/myth -v4 analyze /tmp/<flat-contract-name>.sol --max-depth 10Or, if you don't use Docker, use this command alone:
myth -v4 analyze flattened/PunkForbiddenTlds.sol --max-depth 10Flags:
v4: verboseo: outputa: address onchainl: automatically retrieve dependenciesmax-depth: maximum recursion depth
Docs: https://mythril-classic.readthedocs.io/en/master/security-analysis.html
Install Slither:
pip3 install slither-analyzer --userRun it in the flattened folder:
slither .Docs: https://github.com/crytic/slither
Run npx hardhat clean and then npx hardhat compile.