Squads Public Client v4

This repository hosts the code for a simplified client application for the Squads V4 Program. The app can be built, verified for integrity, and deployed as a static site using multiple hosting options, including self-hostable solutions like Docker with Nginx. Here’s how you can use it effectively.

---

Features

• Verifiable Build: The dist/ directory contains the static files that can be verified via a hash. This ensures the integrity of the build delivered.
  • Verification can be done against:
    • Remote URLs: Downloaded files can be verified for consistency with the expected hash.
    • IPFS CID: Retrieve the build from IPFS and verify its authenticity.
• Self-hosting: Run the application as a Docker container using an Nginx server for fully self-managed hosting.

---

Getting Started

The following steps will guide you to build, verify, and host the application.

1. Build the Web App

Prerequisites:

• Node.js v20+
• Yarn

Steps:

1. Clone the repository:

   git clone https://github.com/x1-labs/squads-v4-ui
   cd squads-v4-ui

2. Install dependencies:

   yarn install --frozen-lockfile

3. Configure environment variables (optional):

   cp .env.example .env

   Edit .env to customize the following variables:

   • APP_RPC_URL: Solana RPC endpoint (default: https://rpc.testnet.x1.xyz)
   • APP_PROGRAM_ID: Squads program ID (default: DDL3Xp6ie85DXgiPkXJ7abUyS2tGv4CGEod2DeQXQ941)
   • APP_EXPLORER_URL: Solana explorer URL (default: https://explorer.x1.xyz)
   • APP_SAVED_SQUAD_*: Pre-configured saved squads (see .env.example for format)

   Note: These values can also be configured at runtime through the app's settings page.

4. Build the application:

   yarn build

   A dist/ directory will be created containing the static files.

5. Generate a hash of the build:

   ./scripts/generate-hash.sh

---

2. Verify the Build

Verifying Against a Remote URL

To verify the files hosted at a remote URL:

1. Use the scripts/verify-remote.sh script:

   ./scripts/verify-remote.sh <REMOTE_URL> <EXPECTED_HASH>

   Replace <REMOTE_URL> with the base URL of the remote site and <EXPECTED_HASH> with the known SHA-256 hash of the build.

---

Verifying Against an IPFS CID

To verify an IPFS-hosted build:

1. Ensure you have the IPFS CLI installed (ipfs).
2. Use the scripts/verify-ipfs.sh script:

   ./scripts/verify-ipfs.sh <IPFS_CID> <EXPECTED_HASH>

   Replace <IPFS_CID> with the CID of the IPFS build and <EXPECTED_HASH> with the known SHA-256 hash.

---

3. Self-Host with Docker

Prerequisites:

• Docker

Run the Docker Container

You can deploy the web app via a self-hosted Docker container using Nginx:

1. Build the Docker image:

   docker build -t squads-public-v4-client .

2. Run the container:

   docker run -d -p 8080:80 squads-public-v4-client

The app will now be available at http://localhost:8080.

3. Retrieve the hash from the running container:

   docker exec <container_id> cat /var/build-metadata/hash.txt

---

4. Build Hash

A SHA-256 build hash is generated by combining all files in the dist/ directory in a deterministic order.

To Check or Compute the Build Hash Locally:

1. Run the scripts/generate-hash.sh script:

   ./scripts/generate-hash.sh

   The output will show the computed hash of the local dist/ content. This hash should match the one provided in the deployment.

---

File Integrity During Deployment

Manifest File

A manifest.json file is included in the build, containing references to all static assets. It ensures that asset file mappings remain consistent during deployment.

---

Hash List

Recent hashes may be found here: Recent Hashes

---

Program Registry

The application includes a central registry system for X1 programs that manages IDLs, instruction summaries, and transaction tags. This allows for better transaction decoding and user-friendly display of on-chain data.

Adding a New Program

To add support for a new X1 program, edit the src/registry.ts file and add your program registration:

registry.register({
  programId: 'YourProgramId123...', // Your program's public key
  name: 'Your Program Name', // Human-readable name
  idl: yourIdl, // Optional: Import your IDL JSON
  instructions: {
    // Define instruction-specific configurations
    YourInstruction: {
      summary: YourInstructionSummary, // Optional: React component for custom display summary
      tags: {
        label: 'Your Action',
        color: 'blue', // Tag color: blue, green, purple, etc.
        variant: 'subtle', // Tag style: default, outline, or subtle
      },
    },
  },
});

Components of the Registry

1. IDLs (Interface Definition Language)

IDLs enable proper decoding of instruction data and accounts. Import your program's IDL JSON file and include it in the registration:

import yourProgramIdl from './lib/idls/your-program.json';

registry.register({
  programId: 'YourProgramId...',
  name: 'Your Program',
  idl: yourProgramIdl,
  // ...
});

2. Instruction Summaries

Create custom React components to display human-readable summaries of specific instructions:

// Create a summary component in src/components/instructions/summaries/
export const YourInstructionSummary: React.FC<InstructionSummaryProps> = ({ instruction, connection }) => {
  return (
    <div className="space-y-2 text-sm">
      <div className="font-semibold">Your Action Summary</div>
      {/* Display relevant instruction data */}
    </div>
  );
};

// Register it in src/registry.ts
instructions: {
  YourInstruction: {
    summary: YourInstructionSummary,
    // ...
  }
}

3. Transaction Tags

Tags provide visual indicators for transaction types. They appear in the transaction table and details page:

instructions: {
  Transfer: {
    tags: { label: 'Token Transfer', color: 'purple', variant: 'subtle' }
  },
  Swap: {
    tags: { label: 'Swap', color: 'green', variant: 'subtle' }
  }
}

You can also set default tags for all instructions in a program:

registry.register({
  programId: 'YourDeFiProgram...',
  name: 'Your DeFi Protocol',
  defaultTags: { label: 'DeFi', color: 'blue', variant: 'subtle' },
  // ...
});

File Structure

• src/registry.ts - Main registry file with all program registrations
• src/lib/registry/ - Core registry implementation
• src/lib/idls/ - IDL JSON files for various programs
• src/components/instructions/summaries/ - Custom instruction summary components
• src/lib/instructions/types.ts - TypeScript interfaces for the registry system

---

Contributing

Contributions are welcome! Please fork the repository, make your changes, and open a pull request.

---

License

This project is licensed under the MIT License. Please see the included LICENSE file for details.