1  # dtub.testnet Deployment Tools
  2  
  3  This directory contains tools for deploying DaokoTube to the dtub.testnet NEAR account.
  4  
  5  ## IPFS Hash Deployment
  6  
  7  The `deploy-to-ipfs-hash.js` script allows you to deploy a specific IPFS hash to the dtub.testnet account (or any other NEAR account with a web4 contract).
  8  
  9  ### Prerequisites
 10  
 11  1. Node.js installed
 12  2. The dtub.testnet account must have a web4 contract deployed
 13  3. Access to the private key for the account
 14  
 15  ### Deploying the Web4 Contract
 16  
 17  Before you can deploy content to your NEAR account, you need to deploy the web4-min-contract. This is a one-time setup process:
 18  
 19  #### Option 1: Using Pre-built Contract (Recommended)
 20  
 21  1. Install [near-cli-rs](https://github.com/near/near-cli-rs):
 22     ```bash
 23     curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh
 24     ```
 25  
 26  2. Login to your NEAR account:
 27     ```bash
 28     near account login
 29     ```
 30  
 31  3. Deploy the pre-built contract:
 32     ```bash
 33     # Download the latest release
 34     curl -L https://github.com/vgrichina/web4-min-contract/releases/download/0.1.1/web4-min -o web4-min.wasm
 35  
 36     # Deploy to your account
 37     near deploy --wasmFile web4-min.wasm --accountId your-account.testnet
 38     ```
 39  
 40  #### Option 2: Building from Source
 41  
 42  If you want to customize the contract or build from source:
 43  
 44  1. Install [Zig](https://ziglang.org/learn/getting-started/#installing-zig) (v0.13.0 or later):
 45     ```bash
 46     # For Ubuntu/Debian
 47     sudo snap install zig --classic --beta
 48  
 49     # For macOS
 50     brew install zig
 51     ```
 52  
 53  2. Clone the repository:
 54     ```bash
 55     git clone https://github.com/vgrichina/web4-min-contract.git
 56     cd web4-min-contract
 57     ```
 58  
 59  3. Build the contract:
 60     ```bash
 61     zig build --release=small
 62     ```
 63  
 64  4. Deploy the contract:
 65     ```bash
 66     near deploy --wasmFile zig-out/bin/web4-min --accountId your-account.testnet
 67     ```
 68  
 69  #### Verifying the Deployment
 70  
 71  After deploying, verify that the contract is working:
 72  
 73  ```bash
 74  # This should return the contract's static URL (if any)
 75  near view your-account.testnet web4_get
 76  ```
 77  
 78  Once the web4 contract is deployed, you can proceed with deploying your IPFS content using the tools in this directory.
 79  
 80  ### Quick Start
 81  
 82  ```bash
 83  # Extract the current IPFS hash
 84  npx -y ./dtub.testnet/extract-hash.js dtub.testnet
 85  
 86  # Set your private key as an environment variable
 87  export NEAR_SIGNER_KEY="ed25519:your-private-key"
 88  
 89  # Deploy to a specific IPFS hash
 90  npx -y ./dtub.testnet/deploy-to-ipfs-hash.js dtub.testnet QmYourIPFSHash
 91  ```
 92  
 93  ### Setting Up Your Private Key
 94  
 95  The deployment script requires your NEAR private key to sign transactions. You need to set it as an environment variable:
 96  
 97  ```bash
 98  export NEAR_SIGNER_KEY="ed25519:your-private-key"
 99  ```
100  
101  #### Where to Find Your Private Key
102  
103  Your private key is stored in the NEAR credentials file, which is created when you log in with the NEAR CLI:
104  
105  1. The file is located at: `~/.near-credentials/testnet/your-account.testnet.json`
106  2. Open this file with any text editor: `cat ~/.near-credentials/testnet/dtub.testnet.json`
107  3. Look for the `private_key` field in the JSON file
108  4. Copy the entire string (including the `ed25519:` prefix)
109  
110  #### Private Key Format
111  
112  The `NEAR_SIGNER_KEY` must be in the correct format:
113  - It must start with `ed25519:`
114  - It must be followed by the base58-encoded private key
115  - Example: `ed25519:2JKZSWEyFGDtmXxk...`
116  
117  ### Deployment Options
118  
119  Deploy to dtub.testnet with a specific IPFS hash:
120  
121  ```bash
122  # Using npx directly (recommended)
123  npx -y ./dtub.testnet/deploy-to-ipfs-hash.js dtub.testnet QmYourIPFSHash
124  
125  # Or if you've installed the package
126  cd dtub.testnet
127  npm run deploy:testnet QmYourIPFSHash
128  ```
129  
130  Deploy to any account:
131  
132  ```bash
133  npx -y ./dtub.testnet/deploy-to-ipfs-hash.js account-name.testnet QmYourIPFSHash
134  ```
135  
136  ### Extracting the Current IPFS Hash
137  
138  Before deploying, you might want to check the current IPFS hash that the contract is using:
139  
140  ```bash
141  # Using npx directly
142  npx -y ./dtub.testnet/extract-hash.js dtub.testnet
143  
144  # Or if you've installed the package
145  cd dtub.testnet
146  npm run extract:testnet
147  ```
148  
149  This will:
150  1. Connect to the NEAR network
151  2. Query the contract for its current static URL
152  3. Extract and display the IPFS hash
153  4. Show the command you would use to deploy with this hash
154  
155  ### Optional: Specify a Different Signing Account
156  
157  By default, the script uses the same account for signing as the destination account. If you need to use a different account for signing:
158  
159  ```bash
160  export NEAR_SIGNER_ACCOUNT="your-signer-account.testnet"
161  npx -y ./dtub.testnet/deploy-to-ipfs-hash.js dtub.testnet QmYourIPFSHash
162  ```
163  
164  ### Troubleshooting
165  
166  If you encounter errors, you can use these options to help diagnose the issue:
167  
168  #### Test Mode
169  
170  Run the script in test mode to verify the connection without making any transactions:
171  
172  ```bash
173  npx -y ./dtub.testnet/deploy-to-ipfs-hash.js dtub.testnet QmYourIPFSHash --test
174  ```
175  
176  This will:
177  - Connect to NEAR
178  - Verify your account exists
179  - Check that the contract exists
180  - Show what would be deployed
181  - Exit without making any transactions
182  
183  #### Debug Mode
184  
185  Enable debug mode to see more detailed error information:
186  
187  ```bash
188  DEBUG=true npx -y ./dtub.testnet/deploy-to-ipfs-hash.js dtub.testnet QmYourIPFSHash
189  ```
190  
191  This will show:
192  - Detailed connection information
193  - Full error objects
194  - Contract state information
195  - Transaction results
196  
197  ### How It Works
198  
199  The script:
200  1. Connects to the NEAR network (testnet by default for .testnet accounts)
201  2. Uses your private key to authenticate
202  3. Calls the `web4_setStaticUrl` method on the contract with the URL `ipfs://{your-hash}`
203  
204  ### Notes
205  
206  - The script automatically detects whether to use mainnet or testnet based on the account suffix
207  - You can override the network by setting the `NEAR_ENV` environment variable to `mainnet` or `testnet`
208  - The IPFS hash must be in CIDv0 format (starting with "Qm") or CIDv1 format (starting with "bafy")
209  - This script only updates the URL in your smart contract - it doesn't upload any content to IPFS
210  
211  ### Troubleshooting
212  
213  If you encounter errors:
214  
215  1. **Missing contract**: Make sure the account has a web4 contract deployed
216  2. **Missing method**: Ensure the contract has the `web4_setStaticUrl` method
217  3. **Authentication errors**: Check that your NEAR_SIGNER_KEY is correct and has permission to call the contract
218  4. **Invalid hash format**: Verify your IPFS hash is in the correct format
219  
220  ## Web4 Contract Information
221  
222  The web4 contract should implement the `web4_setStaticUrl` method, which updates the IPFS URL that the contract serves. This allows updating the website content without redeploying the contract.
223  
224  ### About web4-min-contract
225  
226  The [web4-min-contract](https://github.com/vgrichina/web4-min-contract) is a minimal implementation of a web4 contract that:
227  
228  - Provides a way to host web content on the NEAR blockchain
229  - Allows updating content by pointing to IPFS hashes without redeploying the contract
230  - Implements the web4 protocol for decentralized web hosting
231  - Requires minimal storage and is cost-effective to deploy
232  - Built with Zig programming language for optimal performance and small contract size
233  
234  Key methods in the contract:
235  - `web4_get`: Serves static content from IPFS, with SPA support (redirects to index.html)
236  - `web4_setStaticUrl`: Updates the static URL to a new IPFS hash
237  - `web4_setOwner`: Updates the contract owner account
238  
239  #### SPA Support
240  
241  The web4-min-contract automatically redirects paths without file extensions to `index.html`, making it suitable for Single Page Applications (SPAs). For example:
242  - `/about` → serves `/index.html`
243  - `/style.css` → serves directly
244  
245  This means your React, Vue, or other SPA frameworks will work correctly with client-side routing.
246  
247  #### Access Control
248  
249  The contract can be managed by:
250  - The contract account itself (the account where the contract is deployed)
251  - An owner account (if set via `web4_setOwner`)
252  
253  ### Benefits of Using web4-min-contract
254  
255  - **Decentralized hosting**: Content is served from IPFS, a decentralized storage network
256  - **Immutable references**: Each version of your site has a unique IPFS hash
257  - **Blockchain-based addressing**: Your site is accessible via your NEAR account name
258  - **Easy updates**: Change your site content without redeploying the contract
259  
260  For more information on web4 contracts, see:
261  - [web4-deploy](https://github.com/vgrichina/web4-deploy)
262  - [web4-min-contract](https://github.com/vgrichina/web4-min-contract)
263  - [NEAR Web4 Documentation](https://docs.near.org/concepts/web4)
264  
265  ### Accessing Your Deployed Website
266  
267  After deploying your content to IPFS and setting the IPFS hash in your web4 contract, you can access your website through:
268  
269  1. **Web4 Gateway**: `https://your-account.testnet.page` or `https://your-account.near.page` (for mainnet)
270  
271  2. **Direct IPFS Gateway**: `https://ipfs.io/ipfs/QmYourIPFSHash`
272  
273  3. **Local IPFS Node**: If you have a local IPFS node running, you can access it via `http://localhost:8080/ipfs/QmYourIPFSHash`
274  
275  The Web4 gateway automatically resolves your NEAR account name to the IPFS hash stored in your web4 contract, providing a human-readable URL for your decentralized website.